# Exporting

LuxonisTrain exports trained models to ONNX, packages them into NN Archives, and converts them for target platforms through Hub
AI. Export commands can use the configuration and dataset metadata stored in a LuxonisTrain checkpoint without access to the
original dataset.

## ONNX Export

Export a checkpoint from the CLI:

```bash
luxonis_train export \
  --weights path/to/checkpoint.ckpt \
  --save-path exported
```

To supply configuration separately, add `--config config.yaml`. Configure ONNX options under `exporter.onnx`:

```yaml
exporter:
  name: my_model
  onnx:
    opset_version: 16
    disable_onnx_simplification: false
```

The default ONNX opset is 16, and graph simplification is enabled. Without `--save-path`, output goes to the run's `export/`
directory. The filename uses `exporter.name`, or `model.name` when no export name is set. For a single-input model, export also
writes a ModelConverter YAML configuration beside the ONNX file.

### Python API

```python
from luxonis_train import LuxonisModel

model = LuxonisModel(
    weights="path/to/checkpoint.ckpt",
    allow_empty_dataset=True,
)
onnx_path = model.export(save_path="exported")
```

Pass weights to the constructor so the checkpoint's model configuration and dataset metadata are available during initialization.
`export()` returns the output path. `exporter.upload_to_run` controls uploading export artifacts to the tracker, and
`exporter.upload_url` specifies an additional upload destination.

ONNX export does not run platform conversion. Use `convert` to apply `exporter.hubai` or `exporter.blobconverter` settings.

## NN Archive

An [NN Archive](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md) packages an executable with metadata describing
inputs, outputs, preprocessing, and model heads. LuxonisTrain creates an ONNX-based `.tar.xz` archive:

```bash
luxonis_train archive --weights path/to/checkpoint.ckpt
```

To package an ONNX file you have already exported from this model, pass `--executable path/to/model.onnx`. The supplied executable
must match the model configuration. Without it, a standalone CLI invocation exports ONNX first.

### Python API

```python
from luxonis_train import LuxonisModel

model = LuxonisModel(
    weights="path/to/checkpoint.ckpt",
    allow_empty_dataset=True,
)
onnx_path = model.export(save_path="exported")
archive_path = model.archive(path=onnx_path, save_dir="exported")
```

In Python, `archive()` without a path reuses the instance's most recent ONNX export, or exports one if needed. It returns the
archive path. Configure naming and uploads separately from ONNX export:

```yaml
archiver:
  name: my_model
  upload_to_run: true
```

The default destination is the run's `archive/` directory. The archive name uses `archiver.name` or `model.name`, followed by
`.onnx.tar.xz`. Set `archiver.upload_url` for an additional upload destination.

Preprocessing metadata uses `exporter.mean_values` and `exporter.scale_values` when supplied. Otherwise, it derives them from
`trainer.preprocessing.normalize`. Keep these values consistent with the preprocessing used to train the model.

## Platform Conversion

`convert` exports ONNX, creates an NN Archive, and runs the enabled conversion backends. Enable conversion through Hub AI in your
configuration:

```yaml
exporter:
  hubai:
    active: true
    platform: rvc4
```

Set `HUBAI_API_KEY` in the environment. The supported platforms are `rvc2`, `rvc3`, and `rvc4`. The conversion uploads the model
to the [Hub AI model registry](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md) and downloads the converted NN
Archive. `exporter.hubai.params` passes additional options to the SDK's conversion call.

### CLI

```bash
luxonis_train convert \
  --config config.yaml \
  --weights path/to/checkpoint.ckpt \
  --save-dir converted
```

You can also enable a backend with overrides while using the checkpoint's configuration:

```bash
luxonis_train convert --weights path/to/checkpoint.ckpt \
  exporter.hubai.active true \
  exporter.hubai.platform rvc4
```

### Python API

```python
from luxonis_train import LuxonisModel

model = LuxonisModel(
    "config.yaml",
    weights="path/to/checkpoint.ckpt",
    allow_empty_dataset=True,
)
archive_path, conversion_artifacts = model.convert(save_dir="converted")
```

`archive_path` is the ONNX-based NN Archive. `conversion_artifacts` contains `hubai_archive` when Hub AI conversion runs and
`blob` when BlobConverter conversion runs. With no conversion backend enabled, `convert` still produces ONNX and its NN Archive,
and the dictionary is empty.

`exporter.blobconverter.active` enables BlobConverter output; its settings include `shaves` and the OpenVINO `version`. Use the
Hub AI backend for platform conversion workflows.

## Export After Training

`ConvertOnTrainEnd` combines export, archiving, and enabled platform conversions. Automatic configuration adds it to the trainer
unless a callback with that name is already present. It uses a selected training checkpoint.

You can configure `ExportOnTrainEnd` for ONNX export or `ArchiveOnTrainEnd` for archive generation individually. Disable
`ConvertOnTrainEnd` explicitly when using these callbacks on their own. If an active `ConvertOnTrainEnd` is explicitly configured
alongside them, configuration validation deactivates the other two to avoid duplicate work. See [Automatic Configuration and
Callbacks](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/training.md) for controlling
callback activation.

## AIMET Quantization

Install the AIMET extra to run quantization:

```bash
python -m pip install 'luxonis-train[aimet]'
```

Quantization needs a working dataset for calibration and evaluation. Settings live under `exporter.aimet`, for example:

```yaml
exporter:
  aimet:
    default_output_bw: 8
    default_param_bw: 8
    max_calibration_images: 100
    epochs: 5
```

```bash
luxonis_train quantize --config config.yaml --weights path/to/checkpoint.ckpt
```

```python
from luxonis_train import LuxonisModel

model = LuxonisModel("config.yaml", weights="path/to/checkpoint.ckpt")
output_dir = model.quantize()
```

The workflow evaluates the floating-point model, calibrates post-training quantization on validation images, runs
quantization-aware training on the training view, and evaluates the result. It writes the quantized ONNX model and NN Archive
under the run's `aimet/` directory. The Python method returns that output directory.