mas-ods 🚀

mas-ods is an ultra-lightweight, high-accuracy, single-class (person) object detection engine and model hub designed for extreme cost efficiency and high throughput on CPUs, edge devices, and GPUs.

Built from the ground up for production deployment, mas-ods runs exclusively on ONNX Runtime with pure NumPy/OpenCV pre/post-processing, automatic model downloading from Google Drive into a local .models/ directory, seamless CPU/GPU/AUTO hardware toggles, and 100% Apache-2.0 commercial compliance.

🌟 Key Features

• ⚡ Ultra-Lightweight & Fast: Sub-5ms latency and 150–250+ FPS on standard CPUs.
• 🌐 Dynamic Model Hub (Auto-Download): Simply pass the model name (e.g. PersonDetector("masx_nano")) and the model is automatically downloaded into .models/ on first run.
• 🎯 Single-Class Person Focus: Eliminates multi-class softmax/NMS overhead for maximum efficiency.
• 💻 Pure ONNX Runtime Core: No heavy PyTorch or PaddlePaddle dependencies needed during inference.
• 🔄 AUTO Hardware Acceleration: Choose between device="auto", "cpu", "gpu", "cuda", or "directml" with automatic graceful fallback.
• 📊 Profiling & Diagnostics: Built-in latency (P50/P95/P99), FPS, and hardware execution provider benchmark suite.
• ⚖️ Commercial Friendly: Free from copyleft/AGPL constraints (Apache-2.0).

📦 Installation

# Using uv (recommended)
uv add mas-ods

# Or using pip
pip install mas-ods

🚀 Quickstart

1. Python API (Zero Setup — Auto Downloads Model)

import cv2
from mas_ods import PersonDetector

# 1. Initialize detector by model name (automatically downloads if not cached)
# Models available: "masx_nano", "nanodet-plus-m_320", "nanodet-plus-m_416", "masx_tiny", "masx_s", "masx_m"
detector = PersonDetector(
    model="masx_nano",         # or pass custom local file path: "path/to/model.onnx"
    device="auto",              # "auto" (prioritizes GPU with CPU fallback) | "cpu" | "gpu"
    confidence_threshold=0.40,  # Filter out low-confidence predictions
    iou_threshold=0.45,         # NMS IoU threshold
)

# 2. Run inference on an image (filepath, numpy array, or PIL image)
image = cv2.imread("street.jpg")
result = detector.predict(image)

print(f"Persons detected: {result.count}")
print(f"Total time: {result.total_time_ms:.2f} ms ({result.fps:.1f} FPS)")

for box in result.boxes:
    print(f"Coordinates: {box.xyxy} | Confidence: {box.score:.2f}")

# 3. Render bounding boxes and HUD overlay
annotated_frame = detector.render(image, result, show_fps=True)
cv2.imwrite("output.jpg", annotated_frame)

2. Real-Time Webcam / Video Stream

from mas_ods import PersonDetector, VideoPipeline

detector = PersonDetector(model="masx_nano", device="auto")
pipeline = VideoPipeline(detector)

# Stream from webcam (0) or video file ("video.mp4")
pipeline.process_stream(source=0, show=True)

📋 Available Model Catalog

🖥️ Command-Line Interface (CLI)

List Available Models in the Catalog

mas-ods models

Check Hardware & Available Execution Providers

mas-ods devices

Benchmark Latency & Throughput (FPS)

mas-ods benchmark --model masx_nano --device auto --iterations 100

Run Detection via CLI

mas-ods detect --model masx_nano --source test.jpg --device auto --save output.jpg

📄 License

This project is licensed under the Apache License 2.0 - free for both commercial and personal use.