mas-ods 0.2.4__tar.gz

mas_ods-0.2.4/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.3
+Name: mas-ods
+Version: 0.2.4
+Summary: Ultra-lightweight, high-accuracy single-class person detection library
+Author: MASWorld, Prasad Maskar
+Author-email: MASWorld <masworldit@gmail.com>, Prasad Maskar <prasad.maskar7@gmail.com>
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: nvidia-cudnn-cu12>=9.24.0.43
+Requires-Dist: onnx>=1.16.0
+Requires-Dist: onnxruntime>=1.18.0
+Requires-Dist: onnxruntime-gpu>=1.18.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: nvidia-cudnn-cu12>=9.0.0 ; extra == 'gpu'
+Requires-Dist: nvidia-cublas-cu12>=12.0.0 ; extra == 'gpu'
+Requires-Python: >=3.13
+Provides-Extra: gpu
+Description-Content-Type: text/markdown
+
+# 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("yolox_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
+
+```bash
+# Using uv (recommended)
+uv add mas-ods
+
+# Or using pip
+pip install mas-ods
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Python API (Zero Setup — Auto Downloads Model)
+
+```python
+import cv2
+from mas_ods import PersonDetector
+
+# 1. Initialize detector by model name (automatically downloads if not cached)
+# Models available: "yolox_nano", "nanodet-plus-m_320", "nanodet-plus-m_416", "yolox_tiny", "yolox_s", "yolox_m"
+detector = PersonDetector(
+    model="yolox_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
+
+```python
+from mas_ods import PersonDetector, VideoPipeline
+
+detector = PersonDetector(model="yolox_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
+
+| Model Name | Input Shape | Model Size | Description |
+| :--- | :--- | :--- | :--- |
+| **`yolox_nano`** | 416x416 | **~3.7 MB** | Ultra-lightweight (0.91M params), 150–250+ FPS on CPU |
+| **`nanodet-plus-m_320`** | 320x320 | **~4.8 MB** | Ultra-fast anchor-free CPU detector |
+| **`nanodet-plus-m_416`** | 416x416 | **~4.8 MB** | High resolution anchor-free CPU detector |
+| **`nanodet-plus-m-1.5x_416`** | 416x416 | **~9.9 MB** | High accuracy anchor-free detector |
+| **`yolox_tiny`** | 416x416 | **~20.2 MB**| Balanced speed and accuracy (~5M params) |
+| **`yolox_s`** | 640x640 | **~35.9 MB**| Small detector (~9M params), great for GPU |
+| **`yolox_m`** | 640x640 | **~101.3 MB**| Medium detector (~25M params) |
+
+---
+
+## 🖥️ Command-Line Interface (CLI)
+
+### List Available Models in the Catalog
+```bash
+mas-ods models
+```
+
+### Check Hardware & Available Execution Providers
+```bash
+mas-ods devices
+```
+
+### Benchmark Latency & Throughput (FPS)
+```bash
+mas-ods benchmark --model yolox_nano --device auto --iterations 100
+```
+
+### Run Detection via CLI
+```bash
+mas-ods detect --model yolox_nano --source test.jpg --device auto --save output.jpg
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [Apache License 2.0](LICENSE) - free for both commercial and personal use.

mas_ods-0.2.4/README.md

@@ -0,0 +1,119 @@
+# 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("yolox_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
+
+```bash
+# Using uv (recommended)
+uv add mas-ods
+
+# Or using pip
+pip install mas-ods
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Python API (Zero Setup — Auto Downloads Model)
+
+```python
+import cv2
+from mas_ods import PersonDetector
+
+# 1. Initialize detector by model name (automatically downloads if not cached)
+# Models available: "yolox_nano", "nanodet-plus-m_320", "nanodet-plus-m_416", "yolox_tiny", "yolox_s", "yolox_m"
+detector = PersonDetector(
+    model="yolox_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
+
+```python
+from mas_ods import PersonDetector, VideoPipeline
+
+detector = PersonDetector(model="yolox_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
+
+| Model Name | Input Shape | Model Size | Description |
+| :--- | :--- | :--- | :--- |
+| **`yolox_nano`** | 416x416 | **~3.7 MB** | Ultra-lightweight (0.91M params), 150–250+ FPS on CPU |
+| **`nanodet-plus-m_320`** | 320x320 | **~4.8 MB** | Ultra-fast anchor-free CPU detector |
+| **`nanodet-plus-m_416`** | 416x416 | **~4.8 MB** | High resolution anchor-free CPU detector |
+| **`nanodet-plus-m-1.5x_416`** | 416x416 | **~9.9 MB** | High accuracy anchor-free detector |
+| **`yolox_tiny`** | 416x416 | **~20.2 MB**| Balanced speed and accuracy (~5M params) |
+| **`yolox_s`** | 640x640 | **~35.9 MB**| Small detector (~9M params), great for GPU |
+| **`yolox_m`** | 640x640 | **~101.3 MB**| Medium detector (~25M params) |
+
+---
+
+## 🖥️ Command-Line Interface (CLI)
+
+### List Available Models in the Catalog
+```bash
+mas-ods models
+```
+
+### Check Hardware & Available Execution Providers
+```bash
+mas-ods devices
+```
+
+### Benchmark Latency & Throughput (FPS)
+```bash
+mas-ods benchmark --model yolox_nano --device auto --iterations 100
+```
+
+### Run Detection via CLI
+```bash
+mas-ods detect --model yolox_nano --source test.jpg --device auto --save output.jpg
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [Apache License 2.0](LICENSE) - free for both commercial and personal use.

mas_ods-0.2.4/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "mas-ods"
+version = "0.2.4"
+description = "Ultra-lightweight, high-accuracy single-class person detection library"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "numpy>=2.0.0",
+    "nvidia-cudnn-cu12>=9.24.0.43",
+    "onnx>=1.16.0",
+    "onnxruntime>=1.18.0",
+    "onnxruntime-gpu>=1.18.0",
+    "opencv-python>=4.8.0",
+    "pillow>=10.0.0",
+]
+
+[[project.authors]]
+name = "MASWorld"
+email = "masworldit@gmail.com"
+
+[[project.authors]]
+name = "Prasad Maskar"
+email = "prasad.maskar7@gmail.com"
+
+[project.optional-dependencies]
+gpu = [
+    "nvidia-cudnn-cu12>=9.0.0",
+    "nvidia-cublas-cu12>=12.0.0",
+]
+
+[project.scripts]
+mas-ods = "mas_ods.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

mas_ods-0.2.4/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "mas-ods"
+version = "0.2.4"
+description = "Ultra-lightweight, high-accuracy single-class person detection library"
+readme = "README.md"
+authors = [
+    { name = "MASWorld", email = "masworldit@gmail.com" },
+    { name = "Prasad Maskar", email="prasad.maskar7@gmail.com"}
+]
+requires-python = ">=3.13"
+dependencies = [
+    "numpy>=2.0.0",
+    "nvidia-cudnn-cu12>=9.24.0.43",
+    "onnx>=1.16.0",
+    "onnxruntime>=1.18.0",
+    "onnxruntime-gpu>=1.18.0",
+    "opencv-python>=4.8.0",
+    "pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+gpu = [
+    "nvidia-cudnn-cu12>=9.0.0",
+    "nvidia-cublas-cu12>=12.0.0",
+]
+
+[project.scripts]
+mas-ods = "mas_ods.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

mas_ods-0.2.4/src/mas_ods/__init__.py

@@ -0,0 +1,82 @@
+"""
+mas-ods: Ultra-lightweight, high-accuracy single-class person detection engine & model hub.
+"""
+
+__version__ = "0.2.4"
+__author__ = "MASWorld"
+
+from mas_ods.core.structures import (
+    BoundingBox,
+    DetectionResult,
+    DeviceType,
+    Keypoint,
+    PoseResult,
+    MultiPoseResult,
+    HandResult,
+    TrackedObject,
+    COCO_KEYPOINTS,
+    COCO_SKELETON_EDGES,
+    HAND_LANDMARK_EDGES,
+)
+from mas_ods.core.config import DetectorConfig
+from mas_ods.pipeline.detector import PersonDetector
+from mas_ods.pipeline.vehicle import VehicleDetector, COCO_VEHICLE_CLASSES
+from mas_ods.pipeline.pose import PoseDetector
+from mas_ods.pipeline.hand import HandDetector, HandTracker
+from mas_ods.pipeline.palm import PalmDetector
+from mas_ods.pipeline.stream import VideoPipeline
+from mas_ods.tracking.tracker import ByteTracker
+from mas_ods.tracking.counter import LineCrossingCounter
+from mas_ods.processing.visualizer import Visualizer
+from mas_ods.benchmark.profiler import BenchmarkProfiler
+from mas_ods.models.hub import (
+    MODEL_REGISTRY,
+    resolve_model,
+    list_models,
+    get_model_info,
+)
+from mas_ods.engine.hardware import (
+    get_available_providers,
+    is_gpu_available,
+    is_cuda_available,
+    is_directml_available,
+    get_hardware_info,
+)
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "BoundingBox",
+    "DetectionResult",
+    "DeviceType",
+    "DetectorConfig",
+    "Keypoint",
+    "PoseResult",
+    "MultiPoseResult",
+    "HandResult",
+    "TrackedObject",
+    "COCO_KEYPOINTS",
+    "COCO_SKELETON_EDGES",
+    "HAND_LANDMARK_EDGES",
+    "COCO_VEHICLE_CLASSES",
+    "PersonDetector",
+    "VehicleDetector",
+    "PalmDetector",
+    "HandDetector",
+    "HandTracker",
+    "PoseDetector",
+    "ByteTracker",
+    "LineCrossingCounter",
+    "Visualizer",
+    "VideoPipeline",
+    "BenchmarkProfiler",
+    "MODEL_REGISTRY",
+    "resolve_model",
+    "list_models",
+    "get_model_info",
+    "get_available_providers",
+    "is_gpu_available",
+    "is_cuda_available",
+    "is_directml_available",
+    "get_hardware_info",
+]

mas_ods-0.2.4/src/mas_ods/benchmark/__init__.py

@@ -0,0 +1,3 @@
+from mas_ods.benchmark.profiler import BenchmarkProfiler
+
+__all__ = ["BenchmarkProfiler"]

mas_ods-0.2.4/src/mas_ods/benchmark/profiler.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import logging
+from typing import Dict, Any, Tuple
+import numpy as np
+
+from mas_ods.pipeline.detector import PersonDetector
+
+logger = logging.getLogger(__name__)
+
+
+class BenchmarkProfiler:
+    """
+    Measures latency percentiles, throughput (FPS), and execution breakdown
+    for ONNX models across CPU and GPU backends.
+    """
+
+    def __init__(self, detector: PersonDetector):
+        self.detector = detector
+
+    def run(
+        self,
+        iterations: int = 100,
+        warmup_iterations: int = 10,
+        image_shape: Tuple[int, int] = (640, 640),
+    ) -> Dict[str, Any]:
+        """
+        Executes benchmark with synthetic image frames.
+        """
+        h, w = image_shape
+        dummy_frame = (np.random.rand(h, w, 3) * 255).astype(np.uint8)
+
+        # Warmup
+        for _ in range(warmup_iterations):
+            _ = self.detector.predict(dummy_frame)
+
+        # Timed runs
+        total_latencies = []
+        preprocess_latencies = []
+        inference_latencies = []
+        postprocess_latencies = []
+
+        for _ in range(iterations):
+            res = self.detector.predict(dummy_frame)
+            total_latencies.append(res.total_time_ms)
+            preprocess_latencies.append(res.preprocess_time_ms)
+            inference_latencies.append(res.inference_time_ms)
+            postprocess_latencies.append(res.postprocess_time_ms)
+
+        total_latencies = np.array(total_latencies)
+        inference_latencies = np.array(inference_latencies)
+
+        mean_total = float(np.mean(total_latencies))
+        p50 = float(np.percentile(total_latencies, 50))
+        p95 = float(np.percentile(total_latencies, 95))
+        p99 = float(np.percentile(total_latencies, 99))
+        min_lat = float(np.min(total_latencies))
+        max_lat = float(np.max(total_latencies))
+        fps = 1000.0 / mean_total if mean_total > 0 else 0.0
+
+        mean_infer = float(np.mean(inference_latencies))
+        mean_pre = float(np.mean(preprocess_latencies))
+        mean_post = float(np.mean(postprocess_latencies))
+
+        report = {
+            "model_name": self.detector.model_name,
+            "active_provider": self.detector.active_provider,
+            "iterations": iterations,
+            "mean_latency_ms": round(mean_total, 2),
+            "inference_latency_ms": round(mean_infer, 2),
+            "preprocess_latency_ms": round(mean_pre, 2),
+            "postprocess_latency_ms": round(mean_post, 2),
+            "p50_ms": round(p50, 2),
+            "p95_ms": round(p95, 2),
+            "p99_ms": round(p99, 2),
+            "min_ms": round(min_lat, 2),
+            "max_ms": round(max_lat, 2),
+            "fps": round(fps, 1),
+        }
+
+        return report
+
+    @staticmethod
+    def format_table(report: Dict[str, Any]) -> str:
+        """Formats report as a clean ASCII table."""
+        lines = [
+            "=" * 55,
+            "  MAS-ODS PERFORMANCE BENCHMARK REPORT",
+            "=" * 55,
+            f"  Model:            {report['model_name']}",
+            f"  Provider:         {report['active_provider']}",
+            f"  Iterations:       {report['iterations']}",
+            "-" * 55,
+            f"  Throughput (FPS): {report['fps']:.1f} FPS",
+            f"  Mean Total:       {report['mean_latency_ms']:.2f} ms",
+            f"  Pure Inference:   {report['inference_latency_ms']:.2f} ms",
+            f"  Pre-processing:   {report['preprocess_latency_ms']:.2f} ms",
+            f"  Post-processing:  {report['postprocess_latency_ms']:.2f} ms",
+            "-" * 55,
+            f"  Latency P50:      {report['p50_ms']:.2f} ms",
+            f"  Latency P95:      {report['p95_ms']:.2f} ms",
+            f"  Latency P99:      {report['p99_ms']:.2f} ms",
+            f"  Latency Min/Max:  {report['min_ms']:.2f} ms / {report['max_ms']:.2f} ms",
+            "=" * 55,
+        ]
+        return "\n".join(lines)

mas_ods-0.2.4/src/mas_ods/cli/__init__.py

@@ -0,0 +1,3 @@
+from mas_ods.cli.main import main
+
+__all__ = ["main"]