What Is A Label Map?

If you have exported a computer vision dataset and opened the annotation files, you have probably asked: What is a label map?

The annotations reference classes as bare integers, and somewhere alongside them sits a small file that turns those integers back into names. That file is the label map, and when it goes missing or falls out of sync with the annotations, the whole dataset stops making sense.

In this post, I'll cover the role the label map plays in the annotation process, walk through real label maps from common formats, and show how to troubleshoot the errors they cause.

The Role of the Label Map

Computer vision datasets come in all flavors of formats. Roboflow supports the injection, conversion, and exportation of over 30 computer vision formats. While automatic conversion of computer vision datasets is convenient, it is useful to understand the dataset structure for use after export.

In a computer vision dataset, it is common to have annotations referring to class labels. In the above image, our class labels include the different colors and shapes of chess pieces. In order to annotate an image, an image annotation file will often define the annotations specific to a particular image. This annotation file may or may not contain the class labels specific to the annotation in question.

In the case where the annotation file does not specify class labels, a label map is referenced to look up the class name. The label map is the separate source of record for class annotations.

Hands on with the Label Map

It is important to note that not all computer vision dataset formats use the label map. Computer vision datasets that leverage the label map for class labeling include:

• YOLO Darknet TXT
• YOLOv5 PyTorch TXT
• TensorFlow TFRecord
• YOLO Keras TXT
• SuperAnnotate JSON

Other formats are self-contained. COCO JSON carries a categories block inside the same JSON file that holds the annotations, so the ID-to-name mapping travels with the data. Pascal VOC XML goes further and writes the class name as a string inside every annotation.

Let's take a look at an example annotation of the above image f9a9a175f26d4b26bca3a5338cc1405e.jpg in YOLO Darknet format. The corresponding f9a9a175f26d4b26bca3a5338cc1405e.txt file contains the annotations for objects in the image.

1 0.23563218390804597 0.13218390804597702 0.27586206896551724 0.14080459770114942
0 0.09051724137931035 0.28304597701149425 0.1810344827586207 0.10057471264367816
5 0.03879310344827586 0.27873563218390807 0.07758620689655173 0.10344827586206896
5 0.1896551724137931 0.40804597701149425 0.16666666666666666 0.10632183908045977
2 0.1997126436781609 0.5014367816091954 0.1781609195402299 0.10057471264367816
3 0.1221264367816092 0.4942528735632184 0.14367816091954022 0.08908045977011494
3 0.2916666666666667 0.2471264367816092 0.14655172413793102 0.08620689655172414
3 0.5387931034482759 0.4224137931034483 0.15517241379310345 0.08908045977011494
3 0.8204022988505747 0.3620689655172414 0.16091954022988506 0.10632183908045977
3 0.6925287356321839 0.5488505747126436 0.16954022988505746 0.10632183908045977
2 0.8362068965517241 0.7126436781609196 0.22413793103448276 0.12643678160919541
7 0.40948275862068967 0.8951149425287356 0.28160919540229884 0.14367816091954022
11 0.05459770114942529 0.7183908045977011 0.10919540229885058 0.11494252873563218
8 0.860632183908046 0.9425287356321839 0.22701149425287356 0.10919540229885058
10 0.10488505747126436 0.5775862068965517 0.20977011494252873 0.1206896551724138
6 0.10057471264367816 0.7586206896551724 0.1925287356321839 0.10057471264367816
6 0.4209770114942529 0.6724137931034483 0.19540229885057472 0.10344827586206896
9 0.09051724137931035 0.3864942528735632 0.14942528735632185 0.08908045977011494
9 0.11494252873563218 0.6623563218390804 0.15517241379310345 0.09770114942528736
9 0.3175287356321839 0.7514367816091954 0.14942528735632185 0.08908045977011494
9 0.4367816091954023 0.7931034482758621 0.15229885057471265 0.10344827586206896
9 0.5804597701149425 0.7212643678160919 0.16379310344827586 0.10632183908045977

Here, you will notice that the class name is nowhere to be found. Rather, the first entry per line is an integer mapping to the correct class name found in the label map!

Let's take a look at the label map _darknet.labels.

black-bishop
black-king
black-knight
black-pawn
black-queen
black-rook
white-bishop
white-king
white-knight
white-pawn
white-queen
white-rook

Each integer above maps to a position in this list, and this is how the dataset expresses class labels in the annotations.

That is how the label map works in practice!

It is important to note that different label maps function slightly differently from format to format. For example, the .pbtxt label map for our dataset in TensofFlow TFRecord format looks like this:

item {
    name: "black-bishop",
    id: 1,
    display_name: "black-bishop"
}
item {
    name: "black-king",
    id: 2,
    display_name: "black-king"
}
item {
    name: "black-knight",
    id: 3,
    display_name: "black-knight"
}
item {
    name: "black-pawn",
    id: 4,
    display_name: "black-pawn"
}
item {
    name: "black-queen",
    id: 5,
    display_name: "black-queen"
}
item {
    name: "black-rook",
    id: 6,
    display_name: "black-rook"
}
item {
    name: "white-bishop",
    id: 7,
    display_name: "white-bishop"
}
item {
    name: "white-king",
    id: 8,
    display_name: "white-king"
}
item {
    name: "white-knight",
    id: 9,
    display_name: "white-knight"
}
item {
    name: "white-pawn",
    id: 10,
    display_name: "white-pawn"
}
item {
    name: "white-queen",
    id: 11,
    display_name: "white-queen"
}
item {
    name: "white-rook",
    id: 12,
    display_name: "white-rook"
}

Here you can see that the label map is specified in a slightly different fashion with labels displayed in a series of small dictionary entries. And furthermore, the integer referencing a class name starts with 1 not 0!

Common Label Map Errors and How to Fix Them

Most label map problems show up like this:

• Class names show as integers. The label map is missing or your tooling is not loading it. Confirm the label map file exported alongside the annotations and that your code points at it.
• Class labels not recognized. The label map contains names that do not match the class list you're training or evaluation config expects. Diff the two lists; check for a renamed or trailing-whitespace class.
• Class names do not match the dataset. The annotations and label map came from different versions of the dataset. Re-export both together instead of mixing files from separate exports.
• Every class is shifted by one. A zero-indexed label map was applied to one-indexed annotations or vice versa, usually after a manual TFRecord conversion. Convert with a tool that handles indexing, rather than editing files by hand.

Manages Label Maps with Roboflow

A simple fix for label map errors is to upload a dataset to Roboflow to parse the annotations and label map together, hold the class list as structured data, and regenerate a correct label map for whatever format you export to, with the right indexing for that format. Converting between a zero-indexed format and a one-indexed one is handled for you.

Class management happens at the project level in Roboflow Annotate. You can rename, merge, or drop classes when you generate a dataset version, and every export stays consistent with the annotations, because both are generated from the same source of record. If you are labeling from scratch, Auto Label drafts annotations with foundation models so you can review boxes instead of drawing them, and the class list is maintained for you from your first image.

Train a Model Without a Label Map

If you train inside Roboflow, you upload images, label them, generate a version, and train RF-DETR, Roboflow's real-time transformer-based detection architecture, entirely in the browser. Class names flow from your project straight through training, and predictions come back as name strings, not integers.

The same holds at inference time. Running a trained model through the Serverless Hosted API returns class names directly in the response:

pip install inference-sdk supervision

import os
import cv2
import supervision as sv
from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.getenv("ROBOFLOW_API_KEY"),
)

result = client.infer("image.jpg", model_id="your-project/1")

image = cv2.imread("image.jpg")
detections = sv.Detections.from_inference(result)

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()
annotated = box_annotator.annotate(scene=image.copy(), detections=detections)
annotated = label_annotator.annotate(scene=annotated, detections=detections)
cv2.imwrite("annotated.png", annotated)

Every prediction in result includes the class name your team assigned during labeling. There is no label map to load, version, or keep in sync. For the full training walkthrough, see how to train RF-DETR on a custom dataset.

Conclusion

We have discussed the role that a label map plays in annotating a computer vision dataset. We also got hands on with some real live label maps to see how the label map functions in practice.

Do all annotation formats use a label map?

No. Formats like COCO JSON embed the ID-to-name mapping inside the annotation file itself, and Pascal VOC XML writes class names as strings in every annotation. Label maps only appear in formats that store class references as bare integers.

Why do my class names show up as numbers?

Your tooling is reading the annotations without the label map. Either the label map file is missing from the export, or your code is not loading it. Re-export the dataset so the annotations and label map come from the same version, and confirm the file path in your config.

Do label maps start at 0 or 1?

It depends on the format. YOLO-family TXT formats are zero-indexed, while TensorFlow TFRecord label maps start at 1. Mixing the two conventions during a manual conversion shifts every class name by one, which is why format conversion is best done with a tool that handles indexing, such as the Roboflow format converter.

Can I still export label map formats like YOLO Darknet TXT from Roboflow?

Yes. Roboflow exports to all the label map formats covered in this post, with the correct label map generated automatically for each. For training, RF-DETR inside Roboflow is the recommended path for object detection, instance segmentation, and keypoint detection: it is accurate, fast to fine-tune, commercially licensed, and never requires you to manage a label map.

Cite this Post

Use the following entry to cite this post in your research:

Jacob Solawetz. (May 25, 2026). What Is A Label Map?. Roboflow Blog: https://blog.roboflow.com/label-map/