# CV Toolbox

A comprehensive computer vision toolbox for road infrastructure analysis.

## Installation

### From PyPI (Recommended)

```bash
# Install the latest version
pip install ltoolbox

# Install a specific version
pip install ltoolbox==1.0.1

# Install with optional dependencies
pip install ltoolbox[dev]  # Development tools
pip install ltoolbox[docs]  # Documentation tools
pip install ltoolbox[dev,docs]  # All optional dependencies
```

### From Source

```bash
# Clone the repository
git clone https://github.com/logiroad/cv-toolbox.git
cd cv-toolbox

# Install in development mode
pip install -e ".[dev]"
```

### System Requirements

- Python 3.12 or higher
- pip (Python package installer)

For OpenCV support, you may need system libraries:

```bash
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y \
    libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1

# macOS
brew install opencv

# Windows: Should work out of the box
```

## Quick Start

### Command Line Interface

```bash
# Check installation
cv-toolbox --help
toolbox --help  # Alternative command

# Example usage (when implemented)
cv-toolbox process --input image.jpg --output result.jpg
```

### Python API

```python
import cv_toolbox

# Example usage of spatial primitives
from cv_toolbox.spatial.primitives import Point, Vector

# Create a 3D point
point = Point(x=1.0, y=2.0, z=3.0)

# Create a vector
vector = Vector(x=0.0, y=0.0, z=1.0)

# More examples coming soon...
```

## Development

### Setting up Development Environment

```bash
# Clone the repository
git clone https://github.com/logiroad/cv-toolbox.git
cd cv-toolbox

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=cv_toolbox

# Run specific test categories
pytest -m "not slow"  # Skip slow tests
pytest -m integration  # Only integration tests
pytest -m unit  # Only unit tests
```

### Code Quality

```bash
# Format code
ruff format cv_toolbox/ tests/

# Lint code
ruff check cv_toolbox/ tests/

# Type checking
mypy cv_toolbox/
```

### Building the Package

```bash
# Clean previous builds
make clean

# Build the package
make build

# This creates:
# - dist/ltoolbox-X.Y.Z-py3-none-any.whl
# - dist/ltoolbox-X.Y.Z.tar.gz
```

## Docker Support

### Using with Docker

```dockerfile
FROM python:3.12-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1 \
    && rm -rf /var/lib/apt/lists/*

# Install ltoolbox from PyPI
RUN pip install ltoolbox

# Copy your application
COPY . .

CMD ["cv-toolbox"]
```

Build and run:

```bash
docker build -t my-cv-app .
docker run -it my-cv-app
```

## Features

### Spatial Primitives

- **Points and Vectors**: 3D point and vector operations
- **Rotations**: Support for multiple rotation representations (quaternion, Euler angles, rotation matrix, axis-angle)
- **Poses**: 6DOF pose representations with transformations
- **Coordinate Transformations**: Convert between different coordinate systems

### Computer Vision Tools

- **Image Processing**: Cropping, tiling, and preprocessing utilities
- **CVAT Integration**: API client for CVAT annotation platform
- **Hugging Face Integration**: Tools for dataset management

### CLI Tools

- Unified command-line interface for all toolbox features
- Extensible plugin architecture

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please ensure:
- All tests pass (`pytest`)
- Code is formatted (`ruff format`)
- Code passes linting (`ruff check`)
- Type hints are correct (`mypy`)

## Vocabulaire

### Types d'images

* **originals**: images d'origine
* **drawn_bbox**: images d'origine avec une fissure encadrée en rouge
* **crops**: vignettes avec la zone à l'intérieur de l'encadré en rouge extraite
* **tiles**: images carrées extraites des vignettes par tiling et padding pour l'entrainement du modèle

### Splits

Les "splits" sont les parties de la base de données destinés aux étapes d'entrainement, validation et test du modèle:

* **train**: données d'entrainement du modèle
* **validation**: données de validation du modèle
* **test**: données de test du modèle

### Annotations

Les annotations utilisent plusieurs concepts:

* **label**: représente la classe de l'annotation
* **tag**: type d'annotation de classification pure dans laquelle il n'y a pas de détection d'objet
* **detection**: type d'annotation dans laquelle il y a une détection d'objet, avec par exemple un masque, une bounding box
* **mask**: masque de segmentation
* **bbox**: bounding box
* **attribute**: clef/valeur représentant un attribut (ex: Orientation:Transversale)

## License

Copyright (c) 2025 Logiroad. All rights reserved.

## Support

- [Documentation](https://github.com/logiroad/cv-toolbox/wiki)
- [Issue Tracker](https://github.com/logiroad/cv-toolbox/issues)
- [Releases](https://github.com/logiroad/cv-toolbox/releases)
