`remap-yolo`: Remap Class IDs in YOLO Annotations¶

The remap-yolo command performs bulk remapping of class IDs in YOLO annotation text files according to a provided mapping file. This is useful for harmonizing label indices, merging similar classes, or removing unwanted classes from your dataset.

Usage¶

m3-download remap-yolo MAP_FILE YOLO_DIR [--output-dir OUTPUT_DIR]

Parameters¶

MAP_FILE: File (CSV or JSON) containing the class ID remapping definitions
YOLO_DIR: Directory containing YOLO text annotation files to process
--output-dir: (Optional) Output directory for remapped annotations; if omitted, original files are overwritten

Data Loss Risk

If --output-dir is not specified, original annotation files will be overwritten without confirmation. Always use --output-dir when testing a new remapping.

Mapping File Formats¶

The MAP_FILE can be provided in two formats:

CSV Format¶

Simple two-column format with original class IDs in the first column and target class IDs in the second column:

0,1
2,1
3,2
4,-1

JSON Format¶

A JSON object with original class IDs as keys and target class IDs as values:

{
  "0": 1,
  "2": 1,
  "3": 2,
  "4": -1
}

Special Values

If a class ID is mapped to a negative value (e.g., -1), annotations with that class will be removed entirely.

How It Works¶

The command detects the mapping file format based on file extension
For each text file in the input directory, it:
- Processes each line (each represents one bounding box)
- Checks if the class ID (first value in each line) needs remapping
- Replaces the class ID if a match is found, or removes the line if mapped to a negative value
- Writes the modified annotations either in-place or to the output directory

Processing Details

Only class IDs that match entries in the mapping file are modified
Lines with class IDs mapped to negative values are removed completely
The command reports how many annotation files were modified

Examples¶

Using a CSV mapping file with an output directory:

m3-download remap-yolo class_map.csv labels/ --output-dir labels_remapped/

Using a JSON mapping file and overwriting existing files:

m3-download remap-yolo class_mapping.json dataset/labels/

Merging multiple classes into one class ID:

m3-download remap-yolo merge_classes.csv yolo_annotations/ --output-dir merged_annotations/

Where merge_classes.csv might contain:

1,0
2,0
3,0

This would merge classes 1, 2, and 3 into class 0.

remap-yolo: Remap Class IDs in YOLO Annotations¶