Metadata-Version: 2.4
Name: libreyolo
Version: 0.1.1
Summary: Libre YOLO - An open source YOLO library with MIT license.
Author: LibreYOLO Team
License: MIT
Project-URL: Homepage, https://github.com/Libre-YOLO
Project-URL: Repository, https://github.com/Libre-YOLO/libreyolo
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: torch>=1.7.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: requests>=2.25.0
Requires-Dist: opencv-python>=4.11.0.86
Provides-Extra: convert
Requires-Dist: ultralytics; extra == "convert"
Provides-Extra: onnx
Requires-Dist: onnx>=1.14.0; extra == "onnx"
Requires-Dist: onnxscript>=0.1.0; extra == "onnx"
Requires-Dist: onnxruntime>=1.16.0; extra == "onnx"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: ruff>=0.14.10; extra == "dev"
Requires-Dist: jupyterlab>=4.3.1; extra == "dev"
Dynamic: license-file

# Libre YOLO

[![Documentation](https://img.shields.io/badge/docs-docs.libreyolo.com-blue)](https://docs.libreyolo.com)

Libre YOLO is an open-source, MIT-licensed implementation of YOLO object detection models. It provides a clean, independent codebase for training and inference, designed to be free from restrictive licensing for the software itself.

📖 **Full Documentation:** [docs.libreyolo.com](https://docs.libreyolo.com)

> **Note:** While this codebase is MIT licensed, pre-trained weights converted from other repositories (like Ultralytics) may inherit their original licenses (often AGPL-3.0). Please check the license of the specific weights you use.

## Features

- 🚀 **Supported Models:** Full support for **YOLOv8** and **YOLOv11** architectures.
- 📦 **Unified API:** Simple, consistent interface for loading and using different YOLO versions.
- 🛠️ **Training Engine:** Built-in support for training models on custom datasets.
- ⚖️ **MIT License:** Permissive licensing for the codebase, making it suitable for commercial and research integration.
- 🔄 **Weight Conversion:** Tools to convert weights from Ultralytics format to LibreYOLO.

## Installation

Requirements: Python 3.10+ and a working pip/virtualenv. If you prefer `uv`, install it first (`pip install uv`).

Recommended (install everything: convert + onnx + dev/test tools):

```bash
git clone https://github.com/Libre-YOLO/libreyolo.git
cd libreyolo
uv sync --all-extras --group dev
# or, with pip extras:
pip install -e .[convert,onnx,dev]
```

If you want a lean install without extras:

```bash
pip install -e .
```

## Testing

We have two types of tests:

**Unit Tests** (fast, no weights needed)
- Check that functions work correctly without loading real model weights
- Run automatically when you type `make test` or `pytest`
- These run in seconds and catch bugs quickly

**Integration Tests** (slower, needs real weights)
- Load real model weights and test the full pipeline
- Run with `make test_integration` or `pytest -m integration`
- These take longer but verify everything works end-to-end

**Quick Commands:**
```bash
# Using Makefile (requires uv installed)
make test              # Run fast unit tests (default)
make test_integration  # Run slower integration tests (needs weights)

# Or run pytest directly (if you have dependencies installed)
pytest                 # Run fast unit tests
pytest -m integration # Run integration tests
```

**Why two types?** Unit tests are fast so you can run them constantly while coding. Integration tests are slower but make sure everything works together with real models.

## Quick Start

### Inference

Libre YOLO provides a unified factory to load models. It automatically detects the model version (v8 or v11) from the weights.

```python
from libreyolo import LIBREYOLO

# Load a model (automatically detects v8 vs v11)
model = LIBREYOLO(model_path="weights/libreyolo8n.pt", size="n")

# Run inference
detections = model(image="media/test_image_1_creative_commons.jpg", save=True)

# Access results
for detection in detections:
    print(f"Detected {detection.class_name} with confidence {detection.confidence:.2f}")
```

### Training

You can train models using the training module.

```python
from libreyolo import LIBREYOLO8

model = LIBREYOLO8(model_path="libreyolo8n.pt", size="n")
detections = model(image="image.jpg", save=True)
```

## Feature Map Visualization

Save feature maps from different layers of the model for visualization and analysis.

### Usage

```python
# Save all layers
model = LIBREYOLO8(model_path="weights/libreyolo8n.pt", size="n", save_feature_maps=True)

# Save specific layers only
model = LIBREYOLO8(model_path="weights/libreyolo8n.pt", size="n", 
                   save_feature_maps=["backbone_p1", "backbone_c2f2_P3", "neck_c2f21"])

# Get list of available layers
print(model.get_available_layer_names())
```

Feature maps are saved to `runs/feature_maps/` directory.

## Documentation

📖 **Full Documentation:** [docs.libreyolo.com](https://docs.libreyolo.com)

The documentation includes:
- Getting Started & Installation
- Inference Guide
- Training Guide  
- Explainability (CAM methods)
- Complete API Reference

## License

- **Code:** [MIT License](LICENSE)
- **Weights:** Use of converted weights must comply with their original licenses (typically AGPL-3.0 for Ultralytics models). See `weights/LICENSE_NOTICE.txt` for details.


## PossibleRoadmap

- [ ] Unified Command Line Interface (CLI)
- [ ] Video & Webcam Inference Support
- [ ] Letterbox Resizing (Padding)
- [ ] Batch Inference Support
- [ ] Benchmark / Speed Test Module
- [ ] Training Data Augmentations
- [ ] TorchScript Export
- [ ] Model Summary & Info
- [ ] Result Filtering (Class/Size)
- [ ] Confusion Matrix Generation
- [ ] onnx inference
- [ ] Add tiled inference
- [x] YOLOv8 Support
- [x] YOLOv11 Support
- [x] Training Engine
- [x] Weight Conversion Tools
- [ ] Fine-tuning with custom datasets
- [ ] Publish to PyPI
- [ ] Export formats (ONNX, TensorRT)
- [ ] Other models support (YOLOv10, YOLOv12, etc.)
- [ ] Feature Maps Visualization
- [ ] Automated testing (when a commit is pushed)
- [ ] Add explainability techniques
- [ ] Cocoeval to measure how good the model is
- [ ] CLI Tool
- [ ] Batch Processing
- [ ] Export Formats
- [ ] Video Processing
- [ ] Model Validation/Testing
- [ ] Training Support
- [ ] Model Quantization
- [ ] ONNX/TensorRT Export
- [ ] Web API / Server
- [ ] Documentation & Examples
- [ ] GPU memory optimization (gradient checkpointing)
- [ ] Multi-threaded batch processing
- [ ] Async inference support
- [ ] Model pruning (remove unnecessary weights)
- [ ] Knowledge distillation (smaller models)
- [ ] Mixed precision inference (FP16/BF16)
- [ ] TensorRT optimization pipeline
- [ ] CoreML export for Apple devices
- [ ] OpenVINO export for Intel hardware
- [ ] Model caching for faster repeated loads
- [ ] Real-time webcam detection
- [ ] Stream processing (RTSP/HTTP streams)
- [ ] Object tracking (track IDs across frames)
- [ ] Custom class names support
- [ ] Region of Interest (ROI) detection
- [ ] Confidence score calibration
- [ ] Multi-model ensemble inference
- [ ] Temporal smoothing for video
- [ ] Object counting per class
- [ ] Detection filtering by area/size
- [ ] YOLO format dataset export
- [ ] COCO format dataset export
- [ ] Pascal VOC format export
- [ ] LabelImg format compatibility
- [ ] CSV export with metadata
- [ ] JSON-LD export for structured data
- [ ] Database integration (SQLite/PostgreSQL)
- [ ] Image augmentation pipeline
- [ ] Dataset validation tools
- [ ] Annotation format converters
- [ ] Type hints throughout codebase
- [ ] Configuration file support (YAML/TOML)
- [ ] Progress bars for batch processing
- [ ] Logging system with levels
- [ ] Error handling improvements
- [ ] Model versioning system
- [ ] Checkpoint management
- [ ] Pre-commit hooks setup
- [ ] Code formatting (black/isort)
- [ ] Linting setup (pylint/flake8)
- [ ] Docker container image
- [ ] PyPI package publication
- [ ] Conda package support
- [ ] GitHub Actions CI/CD
- [ ] Pre-built Docker images
- [ ] Kubernetes deployment examples
- [ ] AWS Lambda function template
- [ ] Google Cloud Function template
- [ ] Azure Function template
- [ ] Edge device deployment guide



### Available Layers

#### LIBREYOLO8

| Layer | Description |
|-------|-------------|
| `backbone_p1` | First convolution |
| `backbone_p2` | Second convolution |
| `backbone_c2f1` | First C2F block |
| `backbone_p3` | Third convolution |
| `backbone_c2f2_P3` | C2F at P3 (Stride 8) |
| `backbone_p4` | Fourth convolution |
| `backbone_c2f3_P4` | C2F at P4 (Stride 16) |
| `backbone_p5` | Fifth convolution |
| `backbone_c2f4` | Fourth C2F block |
| `backbone_sppf_P5` | SPPF at P5 (Stride 32) |
| `neck_c2f21` | Neck C2F block 1 |
| `neck_c2f11` | Neck C2F block 2 |
| `neck_c2f12` | Neck C2F block 3 |
| `neck_c2f22` | Neck C2F block 4 |
| `head8_conv11` | Head8 box conv |
| `head8_conv21` | Head8 class conv |
| `head16_conv11` | Head16 box conv |
| `head16_conv21` | Head16 class conv |
| `head32_conv11` | Head32 box conv |
| `head32_conv21` | Head32 class conv |

#### LIBREYOLO11

| Layer | Description |
|-------|-------------|
| `backbone_p1` | First convolution |
| `backbone_p2` | Second convolution |
| `backbone_c2f1` | First C3k2 block |
| `backbone_p3` | Third convolution |
| `backbone_c2f2_P3` | C3k2 at P3 (Stride 8) |
| `backbone_p4` | Fourth convolution |
| `backbone_c2f3_P4` | C3k2 at P4 (Stride 16) |
| `backbone_p5` | Fifth convolution |
| `backbone_c2f4` | Fourth C3k2 block |
| `backbone_sppf` | SPPF block |
| `backbone_c2psa_P5` | C2PSA at P5 (Stride 32) |
| `neck_c2f21` | Neck C3k2 block 1 |
| `neck_c2f11` | Neck C3k2 block 2 |
| `neck_c2f12` | Neck C3k2 block 3 |
| `neck_c2f22` | Neck C3k2 block 4 |
| `head8_conv11` | Head8 box conv |
| `head8_conv21` | Head8 class conv |
| `head16_conv11` | Head16 box conv |
| `head16_conv21` | Head16 class conv |
| `head32_conv11` | Head32 box conv |
| `head32_conv21` | Head32 class conv |
