Metadata-Version: 2.3
Name: mas-lwym
Version: 0.2.2
Summary: Ultra-lightweight, high-accuracy single-class person detection library
Author: MASWorld
Author-email: MASWorld <masworldit@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-lwym 🚀

**mas-lwym** 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-lwym** 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-lwym

# Or using pip
pip install mas-lwym
```

---

## 🚀 Quickstart

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

```python
import cv2
from mas_lwym 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_lwym 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-lwym models
```

### Check Hardware & Available Execution Providers
```bash
mas-lwym devices
```

### Benchmark Latency & Throughput (FPS)
```bash
mas-lwym benchmark --model yolox_nano --device auto --iterations 100
```

### Run Detection via CLI
```bash
mas-lwym 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.
