Metadata-Version: 2.5
Name: ptyolox-garage
Version: 0.5.0
Summary: A practical GUI and Python toolkit for Pixeltable YOLOX
Project-URL: Homepage, https://github.com/Moge800/ptyolox-garage
Project-URL: Repository, https://github.com/Moge800/ptyolox-garage
Project-URL: Documentation, https://github.com/Moge800/ptyolox-garage/tree/main/docs
Project-URL: Issues, https://github.com/Moge800/ptyolox-garage/issues
Author: Moge800
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: computer-vision,object-detection,pytorch,tkinter,yolox
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: beep-lite>=0.1.3
Requires-Dist: ml-dtypes>=0.5.0
Requires-Dist: numpy>=1.24
Requires-Dist: onnx>=1.16
Requires-Dist: opencv-python>=4.8
Requires-Dist: pillow>=10.0
Requires-Dist: pixeltable-yolox>=0.4.2
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: torch>=2.5.1
Requires-Dist: torchvision>=0.20.1
Description-Content-Type: text/markdown

# PTYOLOX Garage

[日本語](https://github.com/Moge800/ptyolox-garage/blob/main/README_JP.md)

PTYOLOX Garage is a practical desktop and Python toolkit for training, testing, and exporting object-detection models with [Pixeltable YOLOX](https://github.com/pixeltable/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:

```bash
pip install ptyolox-garage
```

For development with [uv](https://docs.astral.sh/uv/):

```bash
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](https://pytorch.org/get-started/locally/) 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

```bash
ptyolox-garage
```

![PTYOLOX Garage training screen](https://raw.githubusercontent.com/Moge800/ptyolox-garage/main/docs/assets/ptyolox-garage-gui.png)

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:

```python
import ptyolox_garage

print(ptyolox_garage.__version__)
```

```python
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:

```python
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:

```text
export/
  result.json
  images/
```

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

The existing `data.yaml` form remains supported:

```yaml
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

| Name | Depth | Width |
|---|---:|---:|
| `nano` | 0.33 | 0.25 |
| `tiny` | 0.33 | 0.375 |
| `s` | 0.33 | 0.50 |
| `m` | 0.67 | 0.75 |
| `l` | 1.00 | 1.00 |
| `x` | 1.33 | 1.25 |

## Development

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

Detailed guides are available in the [English documentation](https://github.com/Moge800/ptyolox-garage/tree/main/docs/en) and [Japanese documentation](https://github.com/Moge800/ptyolox-garage/tree/main/docs/jp).

## Attribution

PTYOLOX Garage is built on [Pixeltable YOLOX](https://github.com/pixeltable/pixeltable-yolox), which is derived from [Megvii YOLOX](https://github.com/Megvii-BaseDetection/YOLOX). PTYOLOX Garage is an independent project and is not an official Pixeltable product.

## License

Licensed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution.
