Metadata-Version: 2.3
Name: mas-lwym
Version: 0.1.2
Summary: Ultra-lightweight, high-accuracy single-class person detection library
Author: MASWorld
Author-email: MASWorld <masworldit@gmail.com>
Requires-Dist: cmake>=4.4.2
Requires-Dist: numpy>=2.0.0
Requires-Dist: onnx>=1.16.0
Requires-Dist: onnxruntime>=1.18.0
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: paddle2onnx>=0.8.1
Requires-Dist: paddlepaddle>=3.0.0
Requires-Dist: pillow>=10.0.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# mas-lwym 🚀

**mas-lwym** is an ultra-lightweight, high-accuracy, single-class (`person`) object detection library designed for extreme cost efficiency and high throughput on commodity 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, zero runtime framework bloat, seamless CPU/GPU hardware toggles, and 100% **Apache-2.0** commercial compliance.

---

## 🌟 Key Features

* **⚡ Ultra-Lightweight & Fast:** Sub-5ms latency and 150–250+ FPS on standard CPUs.
* **🎯 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.
* **🔄 Seamless Hardware Toggle:** Switch between `device="cpu"` and `device="gpu"` with automatic graceful fallback.
* **🛠️ Integrated Converter:** Built-in `convert_to_onnx()` utility to convert checkpoints (.pdparams, .pdmodel) to standalone, graph-optimized ONNX models.
* **📊 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

```python
import cv2
from mas_lwym import PersonDetector

# Initialize detector (CPU by default, or device="gpu" / "cuda" / "directml")
detector = PersonDetector(
    model_path="models/picodet_s_320_pedestrian.onnx",
    device="cpu",               # "cpu" | "gpu" | "cuda" | "directml"
    confidence_threshold=0.40,
    iou_threshold=0.45,
    input_shape=(320, 320),
)

# 1. Run inference on an 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"Confidence: {box.score:.2f} | Coordinates: {box.xyxy}")

# 2. Render bounding boxes and HUD
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_path="models/picodet_s_320_pedestrian.onnx", device="cpu")
pipeline = VideoPipeline(detector)

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

### 3. Model Conversion (`convert_to_onnx`)

```python
from mas_lwym import convert_to_onnx

# Convert Paddle / PicoDet checkpoint to optimized standalone ONNX
convert_to_onnx(
    model_path="models/picodet_s_320_pedestrian",
    output_path="models/picodet_s_320_pedestrian.onnx",
    input_shape=(320, 320),
    simplify=True,
)
```

---

## 🖥️ Command-Line Interface (CLI)

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

### Benchmark Model Latency & FPS
```bash
mas-lwym benchmark --model models/picodet_s_320_pedestrian.onnx --device cpu --iterations 100
```

### Run Detection via CLI
```bash
mas-lwym detect --model models/picodet_s_320_pedestrian.onnx --source frame.jpg --device cpu --save output.jpg
```

### Convert Checkpoints to ONNX
```bash
mas-lwym convert --input models/picodet_s_320_pedestrian --output models/picodet_s_320_pedestrian.onnx --shape 320
```

---

## 📂 Package Architecture

```
src/mas_lwym/
├── core/             # Typed dataclasses (BoundingBox, DetectionResult, DeviceType)
├── engine/           # ONNX Runtime session & hardware provider management
├── processing/       # Vectorized letterbox preprocessor, single-class NMS, visualizer
├── converter/        # Checkpoint to ONNX export router & graph optimizer
├── pipeline/         # High-level PersonDetector and VideoPipeline streams
├── benchmark/        # Latency percentiles (P50/P95/P99) & throughput profiler
└── cli/              # Unified command line tool (mas-lwym)
```

---

## 📄 License

This project is licensed under the [Apache License 2.0](LICENSE) - free for both commercial and personal use.
