mblt-vision-python 0.0.0__tar.gz

mblt_vision_python-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Mobilint, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mblt_vision_python-0.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: mblt-vision-python
+Version: 0.0.0
+Summary: Mobilint NPU vision models: classification, detection, segmentation, pose
+Author: Mobilint
+License: BSD-3-Clause
+Project-URL: Home, https://www.mobilint.com/
+Project-URL: Repository, https://github.com/mobilint/mblt-vision-python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mblt-npu-python>=0.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: torch>=2.4.1
+Requires-Dist: opencv-python>=4.11.0.86
+Requires-Dist: pillow>=11.1.0
+Requires-Dist: faster-coco-eval
+Requires-Dist: gdown>=5.2.0
+Requires-Dist: huggingface-hub
+Requires-Dist: matplotlib
+Requires-Dist: requests>=2.32.0
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Requires-Dist: PyYAML
+Provides-Extra: onnxruntime
+Requires-Dist: onnx; extra == "onnxruntime"
+Requires-Dist: onnxruntime; extra == "onnxruntime"
+Provides-Extra: onnxruntime-gpu
+Requires-Dist: onnx; sys_platform != "darwin" and extra == "onnxruntime-gpu"
+Requires-Dist: onnxruntime-gpu; sys_platform != "darwin" and extra == "onnxruntime-gpu"
+Provides-Extra: qbcompiler
+Requires-Dist: qbcompiler>=1.2.0; extra == "qbcompiler"
+Requires-Dist: onnxruntime; extra == "qbcompiler"
+Dynamic: license-file
+
+# Mobilint Vision Python
+
+Run pre-trained Mobilint Vision models from Python. `mblt-vision-python` provides
+model configuration, artifact loading, preprocessing, inference integration, and
+typed postprocessing results for image classification, depth estimation, face and
+object detection, OBB, instance and semantic segmentation,
+and pose estimation.
+
+Version `0.0.0` is the initial standalone release.
+
+## Installation
+
+```bash
+pip install mblt-vision-python
+```
+
+MXQ inference requires a supported Mobilint NPU environment. Model artifacts are
+downloaded from the Mobilint Hugging Face organization when no local `model_path`
+is supplied. For ONNX execution, install one of the optional extras:
+
+```bash
+pip install "mblt-vision-python[onnxruntime]"
+# Or, on supported systems:
+pip install "mblt-vision-python[onnxruntime-gpu]"
+```
+
+## Quick start
+
+Each model includes its matching preprocess and postprocess behavior:
+
+```python
+from mblt_vision import ResNet50
+
+model = ResNet50()
+x = model.preprocess("image.jpg")
+result = model.postprocess(model(x))
+```
+
+For configurable model selection and local MXQ or ONNX artifacts, use
+`MBLT_Engine`:
+
+```python
+from mblt_vision import MBLT_Engine
+
+model = MBLT_Engine(model_cls="resnet50", model_type="DEFAULT")
+try:
+    result = model.postprocess(model(model.preprocess("image.jpg")))
+finally:
+    model.dispose()
+```
+
+Discover supported tasks and models with `list_tasks()` and `list_models()`. New
+code should use the task subpackages (for example,
+`mblt_vision.object_detection`) or `MBLT_Engine`. Top-level model imports such as
+`from mblt_vision import ResNet50` remain supported for convenience.
+
+`obb` is the canonical oriented-bounding-box task name.
+
+## Model Zoo migration
+
+Vision is now maintained in this package. `mblt-model-zoo` retains
+`mblt_model_zoo.vision` as a compatibility facade for existing applications; new
+projects should import from `mblt_vision` directly. Its `mblt-model-zoo predict`,
+`val`, and `compile` commands also delegate to this package.
+
+## Command line
+
+The standalone package provides the `mblt-vision` command with `predict`, `val`,
+and `compile` subcommands:
+
+```bash
+mblt-vision predict --source image.jpg --model resnet50
+```
+
+`predict` is the single inference command for classification, depth estimation,
+object and face detection, instance and semantic segmentation, OBB, and pose
+estimation. The selected model determines its task and processing pipeline.
+By default it downloads the model artifact and saves a plotted result under
+`runs/vision/predict/`. Use `--output` to choose the result-image path,
+`--topk` for classification labels, and `--conf-thres`/`--iou-thres` for
+detection-style tasks. `--framework onnx` selects ONNX Runtime inference;
+`--target-device` and `--core-mode` select the MXQ board/runtime mode.
+
+```bash
+mblt-vision predict --source image.jpg --model yolo11m --conf-thres 0.4 --output result.jpg
+mblt-vision predict --source image.jpg --model yolo11m-pose --target-device regulus-ra --core-mode single
+```
+
+The corresponding `mblt-model-zoo` commands use the same standalone handlers for
+backward compatibility.
+
+## Documentation and tests
+
+See [the Vision API guide](mblt_vision/README.md) for supported model families,
+model details, artifact selection, and output taxonomy behavior. See the
+[compilation guide](compile/README.md) for calibration-data preparation
+and MXQ compilation. The [test guide](tests/TEST.md) explains offline, Hugging
+Face, and NPU test runs.
+
+## Support and issues
+
+For installation, model, or runtime support, visit the
+[Mobilint forum](https://discuss.mobilint.com/). Report reproducible package issues in the
+[mblt-vision-python issue tracker](https://github.com/mobilint/mblt-vision-python/issues).
+
+## License
+
+Distributed under the [BSD 3-Clause License](LICENSE).

mblt_vision_python-0.0.0/README.md

@@ -0,0 +1,108 @@
+# Mobilint Vision Python
+
+Run pre-trained Mobilint Vision models from Python. `mblt-vision-python` provides
+model configuration, artifact loading, preprocessing, inference integration, and
+typed postprocessing results for image classification, depth estimation, face and
+object detection, OBB, instance and semantic segmentation,
+and pose estimation.
+
+Version `0.0.0` is the initial standalone release.
+
+## Installation
+
+```bash
+pip install mblt-vision-python
+```
+
+MXQ inference requires a supported Mobilint NPU environment. Model artifacts are
+downloaded from the Mobilint Hugging Face organization when no local `model_path`
+is supplied. For ONNX execution, install one of the optional extras:
+
+```bash
+pip install "mblt-vision-python[onnxruntime]"
+# Or, on supported systems:
+pip install "mblt-vision-python[onnxruntime-gpu]"
+```
+
+## Quick start
+
+Each model includes its matching preprocess and postprocess behavior:
+
+```python
+from mblt_vision import ResNet50
+
+model = ResNet50()
+x = model.preprocess("image.jpg")
+result = model.postprocess(model(x))
+```
+
+For configurable model selection and local MXQ or ONNX artifacts, use
+`MBLT_Engine`:
+
+```python
+from mblt_vision import MBLT_Engine
+
+model = MBLT_Engine(model_cls="resnet50", model_type="DEFAULT")
+try:
+    result = model.postprocess(model(model.preprocess("image.jpg")))
+finally:
+    model.dispose()
+```
+
+Discover supported tasks and models with `list_tasks()` and `list_models()`. New
+code should use the task subpackages (for example,
+`mblt_vision.object_detection`) or `MBLT_Engine`. Top-level model imports such as
+`from mblt_vision import ResNet50` remain supported for convenience.
+
+`obb` is the canonical oriented-bounding-box task name.
+
+## Model Zoo migration
+
+Vision is now maintained in this package. `mblt-model-zoo` retains
+`mblt_model_zoo.vision` as a compatibility facade for existing applications; new
+projects should import from `mblt_vision` directly. Its `mblt-model-zoo predict`,
+`val`, and `compile` commands also delegate to this package.
+
+## Command line
+
+The standalone package provides the `mblt-vision` command with `predict`, `val`,
+and `compile` subcommands:
+
+```bash
+mblt-vision predict --source image.jpg --model resnet50
+```
+
+`predict` is the single inference command for classification, depth estimation,
+object and face detection, instance and semantic segmentation, OBB, and pose
+estimation. The selected model determines its task and processing pipeline.
+By default it downloads the model artifact and saves a plotted result under
+`runs/vision/predict/`. Use `--output` to choose the result-image path,
+`--topk` for classification labels, and `--conf-thres`/`--iou-thres` for
+detection-style tasks. `--framework onnx` selects ONNX Runtime inference;
+`--target-device` and `--core-mode` select the MXQ board/runtime mode.
+
+```bash
+mblt-vision predict --source image.jpg --model yolo11m --conf-thres 0.4 --output result.jpg
+mblt-vision predict --source image.jpg --model yolo11m-pose --target-device regulus-ra --core-mode single
+```
+
+The corresponding `mblt-model-zoo` commands use the same standalone handlers for
+backward compatibility.
+
+## Documentation and tests
+
+See [the Vision API guide](mblt_vision/README.md) for supported model families,
+model details, artifact selection, and output taxonomy behavior. See the
+[compilation guide](compile/README.md) for calibration-data preparation
+and MXQ compilation. The [test guide](tests/TEST.md) explains offline, Hugging
+Face, and NPU test runs.
+
+## Support and issues
+
+For installation, model, or runtime support, visit the
+[Mobilint forum](https://discuss.mobilint.com/). Report reproducible package issues in the
+[mblt-vision-python issue tracker](https://github.com/mobilint/mblt-vision-python/issues).
+
+## License
+
+Distributed under the [BSD 3-Clause License](LICENSE).

mblt_vision_python-0.0.0/mblt_vision/__init__.py

@@ -0,0 +1,86 @@
+"""MBLT vision task exports and discovery helpers.
+
+The vision package keeps task subpackages as the preferred import surface while
+also supporting legacy top-level model imports such as
+``from mblt_model_zoo.vision import ResNet50``.
+"""
+
+from __future__ import annotations
+
+from . import depth_estimation as depth_estimation
+from . import face_detection as face_detection
+from . import image_classification as image_classification
+from . import instance_segmentation as instance_segmentation
+from . import obb as obb
+from . import object_detection as object_detection
+from . import pose_estimation as pose_estimation
+from . import semantic_segmentation as semantic_segmentation
+from ._api import list_models as list_models
+from ._api import list_tasks as list_tasks
+from .wrapper import MBLT_Engine as MBLT_Engine
+
+__version__ = "0.0.0"
+
+_TASK_MODULES = (
+    face_detection,
+    depth_estimation,
+    image_classification,
+    instance_segmentation,
+    object_detection,
+    obb,
+    pose_estimation,
+    semantic_segmentation,
+)
+
+_LEGACY_MODEL_EXPORTS: dict[str, object] = {}
+for _task_module in _TASK_MODULES:
+    for _export_name in getattr(_task_module, "__all__", ()):
+        if _export_name in _LEGACY_MODEL_EXPORTS:
+            raise RuntimeError(
+                f"Duplicate vision export detected for '{_export_name}'."
+            )
+        _LEGACY_MODEL_EXPORTS[_export_name] = _task_module
+
+_PUBLIC_EXPORTS = [
+    "MBLT_Engine",
+    "list_models",
+    "list_tasks",
+    "face_detection",
+    "depth_estimation",
+    "image_classification",
+    "instance_segmentation",
+    "object_detection",
+    "obb",
+    "pose_estimation",
+    "semantic_segmentation",
+] + sorted(_LEGACY_MODEL_EXPORTS)
+# Keep legacy compatibility exports synchronized with their task packages.
+__all__: list[str] = _PUBLIC_EXPORTS  # pyright: ignore[reportUnsupportedDunderAll]
+
+
+def __getattr__(name: str) -> object:
+    """Lazily resolve legacy top-level model exports.
+
+    Args:
+        name: Attribute requested from the vision package.
+
+    Returns:
+        The exported model wrapper class for the requested legacy name.
+
+    Raises:
+        AttributeError: If the requested name is not exported by the package.
+    """
+
+    task_module = _LEGACY_MODEL_EXPORTS.get(name)
+    if task_module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    value = getattr(task_module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return package attributes including lazy legacy exports."""
+
+    return sorted(set(globals()) | set(__all__))

mblt_vision_python-0.0.0/mblt_vision/_api.py

@@ -0,0 +1,53 @@
+"""Public helpers for discovering available vision tasks and models."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from typing import Iterable
+
+from ._tasks import VISION_TASKS, normalize_vision_task
+from .wrapper import MBLT_Engine
+
+
+def list_tasks() -> list[str]:
+    """Lists the available vision tasks."""
+
+    return list(VISION_TASKS)
+
+
+def list_models(tasks: str | Iterable[str] | None = None) -> dict[str, list[str]]:
+    """Lists available models for the selected vision tasks.
+
+    Args:
+        tasks: Task name or names to inspect. When omitted, all tasks are used.
+
+    Returns:
+        A mapping of task name to exported model class names.
+
+    Raises:
+        ValueError: If an unknown task name is provided.
+    """
+
+    if tasks is None:
+        task_list = list(VISION_TASKS)
+    elif isinstance(tasks, str):
+        task_list = [tasks]
+    else:
+        task_list = list(tasks)
+
+    available_models: dict[str, list[str]] = {}
+    for task in task_list:
+        module_name = normalize_vision_task(task)
+        module = importlib.import_module(
+            f".{module_name}", package=__name__.replace("._api", "")
+        )
+        available_models[task] = sorted(
+            name
+            for name, obj in inspect.getmembers(module, inspect.isclass)
+            if issubclass(obj, MBLT_Engine)
+            and obj is not MBLT_Engine
+            and not getattr(obj, "_yaml_missing", False)
+        )
+
+    return available_models

mblt_vision_python-0.0.0/mblt_vision/_compat.py

@@ -0,0 +1,227 @@
+"""Compatibility helpers for YAML-backed vision model exports.
+
+This module rebuilds the legacy task package exports that were removed during
+the YAML migration. The generated classes keep the familiar import paths and
+constructor shape while delegating model loading to ``MBLT_Engine``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Iterable, Sequence, TypeAlias, cast
+
+from ._model_paths import uses_shifted_compat_model_path_layout
+from .wrapper import CoreMode, MBLT_Engine
+
+_MODEL_DIR = Path(__file__).parent / "models"
+
+
+class CompatMBLTEngine(MBLT_Engine):
+    """Typed base for dynamically generated legacy compatibility wrappers."""
+
+    def __init__(
+        self,
+        local_path: str | None = None,
+        model_type: str = "DEFAULT",
+        infer_mode: CoreMode = "global8",
+        product: str = "aries",
+        dev_no: int = 0,
+        target_cores: Sequence[str] | None = None,
+        target_clusters: Sequence[int] | None = None,
+        mxq_path: str | None = None,
+        onnx_path: str | None = None,
+        framework: str | None = None,
+        model_path: str | None = None,
+    ) -> None:
+        """Type-only constructor matching the generated legacy wrappers."""
+        del (
+            local_path,
+            model_type,
+            infer_mode,
+            product,
+            dev_no,
+            target_cores,
+            target_clusters,
+            model_path,
+            mxq_path,
+            onnx_path,
+            framework,
+        )
+        raise NotImplementedError
+
+
+CompatMBLTEngineClass: TypeAlias = type[CompatMBLTEngine]
+
+
+def _normalize_name(value: str) -> str:
+    """Returns an alphanumeric-only, case-insensitive identifier."""
+
+    return "".join(char for char in value.lower() if char.isalnum())
+
+
+def _resolve_yaml_name(class_name: str) -> str:
+    """Resolves the YAML config stem associated with a legacy class name.
+
+    Args:
+        class_name: Exported legacy class name.
+
+    Returns:
+        The YAML filename stem without the ``.yaml`` suffix.
+
+    Raises:
+        ValueError: If no unique matching YAML file can be determined.
+    """
+
+    yaml_stems = [path.stem for path in _MODEL_DIR.glob("*.yaml")]
+
+    exact_matches = [stem for stem in yaml_stems if stem.lower() == class_name.lower()]
+    if len(exact_matches) == 1:
+        return exact_matches[0]
+
+    normalized_name = _normalize_name(class_name)
+    normalized_matches = [
+        stem for stem in yaml_stems if _normalize_name(stem) == normalized_name
+    ]
+    if len(normalized_matches) == 1:
+        return normalized_matches[0]
+
+    if not normalized_matches:
+        raise ValueError(
+            f"Could not find a YAML config for legacy class '{class_name}'."
+        )
+
+    raise ValueError(
+        f"Found multiple YAML configs for legacy class '{class_name}': {sorted(normalized_matches)}."
+    )
+
+
+def _build_init(yaml_name: str) -> Callable[..., None]:
+    """Builds a legacy-compatible ``__init__`` implementation."""
+
+    def __init__(
+        self,
+        local_path: str | None = None,
+        model_type: str = "DEFAULT",
+        infer_mode: CoreMode = "global8",
+        product: str = "aries",
+        dev_no: int = 0,
+        target_cores: Sequence[str] | None = None,
+        target_clusters: Sequence[int] | None = None,
+        mxq_path: str | None = None,
+        onnx_path: str | None = None,
+        framework: str | None = None,
+        model_path: str | None = None,
+    ) -> None:
+        """Initializes a YAML-backed compatibility wrapper.
+
+        Args:
+            local_path: Deprecated legacy MXQ path alias. Prefer ``model_path``
+                for generic MXQ or ONNX loading, or ``mxq_path`` for an
+                explicit MXQ-only override.
+            model_type: YAML config variant to load.
+            infer_mode: Execution mode forwarded to ``MBLT_Engine``.
+            product: Legacy product/board value forwarded as ``target_device``.
+            dev_no: Accelerator device number.
+            target_cores: Optional core selection for single-core mode.
+            target_clusters: Optional cluster selection for multi/global modes.
+            mxq_path: Optional explicit MXQ path alias.
+            onnx_path: Optional explicit ONNX path.
+            framework: Execution framework, either ``"mxq"`` or ``"onnx"``. When
+                omitted, ``model_path`` suffix is used first, then MXQ is the fallback.
+            model_path: Optional explicit local model path for MXQ or ONNX.
+        """
+
+        if uses_shifted_compat_model_path_layout(
+            model_path, mxq_path, onnx_path, framework
+        ):
+            model_path, mxq_path, onnx_path, framework = (
+                mxq_path,
+                onnx_path,
+                framework,
+                cast(str | None, model_path),
+            )
+        MBLT_Engine.__init__(
+            self,
+            model_cls=yaml_name,
+            model_type=model_type,
+            model_path=model_path or "",
+            mxq_path=mxq_path or local_path or "",
+            onnx_path=onnx_path or "",
+            dev_no=dev_no,
+            core_mode=infer_mode,
+            target_cores=list(target_cores) if target_cores is not None else None,
+            target_clusters=list(target_clusters)
+            if target_clusters is not None
+            else None,
+            target_device=product,
+            framework=framework,
+        )
+
+    return __init__
+
+
+def _build_missing_init(class_name: str, reason: str) -> Callable[..., None]:
+    """Builds an ``__init__`` that fails with a clear compatibility message."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Raises an informative error for removed YAML-backed models."""
+
+        del args, kwargs
+        raise ValueError(
+            f"Legacy vision model '{class_name}' is not available in the YAML model registry: {reason}"
+        )
+
+    return __init__
+
+
+def create_model_class(class_name: str, module_name: str) -> CompatMBLTEngineClass:
+    """Creates a legacy model class that delegates to ``MBLT_Engine``.
+
+    Args:
+        class_name: Class name to expose from the task module.
+        module_name: Module path that should own the generated class.
+
+    Returns:
+        A dynamically generated ``MBLT_Engine`` subclass.
+    """
+
+    class_doc = f"Compatibility wrapper for the legacy ``{class_name}`` vision model."
+    try:
+        yaml_name = _resolve_yaml_name(class_name)
+    except ValueError as exc:
+        return type(
+            class_name,
+            (CompatMBLTEngine,),
+            {
+                "__doc__": class_doc,
+                "__init__": _build_missing_init(class_name, str(exc)),
+                "__module__": module_name,
+                "_yaml_missing": True,
+            },
+        )
+
+    return type(
+        class_name,
+        (CompatMBLTEngine,),
+        {
+            "__doc__": class_doc,
+            "__init__": _build_init(yaml_name),
+            "__module__": module_name,
+            "_yaml_name": yaml_name,
+        },
+    )
+
+
+def export_model_classes(
+    namespace: dict[str, Any], class_names: Iterable[str], module_name: str
+) -> None:
+    """Populates a module namespace with generated model classes.
+
+    Args:
+        namespace: Target module globals.
+        class_names: Legacy class names to generate.
+        module_name: Import path for generated classes.
+    """
+
+    for class_name in class_names:
+        namespace[class_name] = create_model_class(class_name, module_name)