# CLI

Python API: `modelconverter.__main__`

Entry point of the `modelconverter` command-line interface.

Defines the commands the CLI exposes: converting a model for a platform, running inference, benchmarking and analyzing it on a
device, visualizing the analysis, packaging a model into an NN Archive, opening a shell in a platform's container and managing the
cache. The commands that need the vendor conversion tools -- `convert`, `infer` and `shell` -- are re-run inside the Docker image
of the requested platform unless they already run inside one; the others run on the host.

## Functions

### analyze

```python
def analyze(*, device_ip: str | None = None, device_id: str | None = None, dlc_model_path: str, onnx_model_path: str, image_subset: int | None = None, image_dirs: Annotated[list[str], Parameter(negative_iterable=[], consume_multiple=True)], analyze_outputs: bool = True, analyze_cycles: bool = True):
```

Run layer and cycle analysis on the specified DLC model.

Requires the RVC4 device to be connected and accessible using the `adb` command.

Parameters

 * `device_ip` (`str | None`): IP address of the device to run the analysis on. Interchangeable with `device_id`. If neither is
   given, ADB selects the first connected device. If both are given, `device_id` takes precedence.
 * `device_id` (`str | None`): The unique ID of the device to run the analysis on. Interchangeable with `device_ip`. If neither is
   given, ADB selects the first connected device. If both are given, `device_id` takes precedence.
 * `dlc_model_path` (`str`): The path to the DLC model file.
 * `onnx_model_path` (`str`): The path to the corresponding ONNX model file that was used for converting to DLC.
 * `image_subset` (`int | None`): If provided, limit analysis to the first N supported input files per input directory.
 * `image_dirs` (`Annotated[list[str], Parameter(negative_iterable=[], consume_multiple=True)]`): A list of names and paths to
   directories with images for each input of the model.
 * `analyze_outputs` (`bool`): Whether to analyze the layer outputs.
 * `analyze_cycles` (`bool`): Whether to analyze the layer cycles.

### archive

```python
def archive(path: str, *, save_path: str | None = None, put_file_plugin: str | None = None):
```

Convert a model file to a Luxonis NN Archive.

Parameters

 * `path` (`str`): A URL or a path to the model file.
 * `save_path` (`str | None`): Path or URL to save the archive to. By default, it is saved to the current directory under the name
   of the model.
 * `put_file_plugin` (`str | None`): The name of the plugin to use for uploading the file.

### benchmark

```python
def benchmark(platform: Platform, /, *, model_path: str, full: bool = False, save: bool = False, repetitions: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 10, benchmark_time: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 20, num_threads: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 2, num_messages: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 50, requests: Annotated[int, Parameter(group='RVC3')] = 1, profile: Annotated[Literal['low_balanced', 'balanced', 'high_performance', 'sustained_high_performance', 'burst', 'low_power_saver', 'power_saver', 'high_power_saver', 'extreme_power_saver', 'system_settings'], Parameter(group='RVC4')] = 'balanced', runtime: Annotated[Literal['dsp', 'cpu'], Parameter(group='RVC4')] = 'dsp', num_images: Annotated[int, Parameter(group='RVC4')] = 500, device_ip: Annotated[str | None, Parameter(group='RVC4')] = None, device_id: Annotated[str | None, Parameter(group='RVC4')] = None, dai_benchmark: Annotated[bool, Parameter(group='RVC4')] = True, device_monitor: Annotated[bool, Parameter(group='RVC4')] = True):
```

Run benchmark on the specified platform.

Parameters

 * `platform` (`Platform`): The platform to run the benchmark on.
 * `model_path` (`str`): A URL or a path to the model file.
 * `full` (`bool`): If `True`, runs the full benchmark using all configurations.
 * `save` (`bool`): If `True`, saves the benchmark results to a file.
 * `repetitions` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): The number of repetitions to perform. Only relevant for
   DAI benchmark.
 * `benchmark_time` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): The duration in seconds for time-based benchmarking
   (overrides repetitions).
 * `num_threads` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): The number of threads to use for inference. Only relevant
   for DAI benchmark.
 * `num_messages` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): The number of messages to measure for each report. Only
   relevant for DAI benchmark.
 * `requests` (`Annotated[int, Parameter(group='RVC3')]`): The number of requests to perform.
 * `profile` (`Annotated[Literal['low_balanced', 'balanced', 'high_performance', 'sustained_high_performance', 'burst',
   'low_power_saver', 'power_saver', 'high_power_saver', 'extreme_power_saver', 'system_settings'], Parameter(group='RVC4')]`):
   The SNPE profile to use for inference.
 * `runtime` (`Annotated[Literal['dsp', 'cpu'], Parameter(group='RVC4')]`): The SNPE runtime to use for inference (dsp or cpu).
 * `num_images` (`Annotated[int, Parameter(group='RVC4')]`): The number of images to use for inference. Only relevant for SNPE
   backend.
 * `device_ip` (`Annotated[str | None, Parameter(group='RVC4')]`): IP address of the device to run the benchmark on.
   Interchangeable with `device_id`. If neither is given, DAI selects the default device. If both are given, `device_id` takes
   precedence.
 * `device_id` (`Annotated[str | None, Parameter(group='RVC4')]`): The unique ID of the device to run the benchmark on.
   Interchangeable with `device_ip`. If neither is given, DAI selects the default device. If both are given, `device_id` takes
   precedence.
 * `dai_benchmark` (`Annotated[bool, Parameter(group='RVC4')]`): Whether to run the benchmark using the DAI V3. If `False`, the
   SNPE tools are used.
 * `device_monitor` (`Annotated[bool, Parameter(group='RVC4')]`): Whether to monitor the device performance during benchmarking
   and include it in the results. Only relevant for RVC4.

### cache_clean

```python
def cache_clean(*, yes: Annotated[bool, Parameter(name='-y', negative_bool=[])] = False):
```

Remove the entire modelconverter cache.

Parameters

 * `yes` (`Annotated[bool, Parameter(name='-y', negative_bool=[])]`): Clear the cache without prompting for confirmation.

### cache_info

```python
def cache_info():
```

Report the location and disk usage of the modelconverter cache.

### catch_exceptions

```python
def catch_exceptions():
```

Log any exception raised in the block and exit.

Exits with status 1 for a `ModelconverterException` and with status 2 for any other exception.

### convert

```python
def convert(platform: Platform, /, *opts: str, path: str | None = None, output_dir: str | None = None, to: Literal['native', 'nn_archive'] = 'nn_archive', main_stage: str | None = None, archive_preprocess: bool = False):
```

Export the model for the specified platform.

Parameters

 * `platform` (`Platform`): The platform to export the model for.
 * `*opts` (`str`): A list of optional CLI overrides for the configuration file.
 * `path` (`str | None`): A URL or a path to the configuration file, NN Archive or a standalone model file.
 * `output_dir` (`str | None`): Name of the directory where the exported model will be saved.
 * `to` (`Literal['native', 'nn_archive']`): Whether to export the model to a simple model file or a Luxonis NN Archive.
 * `main_stage` (`str | None`): Name of the stage with the main model. Only needed for multistage configs and when converting to
   NN Archive. When converting from NN Archive, the stage names are named the same as the model files without the suffix.
 * `archive_preprocess` (`bool`): Add the pre-processing to the NN archive instead of the model. In case of conversion from
   archive to archive, it moves the preprocessing to the new archive.

### infer

```python
def infer(platform: Platform, /, *opts: str, model_path: str, input_path: Path, output_dir: str, config: str | None = None, path: str | None = None, stage: str | None = None):
```

Run inference on the specified platform.

Parameters

 * `platform` (`Platform`): The platform to run the inference on.
 * `*opts` (`str`): A list of optional CLI overrides for the configuration file.
 * `model_path` (`str`): A URL or a path to the model file.
 * `input_path` (`Path`): Path to the directory with data for inference. The directory must contain one subdirectory per input,
   named the same as the input. The files may be images, `.npy` arrays or `.raw` buffers.
 * `output_dir` (`str`): Name of the directory where the inference results will be saved.
 * `config` (`str | None`): A URL or a path to the configuration file.
 * `path` (`str | None`): An alias for `config`. Deprecated.
 * `stage` (`str | None`): Name of the stage to run. Only needed for multistage configs. If not provided, the first stage will be
   used.

### launcher

```python
def launcher(*tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True, json_dict=False, json_list=False)], dev: Annotated[bool, Parameter(group=docker_parameters)] = False, gpu: Annotated[bool, Parameter(group=docker_parameters)] = True, tool_version: Annotated[str | None, Parameter(group=docker_parameters)] = None, image: Annotated[str | None, Parameter(['image', 'docker-image'], group=docker_parameters)] = None, memory: Annotated[str | None, Parameter(group=docker_parameters)] = None, cpus: Annotated[float | None, Parameter(group=docker_parameters)] = None):
```

Convert neural network models for Luxonis devices.

The `convert`, `infer` and `shell` commands run in a docker container, unless they already run inside one. The other commands run
on the host.

Parameters

 * `*tokens` (`Annotated[str, Parameter(show=False, allow_leading_hyphen=True, json_dict=False, json_list=False)]`): The command
   and its arguments, parsed by the wrapped app.
 * `dev` (`Annotated[bool, Parameter(group=docker_parameters)]`): If `True`, builds and runs the platform's `dev` image, which
   also mounts the host's sources, tests and `pyproject.toml` over the ones baked into it.
 * `gpu` (`Annotated[bool, Parameter(group=docker_parameters)]`): If `True`, runs the container with the `nvidia` runtime. Only
   has an effect for the `hailo` platform.
 * `tool_version` (`Annotated[str | None, Parameter(group=docker_parameters)]`): Version of the underlying conversion tools to
   use. Available options differ based on the platform.
 * `image` (`Annotated[str | None, Parameter(['image', 'docker-image'], group=docker_parameters)]`): Full name of the docker image
   to use. If the name includes a tag (e.g. `:latest`), it will be used as is and the `--tool-version` argument will be ignored.
 * `memory` (`Annotated[str | None, Parameter(group=docker_parameters)]`): Amount of memory to allocate to the docker container,
   as a number with an optional binary unit: `4g` for four gibibytes, `512m`, `2GiB`, or a bare count of bytes. By default, uses
   all available system memory.
 * `cpus` (`Annotated[float | None, Parameter(group=docker_parameters)]`): Number of CPU cores to allocate to the docker
   container. Can be a fractional number, e.g. `0.5` for half a core. By default, uses all available CPU cores.

### shell

```python
def shell(platform: Platform, /, *, command: Annotated[str | None, Parameter(name=['-c', '--command'])] = None):
```

Boot up a shell inside a docker container for the specified platform.

Parameters

 * `platform` (`Platform`): The platform.
 * `command` (`Annotated[str | None, Parameter(name=['-c', '--command'])]`): The command to run in the shell. If not provided, a
   bash shell is started. If you want to run a command with arguments, use quotes around the command.

### visualize

```python
def visualize(dir_path: str):
```

Visualize the analysis results.

Parameters

 * `dir_path` (`str`): The path to the directory holding the analysis CSV files. The analyzer writes them to
   `output/analysis/<model_name>`.

## Attributes

### app

### cache_app

### device_commands

### docker_commands

### docker_parameters