PTYOLOX Garage

日本語

PTYOLOX Garage is a practical desktop and Python toolkit for training, testing, and exporting object-detection models with Pixeltable YOLOX. It provides an Ultralytics-style API and a bilingual tkinter GUI for repeatable local and offline workflows.

Features

• Prepare Label Studio COCO exports for training
• Train YOLOX nano, tiny, s, m, l, and x models with staged epoch schedules
• Run inference on images, NumPy arrays, directories, and USB cameras
• Save portable CPU-compatible .pt model packages by default
• Export trained models to ONNX
• Switch the GUI between English and Japanese
• Store reusable CPU/GPU configuration profiles

Requirements

• Python 3.10–3.13
• Windows 11 is the primary supported platform
• NVIDIA CUDA GPU is recommended for training; CPU inference is supported

On Linux, tkinter may need to be installed through the operating-system package manager.

Installation

From PyPI:

pip install ptyolox-garage

For development with uv:

git clone https://github.com/Moge800/ptyolox-garage.git
cd ptyolox-garage
uv sync --group dev

PyTorch builds are hardware-specific. Install the appropriate PyTorch build from the official selector when CUDA support is required.

Model Security

PyTorch checkpoint files such as .pt can execute arbitrary code when loaded. Only open model files from a trusted source. The GUI asks for confirmation before loading a model file; cancel the dialog when you cannot verify its origin.

GUI

ptyolox-garage

The GUI contains four work areas: training, image inference, live camera inference, and ONNX export. The initial language follows the operating-system locale and can be changed from the Language menu.

Configuration is stored in the operating system's user configuration directory. On Windows, the default location is %APPDATA%\ptyolox-garage\config.ini.

Python API

The installed package version is available without loading the ML runtime:

import ptyolox_garage

print(ptyolox_garage.__version__)

from ptyolox_garage import YOLOX

# Train from a Label Studio COCO export.
model = YOLOX("l")
model.train(
    data="data.yaml",
    epochs=[100, 200, 300],
    device="cuda:0",
    batch=16,
)

# Run inference.
model = YOLOX("best_model.pt")
results = model.predict("image.jpg", conf=0.3)
annotated = results[0].plot()

# Save a model that can be loaded on a CPU-only machine.
model.save("deployment_model.pt")

# Export to ONNX.
model.export(format="onnx")

Checkpoints created by current versions store their model size internally, so renaming a .pt file does not affect loading or fine-tuning. Inference from a legacy yolox_wrapper checkpoint does not require a size. To fine-tune a legacy checkpoint that has no size metadata, provide the known architecture explicitly:

legacy = YOLOX("legacy-model.pt", model_size="l")
legacy.train(data="data.yaml")

Checkpoint filenames are never used to infer model size. The explicit value must match the architecture that was used to create the legacy model.

Dataset Configuration

Training accepts three input forms. A Label Studio export directory contains result.json and images/ side by side:

export/
  result.json
  images/

model.train(data="export")
model.train(data="export/result.json", images_dir="export/images")

The existing data.yaml form remains supported:

coco_json: C:/datasets/widgets/result.json
images_dir: C:/datasets/widgets/images
output_dir: C:/datasets/widgets/prepared
val_split: 0.2

For JSON and directory inputs, output_dir can be passed to train(); otherwise the work directory is ./yolox_work. The JSON form requires images_dir.

PTYOLOX Garage remaps COCO category IDs, validates image paths, creates train/validation splits, and writes the directory structure expected by Pixeltable YOLOX.

Model Sizes

Development

uv sync --group dev
uv run pytest
uv run ruff check .
uv build

Detailed guides are available in the English documentation and Japanese documentation.

Attribution

PTYOLOX Garage is built on Pixeltable YOLOX, which is derived from Megvii YOLOX. PTYOLOX Garage is an independent project and is not an official Pixeltable product.

License

Licensed under the Apache License 2.0. See NOTICE for attribution.