User Guide

1. Installation

PixelTagger is available for Windows, macOS, and Ubuntu Linux. Download your platform version below.

Links will be available when PixelTagger exits beta. Contact us for early access.

System Requirements

Windows Install Steps

1. Download PixelTagger_Setup.exe
2. Run the installer and follow the prompts
3. Launch PixelTagger from the Start Menu or Desktop shortcut

macOS Install Steps

1. Download PixelTagger_macOS.dmg
2. Open the DMG and drag PixelTagger.app to the Applications folder
3. Launch from Applications — do not run directly from the DMG
4. If macOS blocks the app, go to System Settings → Privacy & Security → Open Anyway

Ubuntu Install Steps

1. Download PixelTagger_Linux_x86_64.AppImage
2. Make it executable: chmod +x PixelTagger_Linux_x86_64.AppImage
3. Run it: ./PixelTagger_Linux_x86_64.AppImage

2. Loading Your Dataset

PixelTagger works with a simple two-folder structure: one folder for images, one for annotations.

1. Click the Load Data button in the toolbar
2. Select your images folder — PixelTagger will scan it for JPG, PNG, BMP, TIFF, WebP files
3. Select your annotations folder — this is where XML annotation files are saved. It can be empty if you are starting fresh
4. Images appear in the left panel. Any existing annotations load automatically

PixelTagger saves annotations in Pascal VOC XML format by default. Annotations auto-save every time you change an image or make edits — you never need to manually save.

3. Interface Overview

The PixelTagger interface has four main areas:

• Toolbar (top) — Load data, select annotation shape, choose label, zoom controls, image navigation
• Image List (left panel) — All images in your dataset. Images with annotations are marked with ★
• Canvas (center) — The main annotation workspace where you draw and edit annotations
• Annotations Panel (right) — Lists all annotations on the current image

4. Annotating Images

The basic annotation workflow is the same for all shape types:

1. Select a shape type from the Create: dropdown in the toolbar
2. Select a label from the Label: dropdown
3. Click and drag on the canvas to draw the annotation
4. The annotation saves automatically

Selecting and Editing

• Click an annotation to select it — resize handles appear
• Drag the handles to resize
• Drag the body to move the annotation
• Right-click an annotation to change its label from the context menu

Deleting Annotations

Select an annotation and press Delete or Backspace. To delete all annotations on an image, press Ctrl+A to select all, then Delete.

5. Annotation Shapes

Bounding Box

Click and drag to draw a rectangle. Eight resize handles appear when selected. Best for standard object detection tasks.

Polygon

Click to place each vertex. Press Enter or double-click to close the polygon (minimum 3 points). Press Esc to cancel. Best for irregular object shapes.

Line

Click and drag to draw a directional line with an arrowhead. Useful for direction, flow, or connection annotation.

Keypoint

Click to place a single point. A second click toggles the keypoint between visible and occluded states. Used for pose estimation and landmark detection.

Rotated Box

Click and drag to create an oriented bounding box. A green rotation handle appears — drag it to rotate the box freely. Best for aerial and satellite imagery.

Cuboid

Click to place 8 corner points (front face first, then rear face). Used for 3D object annotation in autonomous driving datasets.

Ellipse

Click and drag to define the bounding rectangle of the ellipse. A green rotation handle lets you rotate it. Useful for circular or oval objects.

6. Managing Labels

Labels are the class names assigned to your annotations (e.g. "car", "person", "dog").

Adding Labels

Click the +/- button next to the Label dropdown. Type a name in the text field and click + Add.

Renaming a Label

Go to Edit → Rename Label. Select the label to rename and enter the new name. The rename applies to all annotations across your entire dataset.

Removing a Label

Go to Edit → Remove Label. This removes all annotations with that label from every image in your dataset. Use with caution.

Label Colors

Each label has its own color for visual clarity. Colors are automatically assigned and saved alongside your annotations folder in a label_colors.json file.

7. Navigating Images

• Click any image in the left panel to switch to it
• Press → or the Next > button to go to the next image
• Press ← or the < Prev button to go to the previous image
• Arrow key navigation only works when no annotation is selected. If an annotation is selected, arrow keys nudge it instead

8. Zoom & Pan

• Mouse wheel — zoom in/out centered on cursor
• + / − buttons — zoom in/out centered on selection or image center
• fit button — reset zoom to fit the image in the window
• Right-click + drag — pan the canvas
• Hold Space + drag — pan the canvas
• 🔒 Lock button — when enabled, automatically zooms to annotated regions when switching between images

9. Undo & Redo

PixelTagger tracks up to 10 undo steps per image session.

• Ctrl+Z — undo last change
• Ctrl+Y — redo
• Also accessible via Edit → Undo / Redo in the menu bar

The undo history resets when you switch to a different image.

10. Exporting Annotations

Note: Split Dataset into Train/Test has been moved to the Edit menu.

All export options are under the Export / Import menu.

• YOLO .txt — One text file per image with normalized coordinates. Also exports a classes.txt file
• COCO JSON — Single JSON file for the entire dataset. Compatible with Detectron2, MMDetection, and other frameworks
• DOTA .txt — Oriented bounding box format for aerial image datasets
• CSV — One row per annotation with filename, dimensions, class, and coordinates
• Train/Test Split — Moved to the Edit menu. Randomly splits images and annotations into Train and Test subfolders at a configurable ratio
• Classes File — Exports just the label names as a plain text file
• Collage — Generates a visual grid of annotated crops for dataset review

Annotations are always stored internally in Pascal VOC XML format, regardless of which export format you choose.

11. Importing Annotations

PixelTagger can import annotations from external tools. Imported annotations are converted to VOC XML and saved automatically.

• Import YOLO — Select folder containing .txt label files and a classes.txt
• Import COCO JSON — Select a COCO-format JSON file
• Import DOTA — Select folder containing DOTA .txt files
• Import CSV — Select a CSV file with the standard PixelTagger column format

12. Video Frame Extraction

PixelTagger includes a built-in video frame picker powered by FFmpeg.

1. Go to Edit → Extract Video Frames
2. Select a video file (MP4, AVI, MOV, MKV, WebM supported)
3. Use the ← → buttons or the slider to navigate frames
4. Hold Shift+←→ to jump by 1 second
5. Click Add to Dataset to save the current frame as a PNG into your images folder

14. Train/Test Dataset Split

Found at Edit → Split Dataset into Train/Test subsets...

Randomly shuffles your entire dataset and splits it into Train and Test subfolders at a configurable ratio.

1. Open Edit → Split Dataset into Train/Test subsets...
2. Set the Train % — the Test % updates automatically to always sum to 100
3. Click Split Dataset and choose an output folder
4. PixelTagger copies images and their annotation files into Train/ and Test/ subfolders

The shuffle uses a Fisher-Yates algorithm for an unbiased random distribution. Original files are not modified.

14. AI Video Frame Extraction

Found at Edit → Split Dataset into Train/Test subsets... — Opens a dialog where you set the Train % and Test % ratio. PixelTagger randomly shuffles your dataset and copies images and annotations into Train/ and Test/ subfolders in your chosen output directory.

14. Train/Test Dataset Split

Found at Edit → Split Dataset into Train/Test subsets...

Randomly shuffles your entire dataset and splits it into Train and Test subfolders at a configurable ratio.

1. Open Edit → Split Dataset into Train/Test subsets...
2. Set the Train % — the Test % updates automatically to always sum to 100
3. Click Split Dataset and choose an output folder
4. PixelTagger copies images and their annotation files into Train/ and Test/ subfolders

The shuffle uses a Fisher-Yates algorithm for an unbiased random distribution. Original files are not modified.

Found at Edit → AI Video Frame Extraction (YOLO)... This feature uses a YOLO model to automatically extract frames from a video based on what objects appear in them.

Configuration

Options

• Frame Skip — process every Nth frame to speed up extraction on long videos
• Save Annotation XML Files — save PASCAL VOC XML annotation files alongside each extracted frame
• Save frames where labels are NOT detected (inverse mode) — save frames where none of the listed labels appear; useful for collecting negative/background samples

Frame Filenames

Saved frames have unique timestamped filenames: frame_004300_143052123456.jpg (frame number + time-of-day to microseconds), ensuring no collisions across multiple runs.

Log Colors

• Red — frame saved (SAVED)
• Gray — detection found but not saved (DETECTED)
• Blue — status info

Click Install AI Dependencies to set up the Python environment before first use. See AI Dependencies & GPU Setup for details.

15. Annotate Video with YOLO

Found at Edit → Annotate Video with YOLO... Runs YOLO inference on every frame of a video and writes a new output video with all detections rendered directly on the frames.

Configuration

What gets drawn on the video

• Bounding boxes with class label and confidence score
• Keypoints with skeleton connections
• Segmentation masks for segmentation models
• Rotated bounding boxes for OBB models

Every frame is processed and written to the output video. The file size stays at 0 KB while processing (normal behavior) and jumps to full size when complete.

16. Managing Labels

Open via Edit → Manage Labels.

• Drag rows to reorder labels — order determines their position in the label dropdown
• Double-click a name to rename it inline
• Click the color swatch to change a label's color
• Click X to delete a label
• Delete All removes all labels (with confirmation)

Import / Export Labels

From Export/Import menu:

• Export Classes/Labels text file — saves one label name per line (compatible with YOLO classes.txt)
• Import Classes/Labels text file — adds labels from a text file; duplicates are skipped

17. AI Dependencies & GPU Setup

Both AI features (AI Video Frame Extraction and Annotate Video with YOLO) share the same Python environment and only need to be set up once.

First-time Setup

1. Open either AI dialog from the Edit menu
2. Click Install AI Dependencies
3. Wait 5–20 minutes for PyTorch, yolov12, and opencv to download and install
4. On subsequent clicks it detects the environment is already set up and completes instantly

Dedicated Virtual Environment

PixelTagger creates an isolated Python environment so AI packages never conflict with other software:

When you click Run Inference, PixelTagger automatically uses this environment — no manual management needed.

YOLO Model Compatibility

The installed environment supports YOLOv10, v11, and v12 models (.pt files only).

GPU Acceleration

PixelTagger automatically detects and uses GPU acceleration:

The inference log always shows which device is active: Running on GPU: [name] or Running on CPU.

13. Keyboard Shortcuts