Coordinates and bounding boxes

Many endpoints will return a list containing bounding boxes for detected faces. The bounding boxes are served in the following format:

from dataclasses import dataclass

@dataclass
class Coordinates:
    id: int           # Points to a `FACE_ID`
    boxHeight: float  # Height of bounding box as percentage of image height (0-1)
    boxWidth: float   # Width of bounding box as percentage of image width (0-1)
    centerX: float    # Horizontal coordinate of box center as percentage of image width (0-1)
    centerY: float    # Vertical coordinate of box center as percentage of image height (0-1)
    cornerX: float    # Horizontal coordinate of top-left corner as percentage of image width (0-1)
    cornerY: float    # Vertical coordinate of top-left corner as percentage of image height (0-1)

As such, an example of such data returned by the /api/consistent_identities/upload_target endpoint could be the following:

// ...
"coordinates_list": [
  {
    id: 0,
    boxHeight: 0.273,
    boxWidth: 0.338,
    centerX: 0.197,
    centerY: 0.309,
    cornerX: 0.028,
    cornerY: 0.173
  },
  {
    id: 1,
    boxHeight: 0.182,
    boxWidth: 0.233,
    centerX: 0.539,
    centerY: 0.459,
    cornerX: 0.422,
    cornerY: 0.367
  },
],
// ...

The following example outlines parsing coordinates data from a response in Python. See Uploading a target image to understand how the response object is obtained.

# Refer to the SwapID docs to see how to send a valid request.
# The "response" object is taken from that code.
faces = response.get("faces")

coordinates = []
for coord in faces.get("coordinates_list", []):
    parsed_coords = Coordinates(**coord)
    coordinates.append(parsed_coords)

print(coordinates)

Coordinates will always start from the top-left corner, i.e. the coordinate (0, 0) is the topmost and leftmost pixel at the corner of the image.

As a simple example, let's consider an image 1000 by 1000 pixel was uploaded, generating the response above. All parameters are returned as percentages of the origin image's dimensions so they can be easily converted to pixels:

image_height = 1000
image_width = 1000

coords = coordinates_list[0]

boxHeight = cooords.boxHeight * image_height  # 273 px
boxWidth = cooords.boxWidth * image_width     # 338 px
cornerY = cooords.cornerY * image_height      # 173 px
cornerX = cooords.cornerX * image_width       # 29 px