Metadata-Version: 2.1
Name: rpycocotools
Version: 0.0.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: numpy >=1.21.0
Requires-Dist: rpycocotools-stubs
Requires-Dist: maturin ; extra == 'build'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: hypothesis ; extra == 'test'
Requires-Dist: pytest-benchmark ; extra == 'benchmarks'
Requires-Dist: pycocotools ; extra == 'benchmarks'
Requires-Dist: pycocotools-stubs ; extra == 'benchmarks'
Requires-Dist: pip-tools ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: pyright ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'doc'
Requires-Dist: sphinx-rtd-theme ; extra == 'doc'
Requires-Dist: sphinx-hoverxref ; extra == 'doc'
Requires-Dist: sphinx-codeautolink ; extra == 'doc'
Requires-Dist: flake8 >=5.0.4, <6.0 ; extra == 'flake8'
Requires-Dist: flake8-bugbear >=23.3.12, <24.0 ; extra == 'flake8'
Requires-Dist: flake8-builtins >=2.1.0, <3.0 ; extra == 'flake8'
Requires-Dist: flake8-comprehensions >=3.12.0, <4.0 ; extra == 'flake8'
Requires-Dist: flake8-docstrings >=1.7.0, <2.0 ; extra == 'flake8'
Requires-Dist: flake8-quotes >=3.3.2, <4 ; extra == 'flake8'
Requires-Dist: pep8-naming >=0.13.3 ; extra == 'flake8'
Requires-Dist: flake8-import-order >=0.18.2 ; extra == 'flake8'
Requires-Dist: flake8-noqa >=1.3.1, <2 ; extra == 'flake8'
Requires-Dist: flake8-broken-line >=0.6.0 ; extra == 'flake8'
Requires-Dist: flake8-commas >=2.1.0, <3.0 ; extra == 'flake8'
Requires-Dist: Flake8-pyproject >=1.2.3, <2 ; extra == 'flake8'
Provides-Extra: build
Provides-Extra: test
Provides-Extra: benchmarks
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: flake8
Summary: Package providing utilities to load, manipulate, convert and visualize COCO format datasets.
Keywords: COCO,COCO dataset
Author: Bagard Hoel
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source Code, https://github.com/hoel-bagard/rust_coco_tools

# rpycocotools

[![PyPI](https://img.shields.io/pypi/v/rpycocotools?color=green&style=flat)](https://pypi.org/project/rpycocotools)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rpycocotools?style=flat)](https://pypi.org/project/rpycocotools)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/rpycocotools?style=flat-square)](https://pypistats.org/packages/rpycocotools)
[![PyPI - License](https://img.shields.io/pypi/l/rpycocotools?style=flat)](https://opensource.org/licenses/MIT)
![CI Python](https://github.com/hoel-bagard/cocotools-rs/actions/workflows/ci-python-rpycocotools.yaml/badge.svg)
![CI Rust](https://github.com/hoel-bagard/cocotools-rs/actions/workflows/ci-rust-rpycocotools.yaml/badge.svg)

The `rpycocotools` package provides tools to load, manipulate, convert and visualize COCO format datasets. The documentation is available [here](https://cocotools-rs.readthedocs.io/en/latest/index.html).

### Installation

The package is available on PyPI [here](https://pypi.org/project/rpycocotools/), and can installed with pip:
```
pip install rpycocotools
```

You can also git clone this repo and build it yourself with:
```
pip install -r requirements/requirements-build.txt
pip install .
```

### Usage example

Visualize image with a given `id`:
```python
import rpycocotools
coco_dataset = rpycocotools.COCO("../data_samples/coco_25k/annotations.json", "../data_samples/coco_25k/images")
coco_dataset.visualize_img(174482)
```

<p align="center">
  <img alt="rpycocotools_visu_example" src="https://user-images.githubusercontent.com/34478245/216580391-72226762-3fca-482b-a5ed-f93ed5a21931.png">
</p>

```python
import rpycocotools
coco_dataset = rpycocotools.COCO("../data_samples/coco_25k/annotations.json", "../data_samples/coco_25k/images")
anns = coco_dataset.get_img_anns(174482)
mask = rpycocotools.mask.decode(anns[0].segmentation)
```
The mask is a numpy array and can be visualized (for example with opencv):

<p align="center">
  <img alt="bike_segmentation" src="https://user-images.githubusercontent.com/34478245/226691842-8a11cde1-905d-434e-b287-0c3c685e01d1.png">
</p>


## Benchmarks

<details>
<summary>Details</summary>

There are a few benchmarking scripts to compare to `pycocotools`.\
The results reported here are done on my own PC and presented only to get a general idea. I might run the benchmark on a more reproducible environment in the future.

### Setup
Some of the benchmarks use the `instances_train2017.json` files from the 2017 COCO dataset.\
Either place this file in the `data_samples` folder or only run the commands below with the ` -m "not coco2017"` option.

```bash
pip install -r requirements/requirements-benchmarks.txt
pip install .
```

### Load
Benchmark how much time it takes load a COCO dataset.

```bash
python -m pytest benchmarks/load.py -vv
```

Results:

| Test Name                                       | Mean time in s |
|:-----------------------------------------------:|:--------------:|
| rpycocotools on COCO `instances_train2017.json` | 4.4            |
| pycocotools on COCO `instances_train2017.json`  | 16.5           |

### Area
Benchmark how much time it takes to compute the total number of mask pixels in a COCO dataset.

```bash
python -m pytest benchmarks/area.py -vv -m coco2017
```

Results:
| Test Name                                       | Mean time in ms |
|:-----------------------------------------------:|:---------------:|
| rpycocotools on COCO `instances_train2017.json` | 880.6           |
| pycocotools on COCO `instances_train2017.json`  | 19,302.9        |

### Decode masks
Benchmark how much time it takes to decode all the masks in a COCO dataset.


```bash
python -m pytest benchmarks/decode.py -vv -m coco2017
```

Results:
| Test Name                                       | Mean time in s |
|:-----------------------------------------------:|:--------------:|
| rpycocotools on COCO `instances_train2017.json` | 371            |
| pycocotools on COCO `instances_train2017.json`  | 141            |


Results after converting all the segmentations to RLE before decoding (conversion time not included):
| Test Name                                       | Mean time in s |
|:-----------------------------------------------:|:--------------:|
| rpycocotools on COCO `instances_train2017.json` | 300            |
| pycocotools on COCO `instances_train2017.json`  | 120            |
</details>

