Documentation

Task. Submit.
Review. Export.

The short workflow for one image. Your agent supplies the interpretation; AnnoLabel supplies validation, storage and review operations.

Install

Install uv, then run:

uv tool install annolabel
annolabel --help

Supports Python 3.11–3.14 on Linux, macOS and Windows. If the command is not found, run uv tool update-shell and restart your shell. See the project’s compatibility guide.

Try the example without an LLM

Download these project-owned example files into a new folder:

Open a terminal in that folder:

annolabel task shapes.png --output task \
  --instructions shapes-task.txt \
  --categories shapes-categories.json
annolabel submit task/task.json --file shapes-submission.json
annolabel export shapes.png --output dataset

Open task/pass1/view.png to review the result. Use new output-directory names when repeating the example. The included coordinates belong only to this image.

Work with your agent

Create a task for one image using annolabel task.
Open the returned view with your agent’s image tool.
Submit scene classifications and all objects together with annolabel submit.
Open the returned review image and inspect it.
If needed, submit one corrected complete snapshot using the new returned task handle.
Export the image or its annotated source folder.

annolabel task /data/images/photo.jpg \
  --output /data/work/photo-task \
  --instructions /data/labeling-instructions.txt \
  --categories /data/categories.json \
  --geometry both

--instructions reads a text file. Give those instructions to the agent too. Categories are an optional JSON array of allowed object labels; scene classifications are independent. Use the reusable agent instructions or the full usage guide.

Coordinates and submissions

The task view has the original EXIF-oriented dimensions: no padding, grid or resizing. The top-left is (0, 0); x increases to the right and y down. Use original pixels, even if your image viewer displays a scaled preview.

{
  "classifications": [{"label": "outdoor"}],
  "objects": [{
    "key": "car-1",
    "label": "car",
    "box": [100, 80, 300, 220],
    "polygon": [[100, 140], [140, 80], [280, 80],
                [300, 220], [100, 220]],
    "note": "Far-side boundary is occluded."
  }]
}

Both top-level arrays are required, even when empty. This is an illustrative format, not coordinates for your image.

Boxes use [x1, y1, x2, y2]; x1 < x2 and y1 < y2.
Coordinates must be finite and within the oriented width/height.
Polygons need at least three distinct vertices, nonzero area and no self-intersections. Do not repeat the first vertex.
A polygon-only object can derive its enclosing box. A provided box must contain the polygon.
Object keys are stable and unique. Identical labels do not imply the same object.

A submission replaces the entire image snapshot. Retain every unchanged object and classification in a correction. Do not include hashes, revision strings or annotation IDs in submit JSON.

Review and recovery

After submission, open the returned review view. Check missing objects, identity, clipped outlines and excess background. Valid geometry alone is not evidence of visual accuracy.

annolabel submit /data/work/photo-task/pass1/task.json \
  --file /data/work/corrected-labels.json

Use the actual returned handle, rather than guessing its path. By default a task allows two successful submissions. Invalid submissions do not consume a pass. If a response is lost:

annolabel task-status /data/work/photo-task/task.json

Use a new output directory for each task. Keep one writer per source image. When a revision conflict occurs, stop and reconcile the current state.

Export COCO

annolabel export /data/images --output /data/datasets/labeled

COCO is the built-in training format. Point your loader at annotations/instances_default.json and use images/default/ as its image root. AnnoLabel converts its input boxes to COCO [x, y, width, height].

Whole-image labels are stored in classifications.csv. Provenance, notes and original source paths are stored separately in provenance.json. Folder export includes images with annotation sidecars. Reuse a complete ordered categories file across dataset splits to keep category IDs stable.

Limits and further reading

AnnoLabel runs locally and does not call models, infer boundaries or provide a browser annotation editor. It supports single-frame images and simple polygons. Holes, multipart instances, video, keypoints and automatic dataset splitting are outside its current scope.