Introduction to Refonte.AI API
Data Engine Core Resources
Data Engine Tasks Types
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.
An attachments array describing the attachments to be annotated and a fields parameter describing all the various bits of information to be gathered are required for this operation.
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
The LabelDescription object has the following structure:
Parameters
choice string required
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.
subchoice array of objects
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.
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" },
]
}
]Response Format
The only use for nested labels is to organize a sizable collection of labels into groups. The response will therefore be the same as it would be for unnested labels, in which the worker reports simply the last "leaf" label that they chose. In the aforementioned example, the annotation's label would be "Animal" if a worker chose "Pedestrian" first, then "Animal."
The above command returns as object structured like this:
Response Format
{
"task_id": "5774cc78b01249ab09f089dd",
"created_at": "2016-9-03T07:38:32.368Z",
"callback_url": "http://www.example.com/callback",
"type": "annotation",
"status": "pending",
"instruction": "Annotate the cars and pedestrians",
"params": {
"attachment": "https://i.imgur.com/VDPoOZE.jpg",
"attachment_type": "image",
"objects_to_annotate": [
{
"choice": "Vehicle",
"subchoices": ["Car", "Truck", "Train", "Motorcycle"]
},
{
"choice": "Pedestrian",
"subchoices": ["Animal", "Adult", "Child"]
}
],
"with_labels": false,
"min_width": 30,
"min_height": 30,
"examples": [],
"annotation_attributes": {
"occlusion": {
"description": "What percent of the object is occluded?",
"choices": ["0%", "25%", "50%", "75%"],
"conditions": {
"label_condition": {
"label": ["Car", "Truck", "Motorcycle"]
}
}
}
}
},
"metadata": {}
}An example response with nested labels is below:
{
"response": {
"annotations": [
{
"left": 123,
"top": 10,
"width": 121,
"height": 39,
"label": "Motorcycle",
"attributes": {
"occlusion": "0%"
}
},
{
"left": 82,
"top": 56,
"width": 64,
"height": 30,
"label": "Animal"
},
{ ... },
{ ... }
]
},
"task_id": "5774cc78b01249ab09f089dd",
"task": {
// populated task for convenience
...
}
}Updated about 2 months ago