# utils

Python API: `modelconverter.cli.utils`

Helpers shared by the `modelconverter` CLI commands.

Turns what the user typed on the command line into what the platform packages expect: the directory a run writes its results to,
the parsed configuration (from a config file or an NN Archive), and the preprocessing that is handed to the NN Archive instead of
being baked into the model.

## Functions

### display_output_path

```python
def display_output_path(path: Path) -> str:
```

Return the host-visible representation of an output path when available.

Parameters

 * `path` (`Path`): Artifact path produced by the current conversion environment.

Returns

 * `str`: Host-visible path for a Docker output when mapping context is available, otherwise the original path representation.

### extract_preprocessing

```python
def extract_preprocessing(cfg: Config) -> tuple[Config, dict[str, PreprocessingBlock]]:
```

Move the preprocessing out of the config into archive blocks.

Mean values, scale values and the color encoding are cleared on every input of the config -- so they are not baked into the
converted model -- and returned as `PreprocessingBlock` objects to be stored in the NN Archive instead. A raw input only gets a
block when it has mean or scale values.

Parameters

 * `cfg` (`Config`): Single-stage config to take the preprocessing from. Its inputs are modified in place.

Returns

 * `tuple[Config, dict[str, PreprocessingBlock]]`: Tuple of the modified config and the preprocessing blocks keyed by input name.

Raises

 * `ValueError`: If the config has more than one stage.

### get_configs

```python
def get_configs(platform: Platform, path: str | None, opts: list[str] | Params | None = None) -> tuple[Config, NNArchiveConfig | None, str | None]:
```

Set up the configuration.

Parameters

 * `platform` (`Platform`): Platform the config is built for.
 * `path` (`str | None`): Path to the configuration file or NN Archive. If `None`, the config is built from the overrides alone.
 * `opts` (`list[str] | Params | None`): Optional CLI overrides of the config file. Either a mapping, or a flat list alternating
   keys and values.

Returns

 * `tuple[Config, NNArchiveConfig | None, str | None]`: Tuple of the parsed modelconverter
   [Config](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md),
   the `NNArchiveConfig` if the input was an NN Archive and `None` otherwise, and the key of the main stage -- `None` for a
   multi-stage config in which no main stage was recognized.

Raises

 * `ValueError`: If `opts` is a list of odd length.

### get_output_dir_name

```python
def get_output_dir_name(platform: Platform, name: str, output_dir: str | None) -> Path:
```

Determine the directory the conversion writes its results to.

An existing destination is cleared first, but only when it is a directory that a previous conversion produced -- one holding a
[CONVERSION_MARKER](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/constants.md)
file -- or an empty one.

Parameters

 * `platform` (`Platform`): Platform the model is converted for, used in the generated name.
 * `name` (`str`): Name of the model, sanitized before use.
 * `output_dir` (`str | None`): Directory named by the user, resolved under
   [OUTPUTS_DIR](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/constants.md).
   If `None`, a directory named `<name>_to_<platform>_<timestamp>` is used instead.

Returns

 * `Path`: Path to the output directory. It is not created here.

Raises

 * `ModelconverterException`: If, in a containerized run, `output_dir` is empty, absolute or contains `..`; or if the destination
   exists but is not a directory, or is a non-empty directory that does not hold the results of a previous conversion.

### init_dirs

```python
def init_dirs():
```

Create the directories a conversion reads from and writes to.

### resolve_output_dir

```python
def resolve_output_dir(output_dir: str) -> Path:
```

Resolve a user-provided `--output-dir` under
[OUTPUTS_DIR](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/constants.md).

Only the host's `./output` is mounted into the container, so an absolute path -- which `pathlib` would let win over the mount
point -- or one escaping upwards through `..` would be written to a container-only location and lost when the container is
removed. A native run writes straight to the host filesystem, where every path the user names is reachable, so any path is honored
there.