flashdet 1.0.0__tar.gz

flashdet-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gaurav Goswami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flashdet-1.0.0/PKG-INFO

@@ -0,0 +1,473 @@
+Metadata-Version: 2.4
+Name: flashdet
+Version: 1.0.0
+Summary: FlashDet: Ultra-lightweight real-time object detection with LoRA fine-tuning and Knowledge Distillation
+Author: FlashVision
+License: MIT
+Project-URL: Homepage, https://github.com/FlashVision/FlashDet
+Project-URL: Repository, https://github.com/FlashVision/FlashDet
+Project-URL: Issues, https://github.com/FlashVision/FlashDet/issues
+Keywords: object-detection,computer-vision,deep-learning,pytorch,lora,knowledge-distillation,nanodet,edge-ai,onnx,quantization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchvision>=0.15.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: pycocotools>=2.0.6
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.65.0
+Provides-Extra: export
+Requires-Dist: onnx>=1.14.0; extra == "export"
+Requires-Dist: onnxruntime>=1.15.0; extra == "export"
+Requires-Dist: onnxsim>=0.4.0; extra == "export"
+Provides-Extra: tracker
+Requires-Dist: scipy>=1.10.0; extra == "tracker"
+Requires-Dist: lap>=0.4.0; extra == "tracker"
+Provides-Extra: solutions
+Requires-Dist: scipy>=1.10.0; extra == "solutions"
+Provides-Extra: analytics
+Requires-Dist: matplotlib>=3.7.0; extra == "analytics"
+Requires-Dist: pandas>=2.0.0; extra == "analytics"
+Provides-Extra: all
+Requires-Dist: onnx>=1.14.0; extra == "all"
+Requires-Dist: onnxruntime>=1.15.0; extra == "all"
+Requires-Dist: onnxsim>=0.4.0; extra == "all"
+Requires-Dist: scipy>=1.10.0; extra == "all"
+Requires-Dist: lap>=0.4.0; extra == "all"
+Requires-Dist: matplotlib>=3.7.0; extra == "all"
+Requires-Dist: pandas>=2.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/badge/PyTorch-2.0+-ee4c2c?logo=pytorch&logoColor=white" alt="PyTorch">
+  <img src="https://img.shields.io/badge/Python-3.8+-3776ab?logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/ONNX-Export-005CED?logo=onnx&logoColor=white" alt="ONNX">
+  <img src="https://img.shields.io/badge/LoRA-Fine_Tuning-ff6b6b" alt="LoRA">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
+</p>
+
+<h1 align="center">FlashDet</h1>
+
+<p align="center">
+  <b>Ultra-lightweight real-time object detection with LoRA fine-tuning, knowledge distillation, tracking, and analytics</b>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#models">Models</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#solutions">Solutions</a> •
+  <a href="#trackers">Trackers</a> •
+  <a href="#training">Training</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+## What is FlashDet?
+
+FlashDet is an end-to-end object detection framework built for **speed and efficiency**. Based on the NanoDet-Plus architecture with a ShuffleNetV2 backbone, it delivers real-time inference with models as small as 0.49M parameters.
+
+It ships as a `pip`-installable Python package with a CLI, a high-level Python API, and built-in solutions for counting, tracking, speed estimation, and more — similar to how you'd use Ultralytics YOLO.
+
+```bash
+pip install -e .
+flashdet train --model-size m --epochs 100 --device cuda --train-images data/train --val-images data/val
+flashdet predict --model best.pth --source video.mp4
+```
+
+---
+
+## Installation
+
+### pip (recommended)
+
+```bash
+# Install from GitHub
+pip install git+https://github.com/FlashVision/FlashDet.git
+
+# With all extras (tracking, analytics, ONNX export)
+pip install "flashdet[all] @ git+https://github.com/FlashVision/FlashDet.git"
+```
+
+### From source (for development)
+
+```bash
+git clone https://github.com/FlashVision/FlashDet.git
+cd FlashDet
+pip install -e ".[all]"
+```
+
+### Optional extras
+
+```bash
+pip install -e ".[export]"      # ONNX export support
+pip install -e ".[tracker]"     # ByteTracker, SORT, BoTSORT
+pip install -e ".[solutions]"   # Counting, speed, heatmaps
+pip install -e ".[analytics]"   # Benchmarking, plots
+pip install -e ".[all]"         # Everything
+```
+
+### Verify installation
+
+```bash
+flashdet check       # runs full health check
+flashdet settings    # shows Python, PyTorch, CUDA, GPU info
+flashdet version     # prints version
+```
+
+---
+
+## Usage
+
+### Python API
+
+```python
+from flashdet import FlashDet, Trainer, Predictor, Exporter
+
+# Train a model
+trainer = Trainer(
+    model_size="m",
+    train_images="data/train",
+    val_images="data/val",
+    epochs=100,
+    device="cuda",
+    use_lora=True,
+    pretrained_coco=True,
+)
+trainer.train()
+
+# Run inference
+predictor = Predictor(model_path="workspace/best.pth", device="cuda")
+results = predictor.predict("photo.jpg")
+
+# Export to ONNX
+exporter = Exporter(model_path="workspace/best.pth")
+exporter.export(output="model.onnx", simplify=True)
+```
+
+### CLI
+
+```bash
+# Train
+flashdet train --model-size m --epochs 100 --device cuda \
+  --train-images data/train --val-images data/val --pretrained-coco
+
+# Predict
+flashdet predict --model best.pth --source image.jpg --conf 0.25
+
+# Validate
+flashdet val --model best.pth --val-images data/val
+
+# Export
+flashdet export --model best.pth --output model.onnx --simplify
+```
+
+### Standalone Scripts
+
+```bash
+# Full training with LoRA
+python train.py --lora --lora-rank 8 --epochs 50 --device cuda
+
+# Knowledge Distillation
+python train_kd.py --teacher-checkpoint teacher.pth --teacher-size m-1.5x --model-size m-0.5x
+
+# Inference
+python test.py --model best.pth --image photo.jpg
+```
+
+---
+
+## Models
+
+| Model | Params | FP16 Size | INT8 Size | mAP (COCO) | GPU (ms) |
+|-------|--------|-----------|-----------|------------|----------|
+| **FlashDet-m-0.5x** | 0.49M | ~1.2 MB | ~0.6 MB | — | 3.8 |
+| **FlashDet-m** | 1.17M | ~2.6 MB | ~1.3 MB | 27.0 | 5.3 |
+| **FlashDet-m-1.5x** | 2.44M | ~5.2 MB | ~2.6 MB | 29.9 | 7.2 |
+
+All models auto-download COCO pretrained weights on first use.
+
+### Config-driven Training (Model Zoo)
+
+Pick a config and train — no code changes needed:
+
+```bash
+flashdet train --config configs/flashdet_m_320_coco.yaml --device cuda
+flashdet train --config configs/flashdet_m_320_lora.yaml --device cuda
+flashdet train --config configs/flashdet_m_320_kd.yaml --device cuda
+```
+
+Available configs in [`configs/`](configs/):
+| Config | Description |
+|--------|-------------|
+| `flashdet_m_320_coco.yaml` | Standard FlashDet-m training on COCO |
+| `flashdet_m_416_coco.yaml` | FlashDet-m at higher resolution |
+| `flashdet_m15x_320_coco.yaml` | Larger model for better accuracy |
+| `flashdet_m05x_320_coco.yaml` | Ultra-light for edge deployment |
+| `flashdet_m_320_lora.yaml` | LoRA fine-tuning on custom data |
+| `flashdet_m_320_kd.yaml` | Knowledge distillation |
+
+---
+
+## Solutions
+
+Built-in high-level applications for real-world use cases:
+
+```python
+from flashdet import Predictor
+from flashdet.solutions import ObjectCounter, SpeedEstimator, Heatmap, ParkingManager
+from flashdet.trackers import ByteTracker
+
+predictor = Predictor(model_path="best.pth")
+tracker = ByteTracker()
+
+# Count objects crossing a line
+counter = ObjectCounter(predictor, tracker, line_points=[(100, 300), (500, 300)])
+
+# Estimate speeds
+estimator = SpeedEstimator(predictor, tracker, pixels_per_meter=8.0)
+
+# Generate heatmaps
+heatmap = Heatmap(predictor, decay=0.95)
+
+# Monitor parking
+parking = ParkingManager(predictor, spots_file="spots.json")
+```
+
+| Solution | Description |
+|----------|-------------|
+| **ObjectCounter** | Count objects crossing lines or entering regions |
+| **SpeedEstimator** | Estimate real-world speed from tracked objects |
+| **Heatmap** | Visualize detection density over time |
+| **RegionCounter** | Count objects in polygon zones |
+| **QueueManager** | Monitor queue lengths and wait times |
+| **DistanceCalculator** | Measure real-world distances between objects |
+| **ParkingManager** | Track parking spot occupancy |
+| **SecurityAlarm** | Alert on intrusions into restricted zones |
+
+---
+
+## Trackers
+
+Multi-object tracking with persistent IDs across frames:
+
+```python
+from flashdet.trackers import ByteTracker, SORTTracker, BoTSORT
+
+tracker = ByteTracker(max_age=30, min_hits=3, iou_threshold=0.3)
+tracks = tracker.update(detections)  # [x1,y1,x2,y2,track_id,score,cls]
+```
+
+| Tracker | Method | Best For |
+|---------|--------|----------|
+| **ByteTracker** | IoU + Kalman filter | General purpose, fast |
+| **SORTTracker** | Simple Kalman + Hungarian | Speed-critical applications |
+| **BoTSORT** | Appearance + motion | Crowded scenes, re-identification |
+
+---
+
+## Training
+
+### Standard Training
+
+```bash
+python train.py --model-size m --epochs 100 --batch-size 32 --device cuda --pretrained-coco
+```
+
+### LoRA / QLoRA Fine-Tuning
+
+Parameter-efficient — freeze backbone, train only low-rank adapters:
+
+```bash
+# LoRA (6 variants: standard, dora, lora_plus, adalora, ortho, lora_fa)
+python train.py --lora --lora-variant dora --lora-rank 8 --lora-alpha 16
+
+# QLoRA (quantized base weights + LoRA)
+python train.py --qlora --qlora-dtype nf4 --lora-rank 8
+```
+
+### Knowledge Distillation
+
+Train a small student from a larger teacher:
+
+```bash
+python train_kd.py \
+  --teacher-checkpoint workspace/teacher/best.pth \
+  --teacher-size m-1.5x \
+  --model-size m-0.5x \
+  --kd-temperature 4.0
+```
+
+### Mixed Precision & Multi-GPU
+
+```bash
+python train.py --amp --multi-gpu --device cuda
+```
+
+---
+
+## Analytics
+
+```python
+from flashdet.analytics import Benchmark, Profiler
+
+# Benchmark model speed
+bench = Benchmark(model_path="best.pth", device="cuda")
+results = bench.run()  # {'fps': 142.3, 'latency_ms': 7.0, 'params': 1170000, ...}
+
+# Profile layer-by-layer
+profiler = Profiler(model_path="best.pth")
+profiler.run()  # prints per-layer timing breakdown
+```
+
+---
+
+## Examples
+
+Ready-to-run scripts in the [`examples/`](examples/) folder:
+
+| Script | What it does |
+|--------|--------------|
+| `train_custom_dataset.py` | Train on your own COCO-format dataset |
+| `train_with_lora.py` | LoRA fine-tuning (DoRA variant) |
+| `predict_image.py` | Detect objects in a single image |
+| `track_objects.py` | Multi-object tracking on video |
+| `count_objects.py` | Count objects crossing a line |
+| `export_onnx.py` | Export to ONNX for deployment |
+| `benchmark_model.py` | Measure FPS and latency |
+
+```bash
+cd examples
+python train_custom_dataset.py
+python predict_image.py
+```
+
+---
+
+## Project Structure
+
+```
+FlashDet/
+├── flashdet/                  # Main package (pip install -e .)
+│   ├── __init__.py            # Public API
+│   ├── cli.py                 # CLI entry point (flashdet command)
+│   ├── registry.py            # Pluggable component registry
+│   ├── cfg/                   # Configuration + YAML loading
+│   ├── data/                  # Datasets, loaders, transforms
+│   ├── engine/                # Trainer, Validator, Predictor, Exporter, Callbacks
+│   ├── models/                # ShuffleNetV2, GhostPAN, NanoDet head, LoRA
+│   ├── losses/                # QFL, GIoU, DFL, KD losses
+│   ├── nn/                    # Neural network building blocks
+│   ├── utils/                 # Metrics, visualization, checkpoint
+│   ├── trackers/              # ByteTracker, SORT, BoTSORT
+│   ├── solutions/             # Counting, speed, heatmaps, parking, security
+│   └── analytics/             # Benchmark, profiling, plots
+├── configs/                   # YAML configs for model zoo (pick & train)
+├── examples/                  # Ready-to-run example scripts
+├── tests/                     # Unit tests (pytest)
+├── docker/                    # Dockerfile + docker-compose
+├── train.py                   # Training script (LoRA, QLoRA, AMP, multi-GPU)
+├── train_kd.py                # Knowledge Distillation script
+├── test.py                    # Inference script
+├── scripts/                   # ONNX export, quantization, data prep
+├── pyproject.toml             # Package configuration
+├── CONTRIBUTING.md            # How to contribute
+├── CHANGELOG.md               # Version history
+└── LICENSE                    # MIT
+```
+
+---
+
+## Training Callbacks
+
+Extend the training loop without modifying source code:
+
+```python
+from flashdet import Trainer
+from flashdet.engine.callbacks import EarlyStopping, CSVLogger, TensorBoardCallback
+
+trainer = Trainer(model_size="m", train_images="data/train", val_images="data/val")
+
+trainer.add_callback(EarlyStopping(patience=20, metric="val_mAP"))
+trainer.add_callback(CSVLogger("metrics.csv"))
+trainer.add_callback(TensorBoardCallback("runs/exp1"))
+
+trainer.train()
+```
+
+Built-in callbacks: `EarlyStopping`, `CSVLogger`, `TensorBoardCallback`, `LRSchedulerCallback`.
+
+---
+
+## Docker
+
+```bash
+# Build
+docker build -t flashdet -f docker/Dockerfile .
+
+# Run inference
+docker run --gpus all -v $(pwd)/data:/app/data flashdet predict --model best.pth --source data/test.jpg
+
+# Or use docker-compose
+cd docker && docker compose up
+```
+
+---
+
+## Supported Formats
+
+| Import | Export |
+|--------|--------|
+| COCO JSON | ONNX |
+| YOLO TXT | FP16 weights |
+| Pascal VOC XML | TorchScript |
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+```bash
+git clone https://github.com/FlashVision/FlashDet.git
+cd FlashDet
+pip install -e ".[dev,all]"
+ruff check flashdet/
+flashdet check
+```
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <a href="https://github.com/FlashVision/FlashDet">
+    <b>FlashVision</b>
+  </a>
+  — Open-source lightweight AI
+</p>