Skip to content

get_started.md

Latest commit

 

History

History
311 lines (221 loc) · 14.2 KB

get_started.md

File metadata and controls

311 lines (221 loc) · 14.2 KB

Quick Start Guide

1. Installation and Deployment

X-AnyLabeling provides multiple installation methods. You can install the official package directly via pip to get the latest stable version, install from source by cloning the official GitHub repository, or use the convenient GUI installer package.

Note

Advanced Features: The following advanced features are only available through Git clone installation. Please refer to the corresponding documentation for configuration instructions.

  1. Remote Inference Service: X-AnyLabeling-Server based remote inference service - Installation Guide
  2. Video Object Tracking: Segment-Anything based video object tracking - Installation Guide
  3. Bounding Box Generation: UPN-based bounding box generation - Installation Guide
  4. Interactive Detection & Segmentation: Interactive object detection and segmentation with visual and text prompts - Installation Guide
  5. Smart Detection & Segmentation: Object detection and segmentation with visual prompts, text prompts, and prompt-free modes - Installation Guide
  6. One-Click Training Platform: Ultralytics framework-based training platform - Installation Guide
  7. Multimodal Vision Model: Rex-Omni based object detection, keypoint detection (person/hand/animal), OCR, Pointing, visual prompt localization - Installation Guide

1.1 Prerequisites

1.1.1 Miniconda

If you are already using Miniconda, follow these steps:

Step 0. Download and install Miniconda from the official website.

Step 1. Create a conda environment with Python 3.11 ~ 3.13 (Python 3.12 is recommended) and activate it.

Note

Other Python versions require compatibility verification on your own.

# CPU Environment [Windows/Linux/macOS]
conda create --name x-anylabeling-cpu python=3.12 -y
conda activate x-anylabeling-cpu

# CUDA 11.x Environment [Windows/Linux]
conda create --name x-anylabeling-cu11 python=3.12 -y
conda activate x-anylabeling-cu11

# CUDA 12.x Environment [Windows/Linux]
conda create --name x-anylabeling-cu12 python=3.12 -y
conda activate x-anylabeling-cu12

1.1.2 Venv

You can also use Python's built-in venv module to create virtual environments:

# CPU [Windows/Linux/macOS]
python3.12 -m venv venv-cpu
source venv-cpu/bin/activate  # Linux/macOS
# venv-cpu\Scripts\activate    # Windows

# CUDA 12.x [Windows/Linux]
python3.12 -m venv venv-cu12
source venv-cu12/bin/activate  # Linux
# venv-cu12\Scripts\activate    # Windows

# CUDA 11.x [Windows/Linux]
python3.12 -m venv venv-cu11
source venv-cu11/bin/activate  # Linux
# venv-cu11\Scripts\activate    # Windows

1.1.3 uv

Step 0. Install uv:

# Linux / macOS / WSL2
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 1. Create a virtual environment (uv downloads the required Python automatically) and activate it:

# CPU Environment [Windows/Linux/macOS]
uv venv --python 3.12 .venv-cpu
source .venv-cpu/bin/activate      # Linux/macOS/WSL2
# .venv-cpu\Scripts\activate       # Windows

# CUDA 12.x Environment [Windows/Linux]
uv venv --python 3.12 .venv-cu12
source .venv-cu12/bin/activate     # Linux
# .venv-cu12\Scripts\activate      # Windows

# CUDA 11.x Environment [Windows/Linux]
uv venv --python 3.12 .venv-cu11
source .venv-cu11/bin/activate     # Linux
# .venv-cu11\Scripts\activate      # Windows

1.2 Installation

1.2.1 Pip Installation (Beta Pre-release)

You can easily install the latest beta pre-release version of X-AnyLabeling with the following commands (using uv pip is recommended):

pip install -U uv

# CPU [Windows/Linux/macOS]
uv pip install --pre "x-anylabeling-cvhub[cpu]"

# CUDA 12.x is the default GPU option [Windows/Linux]
uv pip install --pre "x-anylabeling-cvhub[gpu]"

# CUDA 11.x [Windows/Linux]
uv pip install --pre "x-anylabeling-cvhub[gpu-cu11]"

1.2.2 Git Clone (Recommended)

Step a. Clone the repository.

git clone https://github.com/CVHub520/X-AnyLabeling.git
cd X-AnyLabeling

After cloning the repository, you can choose to install the dependencies in either developer mode or regular mode according to your needs.

Step b. Install the dependencies.

pip install -U uv

# CPU [Windows/Linux/macOS]
uv pip install -e ".[cpu]"

# CUDA 12.x is the default GPU option [Windows/Linux]
uv pip install -e ".[gpu]"

# CUDA 11.x [Windows/Linux]
uv pip install -e ".[gpu-cu11]"

If you need to perform secondary development or package compilation, you can install the dev dependencies simultaneously, for example:

uv pip install -e ".[cpu,dev]"

Note

If you switch to a new project directory, rerun the install command there, otherwise the environment will reference the source code from the previous directory.

After installation, you can verify it by running the following command:

xanylabeling checks   # Display system and version information

You can also run the following commands to get other information:

xanylabeling help     # Display help information
xanylabeling version  # Display version number
xanylabeling config   # Display configuration file path

After verification, you can run the application directly:

xanylabeling

Tip

You can use xanylabeling --help to view all available command line options. Please refer to the Command Line Parameters table below for complete parameter descriptions.

Option Description
filename Specify the image or label filename. If a directory path is provided, all files in the folder will be loaded.
--help, -h Display help information and exit.
--reset-config Reset Qt configuration, clearing all settings.
--logger-level Set the logging level: "debug", "info", "warning", "fatal", "error".
--output, -O, -o Specify the output file or directory. Paths ending with .json are treated as files.
--config Specify a configuration file or YAML-formatted configuration string. Defaults to a user-specific path.
--work-dir Specify the working directory for configuration and data files. Defaults to home directory.
--nodata Prevent storing image data in JSON files.
--autosave Enable automatic saving of annotation data.
--nosortlabels Disable label sorting.
--flags Comma-separated list of flags or path to a file containing flags.
--labelflags YAML-formatted string for label-specific flags or a file containing a JSON-formatted string.
--labels Comma-separated list of labels or path to a file containing labels.
--validatelabel Specify the type of label validation.
--keep-prev Keep annotations from the previous frame.
--no-auto-update-check Disable automatic update checks on startup.

Note

Please refer to the X-AnyLabeling pyproject.toml file for a list of dependencies. Note that all the examples above install all required dependencies.

We also supports batch conversion between multiple annotation formats:

xanylabeling convert         # List all supported conversion tasks
xanylabeling convert <task>  # Show detailed help and examples for a specific task, i.e., xlabel2yolo

Important

For GPU acceleration, please follow the instructions below to ensure that your local CUDA and cuDNN versions are compatible with the ONNX Runtime version, and install the required dependencies to ensure GPU-accelerated inference works properly:

Warning

For CUDA 11.x environments, please ensure that the versions meet the following requirements:

  • onnx >= 1.15.0, < 1.16.1
  • onnxruntime-gpu >= 1.15.0, < 1.19.0

Optional Step: Refresh Translation and Resource Files

If you update UI text or maintain localization files, refresh the translation artifacts for all supported interface languages (en_US, zh_CN, ja_JP, ko_KR) with:

# Regenerate .ts catalogs from source strings
python scripts/generate_languages.py

# Compile .qm files and rebuild Qt resources
python scripts/compile_languages.py

Optional Step: Set Environment Variables

# Linux or macOS
export PYTHONPATH=/path/to/X-AnyLabeling

# Windows
set PYTHONPATH=C:\path\to\X-AnyLabeling

Caution

Avoid Dependency Conflicts: To avoid conflicts with third-party packages, please uninstall the old version first:

pip uninstall anylabeling -y

Note

Special Note for Fedora KDE Users: If you encounter slow mouse movement or response lag, try using the --qt-platform xcb parameter to improve performance:

xanylabeling --qt-platform xcb

1.2.3 GUI Installer Package

Download Link: GitHub Releases

Compared to running from source code, the GUI installer package provides a more convenient user experience. Users don't need to understand the underlying implementation and can use it directly after extraction. However, the GUI installer package also has some limitations:

  • Difficult Troubleshooting: If crashes or errors occur, it may be difficult to quickly identify the specific cause, increasing the difficulty of troubleshooting.
  • Feature Lag: The GUI version may lag behind the source code version in functionality, potentially leading to missing features and compatibility issues.
  • GPU Acceleration Limitations: Given the diversity of hardware and operating system environments, current GPU inference acceleration services require users to compile from source code as needed.

Therefore, it is recommended to choose between running from source code and using the GUI installer package based on your specific needs and usage scenarios to optimize the user experience.

2. Usage

For detailed instructions on how to use X-AnyLabeling, please refer to the corresponding User Guide.

3. Packaging and Compilation

Note

Please note that the following steps are optional. This section is intended for users who may need to customize and compile the software to adapt to specific deployment scenarios. If you use the software without such requirements, you can skip this section.

Expand/Collapse

To facilitate users running X-AnyLabeling on different platforms, this tool provides packaging and compilation instructions along with relevant notes. Before executing the following packaging commands, please modify the __preferred_device__ parameter in the app_info.py file according to your environment and requirements to select the appropriate GPU or CPU version for building.

3.1 Notes

  • Modify Device Configuration: Before compiling, ensure that the __preferred_device__ parameter in the anylabeling/app_info.py file has been modified according to the required GPU/CPU version.

  • Verify GPU Environment: If compiling the GPU version, please activate the corresponding GPU runtime environment first and execute pip list | grep onnxruntime-gpu to ensure it is properly installed.

  • Windows-GPU Compilation: Manually modify the datas list parameter in the packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec file to add the relevant *.dll files of the local onnxruntime-gpu dynamic library to the list.

  • Linux-GPU Compilation: Manually modify the datas list parameter in the packaging/pyinstaller/specs/x-anylabeling-linux-gpu.spec file to add the relevant *.so files of the local onnxruntime-gpu dynamic library to the list. Additionally, ensure that you download a matching onnxruntime-gpu package according to your CUDA version. For detailed compatibility information, please refer to the official documentation.

3.2 Build Commands

# Windows-CPU
bash scripts/build_executable.sh win-cpu

# Windows-GPU
bash scripts/build_executable.sh win-gpu

# Linux-CPU
bash scripts/build_executable.sh linux-cpu

# Linux-GPU
bash scripts/build_executable.sh linux-gpu

# macOS
bash scripts/build_executable.sh macos

[!TIP] If you encounter permission issues when executing the above commands on Windows, after ensuring the above preparation steps are completed, you can directly execute the following commands:

pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-cpu.spec
pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec