How Labelme models annotations
Unofficial preview. Docsbook assembled this page from the public
wkentaro/labelmeREADME.mdandexamples/directory. It is not affiliated with, endorsed by, or maintained by the Labelme project. The official documentation lives at labelme.io/docs.
Labelme has a small model: you draw shapes, you name them with labels, you can tag the whole image with flags, and all of it lands in one JSON file per image. Four ideas, and every command-line flag and export script works on top of them.
What is a shape in Labelme?#
A shape in Labelme is one drawn region on one image, stored with the label you gave it and the list of points that define it. Labelme supports polygon, rectangle, circle, line and point primitives, and records which one you used in the shape's shape_type field.
The primitive you choose is what makes the same tool work for different tasks. Rectangles give you object detection boxes; polygons give you segmentation masks; points and lines cover keypoints and paths.
What is the difference between a label and a flag?#
A label in Labelme belongs to a single shape — it names the object you outlined. A flag belongs to the entire image — it records something true of the picture as a whole.
That difference decides which task you are doing. Outlining every cat in a photo and labelling each one is detection or segmentation. Marking the whole photo cat with no shapes at all is classification. Labelme does both, and the classification guide covers the flag-only workflow.
Labels and flags can also be combined: --label-flags attaches per-label flags, so a shape labelled person can additionally carry occluded, truncated or male.
What does group_id do?#
group_id ties several shapes together as one object. Two polygons over the same partly-hidden car, both labelled car and both given group_id: 1, are one car instance rather than two.
This is what separates the two segmentation tasks. Without group IDs you get semantic segmentation — every pixel gets a class. With them you get instance segmentation — every pixel gets a class and an object identity.
Where does Labelme store annotations?#
Labelme writes one JSON file per image, named after the image and saved next to it unless --output says otherwise. The file holds the image path, its width and height, the image-level flags, and the list of shapes.
The JSON file is one of three interfaces the project treats as stable, alongside the command line and the ~/.labelmerc config format. Everything else, including Labelme's Python import surface, is internal — in v7 the internal modules were renamed with underscore prefixes, so import labelme.utils no longer works. To consume annotations from your own code, read the JSON directly.
Why is the image sometimes inside the JSON file?#
Labelme can embed the image itself in the annotation as base64 in an imageData field, which makes the JSON self-contained but much larger. It is off by default and turned on per run with --with-image-data, or permanently with with_image_data: true in your config file.
When imageData is absent, a reader resolves the picture through the imagePath field relative to the JSON file's own directory.
Related#
- Annotation JSON reference — every field, with types
- Get started — draw the first shape
- Configuration reference — the defaults behind this model