# onnx_model_tool

**Repository Path**: xdltek/onnx_model_tool

## Basic Information

- **Project Name**: onnx_model_tool
- **Description**: ONNX model conversion and optimization toolkit for RPP inference deployment
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ONNX Model Tool

![XDL logo](doc/logo/logo_color_horizontal.png)

This project provides deterministic ONNX export pipelines for three predefined demo models:

- `resnet50` (classification)
- `yolov5` (defaults to `yolov5s`)
- `yolov8` (defaults to `yolov8s`)

It is designed for reproducible demo exports, not as a universal model converter.

**Table of Contents**
- [Quick Start](#quick-start)
- [Repository Layout](#repository-layout)
- [Prerequisites](#prerequisites)
- [How to Obtain Models](#how-to-obtain-models)
- [Example ONNX Downloads](#example-onnx-downloads)
- [How to Export](#how-to-export)
- [Program Arguments](#program-arguments)
- [Expected Output](#expected-output)
- [Key Source Files](#key-source-files)
- [Code Execution Workflow](#code-execution-workflow)

## Quick Start

### Environment Setup (One-Time Only)

```bash
# Create conda virtual environment (if you don't have Miniconda/Anaconda, see: https://docs.conda.io/en/latest/miniconda.html)
conda create -n onnx_tool python=3.11

# Activate the environment and install dependencies (only needs to be done once)
conda activate onnx_tool
pip install -r requirements.txt
```

### Exporting ONNX Models

```bash
bash scripts/fetch_resnet50.sh
bash scripts/export_resnet50.sh

bash scripts/fetch_yolov5s.sh
bash scripts/export_yolov5s.sh

bash scripts/fetch_yolov8s.sh
bash scripts/export_yolov8s.sh
```

> `scripts/export_*.sh` runs Python through `conda run -n onnx_tool`, so manual `conda activate` is optional if that environment already exists.

## Repository Layout

```text
ONNX_MODEL_TOOL/
├── README.md
├── requirements.txt
├── export.py
├── registry.py
├── common/
│   ├── config.py
│   ├── utils.py
│   ├── downloader.py
│   ├── checker.py
│   ├── reporter.py
│   ├── simplifier.py
│   └── yolov5_source.py
├── models/
│   ├── resnet50_exporter.py
│   ├── yolov5_exporter.py
│   └── yolov8_exporter.py
├── scripts/
│   ├── _conda_python.sh
│   ├── download_yolo_weights.py
│   ├── fetch_resnet50.sh
│   ├── fetch_yolov5s.sh
│   ├── fetch_yolov8s.sh
│   ├── export_resnet50.sh
│   ├── export_yolov5s.sh
│   └── export_yolov8s.sh
├── weights/
├── examples/
│   └── onnx/
├── outputs/
└── third_party/
```

## Prerequisites

- Linux shell with `bash`
- Conda installed and available in `PATH`

### Conda Environment Setup

If you do not have the `onnx_tool` conda environment yet, initialize it as follows (recommended Python 3.11):

```bash
# Create and activate onnx_tool environment (if it doesn't exist already)
conda create -n onnx_tool python=3.11 -y
conda activate onnx_tool

# Install required Python dependencies
pip install -r requirements.txt
```

If you have already created the `onnx_tool` environment, simply activate it before working with the project:

```bash
conda activate onnx_tool
```

Note: The project scripts (such as `scripts/export_*.sh`) run Python using `conda run -n onnx_tool`, so manual activation is not always necessary. However, activating the environment manually is convenient for interactive development and debugging.


## How to Obtain Models

To obtain all required model files and dependencies, run the following fetch scripts:

```bash
bash scripts/fetch_resnet50.sh
bash scripts/fetch_yolov5s.sh
bash scripts/fetch_yolov8s.sh
```

Descriptions of what each fetch script does:

- `fetch_resnet50.sh`: Prefetches the torchvision ResNet50 pretrained weights into the cache.
- `fetch_yolov5s.sh`: Downloads `weights/yolov5s/model.pt` and sets up `third_party/yolov5-7.0`.
- `fetch_yolov8s.sh`: Downloads `weights/yolov8s/model.pt`.

## Example ONNX Downloads

Pre-exported example ONNX files are available in `examples/onnx/` with MD5 checksums in `examples/onnx/MD5SUMS`.

These ONNX models are provided only for SDK benchmarking, testing, and demonstration. They are not intended for production deployment or commercial use. Please refer to the original projects for the pretrained weights and license terms, and replace these files with your own trained models before deployment.

Source notes:

- `yolov5s.onnx` and `yolov8s.onnx` are exported from official pretrained models released by Ultralytics.
- `resnet50.onnx` is exported from the official torchvision pretrained ResNet50 weights.

Example download commands from `origin/main`:

```bash
wget -O yolov5s.onnx https://raw.githubusercontent.com/xdltek/onnx_model_tool/main/examples/onnx/yolov5s.onnx
wget -O yolov8s.onnx https://raw.githubusercontent.com/xdltek/onnx_model_tool/main/examples/onnx/yolov8s.onnx
wget -O resnet50.onnx https://raw.githubusercontent.com/xdltek/onnx_model_tool/main/examples/onnx/resnet50.onnx
```

For single-file MD5 verification examples, see `examples/onnx/README.md`.

## How to Export

### Script mode (recommended)

```bash
bash scripts/export_resnet50.sh
bash scripts/export_yolov5s.sh
bash scripts/export_yolov8s.sh
```

### Direct CLI mode

```bash
python export.py --model resnet50
python export.py --model yolov5
python export.py --model yolov8
python export.py --list-models
```

## Program Arguments

`export.py` supports:

- `--model` (required unless `--list-models`)
- `--weights` (optional)
- `--output` (optional)
- `--img-size` (optional)
- `--opset` (optional, default `13`)
- `--repo` (optional, YOLOv5 source override)
- `--list-models`

Policy notes:

- Exported ONNX must have fixed input/output dimensions.
- `--dynamic` is rejected by design.
- Simplification is always applied after export.
- `--simplify` is kept only for backward CLI compatibility.

## Expected Output

After a successful export:

- `outputs/<model>.onnx`
- `outputs/<model>.report.txt`
- `outputs/<model>.meta.json`

Example:

- `outputs/resnet50.onnx`
- `outputs/resnet50.report.txt`
- `outputs/resnet50.meta.json`

Terminal output ends with:

```text
[PASS] Export and validation completed
ONNX  : ...
Report: ...
Meta  : ...
```

## Key Source Files

- `export.py`: main CLI entry, request normalization, simplify/validate/report pipeline.
- `registry.py`: model-to-exporter registry and dynamic class loading.
- `models/resnet50_exporter.py`: torchvision-based ResNet50 ONNX export.
- `models/yolov5_exporter.py`: subprocess wrapper around YOLOv5 `export.py`.
- `models/yolov8_exporter.py`: Ultralytics API export for YOLOv8.
- `common/yolov5_source.py`: YOLOv5 source bootstrap and compatibility patching.
- `common/checker.py`: ONNX load/check + I/O metadata extraction.
- `common/simplifier.py`: ONNX simplify pass.
- `common/reporter.py`: text and JSON artifact generation.

## Code Execution Workflow

1. User runs a script in `scripts/` or calls `python export.py ...`.
2. CLI arguments are parsed and normalized into `ExportRequest`.
3. Exporter is selected from `registry.py`.
4. Model-specific exporter generates raw ONNX.
5. ONNX simplify runs unconditionally.
6. ONNX validation runs (`onnx.load` + `onnx.checker`).
7. Static-shape policy is enforced.
8. Report artifacts are written to `outputs/`.
9. CLI prints final `PASS` / error message.