There are often annotation tasks that have too many label choices for a tasker to efficiently sort through them all at once, or times when you want to show one version of a label name to a tasker, but would like another version in the response.
In those cases, you can utilize LabelDescription objects to support nested labels, where labels may have subcategories within them, as well as setting display values for the label.
When declaring objects_to_annotate in your task parameters, we accept a mixed array of strings and the more complex LabelDescription objects.
Definition: LabelDescription
LabelDescriptionThe 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 Scale's response. |
| subchoices | Array<LabelDescription | string> | 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 default false | 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 default choice | 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. |
A simple example is illustrated in the example JSON below, where objects_to_annotate can simply be a string, a nested label with choices and subchoices, or a nested label where the subchoices themselves are LabelDescription objects with a display value.
While there may be a large number of total labels, using subchoices a tasker can first categorize an object as a road, pedestrian, or vehicle, and based on that choice, further select the specific type of pedestrian or vehicle.
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.
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" },
]
}
]
See the Conditional attributes section for more details about conditional attributes.