Metadata-Version: 2.4
Name: mblt-vision-python
Version: 0.0.3
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

<!-- markdownlint-disable MD033 -->
<div align="center">
<p>
<a href="https://www.mobilint.com/" target="_blank">
<img src="https://raw.githubusercontent.com/mobilint/.github/main/assets/Mobilint_Logo_Primary.png" alt="Mobilint Logo" width="60%">
</a>
</p>
</div>
<!-- markdownlint-enable MD033 -->

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

[![PyPI - Version](https://img.shields.io/pypi/v/mblt-vision-python?logo=pypi&logoColor=white)](https://pypi.org/project/mblt-vision-python/)
[![PyPI Downloads](https://static.pepy.tech/badge/mblt-vision-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://clickpy.clickhouse.com/dashboard/mblt-vision-python)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mblt-vision-python?logo=python&logoColor=gold)](https://pypi.org/project/mblt-vision-python/)

```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

Most models include matching `preprocess`/`postprocess` behavior around a raw
call (mask generation is the exception -- see below):

```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.

Mask generation is promptable, so `SAM2HieraLarge` takes point prompts and
returns candidate masks from a single `predict()` call instead of the separate
`preprocess`/raw-call/`postprocess` steps above:

```python
from mblt_vision.mask_generation import SAM2HieraLarge

model = SAM2HieraLarge()  # framework="onnx" for ONNX Runtime inference
result = model.predict("image.jpg", points=[[320, 240]], labels=[1])
```

See the [mask generation section](mblt_vision/README.md#mask-generation) for the
prompt contract, the two-artifact layout, and SA-V validation.

## 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, pose
estimation, and point-prompted mask generation. 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.

Mask generation models require 1-3 point prompts (`--point X,Y,LABEL`, where
LABEL is 1 for positive and 0 for negative) and load two artifacts, overridden
with `--encoder-mxq-path`/`--decoder-mxq-path` (or the `--encoder-onnx-path`/
`--decoder-onnx-path` pair) rather than `--model-path`/`--mxq-path`/`--onnx-path`.

```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
mblt-vision predict --source image.jpg --model sam2-hiera-large --point 320,240,1
```

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).
