Merge pull request #27 from hoel-bagard/documentation

Documentation

README.md

@@ -1,12 +1,19 @@
-# cocotools-rs
+# Cocotools-rs
 COCO utils implemented in rust
 
-This package aims to provide similar functionalities to the [pycocotools package](https://pypi.org/project/pycocotools/) / [cocoapi](https://github.com/cocodataset/cocoapi) with additionnal utilities such as conversion between dataset formats.
+This repository aims to provide similar functionalities to the [pycocotools package](https://pypi.org/project/pycocotools/) / [cocoapi](https://github.com/cocodataset/cocoapi).
+
+### README / Documentation
+#### Rust
+See the [README](./cocotools/), you can also find the documentation [here](https://docs.rs/cocotools/latest/cocotools/index.html).
+
+#### Python
+See the [README](./rpycocotools/), you can also find the documentation [here](https://cocotools-rs.readthedocs.io/en/latest/index.html).
 
 ### Supported formats:
-The COCO dataset describes [6 formats](https://cocodataset.org/#format-data) for 6 different tasks, as of now only the `Object Detection` format is supported.
+The COCO dataset describes [6 formats](https://cocodataset.org/#format-data) for 6 different tasks, as of now only the `Object Detection`/`Stuff Segmentation` format is supported.
 
-## License
+### License
 Licensed under either of:
 - [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
 - [MIT license](http://opensource.org/licenses/MIT)

cocotools/README.md

@@ -1,15 +1,25 @@
 # Cocotools
 ![cocotools ci](https://github.com/hoel-bagard/cocotools-rs/actions/workflows/ci-cocotools.yaml/badge.svg)
+[![Crate](https://img.shields.io/crates/v/cocotools.svg?color=green&style=flat)](https://crates.io/crates/cocotools)
+[![Minimum rustc 1.64](https://img.shields.io/badge/rustc-1.64+-blue.svg)](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
+[![Documentation](https://docs.rs/cocotools/badge.svg)](https://docs.rs/cocotools)
 
-The `cocotools` crate provides tools to load, manipulate, convert and visualize COCO format datasets.
+The `cocotools` crate provides tools to load, manipulate/convert and visualize COCO format datasets.
 
-## API Usage example
+## Setup
+Get the crate from [crates.io](https://crates.io/crates/cocotools).
+
+## API Usage
+You can find the documentation [here](https://docs.rs/cocotools/latest/cocotools/index.html).
+
+### Example
 ```
 use std::path::PathBuf;
 use cocotools::COCO;
 
 let annotations_file_path = PathBuf::from("../data_samples/coco_25k/annotations.json");
-let dataset = COCO::try_from(&annotations_file_path)?;
+let image_folder_path = PathBuf::from("../data_samples/coco_25k/images");
+let coco_dataset = COCO::new(&annotations_file_path, &image_folder_path)?;
 let file_name = dataset.get_img(17627)?.file_name;
 ```
 
@@ -20,7 +30,7 @@ cargo run -- visualize  ../data_samples/coco_25k/annotations.json ../data_sample
 cargo run -- convert-segmentation ../data_samples/coco_25k/annotations.json rle -o annotations_rle.json
 ```
 
-## Planned features
+## Future features
 - [ ] Add support for keypoint detection format.
 - [ ] Add conversion from/to PascalVOC format.
 - [ ] Add conversion from/to SOLO format.

rpycocotools/docs/dataset.rst

@@ -114,6 +114,48 @@ COCO
     :param BBox bbox: The bounding box of the annotation.
     :param int iscrowd: The iscrowd flag for the annotation, which indicates if the annotation represents a group of objects or not.
 
+    .. attribute:: id
+
+        The id of the category.
+
+        :type: int
+
+    .. attribute:: image_id
+
+        The id of the image corresponding to this annotation.
+
+        :type: int
+
+    .. attribute:: category_id
+
+        The id of the category corresponding to this annotation.
+
+        :type: int
+
+    .. attribute:: segmentation
+
+        The segmentation data for the annotation, which can be of type Polygons, PolygonsRS, RLE or COCO_RLE.
+
+        :type: Polygons | PolygonsRS | RLE | COCO_RLE
+
+    .. attribute:: area
+
+        The area of the annotation bounding box.
+
+        :type: float
+
+    .. attribute:: bbox
+
+        The bounding box of the annotation.
+
+        :type: BBox
+
+    .. attribute:: iscrowd
+
+        The iscrowd flag for the annotation, which indicates if the annotation represents a group of objects or not.
+
+        :type: int
+
 .. class:: rpycocotools.anns.Category(id: int, name: str, supercategory: str) -> None
 
     Creates a category used for COCO object detection tasks.
@@ -265,3 +307,15 @@ COCO
         The COCO RLE representation of the mask.
 
         :type: str
+
+.. function:: from_dataset(images: Sequence[Image], annotations: Sequence[_AnnotationAny], categories: Sequence[Category], image_folder_path: str) -> COCO
+
+  Construct a COCO dataset from its components and the image folder.
+
+  :param Sequence[Image] images: The image entries composing the data.
+  :param Sequence[Annotation] annotations: The annotations entries composing the data.
+  :param Sequence[Category] categories: The categories entries composing the data.
+  :param str image_folder_path: Path to the folder with the images.
+  :raise ValueError: If there is an annotation with an image id X, but no image entry has this id.
+  :return: The constructed COCO dataset.
+  :rtype: :py:class:`COCO`