Command Line Interface

X-AnyLabeling provides a powerful command-line interface for label format conversion and system management.

Note

Before using these commands, ensure all dependencies are installed. See the Quick Start Guide for details.

0. Table of Contents

1. GUI Launch Options
2. System Commands
3. Label Format Conversion
4. FAQ

1. GUI Launch Options

# Standard launch
xanylabeling

# Open a specific image file
xanylabeling --filename /path/to/image.jpg

# Open an image directory
xanylabeling --filename /path/to/folder

# Set output directory
xanylabeling --output /path/to/output

# Use a custom configuration file
xanylabeling --config /path/to/config.yaml

# Set logging level
xanylabeling --logger-level debug

# Disable automatic update check
xanylabeling --no-auto-update-check

# Raise Qt image allocation limit to 1024 MB
xanylabeling --qt-image-allocation-limit 1024

2. System Commands

2.1 Display Help Information

Input

xanylabeling --help

Output

usage: xanylabeling [-h] [--reset-config] [--logger-level {debug,info,warning,fatal,error}] [--no-auto-update-check] [--qt-platform QT_PLATFORM]
                    [--qt-image-allocation-limit QT_IMAGE_ALLOCATION_LIMIT] [--filename [FILENAME]] [--output OUTPUT]
                    [--config CONFIG] [--nodata] [--autosave] [--nosortlabels] [--flags FLAGS] [--labelflags LABEL_FLAGS] [--labels LABELS] [--validatelabel {exact}] [--keep-prev]
                    {help,checks,version,config,convert} ...

positional arguments:
  {help,checks,version,config,convert}
                        available commands
    help                show help message
    checks              display system and package information
    version             show version information
    config              show config file path
    convert             run conversion tasks

options:
  -h, --help            show this help message and exit
  --reset-config        reset qt config
  --logger-level {debug,info,warning,fatal,error}
                        logger level
  --no-auto-update-check
                        disable automatic update check on startup
  --qt-platform QT_PLATFORM
                        Force Qt platform plugin (e.g., 'xcb', 'wayland'). If not specified, Qt will auto-detect the platform.
  --qt-image-allocation-limit QT_IMAGE_ALLOCATION_LIMIT
                        Override Qt image allocation limit in MB. Qt default is 256 MB. Use 0 to disable the limit.
  --filename [FILENAME]
                        image or label filename; If a directory path is passed in, the folder will be loaded automatically
  --output OUTPUT, -O OUTPUT, -o OUTPUT
                        output file or directory (if it ends with .json it is recognized as file, else as directory)
  --config CONFIG       config file or yaml-format string (default: /home/cvhub/.xanylabelingrc)
  --nodata              stop storing image data to JSON file
  --autosave            auto save
  --nosortlabels        stop sorting labels
  --flags FLAGS         comma separated list of flags OR file containing flags
  --labelflags LABEL_FLAGS
                        yaml string of label specific flags OR file containing json string of label specific flags (ex. {person-\d+: [male, tall], dog-\d+: [black, brown, white], .*:
                        [occluded]})
  --labels LABELS       comma separated list of labels OR file containing labels
  --validatelabel {exact}
                        label validation types
  --keep-prev           keep annotation of previous frame

2.2 Display System and Package Information

Input

xanylabeling checks

Output

Application
────────────────────────────────────────────────────────────
  App Name:          X-AnyLabeling
  App Version:       3.3.0
  Preferred Device:  CPU
────────────────────────────────────────────────────────────
System
────────────────────────────────────────────────────────────
  Operating System:  Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.31
  CPU:               x86_64
  CPU Count:         20
  RAM:               31.2 GB
  Disk:              841.6/1006.9 GB
  GPU:               CUDA:0 (NVIDIA GeForce RTX 3060, 12288MiB)
  CUDA:              V11.6.124
  Python Version:    3.12.10
────────────────────────────────────────────────────────────
Packages
────────────────────────────────────────────────────────────
  PyQt6 Version:                           6.9.1
  ONNX Version:                            1.19.1
  ONNX Runtime Version:                    1.23.2
  ONNX Runtime GPU Version:                None
  OpenCV Contrib Python Headless Version:  4.11.0.86
────────────────────────────────────────────────────────────

2.3 Display Application Version

Input

xanylabeling version

Output

3.3.0

2.4 Display Configuration File Path

Input

xanylabeling config

Output

~/.xanylabelingrc

3. Label Format Conversion

3.1 List All Available Conversion Tasks

Input

xanylabeling convert

Output

================================================================================
SUPPORTED CONVERSION TASKS
================================================================================

📥 IMPORT TO XLABEL
--------------------------------------------------------------------------------
  • yolo2xlabel [detect, segment, obb, pose]
  • voc2xlabel [detect, segment]
  • coco2xlabel [detect, segment, pose]
  • dota2xlabel
  • mot2xlabel
  • ppocr2xlabel [rec, kie]
  • mask2xlabel
  • vlmr12xlabel
  • odvg2xlabel

📤 EXPORT FROM XLABEL
--------------------------------------------------------------------------------
  • xlabel2yolo [detect, segment, obb, pose]
  • xlabel2voc [detect, segment]
  • xlabel2coco [detect, segment, pose]
  • xlabel2dota
  • xlabel2mask
  • xlabel2mot
  • xlabel2mots
  • xlabel2odvg
  • xlabel2vlmr1
  • xlabel2ppocr [rec, kie]

================================================================================
Total: 19 conversion tasks
================================================================================

Usage:
  xanylabeling convert                          # Show all tasks
  xanylabeling convert --task <task>            # Show detailed help for a task
  xanylabeling convert --task <task> [options]  # Run conversion

3.2 Show Detailed Help for a Specific Task

Input (using yolo2xlabel as an example)

xanylabeling convert --task yolo2xlabel

Output

================================================================================
TASK: yolo2xlabel
================================================================================

Description:
  Convert YOLO format to XLABEL

Modes:
  detect, segment, obb, pose

Required Arguments:
  --images
  --labels
  --output

Mode-Specific Arguments:
  detect: --classes
  segment: --classes
  obb: --classes
  pose: --pose_cfg

Examples:
  # Detection
  xanylabeling convert --task yolo2xlabel --mode detect --images ./images --labels ./labels \
    --output ./output --classes classes.txt

  # Segmentation
  xanylabeling convert --task yolo2xlabel --mode segment --images ./images --labels ./labels \
    --output ./output --classes classes.txt

  # OBB (Oriented Bounding Box)
  xanylabeling convert --task yolo2xlabel --mode obb --images ./images --labels ./labels \
    --output ./output --classes classes.txt

  # Pose
  xanylabeling convert --task yolo2xlabel --mode pose --images ./images --labels ./labels \
    --output ./output --pose-cfg pose_config.yaml

================================================================================

3.3 Run a Conversion Task

Input (using yolo2xlabel:detect as an example)

xanylabeling convert --task yolo2xlabel --mode detect --images ./images --labels ./labels \
    --output ./output --classes classes.txt

Output

Converting YOLO detect to XLABEL: 100%|█████████████████████████████████████| 128/128 [00:00<00:00, 2456.47it/s]
✓ Converted 128 files to XLABEL format: ./output

3.4 Conversion Parameters

Parameter	Description	Required
`--task`	Conversion task name	Yes
`--images`	Path to the image directory	No
`--labels`	Path to the label directory	No
`--output`	Path to the output directory	Yes
`--classes`	Path to the classes file	No
`--pose-cfg`	Path to the pose configuration file	No
`--mode`	Conversion mode (e.g., detect, segment, obb, pose)	No
`--mapping`	Path to the mapping table file	No
`--skip-empty-files`	Skip creating empty output files (supported by xlabel2yolo and xlabel2voc only)	No

For more details, refer to the User Guide - Label Import/Export section.

4. FAQ

Q1: What is the XLABEL format?

XLABEL is X-AnyLabeling's native JSON format. It stores all annotation information in a human-readable format, including shape data, labels, attributes, and metadata.

Q2: Do I need to provide class names for all conversions?

Class names are required for:

YOLO conversions (detect, segment, obb modes)
COCO conversions (detect, segment modes)
MOT conversions

VOC format embeds class names directly in the XML files, so a separate classes file is not required.

Q3: How do I create a classes.txt file?

Simply create a text file with one class name per line:

person
car
bicycle
dog
cat

The line number (0-indexed) corresponds to the class ID.

Q4: What's the difference between MOT and MOTS?

MOT: Multiple Object Tracking with bounding boxes
MOTS: Multiple Object Tracking with segmentation masks

Q5: Can I convert directly between formats without using XLABEL?

Not currently. All conversions use XLABEL as an intermediate format:

Convert to XLABEL first
Then convert from XLABEL to the target format

Q6: What if my images are in subdirectories?

The converter currently processes images in the specified directory only. For nested directory structures, you'll need to either run the conversion multiple times or flatten your directory structure.

Q7: How do I handle non-ASCII paths on Windows?

The converter has built-in support for non-ASCII paths. Ensure your terminal encoding is set to UTF-8:

chcp 65001  # For Windows CMD