Annotations¶
Annotations provide a way to associate semantic labels with files. Each annotation consists of two parts:
- Label - The semantic category of the annotation, chosen from the list of available labels.
- Geometry - The part of the file to which the label most closely applies. For example, the geometry may specify a 2D bounding box or polygon that specifies the extent of an object that has been identified in an image.
Supported file types and geometries¶
The types of files that support annotations are:
Pixel coordinates¶
When pixel coordinates are being used, the x,y values specify the horizontal and vertical offset from the top-left corner of the image.
Specifically, 0,0 is the top-left of the image, width,height is the bottom-right, and 0.5,0.5 is the center of the top-left pixel.
Images¶
The geometry of an image annotation can be either a 2D bounding box or a polygon.
The format for a bounding box is as follows, where X and Y values are specified in pixels, and the min and max values specify the minimum and maximum bounds of the box:
The format for a polygon is as follows, where X and Y values are specified in pixels, there must be 3 or more vertices, and none of the vertices should be duplicated:
"geometry": {
"type": "polygon",
"vertices": [
{"x": 100, "y": 200},
{"x": 190, "y": 205},
{"x": 180, "y": 280},
...
]
}
Orthomosaics¶
The geometry of an orthomosaic annotation can be either a 2D bounding box or a polygon. This is similar to the annotation functionality provided for images, except that orthomosaic annotations additionally include latitude and longitude values.
When creating or modifying the geometry of an orthomosaic annotation, points can be specified using either X and Y pixel coordinates, or latitude and longitude GPS values. Depending on what type of coordinate is provided (either pixels or GPS, but not both), the API will automatically compute the corresponding values of the other type and make them available in API responses.
The format for a bounding box is as follows, where X and Y values are specified in pixels, the min and max values specify the minimum and maximum bounding values of the box, and latitude and longitude values are also included:
"geometry": {
"type": "box",
"min": {"x": 100, "y": 200, "latitude": 1.234, "longitude": 2.345},
"max": {"x": 500, "y": 400, "latitude": 1.345, "longitude": 2.456}
}
Note that in a box, the minimum and maximum X and Y values do not correspond to the same physical point as the minimum and maximum GPS values. Specifically, the minimum X and Y coordinate is the top-left corner of the box, whereas the the minimum GPS coordinate is the bottom-left. Similarly, the maximum X and Y coordinate is the bottom-right corner, and the maximum GPS coordinate is the top-right.
The format for a polygon is as follows, where X and Y values are specified in pixels, there must be 3 or more vertices, none of the vertices should be duplicated, and latitude and longitude values are also included:
"geometry": {
"type": "polygon",
"vertices": [
{"x": 100, "y": 200, "latitude": 1.234, "longitude": 2.345},
{"x": 190, "y": 205, "latitude": 1.239, "longitude": 2.456},
{"x": 180, "y": 280, "latitude": 1.345, "longitude": 2.451},
...
]
}
In contrast to the bounding box, the X,Y and GPS coordinates in a polygon vertex correspond to the same physical point.
Create an annotation¶
Create a new annotation.
Route: /v3{instance-uri}{file-uri}/annotations
Method: POST
When creating a new annotation, the request body should contain the label and geometry that should be used for the annotation (see more details about the geometry types that are supported for each file type). Additionally, the request can optionally contain initial values for custom attributes.
Sample request body:
Upon successful creation of an annotation, the response will contain the details of the newly created annotation.
Get a list of annotations¶
The list of annotations that have been associated with a file can be retrieved in two ways.
The first way is to get the details of a file, and inspect its "annotations" property.
This will list the details of all annotations for the file.
The second way is to access the /annotations endpoint of a file.
This will return a list where each annotation is represented by its URI.
Route: /v3{instance-uri}{file-uri}/annotations
Method: GET
Sample response body:
{
"success": true,
"data": {
"annotations": [
"{file-uri}/annotations/1111-1111",
"{file-uri}/annotations/2222-2222",
"{file-uri}/annotations/3333-3333",
...
]
}
}
Similar to getting the details of a list of files, the /annotations endpoint supports returning the details of all of the annotations (and not just their URIs).
This is accomplished as follows:
Route: /v3{instance-uri}{file-uri}/annotations?details
Method: GET
Sample response body:
{
"success": true,
"data": {
"annotations": [
{
"uri": "{file-uri}/annotations/1111-1111",
"label": "/labels/pallet",
"geometry": {
...
}
},
{
"uri": "{file-uri}/annotations/2222-2222",
"label": "/labels/loader",
"geometry": {
...
}
},
...
]
}
}
Get details of an annotation¶
Get the details of an individual annotation.
Route: /v3{instance-uri}{annotation-uri}
Method: GET
Sample response body:
{
"success": true,
"data": {
"annotation": {
"uri": "{file-uri}/annotations/1111-1111",
"label": "/labels/pallet",
"geometry": {
...
},
"custom_attributes": {
...
}
}
}
}
Description of response attributes:
"uri"- Resource identifier for this annotation."label"- Resource identifier of the label of this annotation."geometry"- Part of the file to which the label most closely applies. See the list of supported file types and geometries for more details."custom_attributes"- Dictionary with custom attribute names and values that have been defined for this annotation.
Update an annotation¶
Update the details of an annotation.
Route: /v3{instance-uri}{annotation-uri}
Method: PATCH
An annotation can be updated via a PATCH request, where the body of the request contains new values for the label, geometry, or custom attributes of the annotation.
Sample request body:
Upon successfully updating an annotation, the response will contain the updated details of the annotation.
Delete an annotation¶
Remove an annotation from a file.
Route: /v3{instance-uri}{annotation-uri}
Method: DELETE
Sample response body:
Custom attributes¶
Annotations support the use of custom attributes. Initial values for custom attributes can be assigned when the annotation is created, though they can always be set and updated at a later time.