mblt-vision-python 0.0.0__py3-none-any.whl

mblt_vision/compile/vision.py

@@ -0,0 +1,1120 @@
+"""Vision model compilation and calibration-data preparation."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import shutil
+import warnings
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from tempfile import TemporaryDirectory, mkdtemp
+from typing import Any
+
+import numpy as np
+import torch
+from huggingface_hub import hf_hub_download
+from huggingface_hub.errors import HfHubHTTPError
+from mblt_vision.utils.datasets.readiness import (
+    _path_has_symlink_component,
+    dataset_ready,
+)
+
+from mblt_vision._tasks import normalize_vision_task
+from mblt_vision.datasets import get_dataset_config_for_task
+from mblt_npu import normalize_target_device
+from mblt_vision.wrapper import (
+    MOBILINT_CACHE_DIR,
+    MBLT_Engine,
+    get_mobilint_cache_dir,
+    resolve_model_config,
+)
+
+DEFAULT_PERCENTILE = 0.9999
+DEFAULT_TOPK_RATIO = 0.01
+DEFAULT_SEED = 0
+DEFAULT_MODEL_DIR = Path(MOBILINT_CACHE_DIR)
+SUPPORTED_TARGET_DEVICES = frozenset({"aries-rb", "regulus-ra", "regulus-rb"})
+DEFAULT_SUBSET_SIZES = {
+    "image_classification": 1,
+    "depth_estimation": 100,
+    "object_detection": 100,
+    "instance_segmentation": 100,
+    "semantic_segmentation": 100,
+    "pose_estimation": 100,
+    "face_detection": 1,
+    "obb": 100,
+}
+IMAGE_SUFFIXES = {".bmp", ".jpeg", ".jpg", ".png", ".tif", ".tiff", ".webp"}
+
+
+def _default_model_dir() -> Path:
+    """Return the writable default compilation output directory lazily."""
+
+    if DEFAULT_MODEL_DIR != Path(MOBILINT_CACHE_DIR):
+        return DEFAULT_MODEL_DIR
+    return Path(get_mobilint_cache_dir())
+
+
+def _normalize_task(task: str) -> str:
+    """Validate and normalize a supported task name.
+
+    Args:
+        task: Task value from a model postprocess configuration.
+
+    Returns:
+        Canonical task name used by the dataset registry.
+
+    Raises:
+        ValueError: If the task is not supported by vision compilation.
+    """
+
+    return normalize_vision_task(task, supported=DEFAULT_SUBSET_SIZES)
+
+
+def _validate_calibration_output_dir(output_dir: str | Path) -> Path:
+    """Return an output path only when it and its ancestors are not symlinks."""
+
+    destination = Path(output_dir).expanduser()
+    if _path_has_symlink_component(destination):
+        raise ValueError(
+            f"Calibration output_dir must not be or contain a symlink: {destination}."
+        )
+    return destination
+
+
+def _dataset_ready(task: str, data_path: Path, dataset: str | None = None) -> bool:
+    """Return whether an organized dataset contains calibration images.
+
+    Args:
+        task: Canonical vision task name.
+        data_path: Organized dataset root.
+        dataset: Optional dense dataset taxonomy.
+
+    Returns:
+        Whether the expected dataset identity, metadata, and full validation split are present.
+    """
+
+    return dataset_ready(data_path, task, dataset)
+
+
+def _find_dataset_source(data_path: Path, filename: str) -> Path | None:
+    """Find a manually supplied dataset source at or beside its organized root.
+
+    Args:
+        data_path: Organized dataset destination.
+        filename: Archive filename to locate.
+
+    Returns:
+        Existing archive path, or ``None`` when it is unavailable.
+    """
+
+    for directory in (data_path, data_path.parent):
+        candidate = directory / filename
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _organize_dataset(task: str, data_path: Path, dataset: str | None = None) -> None:
+    """Organize the registry-backed dataset required by a task.
+
+    Args:
+        task: Canonical vision task name.
+        data_path: Destination dataset root.
+        dataset: Optional dataset taxonomy used to disambiguate semantic datasets.
+    """
+
+    from mblt_vision.utils.datasets import (
+        organize_ade20k,
+        organize_cityscapes,
+        organize_coco,
+        organize_dotav1,
+        organize_imagenet,
+        organize_nyu_depth,
+        organize_widerface,
+    )
+
+    config = get_dataset_config_for_task(task, dataset)
+    download = config.get("download")
+    if not isinstance(download, dict):
+        raise ValueError(
+            f"Dataset `{config.get('name', task)}` does not define download metadata."
+        )
+
+    data_path.parent.mkdir(parents=True, exist_ok=True)
+    if task == "image_classification":
+        organize_imagenet(
+            image_dir=str(download["images"]),
+            xml_dir=str(download["annotations"]),
+            output_dir=str(data_path),
+        )
+    elif task in {"object_detection", "instance_segmentation", "pose_estimation"}:
+        organize_coco(
+            image_dir=str(download["images"]),
+            annotation_dir=str(download["annotations"]),
+            output_dir=str(data_path),
+        )
+    elif task == "face_detection":
+        organize_widerface(
+            image_dir=str(download["images"]),
+            annotation_dir=str(download["annotations"]),
+            output_dir=str(data_path),
+        )
+    elif task == "obb":
+        organize_dotav1(dataset_path=str(download["url"]), output_dir=str(data_path))
+    elif task == "depth_estimation":
+        organize_nyu_depth(dataset_path=str(download["url"]), output_dir=str(data_path))
+    elif config["name"] == "ade20k":
+        organize_ade20k(dataset_path=str(download["url"]), output_dir=str(data_path))
+    elif config["name"] == "cityscapes":
+        image_archive = _find_dataset_source(data_path, str(download["images_archive"]))
+        annotation_archive = _find_dataset_source(
+            data_path, str(download["annotations_archive"])
+        )
+        if image_archive is None or annotation_archive is None:
+            raise ValueError(
+                "Cityscapes compilation requires leftImg8bit_trainvaltest.zip and gtFine_trainvaltest.zip "
+                f"at {data_path} or {data_path.parent}."
+            )
+        organize_cityscapes(
+            image_dir=str(image_archive),
+            annotation_dir=str(annotation_archive),
+            output_dir=str(data_path),
+        )
+    else:
+        raise ValueError(
+            f"Unsupported calibration dataset `{config['name']}` for task `{task}`."
+        )
+
+
+def ensure_calibration_dataset(
+    task: str,
+    data_path: str | Path | None = None,
+    dataset: str | None = None,
+) -> Path:
+    """Resolve and, when needed, organize a calibration dataset.
+
+    Args:
+        task: Vision task name.
+        data_path: Optional organized dataset root.
+        dataset: Optional dataset taxonomy from the model postprocess configuration.
+
+    Returns:
+        Expanded organized dataset root.
+    """
+
+    normalized_task = _normalize_task(task)
+    config = get_dataset_config_for_task(normalized_task, dataset)
+    dataset_name = str(config["name"])
+    resolved_path = (
+        Path(data_path).expanduser()
+        if data_path is not None
+        else _resolve_default_dataset_path(config["path"])
+    )
+    if not _dataset_ready(normalized_task, resolved_path, dataset_name):
+        _organize_dataset(normalized_task, resolved_path, dataset)
+    if not _dataset_ready(normalized_task, resolved_path, dataset_name):
+        raise ValueError(
+            f"Organized calibration dataset at {resolved_path} is incomplete or does not match "
+            f"the expected {dataset_name} dataset."
+        )
+    return resolved_path
+
+
+def _resolve_default_dataset_path(configured_path: str | Path) -> Path:
+    """Translate registry cache paths to the active writable artifact cache."""
+
+    path = Path(configured_path).expanduser()
+    default_cache_root = Path.home() / ".mblt_model_zoo"
+    try:
+        relative_path = path.relative_to(default_cache_root)
+    except ValueError:
+        return path
+    return Path(get_mobilint_cache_dir()) / relative_path
+
+
+def _validate_subset_size(subset_size: int) -> None:
+    """Validate a requested calibration subset size.
+
+    Args:
+        subset_size: Requested per-class or total sample count.
+
+    Raises:
+        ValueError: If the size is not positive.
+    """
+
+    if subset_size <= 0:
+        raise ValueError("subset_size must be greater than zero.")
+
+
+def _validate_calibration_image(image_path: Path, dataset_root: Path) -> Path:
+    """Resolve and validate a calibration image within its dataset root.
+
+    Args:
+        image_path: Candidate calibration image path.
+        dataset_root: Resolved organized dataset root.
+
+    Returns:
+        Resolved regular image path.
+
+    Raises:
+        ValueError: If the candidate is a symlink, not a regular image, or escapes the dataset root.
+    """
+
+    if image_path.is_symlink():
+        raise ValueError(f"Calibration image must not be a symlink: {image_path}.")
+    try:
+        source = image_path.resolve(strict=True)
+    except OSError as exc:
+        raise ValueError(
+            f"Unable to resolve calibration image {image_path}: {exc}."
+        ) from exc
+    if not source.is_file() or source.suffix.lower() not in IMAGE_SUFFIXES:
+        raise ValueError(
+            f"Calibration image must be a supported regular image file: {image_path}."
+        )
+    if not source.is_relative_to(dataset_root):
+        raise ValueError(
+            f"Calibration image must remain within dataset root: {image_path}."
+        )
+    return source
+
+
+def _selectable_calibration_images(
+    paths: Sequence[Path], dataset_root: Path
+) -> list[Path]:
+    """Validate supported image candidates before they enter subset sampling.
+
+    Args:
+        paths: Candidate filesystem paths.
+        dataset_root: Resolved organized dataset root.
+
+    Returns:
+        Validated candidate paths, retaining their original names for stable sampling.
+    """
+
+    images: list[Path] = []
+    for path in paths:
+        if path.suffix.lower() in IMAGE_SUFFIXES and (
+            path.is_symlink() or path.is_file()
+        ):
+            _validate_calibration_image(path, dataset_root)
+            images.append(path)
+    return images
+
+
+def select_calibration_images(
+    task: str,
+    data_path: str | Path,
+    subset_size: int | None = None,
+    seed: int = DEFAULT_SEED,
+) -> list[Path]:
+    """Select deterministic calibration images from an organized dataset.
+
+    For ImageNet and WiderFace, ``subset_size`` is the number selected from
+    every category. For all other datasets it is the total number of selected
+    validation images.
+
+    Args:
+        task: Vision task name.
+        data_path: Organized dataset root.
+        subset_size: Optional sample count, using task-specific defaults when omitted.
+        seed: Random selection seed.
+
+    Returns:
+        Selected image paths in deterministic order.
+
+    Raises:
+        ValueError: If the dataset layout or requested size is invalid.
+    """
+
+    import random
+
+    normalized_task = _normalize_task(task)
+    root = Path(data_path).expanduser()
+    resolved_root = root.resolve()
+    requested_size = (
+        DEFAULT_SUBSET_SIZES[normalized_task] if subset_size is None else subset_size
+    )
+    _validate_subset_size(requested_size)
+    random_generator = random.Random(seed)
+
+    if normalized_task in {"image_classification", "face_detection"}:
+        category_root = (
+            root if normalized_task == "image_classification" else root / "images"
+        )
+        dataset_name = (
+            "ImageNet" if normalized_task == "image_classification" else "WiderFace"
+        )
+        category_dirs = (
+            sorted(path for path in category_root.iterdir() if path.is_dir())
+            if category_root.is_dir()
+            else []
+        )
+        if not category_dirs:
+            raise ValueError(
+                f"No {dataset_name} category directories found in {category_root}."
+            )
+        selected: list[Path] = []
+        for category_dir in category_dirs:
+            images = _selectable_calibration_images(
+                sorted(category_dir.iterdir()), resolved_root
+            )
+            if requested_size > len(images):
+                raise ValueError(
+                    f"subset_size ({requested_size}) exceeds the {len(images)} available images in {category_dir.name}."
+                )
+            selected.extend(random_generator.sample(images, requested_size))
+        return selected
+
+    image_dir = {
+        "depth_estimation": root / "images",
+        "object_detection": root / "val2017",
+        "instance_segmentation": root / "val2017",
+        "semantic_segmentation": root / "images",
+        "pose_estimation": root / "val2017",
+        "obb": root / "images",
+    }[normalized_task]
+    images = (
+        _selectable_calibration_images(sorted(image_dir.rglob("*")), resolved_root)
+        if image_dir.is_dir()
+        else []
+    )
+    if not images:
+        raise ValueError(f"No calibration images found in {image_dir}.")
+    if requested_size > len(images):
+        raise ValueError(
+            f"subset_size ({requested_size}) exceeds the {len(images)} available images in {image_dir}."
+        )
+    return random_generator.sample(images, requested_size)
+
+
+def copy_calibration_subset(
+    images: Sequence[Path], data_path: str | Path, output_dir: str | Path
+) -> list[Path]:
+    """Copy selected images into a flat directory using collision-safe names.
+
+    Args:
+        images: Selected source image paths.
+        data_path: Dataset root used to derive stable relative names.
+        output_dir: Destination directory.
+
+    Returns:
+        Copied image paths in input order.
+    """
+
+    root = Path(data_path).expanduser().resolve()
+    destination = _validate_calibration_output_dir(output_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+    copied: list[Path] = []
+    for image_path in images:
+        source = _validate_calibration_image(image_path, root)
+        relative_name = source.relative_to(root).as_posix()
+        digest = hashlib.sha256(relative_name.encode()).hexdigest()[:12]
+        target = destination / f"{digest}_{source.name}"
+        if target.exists():
+            raise ValueError(f"Calibration subset filename collision for {source}.")
+        shutil.copy2(source, target)
+        copied.append(target)
+    return copied
+
+
+def make_calibration_subset(
+    task: str,
+    data_path: str | Path,
+    output_dir: str | Path,
+    subset_size: int | None = None,
+    seed: int = DEFAULT_SEED,
+) -> list[Path]:
+    """Select and copy a deterministic flat calibration subset.
+
+    Args:
+        task: Vision task name.
+        data_path: Organized dataset root.
+        output_dir: Destination for copied images.
+        subset_size: Optional task-specific selection count.
+        seed: Random selection seed.
+
+    Returns:
+        Copied image paths.
+    """
+
+    source_root = Path(data_path).expanduser().resolve()
+    destination = _validate_calibration_output_dir(output_dir).resolve()
+    if source_root.is_relative_to(destination) or destination.is_relative_to(
+        source_root
+    ):
+        raise ValueError("output_dir must not overlap data_path.")
+    images = select_calibration_images(task, data_path, subset_size, seed)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary_destination = Path(
+        mkdtemp(prefix=f".{destination.name}-", dir=destination.parent)
+    )
+    try:
+        copied = copy_calibration_subset(images, data_path, temporary_destination)
+        backup_destination: Path | None = None
+        if destination.exists():
+            backup_destination = Path(
+                mkdtemp(prefix=f".{destination.name}-backup-", dir=destination.parent)
+            )
+            backup_destination.rmdir()
+            destination.replace(backup_destination)
+        try:
+            temporary_destination.replace(destination)
+        except BaseException:
+            if backup_destination is not None and not destination.exists():
+                backup_destination.replace(destination)
+            raise
+        if backup_destination is not None:
+            shutil.rmtree(backup_destination)
+        return [destination / path.name for path in copied]
+    finally:
+        if temporary_destination.exists():
+            shutil.rmtree(temporary_destination)
+
+
+def _as_hwc_float32(value: Any, image_path: Path) -> np.ndarray:
+    """Validate and convert engine preprocessing output for qbcompiler.
+
+    Args:
+        value: Engine preprocessing result.
+        image_path: Source image used for error context.
+
+    Returns:
+        Contiguous HWC float32 array.
+
+    Raises:
+        TypeError: If preprocessing did not return a tensor or array.
+        ValueError: If preprocessing did not return HWC three-channel data.
+    """
+
+    if isinstance(value, torch.Tensor):
+        array = value.detach().cpu().numpy()
+    elif isinstance(value, np.ndarray):
+        array = value
+    else:
+        raise TypeError(
+            f"Preprocessing {image_path} returned unsupported type {type(value).__name__}."
+        )
+    if array.ndim != 3 or array.shape[-1] != 3:
+        raise ValueError(
+            f"Preprocessing {image_path} must produce an HWC three-channel array; got shape {array.shape}."
+        )
+    return np.ascontiguousarray(array, dtype=np.float32)
+
+
+def prepare_calibration_arrays(
+    engine: MBLT_Engine, images: Sequence[Path], output_dir: str | Path
+) -> list[Path]:
+    """Preprocess calibration images and save one NumPy array per sample.
+
+    Args:
+        engine: ONNX vision engine providing authoritative preprocessing.
+        images: Flat calibration image paths.
+        output_dir: Destination directory for ``.npy`` arrays.
+
+    Returns:
+        Saved NumPy paths.
+    """
+
+    destination = _validate_calibration_output_dir(output_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+    saved: list[Path] = []
+    for index, image_path in enumerate(images):
+        array = _as_hwc_float32(engine.preprocess(str(image_path)), image_path)
+        array_path = destination / f"{index:06d}.npy"
+        np.save(array_path, array)
+        saved.append(array_path)
+    return saved
+
+
+def get_subset_images(subset_path: str | Path) -> list[Path]:
+    """Load all images from an already-sampled subset.
+
+    Args:
+        subset_path: Root containing sampled images, either flat or nested.
+
+    Returns:
+        Image paths in deterministic order.
+
+    Raises:
+        ValueError: If the subset contains no supported image files.
+    """
+
+    root = Path(subset_path).expanduser()
+    images = (
+        sorted(
+            path
+            for path in root.rglob("*")
+            if path.is_file() and path.suffix.lower() in IMAGE_SUFFIXES
+        )
+        if root.is_dir()
+        else []
+    )
+    if not images:
+        raise ValueError(f"No calibration subset images found in {root}.")
+    return images
+
+
+def _calibration_image_shape(pre_cfg: Mapping[str, Any]) -> tuple[int, int]:
+    """Derive the final HWC spatial shape produced by a model preprocessor."""
+
+    image_shape: tuple[int, int] | None = None
+    for operation, config in pre_cfg.items():
+        if operation not in {"LetterBox", "Resize", "CenterCrop"} or not isinstance(
+            config, Mapping
+        ):
+            continue
+        size = config.get("img_size", config.get("size"))
+        if isinstance(size, int) and not isinstance(size, bool) and size > 0:
+            image_shape = (size, size)
+        elif (
+            isinstance(size, Sequence)
+            and not isinstance(size, (str, bytes))
+            and len(size) == 2
+            and all(
+                isinstance(value, int) and not isinstance(value, bool) and value > 0
+                for value in size
+            )
+        ):
+            image_shape = (size[0], size[1])
+    if image_shape is None:
+        raise ValueError(
+            "Unable to derive calibration image shape from pre_cfg; expected a "
+            "positive LetterBox.img_size, Resize.size, or CenterCrop.size."
+        )
+    return image_shape
+
+
+def validate_calibration_dataset(
+    calib_data_path: str | Path,
+    *,
+    image_shape: tuple[int, int] | None = None,
+) -> Path:
+    """Validate a ready directory of preprocessed calibration arrays.
+
+    Args:
+        calib_data_path: Directory containing HWC float32 ``.npy`` tensors.
+
+    Returns:
+        Expanded calibration directory path.
+
+    Raises:
+        ValueError: If the directory is empty or contains an invalid calibration tensor.
+    """
+
+    root = Path(calib_data_path).expanduser()
+    array_paths = sorted(root.glob("*.npy")) if root.is_dir() else []
+    if not array_paths:
+        raise ValueError(f"No calibration .npy files found in {root}.")
+    for array_path in array_paths:
+        try:
+            array = np.load(array_path, mmap_mode="r", allow_pickle=False)
+        except (OSError, ValueError) as exc:
+            raise ValueError(
+                f"Unable to load calibration tensor {array_path}: {exc}."
+            ) from exc
+        if array.ndim != 3 or array.shape[-1] != 3:
+            raise ValueError(
+                f"Calibration tensor {array_path} must be HWC with three channels; got {array.shape}."
+            )
+        if image_shape is not None and array.shape[:2] != image_shape:
+            raise ValueError(
+                f"Calibration tensor {array_path} must match the model pre_cfg "
+                f"image shape {image_shape}, got {array.shape[:2]}."
+            )
+        if array.dtype != np.float32:
+            raise ValueError(
+                f"Calibration tensor {array_path} must use float32; got {array.dtype}."
+            )
+        if not np.isfinite(array).all():
+            raise ValueError(
+                f"Calibration tensor {array_path} must contain only finite values."
+            )
+        if not array.flags.c_contiguous:
+            raise ValueError(f"Calibration tensor {array_path} must be C-contiguous.")
+    return root
+
+
+def _validate_data_level_paths(
+    data_path: str | Path | None,
+    subset_path: str | Path | None,
+    calib_data_path: str | Path | None,
+) -> None:
+    """Ensure at most one calibration pipeline entry level is supplied.
+
+    Args:
+        data_path: Original organized dataset root.
+        subset_path: Already-sampled image subset root.
+        calib_data_path: Ready preprocessed NumPy dataset root.
+
+    Raises:
+        ValueError: If more than one data level is supplied.
+    """
+
+    supplied = [
+        name
+        for name, value in (
+            ("data_path", data_path),
+            ("subset_path", subset_path),
+            ("calib_data_path", calib_data_path),
+        )
+        if value is not None
+    ]
+    if len(supplied) > 1:
+        raise ValueError(
+            "Provide only one calibration pipeline input: `data_path`, `subset_path`, or `calib_data_path`; "
+            f"got {', '.join(supplied)}."
+        )
+
+
+def _load_qbcompiler() -> tuple[Callable[..., Any], type[Any]]:
+    """Load qbcompiler only when compilation is requested.
+
+    Returns:
+        The ``mxq_compile`` function and ``CalibrationConfig`` class.
+
+    Raises:
+        ImportError: If qbcompiler is not installed.
+    """
+
+    try:
+        module = importlib.import_module("qbcompiler")
+    except ImportError as exc:
+        raise ImportError(
+            "Vision compilation requires qbcompiler>=1.2.0. Install the compiler package supplied by Mobilint."
+        ) from exc
+    return module.mxq_compile, module.CalibrationConfig
+
+
+def _validate_ratio(name: str, value: Any) -> float:
+    """Validate a quantization ratio.
+
+    Args:
+        name: Field name used in an error message.
+        value: Candidate numeric ratio.
+
+    Returns:
+        Validated float value.
+
+    Raises:
+        ValueError: If the value is non-numeric or outside zero to one.
+    """
+
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(
+            f"Quantization metadata `{name}` must be numeric, got {value!r}."
+        )
+    resolved = float(value)
+    if not 0.0 <= resolved <= 1.0:
+        raise ValueError(
+            f"Quantization metadata `{name}` must be between 0 and 1, got {resolved}."
+        )
+    return resolved
+
+
+def _fetch_quantization_config(
+    repo_id: str, revision: str, target_device: str = "aries-rb"
+) -> dict[str, Any] | None:
+    """Fetch optional hosted board quantization metadata.
+
+    Args:
+        repo_id: Hugging Face model repository ID.
+        revision: Repository revision.
+        target_device: Board folder containing the metadata.
+
+    Returns:
+        Hosted ``config`` mapping, or ``None`` when the optional file is unavailable.
+
+    Raises:
+        ValueError: If the hosted JSON or its ``config`` field is malformed.
+    """
+
+    try:
+        metadata_path = hf_hub_download(
+            repo_id=repo_id,
+            filename="best_result.json",
+            subfolder=normalize_target_device(target_device),
+            revision=revision,
+        )
+    except (HfHubHTTPError, OSError) as exc:
+        warnings.warn(
+            f"Unable to load optional quantization metadata for {repo_id}: {exc}. Using fallback values.",
+            stacklevel=2,
+        )
+        return None
+
+    try:
+        with Path(metadata_path).open(encoding="utf-8") as metadata_file:
+            metadata = json.load(metadata_file)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Malformed quantization metadata JSON at {metadata_path}: {exc.msg}."
+        ) from exc
+    if not isinstance(metadata, dict) or not isinstance(metadata.get("config"), dict):
+        raise ValueError(
+            f"Quantization metadata at {metadata_path} must contain a `config` object."
+        )
+    return metadata["config"]
+
+
+def resolve_quantization_values(
+    file_cfg: dict[str, Any],
+    percentile: float | None,
+    topk_ratio: float | None,
+) -> tuple[float, float]:
+    """Resolve explicit, hosted, and fallback quantization values independently.
+
+    Args:
+        file_cfg: Resolved model file configuration.
+        percentile: Explicit compiler percentile override.
+        topk_ratio: Explicit compiler top-k ratio override.
+
+    Returns:
+        Resolved percentile and top-k ratio.
+
+    Raises:
+        ValueError: If explicit or hosted values are malformed.
+    """
+
+    resolved_percentile = (
+        _validate_ratio("percentile", percentile) if percentile is not None else None
+    )
+    resolved_topk = (
+        _validate_ratio("topk_ratio", topk_ratio) if topk_ratio is not None else None
+    )
+    hosted_config: dict[str, Any] | None = None
+    if resolved_percentile is None or resolved_topk is None:
+        repo_id = file_cfg.get("repo_id")
+        revision = file_cfg.get("revision", "main")
+        if isinstance(repo_id, str) and repo_id:
+            target_device = file_cfg.get("target_device")
+            if isinstance(target_device, str):
+                hosted_config = _fetch_quantization_config(
+                    repo_id, str(revision), normalize_target_device(target_device)
+                )
+            else:
+                hosted_config = _fetch_quantization_config(repo_id, str(revision))
+        else:
+            warnings.warn(
+                "Model configuration has no repository ID; using fallback quantization values.",
+                stacklevel=2,
+            )
+
+    if (
+        resolved_percentile is None
+        and hosted_config is not None
+        and "percentile" in hosted_config
+    ):
+        hosted_percentile = _validate_ratio(
+            "config.percentile", hosted_config["percentile"]
+        )
+        resolved_percentile = 1.0 - hosted_percentile
+    if resolved_topk is None and hosted_config is not None:
+        hosted_topk = hosted_config.get("topk_ratio", hosted_config.get("topk"))
+        if hosted_topk is not None:
+            resolved_topk = _validate_ratio("config.topk_ratio", hosted_topk)
+
+    if resolved_percentile is None:
+        warnings.warn(
+            f"Quantization percentile is unavailable; using {DEFAULT_PERCENTILE}.",
+            stacklevel=2,
+        )
+        resolved_percentile = DEFAULT_PERCENTILE
+    if resolved_topk is None:
+        warnings.warn(
+            f"Quantization top-k ratio is unavailable; using {DEFAULT_TOPK_RATIO}.",
+            stacklevel=2,
+        )
+        resolved_topk = DEFAULT_TOPK_RATIO
+    return resolved_percentile, resolved_topk
+
+
+def _configured_onnx_filename(file_cfg: dict[str, Any]) -> str | None:
+    """Derive the configured ONNX filename.
+
+    Args:
+        file_cfg: Resolved model file configuration.
+
+    Returns:
+        ONNX filename when it can be determined.
+    """
+
+    onnx_filename = file_cfg.get("onnx_filename")
+    if isinstance(onnx_filename, str) and onnx_filename:
+        return onnx_filename
+    filename = file_cfg.get("filename")
+    if isinstance(filename, str) and filename:
+        return f"{Path(filename).stem}.onnx"
+    return None
+
+
+def _resolve_compile_onnx_path(
+    file_cfg: dict[str, Any], model_path: str | Path | None
+) -> Path:
+    """Resolve an ONNX artifact for compilation without constructing an inference runtime.
+
+    Args:
+        file_cfg: Resolved model file configuration.
+        model_path: Optional caller-provided ONNX path.
+
+    Returns:
+        Existing local or downloaded ONNX artifact path.
+
+    Raises:
+        FileNotFoundError: If no ONNX artifact can be resolved.
+    """
+
+    if model_path is not None:
+        local_path = Path(model_path).expanduser()
+        if local_path.is_file():
+            if local_path.suffix.lower() != ".onnx":
+                raise ValueError(
+                    "Compilation requires an ONNX model; "
+                    f"local model path must end with `.onnx`, got {local_path}."
+                )
+            return local_path.resolve()
+    configured_path = Path(str(file_cfg.get("onnx_path", ""))).expanduser()
+    if configured_path.is_file():
+        return configured_path.resolve()
+    repo_id = file_cfg.get("repo_id")
+    revision = file_cfg.get("revision")
+    filename = _configured_onnx_filename(file_cfg)
+    if isinstance(repo_id, str) and isinstance(revision, str) and filename:
+        downloaded_path = Path(
+            hf_hub_download(
+                repo_id=repo_id,
+                filename=filename,
+                revision=revision,
+                local_dir=get_mobilint_cache_dir(),
+            )
+        )
+        if downloaded_path.is_file():
+            return downloaded_path.resolve()
+    configured_name = filename or "the configured ONNX artifact"
+    raise FileNotFoundError(f"Unable to resolve {configured_name} for compilation.")
+
+
+def _resolve_compile_output_path(
+    save_path: str | Path | None, resolved_onnx: Path
+) -> Path:
+    """Resolve and validate an MXQ compilation output path."""
+
+    requested_output_path = (
+        Path(save_path).expanduser()
+        if save_path is not None
+        else _default_model_dir() / f"{resolved_onnx.stem}.mxq"
+    )
+    if requested_output_path.suffix.lower() != ".mxq":
+        raise ValueError(
+            "Compilation output path must end with `.mxq`, "
+            f"got {requested_output_path}."
+        )
+    output_path = requested_output_path.resolve()
+    if output_path == resolved_onnx.resolve():
+        raise ValueError(
+            "Compilation output path must not be the same as the input ONNX path: "
+            f"{output_path}."
+        )
+    if output_path.suffix.lower() != ".mxq":
+        raise ValueError(
+            "Compilation output path must resolve to a path ending with `.mxq`, "
+            f"got {output_path}."
+        )
+    return output_path
+
+
+def compile_vision_model(
+    model_cls: str,
+    *,
+    target_device: str,
+    model_type: str = "DEFAULT",
+    model_path: str | Path | None = None,
+    onnx_path: str | Path | None = None,
+    data_path: str | Path | None = None,
+    subset_path: str | Path | None = None,
+    calib_data_path: str | Path | None = None,
+    save_path: str | Path | None = None,
+    subset_size: int | None = None,
+    seed: int = DEFAULT_SEED,
+    percentile: float | None = None,
+    topk_ratio: float | None = None,
+) -> Path:
+    """Compile a configured vision ONNX model into a board-specific MXQ artifact.
+
+    Args:
+        model_cls: Vision model name or YAML path.
+        target_device: Required target board: ``aries-rb``, ``regulus-ra``, or ``regulus-rb``.
+        model_type: Model variant from the YAML configuration.
+        model_path: Preferred local ONNX path compatibility option.
+        onnx_path: Local ONNX path alias.
+        data_path: Original organized dataset root. The pipeline organizes it when needed, samples
+            an image subset, and preprocesses that subset.
+        subset_path: Already-sampled image subset. The pipeline preprocesses every image directly
+            without organizing or sampling an original dataset.
+        calib_data_path: Ready directory of HWC float32 ``.npy`` tensors. The pipeline passes it
+            directly to qbcompiler without dataset preparation, sampling, or preprocessing.
+        save_path: Output MXQ path. Defaults to the ONNX stem under ``~/.mblt_model_zoo``.
+        subset_size: ImageNet/WiderFace per-category count or total count for other datasets.
+        seed: Deterministic calibration selection seed.
+        percentile: Explicit quantization percentile.
+        topk_ratio: Explicit quantization top-k ratio.
+
+    Returns:
+        Output MXQ path.
+
+    Raises:
+        ImportError: If qbcompiler is unavailable.
+        ValueError: If model metadata, calibration data, or quantization values are invalid.
+    """
+
+    _validate_data_level_paths(data_path, subset_path, calib_data_path)
+    target_device = normalize_target_device(target_device)
+    if target_device not in SUPPORTED_TARGET_DEVICES:
+        raise ValueError(
+            f"Unsupported target_device {target_device!r}; expected one of "
+            f"{sorted(SUPPORTED_TARGET_DEVICES)}."
+        )
+    mxq_compile, calibration_config_class = _load_qbcompiler()
+    model_config = resolve_model_config(model_cls, model_type)
+    file_cfg = model_config.get("file_cfg")
+    pre_cfg = model_config.get("pre_cfg")
+    post_cfg = model_config.get("post_cfg")
+    if (
+        not isinstance(file_cfg, dict)
+        or not isinstance(pre_cfg, dict)
+        or not isinstance(post_cfg, dict)
+    ):
+        raise ValueError(
+            "Resolved vision model configuration requires `file_cfg`, `pre_cfg`, and `post_cfg` objects."
+        )
+    file_cfg["target_device"] = target_device
+
+    task = _normalize_task(str(post_cfg.get("task", "")))
+    dataset = post_cfg.get("dataset")
+    if not isinstance(dataset, str) or not dataset:
+        raise ValueError(
+            "Resolved vision model configuration requires a non-empty `post_cfg.dataset` value."
+        )
+    selected_local_path = model_path or onnx_path
+    if calib_data_path is not None:
+        resolved_onnx = _resolve_compile_onnx_path(file_cfg, selected_local_path)
+        output_path = _resolve_compile_output_path(save_path, resolved_onnx)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        resolved_percentile, resolved_topk = resolve_quantization_values(
+            file_cfg, percentile, topk_ratio
+        )
+        calibration_config = calibration_config_class(
+            method=1,
+            output=0 if task == "image_classification" else 1,
+            mode=1,
+            max_percentile={
+                "percentile": resolved_percentile,
+                "topk_ratio": resolved_topk,
+            },
+        )
+        mxq_compile(
+            model=str(resolved_onnx),
+            calib_data_path=str(
+                validate_calibration_dataset(
+                    calib_data_path,
+                    image_shape=_calibration_image_shape(pre_cfg),
+                )
+            ),
+            save_path=str(output_path),
+            image_channels=3,
+            backend="onnx",
+            device="gpu",
+            target_device=target_device,
+            inference_scheme="all",
+            calibration_config=calibration_config,
+        )
+        return output_path
+    engine_kwargs: dict[str, Any] = {
+        "model_cls": model_cls,
+        "model_type": model_type,
+        "framework": "onnx",
+        "onnx_providers": ["CPUExecutionProvider"],
+    }
+    if selected_local_path is not None:
+        expanded_local_path = Path(selected_local_path).expanduser()
+        if expanded_local_path.is_file():
+            engine_kwargs["model_path"] = str(expanded_local_path)
+
+    engine: MBLT_Engine | None = None
+    try:
+        engine = MBLT_Engine(**engine_kwargs)
+        resolved_onnx = Path(str(engine.file_cfg.get("onnx_path", ""))).expanduser()
+        if not resolved_onnx.is_file():
+            configured_name = (
+                _configured_onnx_filename(file_cfg) or "the configured ONNX artifact"
+            )
+            raise FileNotFoundError(
+                f"Unable to resolve {configured_name} for model `{model_cls}`."
+            )
+
+        output_path = _resolve_compile_output_path(save_path, resolved_onnx)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        resolved_percentile, resolved_topk = resolve_quantization_values(
+            file_cfg, percentile, topk_ratio
+        )
+        calibration_config = calibration_config_class(
+            method=1,
+            output=0 if task == "image_classification" else 1,
+            mode=1,
+            max_percentile={
+                "percentile": resolved_percentile,
+                "topk_ratio": resolved_topk,
+            },
+        )
+
+        def _compile(calibration_path: Path) -> None:
+            """Run qbcompiler with a resolved calibration directory."""
+
+            mxq_compile(
+                model=str(resolved_onnx),
+                calib_data_path=str(calibration_path),
+                save_path=str(output_path),
+                image_channels=3,
+                backend="onnx",
+                device="gpu",
+                target_device=target_device,
+                inference_scheme="all",
+                calibration_config=calibration_config,
+            )
+
+        with TemporaryDirectory(prefix="mblt-vision-calibration-") as temporary_root:
+            temporary_path = Path(temporary_root)
+            if subset_path is not None:
+                subset_images = get_subset_images(subset_path)
+            else:
+                dataset_path = ensure_calibration_dataset(task, data_path, dataset)
+                subset_images = make_calibration_subset(
+                    task,
+                    dataset_path,
+                    temporary_path / "images",
+                    subset_size=subset_size,
+                    seed=seed,
+                )
+            array_dir = temporary_path / "arrays"
+            prepare_calibration_arrays(engine, subset_images, array_dir)
+            _compile(array_dir)
+        return output_path
+    finally:
+        if engine is not None:
+            engine.dispose()
+
+
+__all__ = [
+    "compile_vision_model",
+    "copy_calibration_subset",
+    "ensure_calibration_dataset",
+    "get_subset_images",
+    "make_calibration_subset",
+    "prepare_calibration_arrays",
+    "resolve_quantization_values",
+    "select_calibration_images",
+    "validate_calibration_dataset",
+]