Introduction to Refonte.AI API
Data Engine Core Resources
Data Engine Tasks Types
Image Annotation Overview
When annotating images using vector geometric shapes, this task type is advised. These are the available geometries:
- Box
- Polygon
- Point
- Cuboid and
- Ellipse
The imageannotation job is created by this endpoint. Refonte will apply the specified geometry to an image that it is given. Attachment and geometry are the necessary factors for this task.
Body Params
project string
The name of the project to associate this task with.
batch string
A Google Doc embedded in an iframe that supports markdown and explains how to perform the segmentation. Markdown can be used to display sample images, organize your instructions, and much more. For further information, see our best practices for instruction. Please do not set this option for Refonte Rapid projects unless you want to override the project level instructions.
callback string
The full url (including the scheme http:// or https://) or email address of the callback that will be used when the task is completed.
attachment string required
A URL to the image you'd like to be segmented.
context_attachment array of objects
An array of objects in the form of ["attachment": "link to actual attachment"] to show to taskers as a reference. Context images themselves can not be labeled. Context images will appear like this in the UI. You cannot use the task's attachment url as a context attachment's url.
geometries object required
The annotation requirements and the annotation geometries (box, polygon, line, point, cuboid, or ellipse) that should be applied to each annotation are specified using this object. Additional details on each geometry are provided in the corresponding section below.
annotation_attributes object
You can add other attributes here that you would like to record for each annotation. This is limited to annotations on instances. For additional information regarding annotation attributes, see Annotation Attributes.
links object
Use this field to define links between annotations.
hypothesis object
Annotations that can be edited and used to initiate a job. When you want annotators to further improve the prelabels that a model you ran to prelabel the task has produced, this is helpful. For further information, see the Segmentation Hypothesis Format.
layer object
Read-only annotations to be pre-drawn on the task.
base_annotations boolean
Annotations that can be edited and have the ability to be "locked" are what a task should start with. When you want annotators to further improve the prelabels that a model you ran to prelabel the task has produced, this is helpful. The annotations field, which follows the same format as the response's annotations field, must be present.
can_add_base_annotations boolean
If base_annotations are utilized, whether or not new annotations can be added to the task. In addition to base_annotations, additional annotations can be provided to the job if set to true. The task will not allow the addition of additional annotations if set to false.
can_edit_base_annotations boolean
Whether base_annotations in the job are editable. Base_annotations, if set to true, allows the tasker to modify the annotation's position, characteristics, and other details. Every feature of base_annotations will be locked if set to false.
can_edit_base_annotation_labels boolean
Whether or not base_annotations labels can be edited in the task. If set to true, the label of base_annotations can be edited by the tasker. If set to false, the label will be locked.
can_delete_base_annotations boolean
Whether or not base_annotations can be removed from the task. If set to true, base_annotations can be deleted from the task. If set to false, base_annotations cannot be deleted from the task.
image_metadata object
This field accepts specified image metadata, supported fields include: - date_time - displays the date and time the image is taken - resolution - configures the units of the ruler tools, resolution_ratio holds the number of resolution_units corresponding to one pixel; e.g. [resolution_ratio: 3, resolution_unit: 'm'], one pixel in the image corresponds to three meters in the real world. - location - the real-world location where this image was captured, in the standard geographic coordinate system; e.g. [lat: 37.77, long: -122.43]
metadata object
A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format. Max 10KB.
paddingX integer
The amount of padding in pixels added to the top and bottom of the image. Overrides padding if set.
priority integer
A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.
unique_id string
A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details.
clear_unique_id_on_error boolean
If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically
tags array of strings
Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.
Request
Python
POST /v1/task/imageannotationimport requests
url = "https://api.refonte.com/v1/task/imageannotation"
payload = {
"instruction": "**Instructions:** Please label all the things",
"attachment": "https://i.imgur.com/iDZcXfS.png",
"geometries": {
"box": {
"min_height": None,
"min_width": None,
"can_rotate": None,
"integer_pixels": None
},
"polygon": {
"min_vertices": None,
"max_vertices": None
},
"line": {
"min_vertices": None,
"max_vertices": None
},
"cuboid": {
"min_height": None,
"min_width": None,
"camera_intrinsics": {
"fx": None,
"fy": None,
"cx": None,
"cy": None,
"skew": None,
"scalefactor": None
},
"camera_rotation_quaternion": {
"w": None,
"x": None,
"y": None,
"z": None
},
"camera_height": None
}
},
"padding": None,
"paddingX": None,
"paddingY": None,
"priority": None
}
headers = {
"accept": "application/json",
"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)Response
{
"task_id": "string",
"created_at": "string",
"type": "imageannotation",
"status": "pending",
"instruction": "string",
"is_test": false,
"urgency": "standard",
"metadata": {},
"project": "string",
"callback_url": "string",
"updated_at": "string",
"work_started": false,
"params": {
"attachment_type": "image",
"attachment": "http://i.imgur.com/3Cpje3l.jpg",
"geometries": {
"box": {
"objects_to_annotate": [
null
],
"min_height": 5,
"min_width": 5
},
"polygon": {
"objects_to_annotate": [
null
]
},
"point": {
"objects_to_annotate": [
null
]
}
},
"annotation_attributes": {
"additionalProp": {
"type": "category",
"description": "string",
"choice": "string"
}
}
}
}Boxes
Refonte.Ai will annotate your image or video with boxes based on a box entry in params.geometries, and it will provide the position and size of the boxes.
Request Parameters
objects_to_annotate array of strings
A list of string or LabelDescription objects.
min_height integer
The minimum height in pixels of the bounding boxes you'd like to be made.
can_rotate boolean
Allows a tasker to rotate the bounding box.
integer_pixels boolean
Response fields (top, left, width, and height) that indicate the location and size of the box will be returned as integers rather than floats. Rotated boxes are not compatible with this.
Key | Type | Description |
|---|---|---|
uuid | string | A computer-generated unique identifier for this annotation. In video annotation tasks, this can be used to track the same object across frames. |
status | string | String indicating geometry type: box |
label | string | objects_to_annotate array for its geometry. In video annotation tasks, any annotation objects with the same uuid will have the same label across all frames. |
attributes | object | See the Annotation Attributes section for more details about the attributes response field. |
left | float | The distance, in pixels, between the left border of the bounding box and the left border of the image. |
top | float | The distance, in pixels, between the top border of the bounding box and the top border of the image. |
width | float | The width, in pixels, of the bounding box. |
height | float | The height, in pixels, of the bounding box. |
If can_rotate was set to true, the following fields will supersede the above fields:
Key | Type | Description |
|---|---|---|
rotation | float | The clockwise rotation in radians |
vertices | array of objects | An array of objects with a schema [x: 0, y: 0]. The vertices of the rotated bounding box |
left | float | The distance, in pixels, between the left border of the bounding box and the left border of the image. |
top | float | The distance, in pixels, between the top border of the bounding box and the top border of the image. |
Example Box Request
Python
{
"geometries": {
"box": {
"objects_to_annotate": [
"traffic_sign",
{
"choice": "vehicle",
"subchoices": [
"Car",
{
"choice": "truck_suv",
"display": "truck or SUV"
}
]
},
"pedestrian"
],
"min_height": 5,
"min_width": 5,
"can_rotate": false
},
...
},
...
}Example Box Response
{
"response": {
"annotations": [
{
"type": "box",
"label": "pedestrian",
"attributes": {
"moving": "yes"
},
"left": 2,
"top": 4,
"width": 3,
"height": 5,
"uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
},
{
"type": "box",
"label": "car",
"attributes": {
"moving": "yes"
},
"left": 7,
"top": 5,
"width": 14,
"height": 5,
"uuid": "0a6cd019-a014-4c67-bd49-c269ba08028a"
},
{ ... },
{ ... }
]
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// populated task for convenience
...
}
}Example Rotated Box Response
{
"response": {
"annotations" : [
{
"label" : "car",
"attributes" : {},
"uuid" : "122a4270-f9b2-4f66-a9ca-2e06f0de66e5",
"width" : 121.878523862864,
"height" : 71.6961921895555,
"rotation" : 1.2440145049532,
"left" : 613.440037825633,
"top" : 199.208745812549,
"type" : "box",
"vertices" : [
{
"x" : 688.769014855216,
"y" : 165.835344251165
},
{
"x" : 727.891633787782,
"y" : 281.264089660824
},
{
"x" : 659.989584658913,
"y" : 304.27833956349
},
{
"x" : 620.866965726348,
"y" : 188.84959415383
}
]
}
{ ... },
{ ... }
]
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// populated task for convenience
...
}
}Polygons
Refonte.Ai will annotate your image or video with polygons and return the polygon vertices given a polygon entry in params, geometries.
Request Parameters
min_vertices integer
The minimum number of vertices in a valid line annotation for your request.
max_vertices integer
The maximum number of vertices in a valid line annotation for your request. Must be at least min_vertices.
Key | Type | Description |
|---|---|---|
uuid | string | A computer-generated unique identifier for this annotation. In video annotation tasks, this can be used to track the same object across frames. |
status | string | String indicating geometry type: polygon |
label | string | objects_to_annotate array for its geometry. In video annotation tasks, any annotation objects with the same uuid will have the same label across all frames. |
attributes | object | See the Annotation Attributes section for more details about the attributes response field. |
vertices | array | An array of vertex objects describing the vertices of the polygon, listed in the order they were annotated. In other words, the point order will be either clockwise or counter-clockwise for each annotation. |
Key | Type | Description |
|---|---|---|
x | number | The distance, in pixels, between the vertex and the left border of the image. |
y | number | The distance, in pixels, between the vertex and the top border of the image. |
Example Polygon Request
Python
{
"geometries": {
"polygon": {
"objects_to_annotate": [
"traffic_sign",
{
"choice": "vehicle",
"subchoices": [
"Car",
{
"choice": "truck_suv",
"display": "truck or SUV"
}
]
},
"pedestrian"
],
"min_vertices": 4,
"max_vertices": 15
},
...
},
...
}Example Polygon Response
{
"response": {
"annotations": [
{
"type": "polygon",
"label": "car",
"vertices": [
{
"x": 123,
"y": 10
},
{
"x": 140,
"y": 49
},
{
"x": 67,
"y": 34
}
],
"uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
},
{ ... },
{ ... }
]
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// task inlined for convenience
...
}
}Lines
Refonte.Ai will add polygons to your image or video based on a line entry in params.geometries and return the polygon vertices.
Request Parameters
min_vertices integer
The minimum number of vertices in a valid line annotation for your request.
max_vertices integer
The maximum number of vertices in a valid line annotation for your request. Must be at least min_vertices.
Key | Type | Description |
|---|---|---|
uuid | string | A computer-generated unique identifier for this annotation. In video annotation tasks, this can be used to track the same object across frames. |
status | string | String indicating geometry type: polygon |
label | string | objects_to_annotate array for its geometry. In video annotation tasks, any annotation objects with the same uuid will have the same label across all frames. |
attributes | object | See the Annotation Attributes section for more details about the attributes response field. |
vertices | array | An array of vertex objects describing the vertices of the polygon, listed in the order they were annotated. In other words, the point order will be either clockwise or counter-clockwise for each annotation. |
Key | Type | Description |
|---|---|---|
x | number | The distance, in pixels, between the vertex and the left border of the image. |
y | number | The distance, in pixels, between the vertex and the top border of the image. |
Example Line Request
Python
{
"geometries": {
"polygon": {
"objects_to_annotate": [
"traffic_sign",
{
"choice": "vehicle",
"subchoices": [
"Car",
{
"choice": "truck_suv",
"display": "truck or SUV"
}
]
},
"pedestrian"
],
"min_vertices": 4,
"max_vertices": 15
},
...
},
...
}Example Line Response
{
"response": {
"annotations": [
{
"type": "polygon",
"label": "car",
"vertices": [
{
"x": 123,
"y": 10
},
{
"x": 140,
"y": 49
},
{
"x": 67,
"y": 34
}
],
"uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
},
{ ... },
{ ... }
]
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// task inlined for convenience
...
}
}Ellipses
Refonte.Ai will annotate your image or video with polygons and return the vertices of the polygons given an ellipses item in params, geometries.
Request Parameters
objects_to_annotate array of objects
A list of string or LabelDescription objects.
Key | Type | Description |
|---|---|---|
uuid | string | A computer-generated unique identifier for this annotation. In video annotation tasks, this can be used to track the same object across frames. |
status | string | String indicating geometry type: polygon |
label | string | objects_to_annotate array for its geometry. In video annotation tasks, any annotation objects with the same uuid will have the same label across all frames. |
attributes | object | See the Annotation Attributes section for more details about the attributes response field. |
vertices | array | A list of Vertex objects of length 4 describing the extremal vertices of the ellipse |
Example Ellipse Request
Python
{
"geometries": {
"polygon": {
"objects_to_annotate": [
"traffic_sign",
{
"choice": "vehicle",
"subchoices": [
"Car",
{
"choice": "truck_suv",
"display": "truck or SUV"
}
]
},
"pedestrian"
],
"min_vertices": 4,
"max_vertices": 15
},
...
},
...
}Example Ellipse Response
{
"response": {
"annotations": [
{
"type": "polygon",
"label": "car",
"vertices": [
{
"x": 123,
"y": 10
},
{
"x": 140,
"y": 49
},
{
"x": 67,
"y": 34
}
],
"uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
},
{ ... },
{ ... }
]
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// task inlined for convenience
...
}
}Cuboids
Refonte.Ai will annotate your image or video with perspective cuboids and return the cuboids' vertices given a cuboids item in params.geometries. Refonte will return refonte-invariant 3D coordinates with regard to the camera, i.e., presuming the camera is at the origin, if both camera intrinsics and extrinsics are supplied.
Request Parameters
objects_to_annotate array of objects
A list of string or LabelDescription objects.
min_height integer
The minimum height in pixels of the cuboids you'd like to be made.
min_width integer
The minimum width in pixels of the cuboids you'd like to be made.
camera_intrinsics object
An object that defines camera intrinsics, in format [fx: number, fy: number, cx: number, cy: number, scalefactor: number, skew: number] (skew defaults to 0, scalefactor defaults to 1). scalefactor is used if the image sent is of different dimensions from the original photo (if the attachment is half the original, set scalefactor to 2) to correct the focal lengths and offsets. Use in conjunction with camera_rotation_quaternion and camera_height to get perspective-corrected cuboids and 3d points.
camera_rotation_quaternion object
Object that defines the rotation of the camera in relation to the world. Expressed as a quaternion, in format [w: number, x: number, y: number, z: number]. Use in conjunction with camera_intrinsics to get perspective-corrected cuboids and 3d points. Note that the z-axis of the camera frame represents the camera's optical axis. Use in conjunction with camera_intrinsics and camera_height to get perspective-corrected cuboids and 3d points.
camera_height integer
The height of camera above the ground, in meters. Use in conjunction with camera_rotation_quaternion and camera_intrinsics to get perspective-corrected cuboids and 3d points.
Key | Type | Description |
|---|---|---|
uuid | string | A computer-generated unique identifier for this annotation. In video annotation tasks, this can be used to track the same object across frames. |
status | string | String indicating geometry type: polygon |
label | string | objects_to_annotate array for its geometry. In video annotation tasks, any annotation objects with the same uuid will have the same label across all frames. |
attributes | object | See the Annotation Attributes section for more details about the attributes response field. |
vertices | array | A list of Vertex objects defining all visible vertices of the cuboid. See the Vertex section for more details. |
edges | array | A list of Edge objects defining the edges of the cuboid.. See the Edge section for more details. |
points_2d | [x, y] | If camera_rotation quaternion, camera_intrinsics, and camera_height were provided, contains projected 2D coordinates of all 8 vertices of the cuboid after perspective correction. See diagram below for the order that the points are returned in. |
points_3d | [x, y, z] | If camera_rotation quaternion, camera_intrinsics, and camera_height were provided, contains 3D coordinates (arbitrarily scaled, relative to the camera location) of all 8 vertices of the cuboid after perspective correction. See diagram below for the order that the points are returned in. |
Key | Type | Description |
|---|---|---|
x | number | The distance, in pixels, between the vertex and the left border of the image. |
y | number | The distance, in pixels, between the vertex and the top border of the image. |
type | string | Always vertex |
description | string | An enum describing the position of the vertex, which is one of: face-topleft,face-bottomleft, face-topright, face-bottomright, side-topcorner, side-bottomcorner |
Key | Type | Description |
|---|---|---|
x1 | number | The distance, in pixels, between the first vertex of the edge and the left border of the image. |
y1 | number | The distance, in pixels, between the first vertex of the edge and the top border of the image. |
x2 | number | The distance, in pixels, between the second vertex of the edge and the left border of the image. |
y2 | number | The distance, in pixels, between the second vertex of the edge and the top border of the image. |
type | string | Always vertex |
description | string | An enum describing the position of the vertex, which is one of: face-topleft,face-bottomleft, face-topright, face-bottomright, side-topcorner, side-bottomcorner |
Example Cuboid Request
Python
{
...
"geometries": {
"cuboid": {
"objects_to_annotate": [
"car"
],
"min_height": 10,
"min_width": 10,
"camera_intrinsics": {
"fx": 986.778503418,
"fy": 984.4254150391,
"cx": 961.078918457,
"cy": 586.9694824219,
"skew": 0,
"scale_factor": 1
},
"camera_rotation_quaternion": {
"w": 0.0197866653,
"x": 0.0181939654,
"y": 0.6981190587,
"z": -0.715476937
},
"camera_height": -0.2993970777
}
},
...
}Text
Points on the cuboid are returned in this order for both points_2d and points_3d:
3-------2
/| /|
/ | / |
0-------1 |
| 7----|--6
| / | /
4-------5Example Cuboid Response
{
...,
"response": {
"annotations": [
{
"label": "car",
"vertices": [
{
"description": "face-topleft",
"y": 270,
"x": 293,
"type": "vertex"
},
{
"description": "face-bottomleft",
"y": 437,
"x": 293,
"type": "vertex"
},
{
"description": "face-topright",
"y": 270,
"x": 471,
"type": "vertex"
},
{
"description": "face-bottomright",
"y": 437,
"x": 471,
"type": "vertex"
},
{
"description": "side-topcorner",
"y": 286,
"x": 607,
"type": "vertex"
},
{
"description": "side-bottomcorner",
"y": 373,
"x": 607,
"type": "vertex"
}
],
"edges": [
{
"description": "face-top",
"x1": 293,
"y1": 270,
"x2": 471,
"y2": 270,
"type": "edge"
},
{
"description": "face-right",
"x1": 471,
"y1": 270,
"x2": 471,
"y2": 437,
"type": "edge"
},
{
"description": "face-bottom",
"x1": 471,
"y1": 437,
"x2": 293,
"y2": 437,
"type": "edge"
},
{
"description": "face-left",
"x1": 293,
"y1": 437,
"x2": 293,
"y2": 270,
"type": "edge"
},
{
"description": "side-top",
"x1": 471,
"y1": 270,
"x2": 607,
"y2": 286,
"type": "edge"
},
{
"description": "side-bottom",
"x1": 471,
"y1": 437,
"x2": 607,
"y2": 373,
"type": "edge"
}
],
"points_2d": [
{
"y": 270,
"x": 293
},
{
"y": 437,
"x": 293
},
{
"y": 270,
"x": 471
},
{
"y": 437,
"x": 471
},
{
"y": 286,
"x": 607
},
{
"y": 373,
"x": 607
},
{
"y": 373,
"x": 607
},
{
"y": 373,
"x": 607
}
],
"points_3d": [
{
"z": 0,
"y": 270,
"x": 293
},
{
"z": 0,
"y": 437,
"x": 293
},
{
"z": 0,
"y": 270,
"x": 471
},
{
"z": 0,
"y": 437,
"x": 471
},
{
"z": 0,
"y": 286,
"x": 607
},
{
"z": 0,
"y": 373,
"x": 607
},
{
"z": 0,
"y": 373,
"x": 607
},
{
"z": 0,
"y": 373,
"x": 607
}
],
}
]
},
...
}Image Response Format
An annotations field (and a global_attributes field, if Global Attributes were supplied in the task creation request) will be included in the response field, which is a component of the callback POST request and is permanently saved as part of the task object. An array of Annotation objects will be included in the annotations field. Every annotation object's schema is determined by the annotation's geometry.
Response
{
"response": {
"annotations": [
{
"type": "box",
"label": "small vehicle",
"attributes": {
"moving": "yes"
},
"left": 2,
"top": 4,
"width": 3,
"height": 5,
"uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
},
{
"type": "box",
"label": "large vehicle",
"attributes": {
"moving": "yes"
},
"left": 7,
"top": 5,
"width": 14,
"height": 5,
"uuid": "0a6cd019-a014-4c67-bd49-c269ba08028a"
},
{
"type": "polygon",
"label": "car",
"vertices": [
{
"x": 123,
"y": 10
},
{
"x": 140,
"y": 49
},
{
"x": 67,
"y": 34
}
],
"uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef43"
},
{ ... },
{ ... }
],
"global_attributes": {
"driving": "Yes",
"night": "No"
}
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// populated task for convenience
...
}
}Image Annotation Hypothesis
Prelabels can be used in the hypothesis field when constructing an image annotation task, saving workers from having to annotate the image from beginning. To add pre-labels to a task using hypothesis, you must supply them in the task's hypothesis payload field at task creation. The task response's schema and the hypothesis object's schema must coincide.
- Check the chosen task type's task response field schema.
- Examine the taxonomy of your project (label names, attribute criteria, types of annotations, etc.).
- Produce pre-labels in the format specified by the previously mentioned taxonomy and schema.
- Make a task with the pre-labels in the hypothesis field at the same top level as the project and instructions task fields.
The format for the hypothesis will be similar to that of Refonte.Ai's task response. For basic annotations in this specific job type, the annotations field array inside the hypothesis object is required.
Note: UUIDs are optional; if you would like to track an annotation using a specific UUID, you may add it to the hypothesis; if not, Refonte will create one for you. In the global_attributes field of the hypothesis object, you can also add Global Attributes for Image Annotation at the same level of annotations.
task_payload_with_hypothesis
{
...
"attachment": "https://example.com/attachment.png",
"hypothesis": {
"annotations": [
{
"label": "car",
"left": 90,
"top": 66,
"height": 94,
"width": 96,
"type": "box"
}
]
},
...
}task_taxonomy
{
"geometries": {
"box": {
"objects_to_annotate": [
"car"
],
"min_height": 10,
"min_width": 10
}
},
"annotation_attributes": {}
}refonte_task_response
{
"links": [],
"annotations": [
{
"label": "car",
"uuid": "xfb506ca-d742-4e75-bb52-0725f099b238",
"left": 115,
"top": 68,
"height": 97,
"width": 69,
"type": "box"
},
],
"global_attributes": {}
}Video Annotation Overview
The videoannotation job is created by this endpoint. Refonte will annotate each frame in a sequence of photos taken from a movie (referred to as "frames") with the geometries (box, polygon, line, point, cuboid, and ellipse) that you designate. Geometries is a necessary parameter for this activity.
Label Nesting and Options
Annotation tasks frequently contain too many label options for a tasker to effectively sort through all at once, or there are situations in which you would prefer to provide a tasker with one version of a label name but receive another version in the answer.
In those situations, you can adjust the label's display values and enable nested labels—labels that contain subcategories—by using LabelDescription objects.
We accept both the more complicated LabelDescription objects and a mixed array of strings when you declare objects_to_annotate in your job parameters.
Definition: LabelDescription
Objects_to_annotate can be a string, a nested label with choices and subchoices, or a nested label where the subchoices are LabelDescription objects with a display value. A straightforward example is shown in the example JSON below.
Even though there might be a lot of total labels, a tasker can use subchoices to classify an object as a road, pedestrian, or vehicle first, then choose the particular kind of pedestrian or vehicle depending on that classification.
Nested labels may be specified both for the object labels (the objects_to_annotate array parameter), as well as in the choices array of a categorical annotation attribute. In both cases, you would specify a nested label by using a LabelDescription object instead of a string.
For example, for an objects_to_annotate array of ["Vehicle", "Pedestrian"] , you could instead add a nested label by passing an array, like ["Vehicle", ("choice": "Pedestrian", "subchoices": ["Animal", "Adult", "Child"])] . Then, if a tasker selected "Pedestrian" for an annotation, they would be further prompted to choose one of the corresponding subchoices for that annotation.
The LabelDescription object has the following structure:
Parameter | Type | Description |
|---|---|---|
choice* | string | The name of the label. This should be singular and descriptive (ex: car, background, pole). When both a choice and subchoices are defined, the choice will not be selectable, it will only be used for UX navigation. Only the "leaf" nodes will be returned in Refonte's response. |
subchoices | Array | Optional: Descriptions of the sub-labels to be shown under this parent label. Array can be a mix of LabelDescription objects or strings. |
instance_label | boolean | Optional: For Segmentation-based Tasks - Whether this label should be segmented on a per-instance basis. For example, if you set instance_label to true, each individual car would get a separate mask in the image, allowing you to distinguish between them. |
display | string | Optional: The value to be shown to a Tasker for a given label. Visually overrides the choice field in the user experience, but does not affect the task response or conditionality. |
LabelDescription Example
objects_to_annotate = [
"Road",
{
"choice": "Vehicle",
"subchoices": ["Car", "Truck", "Train", "Motorcycle"]
},
{
"choice": "Pedestrian",
"subchoices": [
"Animal",
{"choice": "Ped_HeightOverMeter", "display": "Adult" },
{"choice": "Ped_HeightUnderMeter", "display": "Child" },
]
}
]Updated about 2 months ago