Metadata-Version: 2.5
Name: modelmaite
Version: 0.2.0
Summary: MAITE-compliant model wrappers built on the maite protocols
Author: OpenTeams
License: Apache-2.0
License-File: LICENSE.md
Keywords: artificial intelligence,jatic,maite,models
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: numpy>=1.24; python_version < '3.13'
Requires-Dist: numpy>=2.1; python_version == '3.13'
Requires-Dist: numpy>=2.3.2; python_version >= '3.14'
Requires-Dist: typing-extensions>=4.5
Provides-Extra: mot
Requires-Dist: supervision>=0.26.1; extra == 'mot'
Requires-Dist: trackers>=2.5.0; extra == 'mot'
Provides-Extra: onnx
Requires-Dist: onnx!=1.19.0,!=1.22.0,>=1.14.0; (python_version == '3.13') and extra == 'onnx'
Requires-Dist: onnx!=1.19.0,>=1.14.0; (python_version != '3.13') and extra == 'onnx'
Requires-Dist: onnxruntime<1.24.0,>=1.19.0; (python_version < '3.11') and extra == 'onnx'
Requires-Dist: onnxruntime<1.29.0,>=1.19.0; (python_version >= '3.11' and python_version < '3.14') and extra == 'onnx'
Requires-Dist: onnxruntime<1.29.0,>=1.25.0; (python_version >= '3.14') and extra == 'onnx'
Provides-Extra: onnx-cuda
Requires-Dist: onnx!=1.19.0,!=1.22.0,>=1.14.0; (python_version == '3.13') and extra == 'onnx-cuda'
Requires-Dist: onnx!=1.19.0,>=1.14.0; (python_version != '3.13') and extra == 'onnx-cuda'
Requires-Dist: onnxruntime-gpu<1.24.0,>=1.19.0; (python_version < '3.11') and extra == 'onnx-cuda'
Requires-Dist: onnxruntime-gpu<1.29.0,>=1.19.0; (python_version >= '3.11' and python_version < '3.14') and extra == 'onnx-cuda'
Requires-Dist: onnxruntime-gpu<1.29.0,>=1.25.0; (python_version >= '3.14') and extra == 'onnx-cuda'
Provides-Extra: torchvision
Requires-Dist: torch>=2.4.0; extra == 'torchvision'
Requires-Dist: torchvision>=0.19.0; extra == 'torchvision'
Provides-Extra: visdrone
Requires-Dist: httpx>=0.28.1; extra == 'visdrone'
Requires-Dist: smqtk-detection>=0.22.0; extra == 'visdrone'
Requires-Dist: torch>=2.4.0; extra == 'visdrone'
Description-Content-Type: text/markdown

# modelmaite - MAITE-compliant model wrappers

`modelmaite` is a Python package providing model utilities built on the
[maite](https://mit-ll-ai-technology.github.io/maite/) protocols.

**THIS PACKAGE IS CURRENTLY UNDER CONSTRUCTION**

## Model wrappers

`modelmaite.image_classification.TorchvisionICModel` wraps torchvision image-classification
models as MAITE-compatible image-classification models.

`modelmaite.image_classification.OnnxICModel` wraps JATIC_ONNX v1 image-classification
models as MAITE-compatible image-classification models.

`modelmaite.object_detection.TorchvisionODModel` wraps torchvision object-detection
models as MAITE-compatible object-detection models.

`modelmaite.object_detection.VisdroneODModel` wraps Kitware CenterNet VisDrone
models as MAITE-compatible object-detection models.

`modelmaite.object_detection.OnnxODModel` wraps JATIC_ONNX v1 object-detection
models as MAITE-compatible object-detection models.

`modelmaite.multiobject_tracking.ByteTrackMOTModel` combines any MAITE-compatible
object-detection model with ByteTrack to produce MAITE-compatible multi-object tracks.

## Installation

The core install contains no model runtime; each wrapper needs an optional
extra:

| Extra | Wrappers |
| --- | --- |
| `torchvision` | `TorchvisionICModel`, `TorchvisionODModel` |
| `visdrone` | `VisdroneODModel` |
| `onnx` | `OnnxICModel`, `OnnxODModel` on CPU ONNX Runtime |
| `onnx-cuda` | the same ONNX wrappers on `onnxruntime-gpu` |
| `mot` | `ByteTrackMOTModel` |

```bash
uv add "modelmaite[torchvision]"
```

Prefer one of `onnx` or `onnx-cuda`; they install competing ONNX Runtime builds.
The `mot` and `visdrone` extras must be installed in separate environments: on
Python 3.10–3.12 they resolve incompatible NumPy versions, and the combination
is untested on 3.13+.

The detector is supplied separately, so the MOT wrapper works with any
MAITE-compatible object-detection model.

## Multi-object tracking with datamaite datasets

[`datamaite`](https://pypi.org/project/datamaite/) reads MOTChallenge, TAO, and
VisDrone-video annotations and presents each video as a MAITE multi-object-tracking
dataset, so `ByteTrackMOTModel` consumes them with no reader of its own.

Install the three packages plus the detector's own extra. `datamaite` 0.5.0 is the first
release whose MAITE view streams image-folder sequences; on 0.4.1 and earlier these
datasets load as zero items:

```bash
uv add "modelmaite[mot,torchvision]" "datamaite>=0.5.0" maite
```

The first run of the example below downloads torchvision's SSDLite weights.

```python
from datamaite import load_mot
from maite.tasks import predict

from modelmaite import ByteTrackMOTModel, TorchvisionODModel

dataset = load_mot("/data/MOT17", dataset_format="motchallenge")
detector = TorchvisionODModel(model_name="ssdlite320_mobilenet_v3_large")
predictions, _ = predict(model=ByteTrackMOTModel(detector=detector), dataset=dataset)
```

Use `dataset_format="tao"` or `dataset_format="visdrone_video"` for the other two
readers. `"visdrone"` is the still-image object-detection reader and will not load as a
tracking dataset.

All three formats store a video as a folder of images rather than a single video file,
so they need `datamaite>=0.5.0`, which added the image-sequence MAITE stream.
Decoding frame folders needs only OpenCV, which `modelmaite[mot]` already installs; PyAV
is required for video-file datasets, not these.

### Options worth setting explicitly

**Frame coverage.** `empty_frame_policy` defaults to `"annotated"`, which streams only
the frames carrying annotations. ByteTrack then sees temporal gaps and track quality
drops, so prefer `"all"` where the dataset has an exact frame count:

```python
dataset = load_mot("/data/MOT17", dataset_format="motchallenge").with_mot_options(
    empty_frame_policy="all"
)
```

An exact count comes from `seqinfo.ini`'s `seqLength` (or a frame-file count) for
MOTChallenge, a frame-file count for VisDrone — taken even with the default
`probe_images=False` — and a gap-free frame table for TAO. `probe_images=True` only
fills in frame width and height; it is *not* what enables `"all"`. Without an exact
count, `"all"` logs a warning and falls back to annotated frames.

**Frame timing.** VisDrone annotations carry no frame rate, so the loader defaults to
`fps=0.0` and every frame reports `time_s == 0.0`. Pass `fps=` for real timestamps.
ByteTrack associates detections by IoU, so tracking itself works either way.

**Label spaces do not line up.** A dataset's `index2label` comes from its own categories
and is often sparse; a model's `index2label` is copied from the wrapped detector (the
91-entry COCO map for torchvision). Build the mapping explicitly before scoring
predictions against ground truth — `modelmaite` does not remap labels for you.

**Pair VisDrone data with the torchvision or ONNX detectors, not `VisdroneODModel`.**
The `mot` and `visdrone` extras are mutually exclusive (see above), so ByteTrack and the
VisDrone detector cannot share an environment.

## Authors and acknowledgment

This project was created for [CDAO JATIC](https://cdao.pages.jatic.net/public/)
and is maintained by OpenTeams with collaborative community support.

### CDAO Funding Acknowledgment

<!-- --8<-- [start:acknowledgment] -->

This material is based upon work supported by the Chief Digital and Artificial
Intelligence Office under Contract No. W519TC-25-9-2041. The views and
conclusions contained herein are those of the author(s) and should not be
interpreted as necessarily representing the official policies or endorsements,
either expressed or implied, of the U.S. Government.

<!-- --8<-- [end:acknowledgment] -->
