# Luxonis Hub

## Overview

For Luxonis devices, we recommend online conversion in Luxonis Hub. It runs
[ModelConverter](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md) in the
cloud and produces deployment artifacts without local converter setup.

This page focuses on online conversion usage and migration from legacy tools. For the managed Model Registry workflow and
platform-specific conversion settings, see the [Luxonis Hub
Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md) guide. For SDK installation,
authentication, and model, variant, and instance APIs, see the [Luxonis Hub AI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) documentation.

## Quick Start

Install `hubai-sdk` and configure `HUBAI_API_KEY` as described in the [Luxonis Hub AI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) page, then run a conversion:

```python
import os

from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))

response = client.convert.RVC2(
    path="path/to/model.onnx",
    name="my-converted-model",
)

print(response.downloaded_path)
```

The returned response downloads the converted artifact locally and also exposes the created Luxonis Hub instance metadata.

## Python API

The online conversion API lives under the `HubAIClient.convert` namespace. Use target-specific helpers such as `convert.RVC2` and
`convert.RVC4` when the target is fixed.

There is also a generic conversion entrypoint if you want to choose the target programmatically:

```python
from hubai_sdk.utils.types import Target

response = client.convert.convert(
    Target.RVC2,
    path="path/to/model.onnx",
    name="my-converted-model",
)
```

The conversion function takes a number of parameters to specify the model and the conversion options. Here we list the main ones
to get you started, but for the exact current parameter set, refer to the [full API
documentation](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md).

### General Parameters

General parameters applicable to all conversion functions.

| argument | type | description |
| --- | --- | --- |
| `path` | `str` | The path to the model file. |
| `tool_version` | `str | None` | The version of the conversion tool. |
| `quantization_mode` | `Literal["INT8_STANDARD", "INT8_ACCURACY_FOCUSED", "INT8_INT16_MIXED",
"INT8_INT16_MIXED_ACCURACY_FOCUSED", "FP16_STANDARD", "FP32_STANDARD"]` | Quantization or precision preset used by targets that
support it, for example `INT8_STANDARD` or `FP16_STANDARD`. |
| `output_dir` | `str | None` | The directory to save the converted model. If not specified, the model will be saved in the
current working directory. |

### YOLO Parameters

These parameters are only relevant if you're converting a YOLO model.

| argument | type | description |
| --- | --- | --- |
| `yolo_input_shape` | `list[int] | None` | The input shape of the YOLO model. |
| `yolo_version` | `str | None` | Optional YOLO version override, for example `"yolov8"`. If omitted, the backend attempts to
detect the version automatically from the PyTorch model file. |
| `yolo_class_names` | `list[str] | None` | The class names of the model. |

You do not need to set `yolo_version` explicitly for YOLO conversions. If it is omitted, the backend attempts to detect the
version automatically. The PyTorch model file still needs to come from one of the supported YOLO versions.

### RVC2 Parameters

Parameters specific to the `RVC2` conversion.

| argument | type | description |
| --- | --- | --- |
| `mo_args` | `list[str] | None` | The arguments to pass to the model optimizer. |
| `compile_tool_args` | `list[str] | None` | The arguments to pass to the BLOB compiler. |
| `compress_to_fp16` | `bool` | Whether to compress the model's weights to FP16 precision. Defaults to `True`. |
| `number_of_shaves` | `int` | The number of shaves to use. Defaults to `8`. |
| `superblob` | `bool` | Whether to create a superblob. Defaults to `True`. Use `False` if you want legacy RVC2 blob conversion. |

### RVC4 Parameters

Parameters specific to the `RVC4` conversion.

> **Note**
> When converting for `RVC4`, choose an SNPE version that matches your deployment environment. See the [SNPE compatibility table in Conversion Troubleshooting](https://docs.luxonis.com/software-v3/ai-inference/conversion/troubleshooting.md).

| argument | type | description |
| --- | --- | --- |
| `snpe_onnx_to_dlc_args` | `list[str] | None` | The arguments to pass to the `snpe-onnx-to-dlc` tool. |
| `snpe_dlc_quant_args` | `list[str] | None` | The arguments to pass to the `snpe-dlc-quant` tool. |
| `snpe_dlc_graph_prepare_args` | `list[str] | None` | The arguments to pass to the `snpe-dlc-graph-prepare` tool. |
| `use_per_channel_quantization` | `bool` | Whether to use per-channel quantization. Defaults to `True`. |
| `use_per_row_quantization` | `bool` | Whether to use per-row quantization. Defaults to `False`. |
| `htp_socs` | `list[str] | None` | The list of HTP SoCs to use. |

Conversion calls can also create or attach Luxonis Hub resources through arguments such as `name`, `model_id`, `variant_id`,
`variant_version`, and `input_shape`. For those workflows and the broader SDK surface, see the [Luxonis Hub AI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) page.

## CLI Reference

The conversion can also be done using the command line interface. Start with:

```bash
hubai login
hubai convert RVC2 --path /path/to/model.onnx --name "my-model"
```

See `hubai convert --help` for the full list of options.

## Migration from BlobConverter

[BlobConverter](https://pypi.org/project/blobconverter/) is our previous library for converting models to the BLOB format for
earlier OAK workflows. It is being replaced by
[ModelConverter](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md) and the
Luxonis Hub AI SDK, which are the supported paths going forward.

`blobconverter` is still available and can be used for conversion, but we recommend the Luxonis Hub AI SDK for new projects. The
API is similar, but there are differences in parameter names and in how conversion is executed.

`blobconverter` offers several functions for converting models from different frameworks, such as `from_onnx`, `from_openvino`,
and `from_tf`. These functions are replaced by `convert.RVC2` in the Luxonis Hub AI SDK, which takes a single `path` argument
pointing to the model input.

The following table shows the mapping between the parameters of `blobconverter` and the Luxonis Hub AI SDK.

| `blobconverter` | Luxonis Hub AI SDK | Notes |
| --- | --- | --- |
| `model` | `path` | The model file path. |
| `xml` | `path` | The XML file path. Only for conversion from OpenVINO IR. |
| `bin` | `opts["input_bin"]` | The BIN file path. Only for conversion from OpenVINO IR. |
| `version` | `tool_version` | The version of the conversion tool. |
| `data_type` | `compress_to_fp16` | Use `True` for FP16-compressed weights and `False` otherwise. `RVC2` does not use
`quantization_mode`. |
| `shaves` | `number_of_shaves` | The number of shaves to use. |
| `optimizer_params` | `mo_args` | The arguments to pass to the model optimizer. |
| `compile_params` | `compile_tool_args` | The arguments to pass to the BLOB compiler. |

By default, the Luxonis Hub AI SDK enables `superblob`, which is only supported on DepthAI v3. If you want to convert a model to
the legacy RVC2 blob format, pass `superblob=False` to `convert.RVC2`.

### Simple Conversion

Simple ONNX conversion using `blobconverter`

```python
import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
)
```

Equivalent code using the Luxonis Hub AI SDK

```python
response = client.convert.RVC2(
    path="resnet18.onnx",
)

blob = response.downloaded_path
```

### Conversion from OpenVINO IR

`blobconverter` example

```python
import blobconverter

blob = blobconverter.from_openvino(
    xml="resnet18.xml",
    bin="resnet18.bin",
)
```

Luxonis Hub AI SDK example

```python
# When the XML and BIN files are at the same location,
# only the XML needs to be specified.
response = client.convert.RVC2(path="resnet18.xml")
blob = response.downloaded_path

# Otherwise, the BIN file can be specified using
# the `opts` parameter.
response = client.convert.RVC2(
    path="resnet18.xml",
    opts={
        "input_bin": "resnet18.bin",
    },
)
blob = response.downloaded_path
```

### Conversion from TFLite

> **Note**
> Luxonis Hub online conversion does not support conversion from frozen PB files. Only TFLite files are supported.

`blobconverter` example

```python
import blobconverter

blob = blobconverter.from_tf(
    frozen_pb="resnet18.tflite",
)
```

Equivalent code using the Luxonis Hub AI SDK

```python
response = client.convert.RVC2(
    path="resnet18.tflite",
)

blob = response.downloaded_path
```

### Advanced Parameters

`blobconverter.from_onnx` with advanced parameters

```python
import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
    data_type="FP16",
    version="2021.4",
    shaves=6,
    optimizer_params=[
        "--mean_values=[127.5,127.5,127.5]",
        "--scale_values=[255,255,255]",
    ],
    compile_params=["-ip U8"],
)
```

Equivalent code using the Luxonis Hub AI SDK

```python
response = client.convert.RVC2(
    path="resnet18.onnx",
    tool_version="2021.4.0",
    number_of_shaves=6,
    mo_args=[
        "mean_values=[127.5,127.5,127.5]",
        "scale_values=[255,255,255]",
    ],
    compile_tool_args=["-ip", "U8"],
)

blob = response.downloaded_path
```

### `Caffe` Conversion

Conversion from the `Caffe` framework is not supported.

## Migration from tools.luxonis.com

The web app hosted on [tools.luxonis.com](https://tools.luxonis.com/) is our legacy application for converting YOLO object
detection models. It is being replaced by Luxonis Hub online conversion.

Compared to the web application, Luxonis Hub online conversion also supports instance segmentation, pose, oriented detection, and
classification YOLO models. For the current conversion capabilities, refer to the [Luxonis Hub
Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) documentation.

Here is an example of converting an existing `.pt` file to an RVC2-compatible `.superblob`:

```python
import os

from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))

converted_model = client.convert.RVC2(
    path="yolov6n.pt",
    yolo_version="yolov6r4",
)
```

This uses our Hub cloud service to perform the conversion and downloads a `.tar.xz` bundle when the job finishes. For additional
YOLO-specific flags, see the [YOLO
parameters](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md) section.
