Annotator¶
AnnotatorApp ¶
Main application class for the Boxlab Annotator GUI.
The AnnotatorApp provides a complete graphical interface for viewing, editing, and auditing object detection datasets. It supports COCO and YOLO formats, multi-split datasets, annotation editing, and audit workflows.
The application consists of several key components: - Image list panel (left): Browse and filter images - Annotation canvas (center): View and edit annotations - Control panel (center bottom): Navigation and mode controls - Info panel (right): Display image metadata and statistics - Menu bar: File operations and settings - Status bar: Current operation status
Features
- Import/export COCO and YOLO datasets
- Visual annotation editing with drag-to-resize
- Multi-split support (train/val/test)
- Audit mode with approve/reject workflow
- Workspace persistence (.cyw files)
- Auto-backup on crashes
- Image tagging system
- Keyboard shortcuts for efficiency
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root | Tk | None | Optional Tkinter root window. If None, creates a new Tk instance. | None |
Attributes:
| Name | Type | Description |
|---|---|---|
root | The main Tkinter window. | |
controller | AnnotationController managing dataset state. | |
canvas | AnnotationCanvas for displaying and editing images. | |
control_panel | ControlPanel for navigation and mode controls. | |
image_list_panel | ImageListPanel for browsing images. | |
info_panel | InfoPanel for displaying metadata. | |
backup_dir | Directory for auto-backup files. | |
status_var | Tkinter StringVar for status bar text. |
Example
Example
Initialize the annotation application.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root | Tk | None | Optional Tkinter root window. If None, creates new instance. | None |
Source code in boxlab/annotator/__init__.py
Functions¶
delete_current_image ¶
Delete current image with confirmation.
Source code in boxlab/annotator/__init__.py
import_dataset ¶
Import dataset from COCO, YOLO, or raw image directory.
Shows ImportDialog for format selection and path input, then loads the dataset in a background thread with progress indication.
Source code in boxlab/annotator/__init__.py
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 | |
export_dataset ¶
Export dataset to COCO or YOLO format.
Shows ExportDialog for format and naming options, then exports the dataset. Generates audit report JSON if in audit mode.
Source code in boxlab/annotator/__init__.py
load_workspace ¶
Load workspace from .cyw file.
Prompts for workspace file, loads it in background thread, and restores the complete application state including annotations, tags, and audit status.
Source code in boxlab/annotator/__init__.py
save_workspace ¶
Save current workspace to associated .cyw file.
If no workspace path is set, delegates to save_workspace_as().
Source code in boxlab/annotator/__init__.py
save_workspace_as ¶
Save workspace to a new .cyw file.
Prompts for file location and saves complete workspace state.
Source code in boxlab/annotator/__init__.py
next_image ¶
Navigate to next image in current split.
prev_image ¶
Navigate to previous image in current split.
load_image ¶
Load and display image with annotations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_id | str | ID of the image to load. | required |
Source code in boxlab/annotator/__init__.py
on_image_selected ¶
Handle image selection from list panel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image_id | str | ID of the selected image. | required |
Source code in boxlab/annotator/__init__.py
on_split_changed ¶
Handle split selection change.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
split | str | Name of the selected split (e.g., "train", "val", "test"). | required |
Source code in boxlab/annotator/__init__.py
on_annotations_changed ¶
Handle annotation modifications on canvas.
Source code in boxlab/annotator/__init__.py
on_edit_mode_changed ¶
Handle edit mode toggle.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled | bool | Whether edit mode is enabled. | required |
Source code in boxlab/annotator/__init__.py
on_category_changed ¶
Handle category selection change.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category_id | int | None | Selected category ID, or None. | required |
on_tags_changed ¶
Handle tags change for current image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tags | list[str] | List of tag strings. | required |
Source code in boxlab/annotator/__init__.py
on_new_tag_created ¶
Handle new tag creation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tag | str | New tag string. | required |
Source code in boxlab/annotator/__init__.py
on_audit_mode_changed ¶
Handle audit mode toggle.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled | bool | Whether audit mode is enabled. | required |
Source code in boxlab/annotator/__init__.py
approve_current ¶
Approve current image and move to next.
Source code in boxlab/annotator/__init__.py
reject_current ¶
Reject current image and move to next.
Source code in boxlab/annotator/__init__.py
on_audit_comment_changed ¶
Handle audit comment change.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
comment | str | Comment text. | required |
Source code in boxlab/annotator/__init__.py
show_audit_report ¶
Show audit report in a text dialog.
Source code in boxlab/annotator/__init__.py
export_audit_report ¶
Export audit report to JSON file.
Source code in boxlab/annotator/__init__.py
open_current_dashboard ¶
Open Streamlit dashboard for current audit state.
Source code in boxlab/annotator/__init__.py
978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 | |
open_file_dashboard ¶
Open Streamlit dashboard for an external audit report file.
Source code in boxlab/annotator/__init__.py
update_after_load ¶
Update UI after loading dataset or workspace.
Source code in boxlab/annotator/__init__.py
update_counter ¶
Update image counter display.
delete_selected ¶
undo ¶
zoom_in ¶
zoom_out ¶
reset_zoom ¶
show_shortcuts ¶
Show keyboard shortcuts help dialog.
Source code in boxlab/annotator/__init__.py
show_about ¶
Show about dialog with version information.
Source code in boxlab/annotator/__init__.py
on_closing ¶
options: show_root_heading: true show_source: false heading_level: 2 members_order: source show_signature_annotations: true separate_signature: true members: - init - run - import_dataset - export_dataset - load_workspace - save_workspace - save_workspace_as - next_image - prev_image - approve_current - reject_current
Overview¶
The Boxlab Annotator is a desktop GUI application for viewing, editing, and auditing object detection datasets. It provides an intuitive interface for working with COCO and YOLO format datasets, with features designed for efficient annotation workflows.
Key Features¶
Dataset Management¶
- Import COCO and YOLO format datasets
- Import raw image directories
- Export to COCO or YOLO with flexible naming strategies
- Multi-split support (train/val/test)
- Workspace persistence (.cyw files)
Annotation Editing¶
- Visual bounding box display
- Drag-to-resize with corner and edge handles
- Point-and-click selection
- Delete and undo operations
- Category assignment
- Real-time validation
Audit Workflow¶
- Approve/reject images
- Add audit comments
- Filter by audit status
- Generate audit reports
- Track audit statistics
- JSON report export
Additional Features¶
- Image tagging system
- Auto-backup on crashes
- Keyboard shortcuts
- Zoom and pan
- Status indicators
- Image metadata display
Application Layout¶
┌──────────────────────────────────────────────────────────────┐
│ Menu Bar (File | View | Audit | Help) │
├─────────────┬───────────────────────────────┬────────────────┤
│ │ │ │
│ Image │ Canvas │ Info Panel │
│ List │ (Annotations) │ - Metadata │
│ Panel │ │ - Tags │
│ - Splits │ │ - Stats │
│ - Filter │ │ - Audit │
│ │ │ │
│ ├───────────────────────────────┤ │
│ │ Control Panel │ │
│ │ [◀ Prev] [Split] [Next ▶] │ │
│ │ [Edit] [Category] [Audit] │ │
├─────────────┴───────────────────────────────┴────────────────┤
│ Status Bar │
└──────────────────────────────────────────────────────────────┘
Quick Start¶
Basic Usage¶
from boxlab.annotator import AnnotatorApp
# Create and run the application
app = AnnotatorApp()
app.run()
Command Line¶
Workflows¶
Import and View Workflow¶
- Launch the annotator
- File → Import Dataset...
- Select format (COCO/YOLO/Raw)
- Choose dataset path
- Select splits to load
- Browse images with arrow keys or image list
Annotation Editing Workflow¶
- Import dataset
- Enable Edit Mode (Control Panel)
- Select category
- Click and drag to create bbox
- Drag corners/edges to resize
- Click bbox to select
- Press Delete to remove
- Ctrl+Z to undo
- File → Save Workspace
Audit Workflow¶
- Import dataset
- Enable Audit Mode (Control Panel)
- Review current image
- Press F1 to approve or F2 to reject
- Add comments (optional)
- Automatically moves to next image
- View progress in Info Panel
- Export audit report when complete
Workspace Management¶
- Work on dataset with edits/audits
- File → Save Workspace (Ctrl+S)
- Saves as .cyw file
- File → Open Workspace (Ctrl+O)
- Restores complete state
Keyboard Shortcuts¶
Navigation¶
←Previous image→Next image
View¶
Ctrl + Mouse WheelZoom in/outMouse WheelScroll verticallyShift + Mouse WheelScroll horizontallyCtrl + 0Reset zoomMiddle Mouse DragPan view
Editing¶
DeleteDelete selected annotationCtrl + ZUndo last changeRight ClickShow context menu- Drag corners: Resize diagonally
- Drag edges: Resize horizontally/vertically
- Click bbox: Select annotation
Audit¶
F1Approve current imageF2Reject current image
File¶
Ctrl + OOpen workspaceCtrl + SSave workspaceCtrl + Shift + SSave workspace as
Auto-Backup¶
The annotator automatically creates backups in case of crashes:
- Backup location:
~/.boxlab/backups/ - Triggered on uncaught exceptions
- Includes all annotations and audit status
- Displayed in error dialog
- Load via File → Open Workspace
File Formats¶
Workspace Files (.cyw)¶
Workspace files preserve:
- Dataset structure and metadata
- All annotations (original + edits)
- Audit status and comments
- Image tags
- Current view state
Audit Reports (JSON)¶
{
"generated_at": "2025-01-16T13:51:01Z",
"total_images": 1000,
"approved": 850,
"rejected": 100,
"pending": 50,
"images": [
{
"image_id": "001",
"file_name": "image1.jpg",
"status": "approved",
"comment": "Good quality",
"audited_at": "2025-01-16T13:45:00Z"
}
]
}
See Also¶
- Dataset Core - Dataset management
- I/O Operations - Loading and exporting
- Types - Data structures
- COCO Plugin - COCO format
- YOLO Plugin - YOLO format