# humansignal/labelimg architecture

> Architecture diagram of the GitHub repository humansignal/labelimg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/humansignal/labelimg
- Repository: https://github.com/humansignal/labelimg

## Overview

LabelImg is a desktop Qt application for drawing object bounding boxes on images and saving annotations in PASCAL VOC, YOLO, or CreateML formats. The main workflow is launch, open an image or directory, create and edit labeled rectangles, then save annotations; existing annotation files can also be displayed. The graph preserves the three documented formats and key UI, settings, and localization components. Sampled excerpts show the canvas/shape and format-writer relationships, but not most main-window event wiring, so those links are omitted or marked unverified.

Main entry points: [`labelImg.py`](https://github.com/humansignal/labelimg/blob/master/labelImg.py) (Main Window), [`libs/labelFile.py`](https://github.com/humansignal/labelimg/blob/master/libs/labelFile.py) (Format Facade), [`libs/canvas.py`](https://github.com/humansignal/labelimg/blob/master/libs/canvas.py) (Drawing Canvas), [`libs/labelDialog.py`](https://github.com/humansignal/labelimg/blob/master/libs/labelDialog.py) (Label Dialog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_main["Main Window<br/>[labelImg.py]"]
  node_image_workflow["Image Workflow<br/>[labelImg.py]"]
  node_settings["Preferences<br/>[settings.py]"]
  node_settings_store[("Qt Settings Store<br/>[settings.py]")]
end

subgraph group_annotation["Annotation Editing"]
  node_canvas["Drawing Canvas<br/>[canvas.py]"]
  node_shape["Rectangle Shapes<br/>[shape.py]"]
  node_label_dialog["Label Dialog<br/>[labelDialog.py]"]
  node_class_picker["Default Class Picker"]
end

subgraph group_formats["Annotation Formats"]
  node_label_file["Format Facade<br/>[labelFile.py]"]
  node_voc["PASCAL VOC I/O<br/>[pascal_voc_io.py]"]
  node_yolo["YOLO I/O<br/>[yolo_io.py]"]
  node_createml["CreateML I/O<br/>[create_ml_io.py]"]
  node_create_ml_writer["CreateML Writer<br/>[create_ml_io.py]"]
end

subgraph group_support["UI Support"]
  node_toolbar["Toolbar<br/>[toolBar.py]"]
  node_color_dialog["Color Dialog<br/>[colorDialog.py]"]
  node_zoom["Zoom Control<br/>[zoomWidget.py]"]
  node_light["Brightness Control<br/>[lightWidget.py]"]
  node_strings["Localization<br/>[stringBundle.py]"]
  node_utils["Qt Utilities<br/>[utils.py]"]
  node_combobox["Label Combo Box<br/>[combobox.py]"]
end

node_user(("Annotator"))

node_user -->|"launches"| node_main
node_user -->|"opens images"| node_image_workflow
node_user -->|"draws boxes"| node_canvas
node_user -->|"saves annotations"| node_label_file
node_main -.->|"uses canvas"| node_canvas
node_main -.->|"manages images"| node_image_workflow
node_main -.->|"loads preferences"| node_settings
node_main -.->|"configures actions"| node_toolbar
node_main -.->|"prompts labels"| node_label_dialog
node_main -.->|"selects classes"| node_class_picker
node_main -.->|"sets colors"| node_color_dialog
node_main -.->|"controls zoom"| node_zoom
node_main -.->|"controls brightness"| node_light
node_main -.->|"loads strings"| node_strings
node_canvas -->|"draws shapes"| node_shape
node_label_file -->|"delegates VOC"| node_voc
node_label_file -->|"delegates YOLO"| node_yolo
node_label_file -->|"delegates CreateML"| node_createml
node_label_dialog -->|"validates labels"| node_utils
node_strings -->|"converts text"| node_utils
node_create_ml_writer -->|"writes JSON"| node_createml

click node_main "https://github.com/humansignal/labelimg/blob/master/labelImg.py"
click node_image_workflow "https://github.com/humansignal/labelimg/blob/master/labelImg.py"
click node_settings "https://github.com/humansignal/labelimg/blob/master/libs/settings.py"
click node_canvas "https://github.com/humansignal/labelimg/blob/master/libs/canvas.py"
click node_shape "https://github.com/humansignal/labelimg/blob/master/libs/shape.py"
click node_label_dialog "https://github.com/humansignal/labelimg/blob/master/libs/labelDialog.py"
click node_class_picker "https://github.com/humansignal/labelimg/blob/master/libs/default_label_combobox.py"
click node_label_file "https://github.com/humansignal/labelimg/blob/master/libs/labelFile.py"
click node_voc "https://github.com/humansignal/labelimg/blob/master/libs/pascal_voc_io.py"
click node_yolo "https://github.com/humansignal/labelimg/blob/master/libs/yolo_io.py"
click node_createml "https://github.com/humansignal/labelimg/blob/master/libs/create_ml_io.py"
click node_settings_store "https://github.com/humansignal/labelimg/blob/master/libs/settings.py"
click node_toolbar "https://github.com/humansignal/labelimg/blob/master/libs/toolBar.py"
click node_color_dialog "https://github.com/humansignal/labelimg/blob/master/libs/colorDialog.py"
click node_zoom "https://github.com/humansignal/labelimg/blob/master/libs/zoomWidget.py"
click node_light "https://github.com/humansignal/labelimg/blob/master/libs/lightWidget.py"
click node_strings "https://github.com/humansignal/labelimg/blob/master/libs/stringBundle.py"
click node_utils "https://github.com/humansignal/labelimg/blob/master/libs/utils.py"
click node_combobox "https://github.com/humansignal/labelimg/blob/master/libs/combobox.py"
click node_create_ml_writer "https://github.com/humansignal/labelimg/blob/master/libs/create_ml_io.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_image_workflow,node_settings,node_settings_store toneBlue
class node_canvas,node_shape,node_label_dialog,node_class_picker toneAmber
class node_label_file,node_voc,node_yolo,node_createml,node_create_ml_writer toneMint
class node_toolbar,node_color_dialog,node_zoom,node_light,node_strings,node_utils,node_combobox toneRose
class node_user toneIndigo
```

## Components

### Application UI

- [Main Window](https://github.com/humansignal/labelimg/blob/master/labelImg.py): `labelImg.py`
- [Image Workflow](https://github.com/humansignal/labelimg/blob/master/labelImg.py): `labelImg.py`
- [Preferences](https://github.com/humansignal/labelimg/blob/master/libs/settings.py): `libs/settings.py`
- [Qt Settings Store](https://github.com/humansignal/labelimg/blob/master/libs/settings.py): `libs/settings.py`

### Annotation Editing

- [Drawing Canvas](https://github.com/humansignal/labelimg/blob/master/libs/canvas.py): `libs/canvas.py`
- [Rectangle Shapes](https://github.com/humansignal/labelimg/blob/master/libs/shape.py): `libs/shape.py`
- [Label Dialog](https://github.com/humansignal/labelimg/blob/master/libs/labelDialog.py): `libs/labelDialog.py`
- [Default Class Picker](https://github.com/humansignal/labelimg/blob/master/libs/default_label_combobox.py): `libs/default_label_combobox.py`

### Annotation Formats

- [Format Facade](https://github.com/humansignal/labelimg/blob/master/libs/labelFile.py): `libs/labelFile.py`
- [PASCAL VOC I/O](https://github.com/humansignal/labelimg/blob/master/libs/pascal_voc_io.py): `libs/pascal_voc_io.py`
- [YOLO I/O](https://github.com/humansignal/labelimg/blob/master/libs/yolo_io.py): `libs/yolo_io.py`
- [CreateML I/O](https://github.com/humansignal/labelimg/blob/master/libs/create_ml_io.py): `libs/create_ml_io.py`
- [CreateML Writer](https://github.com/humansignal/labelimg/blob/master/libs/create_ml_io.py): `libs/create_ml_io.py`

### UI Support

- [Toolbar](https://github.com/humansignal/labelimg/blob/master/libs/toolBar.py): `libs/toolBar.py`
- [Color Dialog](https://github.com/humansignal/labelimg/blob/master/libs/colorDialog.py): `libs/colorDialog.py`
- [Zoom Control](https://github.com/humansignal/labelimg/blob/master/libs/zoomWidget.py): `libs/zoomWidget.py`
- [Brightness Control](https://github.com/humansignal/labelimg/blob/master/libs/lightWidget.py): `libs/lightWidget.py`
- [Localization](https://github.com/humansignal/labelimg/blob/master/libs/stringBundle.py): `libs/stringBundle.py`
- [Qt Utilities](https://github.com/humansignal/labelimg/blob/master/libs/utils.py): `libs/utils.py`
- [Label Combo Box](https://github.com/humansignal/labelimg/blob/master/libs/combobox.py): `libs/combobox.py`

### Other components

- **Annotator**

## Connections

- Annotator → Main Window: launches (evidence: `README.rst`)
- Annotator → Image Workflow: opens images (evidence: `README.rst`)
- Annotator → Drawing Canvas: draws boxes (evidence: `README.rst`)
- Annotator → Format Facade: saves annotations (evidence: `README.rst`)
- Main Window → Drawing Canvas: uses canvas (evidence: `labelImg.py`)
- Main Window → Image Workflow: manages images (evidence: `labelImg.py`)
- Main Window → Preferences: loads preferences (evidence: `labelImg.py`)
- Main Window → Toolbar: configures actions (evidence: `labelImg.py`)
- Main Window → Label Dialog: prompts labels (evidence: `labelImg.py`)
- Main Window → Default Class Picker: selects classes (evidence: `labelImg.py`)
- Main Window → Color Dialog: sets colors (evidence: `labelImg.py`)
- Main Window → Zoom Control: controls zoom (evidence: `labelImg.py`)
- Main Window → Brightness Control: controls brightness (evidence: `labelImg.py`)
- Main Window → Localization: loads strings (evidence: `labelImg.py`)
- Drawing Canvas → Rectangle Shapes: draws shapes (evidence: `libs/canvas.py`)
- Format Facade → PASCAL VOC I/O: delegates VOC (evidence: `libs/labelFile.py`)
- Format Facade → YOLO I/O: delegates YOLO (evidence: `libs/labelFile.py`)
- Format Facade → CreateML I/O: delegates CreateML (evidence: `libs/labelFile.py`)
- Label Dialog → Qt Utilities: validates labels (evidence: `libs/labelDialog.py`)
- Localization → Qt Utilities: converts text (evidence: `libs/stringBundle.py`)
- CreateML Writer → CreateML I/O: writes JSON (evidence: `libs/labelFile.py`)
