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

# Using uv (recommended)
uv add mas-lwym

# Or using pip
pip install mas-lwym

🚀 Quickstart

1. Python API

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

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)

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

mas-lwym devices

Benchmark Model Latency & FPS

mas-lwym benchmark --model models/picodet_s_320_pedestrian.onnx --device cpu --iterations 100

Run Detection via CLI

mas-lwym detect --model models/picodet_s_320_pedestrian.onnx --source frame.jpg --device cpu --save output.jpg

Convert Checkpoints to ONNX

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 - free for both commercial and personal use.