Labels, text prompts and attributes
A label is a name and a colour. Two optional fields let you say more, and they answer different questions: a text prompt describes what the class looks like and is written once, while an attribute records a property that differs between individual objects and is filled in per object. If the answer is the same for every car in your dataset it belongs in the prompt; if it changes from car to car it belongs in an attribute.
The difference in one table
| Text prompt | Attribute | |
|---|---|---|
| Describes | The class as a whole | One individual object |
| Written | Once, on the label | Every time you draw an object |
| Example | a red delivery van | occluded = yes |
| Used by | The text-prompt tool, to find objects for you | Your training or evaluation code, after export |
| Stored in | The project | Each annotation |
| Survives export | Not in the standard files of any format — it is a project setting, not per-object data. It does come back through the AnnotateIt sidecar | Yes: all of them in COCO and Datumaro, VOC’s own four in VOC, none in YOLO. The sidecar restores the full set either way |
A quick test: could two objects with the same label ever disagree about it? If yes, it is an attribute. If no, it is a prompt.
Text prompts
Select "+ Add prompt" on a label and type a short visual description. The text-prompt tool reads it and finds matching objects in your images, so you confirm shapes instead of drawing them. Write what a stranger would need in order to point at the object.
| Label name | Weak prompt | Better prompt |
|---|---|---|
| class_3 | none — falls back to the name | a yellow school bus seen from behind |
| defect | a defect | a dark scratch on a metal surface |
| person | human being | a person riding a bicycle |
| tomato | expensive tomato | a ripe red tomato on the vine |
Avoid words the model cannot see. "Expensive" or "the one we care about" describe context that is not in the pixels. Colour, shape, material and setting are what work. A prompt is optional: without one the tool falls back to the label name, which is fine when the name is already descriptive (zebra) and poor when it is not (class_3).
Prompts matter most in detection and instance segmentation projects, where the tool can produce shapes. They are hidden on iPhone and iPad, and can be hidden everywhere in Settings, under Project, if you do not use them.
Attributes
Select "+ Add attribute" on a label to declare a property every object with that label will carry. While you annotate, the attribute appears under each object in the Annotations list and you fill it in there. Five types are available.
| Type | Use it for | Example |
|---|---|---|
| Checkbox | A yes/no flag | occluded, truncated, difficult |
| Select | One of a known list | vehicle type: car, truck, bus |
| Radio | One of a short known list | view: front, side, rear |
| Number | A measured quantity, with min;max;step | occlusion percent: 0;100;10 |
| Text | Anything else — a last resort | notes |
Prefer Select over Text wherever the answer comes from a known set: free text cannot be filtered reliably and is hard to train on. An attribute can be marked Required, which records the intent on the definition and travels with it through export and import. Required never blocks saving incomplete work: the Annotations list shows an “N required” badge, and Dataset Quality reports every remaining gap before export.
When you need attributes
- Excluding hard objects from training, or scoring them separately — the classic occluded, truncated and difficult trio.
- Recording a sub-type without turning one class into a dozen — sign category, vehicle type, defect severity.
- Dataset bookkeeping that travels with the object — camera, weather, review status.
- Round-tripping a dataset you imported, so the fields it arrived with are still there when you export.
When you do not
- Every object of the class is interchangeable. An attribute nobody fills in is worse than no attribute.
- The property is really a separate class. To tell cars from trucks, make two labels — one Vehicle label with a type attribute will not teach a detector the difference.
- The value belongs to the image rather than the object. A whole-image property is better recorded as a classification label.
Move the label schema without moving the dataset
The Import labels and Export labels actions on the Labels page move a schema as a small, versioned AnnotateIt JSON file. It includes label names and colours, keyboard shortcuts, text prompts, attribute definitions, label behaviour, hierarchy and each group’s single- or multiple-selection mode. It contains no media or annotations, so it is the right artifact when another compatible project needs the same vocabulary rather than a copy of the dataset.
Label JSON can move between supported non-keypoint project domains, with label behaviour and hierarchy adapted and validated for the destination. Keypoint projects are excluded because their schema requires a skeleton template. For each incoming label, choose an existing label to preserve that label’s ID and annotations, or create a new one with the imported metadata. Existing labels are never removed or overwritten. Duplicate names, an incompatible hierarchy and shortcut conflicts are blocked before the schema is saved.
This labels file is separate from a dataset archive and from annotateit-metadata.json. Use label transfer to reuse only the schema; use a standard dataset export plus its sidecar for annotated media; use Export project for a complete project copy.
Filtering by what you recorded
Attributes are not only for export. The filter above the annotation list narrows both the list and the canvas by rule, and an attribute is one of the things a rule can match on — alongside the label, the shape type, the object’s area in pixels or as a percentage of the image, the prediction score, and where the annotation came from. Rules combine with all / any / none, and the operators follow the attribute’s own type: a checkbox is is / is not, a number compares, free text also offers contains.
This is what makes an attribute worth filling in during annotation rather than after it. "Show me every occluded truck under 2% of the image" is a question you can answer while you work, and "show me only what the model produced, scoring under 60%" is how you find the predictions worth reviewing first. Area is measured exactly — a polygon by its outline, a mask by its actual pixels — not by a bounding box, so a size filter means what it says on an irregular shape.
Filtering is a view, never a deletion. An annotation that stops matching after you edit it stays visible until you press Refresh, so the list cannot rearrange itself under your cursor mid-edit.
Which export formats keep attributes
| Format | Attributes | What it carries |
|---|---|---|
| Datumaro | All | Everything, in its native attributes block. The safest lossless round trip. |
| COCO | All | iscrowd as a first-class field, everything else in an attributes block. |
| Pascal VOC | Its own four only | pose, truncated, difficult and occluded — the fields the VOC XML schema defines. An attribute of your own, however it is named, is not written here. |
| KITTI | Its own two only | truncated (a float 0–1) and occluded (0–3) — the two fields KITTI defines, encoded its own way, not VOC’s booleans of the same name. Any other attribute is not written here. |
| YOLO | None | A class and a shape. The format has nowhere to put an attribute. |
| MOTS | None | A class id, a track id and a mask. The format has nowhere to put an attribute. |
| The AnnotateIt sidecar | All | Attached to every annotated export except plain ZIP. It restores the complete set — definitions and values — when the archive is re-imported into AnnotateIt, whatever the standard layer could hold. |
Read that table as two layers. The standard files are what a third-party tool reads, and they are where an attribute can genuinely be lost. The sidecar sits beside them and is what makes an AnnotateIt-to-AnnotateIt round trip exact — so "YOLO carries no attributes" is true of the .txt files and not of the archive as a whole.
The export dialog warns you when your project has attributes and the format you picked would drop them. Import works the same way in reverse: an archive in a format that carries attributes arrives with them already declared on your labels, ready to edit — including the fields that decide how a benchmark scores you, such as VOC difficult and COCO iscrowd, which standard evaluation code excludes from the metric.
A worked example
A parking-lot dataset for a detection model that must ignore partly hidden cars during evaluation, and distinguish cars from vans.
- Create two labels, Car and Van — the model has to tell them apart, so they are classes, not an attribute.
- Give Car the prompt "a parked passenger car seen from above" and Van "a parked delivery van seen from above", so the text-prompt tool can draft the boxes.
- On both labels add a Checkbox attribute named occluded, and a Number attribute named occlusion percent with the range 0;100;10.
- Annotate. Confirm the drafted boxes, then tick occluded and set the percentage on the cars that are partly behind something.
- Export to COCO. Both attributes travel with each object — occluded and your own occlusion percent — and your training script can filter on them. Pascal VOC would carry occluded, because that is one of its four defined fields, but not occlusion percent: a custom attribute has nowhere to go in the VOC schema and would survive only in the AnnotateIt sidecar.
Both fields are optional and both can be switched off in Settings, under Project. Hiding a field only removes the control — prompts and attributes already saved keep working and keep being exported.