User Manual

This guide provides comprehensive instructions for using X-AnyLabeling, covering everything from basic file management and annotation tasks to advanced features and customization.

0. Table of Contents

• 1. File Management
  • 1.1 Importing Data
  • 1.2 Deleting Data
  • 1.3 Switching Images
  • 1.4 Saving Label Data
  • 1.5 Embedding Image Data
• 2. Editing
  • 2.1 Creating Shapes
  • 2.2 Editing Shapes
  • 2.3 Editing Labels
  • 2.4 Adding Image Captions
  • 2.5 Searching Images
• 3. View Options
  • 3.1 Canvas Controls
  • 3.2 Image Display
  • 3.3 Shape Display
  • 3.4 Crosshair Customization
  • 3.5 Navigator
  • 3.6 Compare View
• 4. Annotation Formats (Import/Export)
  • 4.1 YOLO Format
  • 4.2 VOC Format
  • 4.3 COCO Format
  • 4.4 DOTA Format
  • 4.5 Mask Format
  • 4.6 MOT Format
  • 4.7 PPOCR Format
  • 4.8 ODVG Format
  • 4.9 VLM-R1-OVD Format
  • 4.10 MMGD Format
• 5. Toolbar Tools
  • 5.1 Data Statistics (Overview)
  • 5.2 Save Cropped Images
  • 5.3 Label Manager
  • 5.4 Shape Type Conversion
  • 5.5 Digit Shortcut Manager
  • 5.6 Group ID Manager
  • 5.7 Shape Manager
• 6. Help and Language
  • 6.1 About X-AnyLabeling
  • 6.2 Setting the Language
• 7. Configuration
  • 7.1 Keyboard Shortcuts
  • 7.2 Custom Label Colors
  • 7.3 Predefined Labels
  • 7.4 Auto-Switch to Edit Mode
  • 7.5 Hover Auto-Highlight
  • 7.6 Shape Appearance
  • 7.7 Model Download Source
  • 7.8 Theme Settings
• 8. Supported Tasks
  • 8.1 Image Classification
  • 8.2 Object Detection
  • 8.3 Image Segmentation
  • 8.4 Pose Estimation
  • 8.5 Face Estimation
  • 8.6 Multi-Object Tracking
  • 8.7 Depth Estimation
  • 8.8 Optical Character Recognition (OCR)
  • 8.9 Interactive Video Object Segmentation (IVOS)
  • 8.10 Matting
  • 8.11 Vision-Language Tasks
  • 8.12 Zero-Shot Counting
  • 8.13 Grounding
• 9. Custom Models
• 10. Advanced Features

1. File Management

This section explains how to import, manage, and save data in X-AnyLabeling. You can import images and videos using various methods, including menu options and keyboard shortcuts. It also covers deleting data, switching between images, and saving labels, helping you maintain an efficient workflow and manage your data securely.

1.1 Importing Data

After opening the application, select the type of data you want to import from the File menu or use the keyboard shortcuts:

X-AnyLabeling supports importing data in the following ways:

• Image File Directory (Ctrl+U): Import all image files within a selected directory, including those nested in subdirectories.
• Single Image File (Ctrl+I): Import an individual image file (formats: *.jpg, *.png, *.bmp, *.webp, *.tif).
• Single Video File (Ctrl+O): Import an individual video file (formats: *.mp4, *.avi, *.mov, *.mkv, *.wmv, *.flv). Video frames will be extracted for annotation.

1.2 Deleting Data

X-AnyLabeling offers the following options for deleting data:

• Delete Label File (Ctrl+Delete): Deletes the annotation file (.json) associated with the currently displayed image. Warning: This action cannot be undone.
• Delete Image File (Ctrl+Shift+Delete): Moves the currently displayed image file and its corresponding label file (if any) to a _delete_ subfolder within the image directory.

1.3 Switching Images

Navigate between images in your dataset using these methods:

• Next/Previous Image: Use the D key (next) or A key (previous) to move sequentially through the image list.
• Jump by Annotation Check Status:
  • Ctrl+Shift+D: Jump to the next unchecked annotation.
  • Ctrl+Shift+A: Jump to the previous unchecked annotation.
• Toggle Annotation Check Status: Right-click the canvas and choose Mark as Checked or Mark as Unchecked, or press Ctrl+Alt+K. The file list shows this review state with a colored dot: green means checked, gray means unchecked.
• Jump to Specific Image: Type the exact filename (including extension) into the file search bar at the bottom right and press Enter.

The checkboxes in the file list are not editable by default. To enable editing, open Settings (Ctrl+0) and enable File List Checkbox Editable under General, or set file_list_checkbox_editable to true in the configuration file. These checkboxes indicate whether a label file exists and are separate from the annotation check status dot.

1.4 Saving Label Data

X-AnyLabeling enables auto-save by default. You can verify or toggle this setting via File > Auto Save.

Label files are saved in *.json format in the same directory as the images by default. The structure is:

{
  "version": "${version}", // X-AnyLabeling version
  "flags": {},             // Image-level flags (if any)
  "shapes": [              // List of annotated shapes
    {
      "label": "${label}",        // Category label
      "score": null,            // Confidence score (e.g., from model), null if N/A
      "points": [...],          // List of [x, y] coordinates defining the shape
      "group_id": null,         // ID for grouping related shapes (e.g., pose keypoints)
      "description": null,      // Optional text description for the shape
      "difficult": false,       // Flag if the object is difficult to identify
      "shape_type": "${shape_type}", // e.g., "rectangle", "polygon"
      "flags": null,            // Shape-level flags (if any)
      "attributes": {}          // Dictionary of custom attributes
    }
    // ... more shapes
  ],
  "description": null,      // Optional text description for the image
  "checked": false,         // Annotation review status
  "chat_history": [         // Chat history (for chatbot)
    {
      "role": "user",
      "content": "Hi",
      "image": null
    },
    {
      "role": "assistant",
      "content": "Hi there! How can I help you today?",
      "image": null
    }
    // ... more dialogs
  ],
  "vqaData": {
    "question": "What animals are shown in the image?",
    "answer": "zebras",
    "split": "train",
    "task": "QA",
    "tags": [
      "natural"
    ],
    // ... more items
  },
  "imagePath": "${filename}", // Relative path to the image file
  "imageData": null,         // Base64 encoded image data (if enabled, see 1.5)
  "imageHeight": -1,         // Image height in pixels
  "imageWidth": -1           // Image width in pixels
}

⚠️ To save labels to a different location: Select File > Change Output Directory and choose your preferred path. The relative imagePath in the JSON will be adjusted accordingly.

1.5 Embedding Image Data

To embed the image data (encoded in base64 by default) directly into the .json label file, enable the Save Image Data option under the File menu. This increases the JSON file size but makes it self-contained.

2. Editing

This section explains how to create, edit, and manage different types of annotation objects (shapes) and their associated labels in X-AnyLabeling.

2.1 Creating Shapes

In X-AnyLabeling, each distinct annotated object is called a shape. Key properties stored for each shape include:

For detailed field definitions, see shape.py.

X-AnyLabeling supports creating the following types of shapes:

• Rectangle (R): Click and drag to define opposite corners, or click once for the first corner and again for the second.
• Rotated Rectangle (O): Click once to set the first corner, move the cursor, and click again to create an axis-aligned box first. To rotate it, select the shape in Editing Mode and press Z, X, C, or V.
• Polygon (P): Click along the object's boundary to place vertices. Click the starting point or double-click the last point to close the polygon. Requires at least 3 points. A brush mode (Ctrl+N) is also available: once activated, click to place the first point, then move the mouse to automatically trace polygon vertices along the cursor path. Move near the starting point to auto-close. The point distance can be adjusted via Settings > Canvas > brush.point_distance.
• Quadrilateral (T): Click to place the first corner, then click the remaining three corners in order to complete the quadrilateral.
• Point: Click to place a point.
• Line: Click to set the start point, move the cursor, and click again to set the end point. Hold Shift while drawing to snap the segment horizontally or vertically.
• Line Strip: Click to place the first point, then click to add subsequent points for connected line segments. Hold Shift while drawing each segment to snap it horizontally or vertically. Double-click to finish.
• Circle: Click to set the center, move the cursor to define the radius, and click again.
• Cuboid (Ctrl+R): Draw the front face as a rectangle (same gesture as rectangle creation). The rear face is auto-generated using canvas.cuboid.default_depth_vector (adjustable in Settings > Canvas > Cuboid); if depth is too small, it is normalized to satisfy canvas.cuboid.min_depth.

You can create shapes using the tools in the left toolbar, the right-click context menu, or keyboard shortcuts.

2.2 Editing Shapes

X-AnyLabeling provides two shape interaction modes:

• Drawing Mode allows rapid creation of new shapes.
• Editing Mode enables editing operations such as switching modes (Ctrl+E), undo (Ctrl+Z), copy (Ctrl+C), paste (Ctrl+V), delete (Delete), move, resize, and rotate.

Press Ctrl+J to quickly switch between Drawing and Editing modes. Additional object-specific operations:

To protect completed annotations, select one or more shapes and check Lock Shape in the canvas right-click menu. You can also right-click selected items in the Shapes panel to invert each item's lock state; locked items display a lock icon. Locked shapes remain selectable and allow label and attribute edits, while geometry changes and deletion are disabled.

When Show Groups is enabled, each group displays an interactive bounding frame and a compact badge such as G3 · S5 (group 3 with 5 shapes). Clicking a shape still selects that shape first. Click the badge, frame, or empty area inside the frame to select the whole group, then drag it or use the arrow keys to move all members together (Shift accelerates keyboard movement). Copying and pasting a selected group assigns the pasted group the next available group ID and offsets it slightly. Deleting a selected group requires confirmation.

• Rectangles: You can drag a rectangle's corner handles to resize it, or select multiple rectangles and merge them using the right-click menu. Mouse wheel editing is also supported; you can enable it in Settings > Canvas > Wheel Editing > Enable Wheel Rectangle Editing, or via the wheel_rectangle_editing setting. When enabled, scrolling inside the rectangle scales it, while scrolling outside adjusts the nearest edge. Note: wheel rectangle editing is automatically disabled when auto_highlight_shape is enabled.
• Polygons: In Editing Mode, dragging an edge adds a new vertex, and holding Shift while clicking a vertex removes it. When exactly one polygon or line strip is selected, you can hold Alt to enter eraser mode, then drag with the left mouse button across vertices to remove them and reconnect the remaining points. If a polygon has fewer than 3 points, or a line strip has fewer than 2 points, the object is removed and can be restored with undo. Polygons also support merging via the right-click menu. When exactly one polygon is selected, you can also activate Edit Brush from the toolbar, context menu, or with Shift+B: drag with the left mouse button to expand the region, hold Ctrl while dragging to erase, and use the mouse wheel to resize the brush. Stroke-level undo and redo are supported, and the target remains locked while editing. Right-click or turn off Edit Brush to commit; press Esc, switch images, or select another tool to discard the changes and restore the original polygon. Brush point spacing and contour simplification tolerance are available under Settings > Canvas > Interaction > Brush; set the simplification tolerance to 0 to preserve the extracted contour points.
• Rotated Rectangles: Select a rotated rectangle, drag the rotation handle above it for quick coarse angle adjustment, then press Z, X, C, or V for fine-grained rotation control. A real-time display of the rotation angle is available via the View menu.
• Cuboid: In Edit Mode, cuboid controls include 11 visible handles: 4 front vertices, 4 front edge centers, 2 visible rear vertices, and 1 visible rear edge center (depth handle). Dragging the front face moves the whole cuboid. Dragging the left/right/back faces adjusts geometry. Dragging rear visible vertices adjusts vertical alignment of top/bottom planes, while dragging the rear center adjusts depth with geometric constraints. The visible rear side is determined automatically from the depth vector direction.

Additionally, you can quickly copy the coordinates of any selected shape to your clipboard using the Copy Coordinates option from the right-click context menu. For rectangles, this outputs the format [x1, y1, x2, y2] (top-left and bottom-right corners), while other shape types output [x1, y1, x2, y2, x3, y3, ...] (all vertex coordinates). In Editing Mode, double-clicking a shape on the canvas opens the label editor; you can disable this in Settings > Canvas > Interaction > Double Click Edit Label, or via the double_click_edit_label canvas setting (default: true).

When drawing a shape on a zoomed canvas with scrollbars, hold Space and drag with the left mouse button to temporarily pan the canvas without leaving Drawing Mode.

2.3 Editing Labels

When you create a shape or select an existing one in Edit Mode, the label panel appears (usually on the right), allowing you to edit its properties:

2.4 Adding Image Captions

X-AnyLabeling allows you to add a description or caption to the entire image:

1. Enter Edit Mode (Ctrl+E).
2. Click on an empty area of the canvas (not on a shape).
3. Enter your text in the Description field in the right panel. This is saved in the flags field of the main JSON structure.

2.5 Searching Images

The file search feature supports multiple search modes to help you quickly locate target images. Enter your search criteria in the search box above the file list on the right panel and press Enter to execute the search.

You can also right-click an image in the file list to open a context menu for quick copy operations:

• Copy File Name: Copies only the selected image filename, such as image001.jpg.
• Copy File Path: Copies the full selected image path to the clipboard.

The following search modes are currently supported:

Text Search

Enter plain text directly, and the system will search for files whose names contain that text. For example, entering test will find all images with "test" in their filename.

Index Search

Use the #N format to target an image by index, where N must be a positive integer. Examples:

• #1 targets the 1st image in the current file list
• #10 targets the 10th image in the current file list

Regular Expression Search

Use the <pattern> format for regular expression searches. Examples:

• <\.png$> searches for all PNG format images
• <test.*\.jpg$> searches for images whose filenames start with "test" and end with ".jpg"

Attribute Search

Filter images by object attributes using the format attribute::value:

• difficult::1 or difficult::true: Find images containing difficult annotations
• gid::0: Find images containing objects with group ID 0 (supports any integer group ID)
• shape::1 or shape::true: Find annotated images (containing at least one annotation object)
• label::person: Find images containing objects labeled "person"
• type::rectangle: Find images containing rectangle objects. Supported types include: rectangle, polygon, rotation, quadrilateral, point, line, circle, linestrip
• score::[0,0.5]: Find images containing objects with scores in the range [0, 0.5] (closed interval)
• score::(0,0.6]: Find images containing objects with scores in the range (0, 0.6] (left-open, right-closed)
• score::[0,0.6): Find images containing objects with scores in the range [0, 0.6) (left-closed, right-open)
• score::(0,0.6): Find images containing objects with scores in the range (0, 0.6) (open interval)
• description::1 or description::true: Find images containing objects with non-empty descriptions
• checked::1 or checked::true: Find checked images
• checked::0 or checked::false: Find unchecked images; images without generated label files are also treated as unchecked

3. View Options

This section explains how to customize the view settings in X-AnyLabeling, including adjusting the canvas, image appearance, and how shape information is displayed, to optimize your workflow.

3.1 Canvas Controls

• Zoom In (Ctrl + +)
• Zoom Out (Ctrl + -)
• Zoom to Actual Size (100%) (Ctrl + =)
• Zoom to Fit Window (Ctrl + F)
• Zoom to Fit Width (Ctrl + Shift + F)

In addition to using menu options and shortcuts, you can zoom dynamically by holding Ctrl and using the mouse scroll wheel. This is useful for precise annotations, especially on small objects.

To maintain the current zoom level when switching between images, enable View > Keep Previous Zoom Ratio.

3.2 Image Display

X-AnyLabeling allows you to adjust the appearance of the current image and the visibility of annotations:

• Select View > Brightness Contrast to open the adjustment controls.
• To apply the current adjustments to all subsequent images in the session, enable View > Keep Current Brightness and View > Keep Current Contrast.

Use the collapsible Canvas Display panel at the bottom-left of the canvas to quickly adjust annotation opacity and image brightness or contrast. Opacity affects annotation shapes and masks while keeping label text fully visible; Brightness and Contrast adjust the underlying image. Click the caret button to collapse or expand the panel.

The status bar at the bottom displays the current filename, annotation progress (e.g., "Image 5/100"), and cursor coordinates.

3.3 Shape Display

You can control the visibility of various shape attributes:

• Toggle display of label names next to shapes (Ctrl+L or View > Show Labels).
• Toggle display of shape descriptions (Ctrl+T or View > Show Text).
• Toggle display of other info like Group IDs, rotation angles, scores (check View menu for options).

When you hover over a shape, its dimensions (width and height) are displayed in the status bar.

3.4 Crosshair Customization

You can customize the appearance (width, transparency, color) of the crosshair cursor via View > Set Crosshair. The status bar shows the cursor's real-time pixel coordinates.

3.5 Navigator

The navigator helps you quickly navigate to any area of high-resolution images.

To open the navigator, simply click View -> Navigator in the menu bar or press the shortcut key F9. The navigator displays a thumbnail of the current image in a separate window, with a red frame indicating your current visible area.

You can click anywhere on the thumbnail to quickly jump to that location, or drag the red frame to move your view. The navigator also displays all your annotated objects in real-time, giving you a clear overview of your progress.

At the bottom of the navigator, you can precisely set the zoom ratio through the input box (supporting 1% to 1000%), or drag the slider to adjust it. Additionally, you can use the mouse wheel to zoom directly in either the main canvas or the navigator window.

This feature is particularly useful when working with ultra-high resolution images, allowing you to maintain precise local operations while keeping the global perspective.

3.6 Compare View

X-AnyLabeling provides a Compare View feature that allows you to compare two images side-by-side using a split-screen interface. This is particularly useful for:

• Infrared + Visible Light: Comparing thermal and RGB images to identify targets that are clearer in different spectrums.
• Mask Preview: Viewing segmentation results overlaid on the original image in real-time.
• Super-Resolution: Comparing enhanced images with their original versions.

How to Use:

1. Open an image directory and load an image.
2. Click File > Compare View (or press Ctrl+Alt+C) to open the compare directory selector.
3. Select a directory containing comparison images with matching filenames (same base name, can have different extensions).
4. Use the slider at the bottom to adjust the split position, or hold Shift and scroll the mouse wheel to move the divider.
5. Click the close button (×) on the slider to exit Compare View.

Note: The comparison image must have the same dimensions as the original image. If the sizes do not match, a warning will be displayed in the status bar.

4. Annotation Formats (Import/Export)

X-AnyLabeling supports importing and exporting annotations in various standard formats. This section provides a guide for each. Access import/export functions via the File menu or dedicated toolbar buttons (e.g., Import Annotations, Export Annotations).

General Notes:

• Configuration Files: Many formats require specific configuration files (e.g., listing class names) for import/export. Ensure these are prepared correctly.
• Default Export Path: By default, exported files are saved to a format-specific subfolder (e.g., labels, Annotations, mask) within the current image directory. You can usually specify a different output path during export.

4.1 YOLO Format

Supports YOLO format (*.txt) labels for object detection, instance segmentation, rotated bounding boxes, and keypoint detection.

Configuration:

• Detection/Segmentation/Rotation: Prepare a classes.txt file listing class names, one per line (0-indexed). See example: classes.txt.
• Keypoint Detection (Pose): Prepare a *.yaml file defining the skeleton and class names. See example: yolov8_pose.yaml. Refer to the Ultralytics Docs for format details (e.g., kpt_shape, flip_idx).

Note: For YOLO-Pose export, you must assign the same group_id to each bounding box and its corresponding keypoints during annotation so they are correctly associated.

Importing:

1. Click the Import button in the top menu bar.
2. Select the corresponding task.
3. Upload the prepared configuration file.
4. Select the directory containing the label files.
5. Optionally check "Preserve Existing Annotations" to merge new annotations with existing ones.
6. Click OK to confirm.

Exporting:

1. Select Export Annotations > Export YOLO Annotations.
2. Select the corresponding task.
3. Provide the required configuration file.
4. Configure options (e.g., coordinate format) if prompted and click OK.
5. Export path defaults to a labels subfolder. Sample: demo.txt.

4.2 VOC Format

Supports Pascal VOC format (*.xml) labels for object detection (bounding boxes) and segmentation (polygons saved within the XML, if applicable).

Configuration: None usually required for standard VOC detection import/export. For segmentation, ensure labels match your desired classes.

Importing:

1. Select Import Annotations > Import VOC Annotations.
2. Select the directory containing the *.xml files (usually named Annotations).

Exporting:

1. Select Export Annotations > Export VOC Annotations.
2. Configure options if prompted and click OK.
3. Export path defaults to an Annotations subfolder. Sample: demo.xml.

4.3 COCO Format

Supports COCO format (*.json) labels for object detection, instance segmentation, and keypoint detection.

Configuration:

• Detection (rectangle) / Segmentation (polygon): Prepare a classes.txt file. For export, ensure _background_ is the first class if required by your training framework. __ignore__ can also be included.
• Keypoint Detection (pose): Prepare a *.yaml file similar to YOLO Pose (e.g., yolov8_pose.yaml).
• Instance Segmentation (polygon): Prepare a labels.txt file.

Importing:

1. Select Import Annotations > Import COCO Annotations.
2. Select the task type.
3. Provide the required configuration file (classes.txt or *.yaml).
4. Select the COCO *.json annotation file.

Exporting:

1. Select Export Annotations > Export COCO Annotations.
2. Select the task type.
3. Provide the required configuration file.
4. Click OK.
5. Export path defaults to an annotations subfolder, saving a single *.json file. Sample: annotations.

4.4 DOTA Format

Supports DOTA format (*.txt) labels for oriented (rotated) object detection. Label format per line: x1 y1 x2 y2 x3 y3 x4 y4 class_name difficult

Configuration: None required for import/export, class names are read/written directly.

Importing:

1. Select Import Annotations > Import DOTA Annotations.
2. Select the directory containing the *.txt label files (usually labelTxt).

Exporting:

1. Select Export Annotations > Export DOTA Annotations.
2. Click OK.
3. Export path defaults to a labelTxt subfolder. Sample: demo_obb.txt.

4.5 Mask Format

Supports importing and exporting semantic segmentation masks as single-channel or color image files (*.png).

Configuration: Prepare a *.json mapping file defining the pixel value (or RGB color) for each class name.

• Color masks: See mask_color_map.json.
• Grayscale masks: See mask_grayscale_map.json.

Importing:

1. Select Import Annotations > Import MASK Annotations.
2. Provide the *.json mapping file.
3. Select the directory containing the mask image files (*.png).

Exporting:

1. Select Export Annotations > Export MASK Annotations.
2. Provide the *.json mapping file.
3. Click OK.
4. Export path defaults to a mask subfolder.

4.6 MOT Format

Supports importing and exporting Multi-Object Tracking (MOT) challenge format labels.

Configuration: Prepare a classes.txt file listing class names (0-indexed).

Importing (gt.txt):

1. Select Import Annotations > Import MOT Annotations.
2. Provide the classes.txt configuration file.
3. Select the directory containing the gt.txt file (and potentially seqinfo.ini).

Exporting (creates gt.txt, det.txt, seqinfo.ini):

1. Select Export Annotations > Export MOT Annotations.
2. Provide the classes.txt configuration file.
3. Choose the output directory and click OK.

Sample files (seqinfo.ini, det.txt, gt.txt) are available in the MOT directory.

File Formats:

• seqinfo.ini: Sequence metadata (name, frame rate, dimensions, etc.).
• det.txt: Detection results (used by some trackers, format: frame,id,bb_left,bb_top,bb_width,bb_height,conf,-1,-1,-1). Exported detections might have default confidence/ID.
• gt.txt: Ground truth tracking annotations (format: frame,id,bb_left,bb_top,bb_width,bb_height,valid,class_id,visibility).
  • id: Corresponds to the group_id assigned in X-AnyLabeling.
  • valid: 1 for valid, 0 for invalid/ignored. This corresponds to the 'Difficult' checkbox in the label editing panel; checking 'Difficult' marks the trajectory as invalid (0).
  • class_id: 0-indexed based on your classes.txt.

MOTS (Segmentation Tracking) Export: X-AnyLabeling supports exporting polygon annotations in a MOTS-compatible format through the CLI.

# Requires pycocotools: pip install pycocotools
xanylabeling convert --task xlabel2mots --labels /path/to/xlabel/labels --output /path/to/output --classes classes.txt

4.7 PPOCR Format

Supports importing and exporting labels for PaddleOCR (PPOCR) tasks.

Tasks Supported:

• Text Detection and Recognition: Locates text boxes and recognizes content.
• Key Information Extraction (KIE): Extracts entities and relations from text regions.

Importing:

1. Select Import Annotations > Import PPOCR Annotations.
2. Select the task (Recognition or KIE).
3. Choose the appropriate label file (Label.txt for Rec, kie.json for KIE).

Exporting:

1. Select Export Annotations > Export PPOCR Annotations.
2. Select the task.
3. Click OK.

Export Paths & Files:

• Recognition: Defaults to ppocr-rec subfolder. Contains:
  • Label.txt: Detection & transcription annotations.
  • rec_gt.txt: Recognition ground truth (transcriptions only).
  • crop_img/: Cropped images of text regions for recognition training.
• KIE: Defaults to ppocr-kie subfolder. Contains:
  • class_list.txt: List of KIE entity classes.
  • ppocr_kie.json: KIE annotation results (linking text regions).

Samples: ppocr-rec, ppocr-kie.

4.8 ODVG Format

Supports importing/exporting ODVG format annotations for visual grounding tasks.

Configuration: Prepare a classes.txt file listing category names.

Importing:

1. Select Import Annotations > Import ODVG Annotations.
2. Select the directory containing the ODVG label files.

Exporting:

1. Select Export Annotations > Export ODVG Annotations.
2. Provide the classes.txt configuration file.
3. Choose the save path and click OK.

Sample: ODVG.

4.9 VLM-R1-OVD Format

Supports importing/exporting VLM-R1-OVD format (.jsonl) labels, often used for Open-Vocabulary Detection tasks.

Configuration (Export):

• classes.txt (Optional): Provide a classes.txt file to export only annotations matching those specific categories/phrases. If omitted, all unique labels found in the images are used as prompts for export.

Importing:

1. Select Import Annotations > Import VLM-R1-OVD Annotations.
2. Choose the .jsonl annotation file.

Exporting:

1. Select Export Annotations > Export VLM-R1-OVD Annotations.
2. (Optional) Provide the classes.txt file if filtering categories.
3. Fill in other configuration items if prompted and click OK.
4. Images without any labels (or matching labels if classes.txt is used) are automatically skipped during export. Sample: vlm_r1_ovd.jsonl.

4.10 MMGD Format

X-AnyLabeling supports one-click import of annotation files generated by MM-Grounding-DINO predictions.

Importing:

1. Click the Import button in the top menu bar.
2. Select the corresponding task type.
3. Upload the category file.
4. Select the directory containing the annotation files, choose the categories of interest, set the confidence threshold according to your needs, and click OK.

The classes.txt file is used for mapping label indices to category names. Each line represents a category, with indices assigned sequentially starting from 0 (top to bottom).

5. Toolbar Tools

The toolbar (usually at the top or integrated with the menu) provides access to additional tools and functionalities.

5.1 Data Statistics (Overview)

X-AnyLabeling provides a data statistics tool (Tools > Overview) for reviewing your annotation progress.

Features:

• Flexible Scope: Analyze all images or select a specific range using sliders or input fields. Statistics update in real-time.
• Detailed Breakdown: View counts per label category and per shape type (rectangle, polygon, etc.). Get an overall dataset summary.
• Export Reports: Generate a zip archive containing detailed CSV files (label_infos.csv, shape_infos.csv) and the class list (classes.txt).

Usage:

1. Go to Tools > Overview.
2. Review the statistics displayed in the window.
3. (Optional) Select a specific image range to analyze.
4. Click Export to save the detailed reports as a zip file.

5.2 Save Cropped Images

The cropped image saving function can be implemented through the following steps:

1. Click Tools > Save Cropped Images in the top menu bar.
2. In the popup dialog, configure:
   • Save Path: Choose the target folder for saving cropped images
   • Min Width: Set minimum width in pixels for filtering
   • Min Height: Set minimum height in pixels for filtering
3. After clicking OK, the system will automatically export all annotated objects sorted by category name to the specified path.

You can also use Tools > Save Visualization Image or Save Visualization Video to export the current annotation visualization as an image or video file.

5.3 Label Manager

X-AnyLabeling provides tools for managing labels globally across your dataset via Tools > Label Manager.

Operations:

• Delete Labels: Remove specific label classes entirely from the list of available labels.
• Rename Labels: Change the name of existing label classes. This updates the label list but does not automatically update existing annotations using the old name.
• Control Label Visibility: Use the Visible column checkboxes to show or hide specific labels on the canvas.
• Change Label Colors: Modify the display color for specific label classes for the current session only. (For persistent changes, see 7.2 Custom Label Colors).

Visibility Quick Actions:

• Right-click on the Visible column to quickly:
  • Select All: Show all labels at once
  • Deselect All: Hide all labels at once
• Visibility settings persist across image switches and take effect after clicking the Go button.

5.4 Shape Type Conversion

X-AnyLabeling provides a unified Shape Converter. Open it from Tools -> Shape Converter, then select a source shape type and a target shape type to run batch conversion.

Currently supported conversion mappings:

• polygon -> rectangle, rotation
• rectangle -> rotation, polygon, circle, quadrilateral
• rotation -> rectangle, quadrilateral, polygon, circle
• line -> linestrip
• circle -> rectangle, rotation, quadrilateral, polygon
• quadrilateral -> polygon

Rules:

• Conversions to circle use an inscribed-circle strategy.
• polygon/rotation -> rectangle uses an axis-aligned bounding box (AABB).
• circle -> rectangle/rotation/quadrilateral generates a four-point shape from circle center and radius.

Note: Some conversions are lossy (e.g., rotation angle, exact boundaries, curve details) and are irreversible. Back up annotations before large batch conversions.

5.5 Digit Shortcut Manager

The Digit Shortcut Manager is a practical feature provided by X-AnyLabeling that allows users to configure numeric keys (0-9) for quick shape creation, significantly improving labeling efficiency.

By pre-setting the drawing mode and label name corresponding to each numeric key, users can quickly create desired annotation shapes with a single keystroke during the labeling process.

To open the Digit Shortcut Manager, select Tools in the top menu bar of the main interface, then click on the Digit Shortcut Manager option, or simply use the shortcut key Alt+D.

In the Digit Shortcut Manager dialog, users can see a table containing all numeric keys (0-9), with each row including the following information:

• Digit: Represents the numeric key (0-9) on the keyboard
• Drawing Mode: Choose the type of shape to draw from the dropdown menu, including rectangle, cuboid, polygon, rotation, quadrilateral, circle, line, point, linestrip, or none
• Label: Specify the default label name for the shape (required)

Configuring Shortcuts: Select the drawing mode corresponding to the digit, enter the default label name for that shape (required when a drawing mode is enabled), then click OK to save the settings.

Resetting Shortcuts: Click the Reset button to clear all shortcut settings. The system will display a confirmation dialog, and all configurations will be cleared after confirmation.

Using Shortcuts: In the labeling interface, simply press the configured numeric key (0-9). The system will automatically switch to the corresponding drawing mode with the preset label name. After drawing is complete, the annotation will automatically use the preset label name.

Offline Configuration: In addition to configuration through the GUI interface, users can directly configure shortcuts in the .xanylabelingrc configuration file in their user directory. The configuration format is as follows:

digit_shortcuts:
  0: {mode: polygon, label: person}
  1: {mode: rectangle, label: car}
  2: {mode: rotation, label: truck}
  # More configurations...

Digit shortcut settings configured through the GUI interface will be automatically synchronized and saved to the .xanylabelingrc configuration file in the current user directory, and will be automatically loaded the next time the software is started. Similarly, if you directly modify the configuration file, the software will automatically recognize and apply these changes after restart.

By properly configuring numeric shortcuts, you can significantly improve labeling efficiency and reduce repetitive operations, particularly suitable for scenarios that require frequent switching between different annotation types.

5.6 Group ID Manager

The Group ID Manager is a batch management feature for group ID fields, allowing users to uniformly modify and delete group IDs within a specified range. You can access it in two ways:

• Select Tools -> Group ID Manager from the top menu bar in the main interface
• Use the shortcut key Alt+G

5.7 Shape Manager

The Shape Manager handles batch annotation operations for video frame sequences. Access it via Tools -> Shape Manager or press Alt+S.

Four operation modes are available (mutually exclusive):

• Delete All Annotations: Removes all JSON annotation files within the specified frame range while preserving image files. Automatically unchecks the corresponding frames after execution.

• Delete All Images with Annotations: Deletes both images and annotations. Image files are moved to the _delete_ backup directory rather than being permanently deleted. The file list refreshes automatically after completion.

• Remove Selected Shapes: Searches for and removes objects matching the currently selected shape within the frame range. If a frame contains only matching objects, the entire annotation file is deleted; otherwise, only matching objects are removed. At least one shape must be selected on the canvas before use.

• Add Selected Shapes: Batch copies the currently selected shapes to specified frames. The system automatically detects boundaries and skips shapes that exceed the image range, while avoiding duplicate additions of existing identical objects. Annotation files are auto-created for frames without them, and corresponding frames are automatically checked upon completion.

Set the start and end frame numbers: From defaults to the current frame, To defaults to empty and must be manually filled. Frame numbers correspond to the file list index (starting from 1). Clicking Go triggers a confirmation dialog before execution. Remove and add operations support progress display and mid-process cancellation.

![NOTE] Note that delete annotation operations are irreversible, while deleted images can be manually recovered from the backup directory.

6. Help and Language

6.1 About X-AnyLabeling

Select Help > About to view the application version and runtime environment details (e.g., Python version, library versions).

6.2 Setting the Language

Select your preferred interface language (Chinese, English, Japanese, or Korean) from the Language menu.

Important: The application will restart automatically after changing the language. Save your work before switching languages to avoid data loss.

7. Configuration

X-AnyLabeling stores user preferences in a configuration file named .xanylabelingrc, located in your user's home directory:

• Linux/macOS: ~/.xanylabelingrc
• Windows: C:\Users\<YourUsername>\.xanylabelingrc

Most common options can now be changed directly in Settings (Ctrl+0), while the configuration file remains useful for manual editing and advanced customization. Close X-AnyLabeling before editing the file manually and restart it afterwards for changes to take effect.

7.1 Keyboard Shortcuts

The default keyboard shortcuts are listed below. You can customize these in the .xanylabelingrc file if needed (e.g., to resolve conflicts with system shortcuts or match personal preferences). You can also update shortcuts in the GUI: open Settings with Ctrl+0, then edit them in the right-side Shortcuts panel.

7.2 Custom Label Colors

To persistently define custom colors for specific labels:

1. Open the .xanylabelingrc file in a text editor.
2. Ensure the shape_color: field is set to manual. If it's null or auto, change it to manual.
3. Find or add the label_colors: section.
4. Add or modify entries for your labels using the format label_name: [R, G, B], where R, G, B are integer values from 0 to 255.
5. Save the file and restart X-AnyLabeling.

Example configuration:

# ... other settings ...
default_shape_color: [0, 255, 0] # Default color if label not in list (Green)
shape_color: manual           # Use colors defined below ('auto' cycles colors)
shift_auto_shape_color: 0     # Offset for 'auto' color cycling
label_colors:
  person: [220, 20, 60]     # Crimson
  car: [0, 0, 142]          # Navy Blue
  bicycle: [119, 11, 32]    # Maroon
  traffic light: [255, 165, 0] # Orange
  # Add more labels and their RGB colors here
# ... other settings ...

Note: You can temporarily change label colors for the current session via Tools > Label Manager. Changes made there are not saved to the configuration file.

7.3 Predefined Labels

To offer flexibility in label management and meet diverse usage scenarios, X-AnyLabeling supports not only loading labels via startup command-line arguments but also provides two additional convenient methods for loading predefined labels.

Option 1: Set via Config File (Persistent)

Edit the labels field in the config file to define your labels. Note: If a label is a number, wrap it in single quotes ('') to avoid parsing issues. For example:

labels:
- car
- '1'
- '2'
- 苹果
- _phone

Option 2: Upload via Interface (Temporary)

Create a simple .txt file with one label per line:

person
car
bicycle
dog
cat

Then upload it through the menu: Upload → Upload Label Classes File.

🔔 Tips:

• Labels set via the config file are saved permanently and remain after restarting the software — ideal for fixed, long-term label sets.
• Labels uploaded via the interface are temporary and reset after restarting — useful when frequently switching between different label sets.

7.4 Auto-Switch to Edit Mode

To streamline the annotation workflow, you can configure the application to automatically switch to Edit Mode immediately after a shape is created. This is useful if you frequently need to adjust a shape right after drawing it. You can change this in Settings > General > Behavior > Auto Switch To Edit Mode, or through the auto_switch_to_edit_mode setting in the .xanylabelingrc file.

• Set to true to enable automatic switching to Edit Mode.
• Set to false (the default) to remain in Drawing Mode, which allows for the continuous creation of multiple shapes.

7.5 Hover Auto-Highlight

For quicker selection of shapes, you can enable Hover Auto-Highlight. When this feature is active, simply moving your mouse cursor over a shape will highlight it, making it clear which shape will be selected if you click. You can change this in Settings > General > Behavior > Auto Highlight Shape, or through the auto_highlight_shape setting in the .xanylabelingrc file.

• Set to true to highlight shapes on hover.
• Set to false (the default) to only highlight shapes upon clicking them.

Note: When working on multi-label classification tasks with a custom attributes file loaded, this setting is automatically disabled to prevent accidentally changing the active shape while interacting with the attributes panel.

7.6 Shape Appearance

Customize the default appearance of shapes (colors during drawing/selection, point size, line width) in Settings > Shape, or by editing the shape: section in the .xanylabelingrc file:

shape:
  # Default drawing colors (RGBA: Red, Green, Blue, Alpha)
  line_color: [0, 255, 0, 128]       # Outline color (Green, semi-transparent)
  fill_color: [220, 220, 220, 150]  # Fill color (Light Gray, semi-transparent)
  vertex_fill_color: [0, 255, 0, 255] # Vertex color (Green, opaque)

  # Colors when selected/hovered (RGBA)
  select_line_color: [255, 255, 255, 255] # Outline color (White, opaque)
  select_fill_color: [0, 255, 0, 155]    # Fill color (Green, semi-transparent)
  hvertex_fill_color: [255, 255, 255, 255] # Vertex color (White, opaque)

  # Sizes (in pixels)
  point_size: 10 # Diameter of points/vertices
  line_width: 4  # Width of shape outlines

7.7 Model Download Source

X-AnyLabeling downloads pre-trained models used for AI-assisted features (like SAM or detection models). You can configure the download source (Model Hub). The source is determined in the following order of priority:

1. Environment Variable (Highest Priority):

   • Set the XANYLABELING_MODEL_HUB environment variable before launching the application.
   • Example (Linux/macOS): export XANYLABELING_MODEL_HUB=modelscope
   • Example (Windows): set XANYLABELING_MODEL_HUB=modelscope
   • Setting this to modelscope forces downloads from ModelScope (often faster for users in China). Any other value (or if unset) falls back to the next priority level.

2. Configuration File (Medium Priority):

   • Open Settings (Ctrl+0) and change General > Behavior > Model Hub, or edit the model_hub: setting in .xanylabelingrc.
   • Set it to modelscope to use ModelScope, or github (default) to use models hosted on GitHub Releases.
   • This setting is used only if the XANYLABELING_MODEL_HUB environment variable is not set to modelscope.

   # In .xanylabelingrc
   language: en_US # Or zh_CN / ja_JP / ko_KR
   model_hub: github  # Options: github, modelscope
   # ... other settings ...
   

3. Language Setting (Lowest Priority):

   • If neither the environment variable nor the config file is explicitly set to modelscope, the default behavior depends on the language setting in .xanylabelingrc:
     • If language: zh_CN (Chinese), it defaults to modelscope.
     • Otherwise (e.g., language: en_US, language: ja_JP, or language: ko_KR), it defaults to github.

7.8 Theme Settings

X-AnyLabeling supports three theme modes, accessible from the top-level Theme menu:

After selecting an option, a confirmation dialog appears. Click OK to save the setting. The application does not restart automatically; a prompt will remind you to restart for the theme to take effect. Click Cancel to discard the change.

You can also set the theme directly in ~/.xanylabelingrc:

theme: auto  # Options: auto, light, dark

8. Supported Tasks

X-AnyLabeling supports various annotation tasks. Follow the links below for specific guides and examples for each task type:

8.1 Image Classification

• Image-level: Link
• Object-level (Shape Attributes): Link

8.2 Object Detection

• Horizontal Bounding Box (HBB): Link
• Oriented Bounding Box (OBB): Link

8.3 Image Segmentation

• Semantic & Instance Segmentation (Polygons): Link

8.4 Pose Estimation

• Keypoint Detection: Link

8.5 Face Estimation

• Face Detection & Landmarks: Link

8.6 Multi-Object Tracking

• MOT/MOTS: Link

8.7 Depth Estimation

• Depth Annotation: Link

8.8 Optical Character Recognition (OCR)

• Text Detection & Recognition: Link
• Key Information Extraction (KIE): Link

8.9 Interactive Video Object Segmentation (IVOS)

• SAM2-Video: Link
• SAM3-Video: Link

8.10 Matting

• Image Matting (Alpha Masks): Link

8.11 Vision-Language Tasks

• Rex-Omni: Link
• Florence 2: Link

8.12 Zero-Shot Counting

• GeCo Counting by Detection/Segmentation: Link
• GeCo2 Counting by Detection/Segmentation: Link

8.13 Grounding

• YOLOE: Link
• SAM 3: Link
• LocateAnything: Link

9. Custom Models

For details on integrating and using your own custom AI models within X-AnyLabeling for assisted annotation, refer to the Custom Models guide.

10. Advanced Features

• Remote Server Guide: Link
• Chatbot Guide: Link
• VQA Guide: Link
• Image Classifier: Link
• Video Classifier: Link
• Ultralytics Training Platforms: Link
• Document Parsing and Intelligent Text Recognition: Link