Metadata-Version: 2.4
Name: lours
Version: 1.3.0
Summary: 
Author: XXII, Lilian Glaudin, Clément Pinard, Quoc Cuong LE, Nacer Kaci, Bastien Botrel
Author-email: Lilian Glaudin <lilian.glaudin@xxii.fr>, Clément Pinard <mail@clementpinard.fr>, Quoc Cuong LE <quoccuong.le@xxii.fr>, Nacer Kaci <nacer.kaci@xxii.fr>, Bastien Botrel <bastien.botrel@xxii.fr>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pandas[parquet]>=2
Requires-Dist: tqdm>=4.64,<5
Requires-Dist: pyyaml>=6.0.1,<7
Requires-Dist: imageio>=2
Requires-Dist: imagesize>=2.0.0,<3
Requires-Dist: pot>=0.9.1,<0.10
Requires-Dist: jsonschema-rs>=0.29.0
Requires-Dist: scikit-learn>=1.3.0,<2
Requires-Dist: watchdog>=6.0.0,<7
Requires-Dist: toml>=0.10.2,<0.11
Requires-Dist: shortuuid>=1.0.11,<2
Requires-Dist: faker>30
Requires-Dist: requests>=2,<3
Requires-Dist: xmltodict>=1.0.0,<2
Requires-Dist: networkx>=3.4.2,<4
Requires-Dist: fiftyone>=1.0.0 ; extra == 'fiftyone'
Requires-Dist: boto3==1.26.83 ; extra == 'fiftyone'
Requires-Dist: matplotlib>=3 ; extra == 'plot-utils'
Requires-Dist: pytest-regressions>=2.5.0,<3 ; extra == 'regression'
Requires-Python: >=3.11, <3.15
Provides-Extra: fiftyone
Provides-Extra: plot-utils
Provides-Extra: regression
Description-Content-Type: text/markdown

<!-- markdownlint-disable MD041 -->
<!-- markdownlint-disable MD033 -->
<div align="center">
<p align="center">
  <img src="docs/_static/logo-title.png" alt="lours logo" width="25%">
</p>

<b>The ultimate companion library for object detection data</b>

| 📚 [Docs](https://lours.readthedocs.io)| 📊 [Slides](https://docs.google.com/presentation/d/1crfwQmDnzkMmekznpZZiX0E0XPEhCAOkFPWa1NmflXU/pub) | 📝 Blogpost (coming soon) |

[![codecov](https://img.shields.io/codecov/c/gh/XXII-AI/lours?logo=codecov&color=cyan)](https://codecov.io/gh/XXII-AI/Lours) [![GitHub License](https://img.shields.io/github/license/XXII-AI/Lours?color=violet&logo=license)](https://github.com/XXII-AI/Lours/blob/main/LICENSE) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/lours?logo=python)](https://pypi.org/project/lours/)
 [![PyPI - Version](https://img.shields.io/pypi/v/lours?logo=pypi)](https://pypi.org/project/lours/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/lours?color=yellow)](https://pypi.org/project/lours/) [![Read the Docs](https://img.shields.io/readthedocs/lours?logo=readthedocs&color=orange)](https://lours.readthedocs.io/)

</div>

## Why Lours ?

The overall complexity and lack of standardization in public object detection data makes it painstakingly hard to work with. Lours is a library that makes construction, conversion and manipulation of any detection dataset easy, fast and reliable.

<p align="center">
  <img src="docs/_static/demo.gif" alt="lours logo" width="90%">
</p>

### The `Dataset` class

At its core, Lours features a unified `Dataset` class. It offers :

- Seamless conversion between popular formats (COCO, PascalVOC, FiftyOne, ...)
- Powerful dataset operations (merging, smart train/val splitting, class remapping, bbox format conversion...)
- Image and Object-Level indexing
- ... and much more !

A Lours dataset object is essentially composed of two `pandas.DataFrame` :

- `images` containing image-level data
- `annotations` containing object-instance-level data

```python
from lours.dataset import Dataset, from_coco

COCO_dataset = from_coco("docs/notebooks/notebook_data/coco_valid.json")
COCO_dataset
```

<p align="center">
  <img src="docs/_static/image_df.png" alt="image_df" width="30%" style="margin-right: 10px"/>
  <img src="docs/_static/annot_df.png" alt="annot_df" width="46%" />
</p>

In addition to Lours-specific utilities and functions, most operations supported by pandas DataFrames can also be applied seamlessly to Lours datasets.

Check the [Dataset 101 Tutorial](https://lours.readthedocs.io/stable/notebooks/1_demo_dataset.html#) or the full [API Reference](https://lours.readthedocs.io/latest/dataset.html) for more details about the `Dataset` class.

### Evaluators

Lours also features evaluators to compare a set of predictions to a ground truth in several settings :

- `DetectionEvaluator`
- `CrowdDetectorEvaluator`

Check the [Object Detection Evaluation Tutorial](https://lours.readthedocs.io/stable/notebooks/3_demo_evaluation_detection.html) of the [API Reference](https://lours.readthedocs.io/stable/evaluation.html) for more details.

## Installation

Simply run :

```bash
pip install lours
```

You can also install the pre-release by adding the `--pre` option

```bash
pip install lours --pre
```

### From source

- `pip`

```bash
git clone https://github.com/XXII-AI/Lours.git
cd Lours
pip install -e . # Only for pip > 21.3
```

- `poetry >= 1.2`

Assuming both lours and your project are in the same folder, adapt the relative path of the repo if needed

```bash
poetry add --editable ../lours/
poetry add --editable https://github.com/XXII-AI/lours.git
```

## Tutorials

A list of tutorials is available in the [Lours documentation tutorials](https://lours.readthedocs.io/stable/tutorials.html).

We also provide examples notebooks in the `docs/notebooks` folder.

## Documentation

For details about the Lours API, see the reference documentation :

- [stable](https://lours.readthedocs.io/stable/)
- [latest](https://lours.readthedocs.io/latest/)
