# nn_archive Python API: `modelconverter.utils.nn_archive` Translation between modelconverter configs and NN Archives. An NN Archive is the Luxonis packaging format: a tar holding one or more model files next to a `config.json` that describes their inputs, outputs, preprocessing and heads. It sits on both ends of a conversion -- an archive can be handed to the converter, in which case it is unpacked and turned into a [Config](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md) here, and the converted models are packed back into a new archive whose config this module builds. ## Functions ### archive_from_model ```python def archive_from_model(model_path: Path) -> NNArchiveConfig: ``` Build a bare archive config out of a model file alone. The inputs and outputs come from the model's own metadata, every input is declared as an image with a default layout and no preprocessing, and no heads are declared. This is what packing an unconverted model into an archive starts from. Parameters * `model_path` (`Path`): Path to the model file to describe. Returns * `NNArchiveConfig`: The archive config describing the model. ### find_archive_input ```python def find_archive_input(cfg: NNArchiveConfig | None, name: str) -> NNArchiveInput | None: ``` Look up an input of an archive config, tolerating its absence. Parameters * `cfg` (`NNArchiveConfig | None`): Archive config to search, or `None` if there is none. * `name` (`str`): Name of the input to look for. Returns * `NNArchiveInput | None`: The matching archive input, or `None` if there is no config or it declares no input of that name. ### generate_archive ```python def generate_archive(platform: Platform, cfg: Config, main_stage: str, out_models: list[Path], output_path: Path, archive_cfg: NNArchiveConfig | None, preprocessing: dict[str, PreprocessingBlock], inference_model_path: Path, archive_name: str | None) -> Path: ``` Pack the converted models into an NN Archive. The archive holds the model files together with the generated config and the build info, and its name is suffixed with the platform it was built for. Parameters * `platform` (`Platform`): Platform the models were built for. * `cfg` (`Config`): Config the conversion was run with. * `main_stage` (`str`): Key of the stage holding the main model. * `out_models` (`list[Path]`): Converted model files to put into the archive. * `output_path` (`Path`): Directory the archive is written to, and where `buildinfo.json` is picked up from. * `archive_cfg` (`NNArchiveConfig | None`): Archive config the conversion started from, or `None` if it did not start from an archive. * `preprocessing` (`dict[str, PreprocessingBlock]`): Preprocessing blocks to attach, keyed by input name. * `inference_model_path` (`Path`): Path to the model whose metadata the shapes and data types are read from. * `archive_name` (`str | None`): Base name for the archive. If `None`, the config's name is used. Returns * `Path`: Path to the created archive. ### get_archive_input ```python def get_archive_input(cfg: NNArchiveConfig, name: str) -> NNArchiveInput: ``` Look up an input of an archive config by name. Parameters * `cfg` (`NNArchiveConfig`): Archive config to search. * `name` (`str`): Name of the input to look for. Returns * `NNArchiveInput`: The matching archive input. Raises * `ValueError`: If the config declares no input of that name. ### modelconverter_config_to_nn ```python def modelconverter_config_to_nn(config: Config, model_name: Path, orig_nn: NNArchiveConfig | None, preprocessing: dict[str, PreprocessingBlock], main_stage_key: str, model_path: Path, platform: Platform) -> NNArchiveConfig: ``` Build the archive config describing a converted model. Shapes and data types are taken from the converted model itself, layouts are guessed from the original ones, and the precision is derived from the platform together with its quantization settings. Of the original archive config, the heads are carried over, as is the type of every input and the preprocessing block of a raw one. Parameters * `config` (`Config`): Config the conversion was run with. * `model_name` (`Path`): File name the converted model is stored under inside the archive. * `orig_nn` (`NNArchiveConfig | None`): Archive config the conversion started from, or `None` if it did not start from an archive. * `preprocessing` (`dict[str, PreprocessingBlock]`): Preprocessing blocks to attach, keyed by input name. * `main_stage_key` (`str`): Key of the stage holding the main model. * `model_path` (`Path`): Path to the model whose metadata the shapes and data types are read from. * `platform` (`Platform`): Platform the model was built for. Returns * `NNArchiveConfig`: The archive config for the converted model. Raises * `NotImplementedError`: If the config has more than two stages. * `ValueError`: If a multi-stage config's archive declares no head. ### process_nn_archive ```python def process_nn_archive(platform: Platform, path: Path, overrides: Params | None) -> tuple[Config, NNArchiveConfig, str]: ``` Read an NN Archive and parse its config. Parameters * `platform` (`Platform`): Platform the config is built for. * `path` (`Path`): Path to the archive. It is either a tar file to unpack, or a directory that already holds an unpacked archive. * `overrides` (`Params | None`): CLI overrides applied on top of the archive's own configuration. Returns * `tuple[Config, NNArchiveConfig, str]`: Tuple of the parsed [Config](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md), `NNArchiveConfig` and the main stage key. Raises * `RuntimeError`: If the path is neither a directory nor a tar file, or if the archive holds no `config.json`.