Docs (#4)

* docs: populate file headers

* docs: add readme file for the notebooks folder

* docs: fix reference + add acknowledgment section

* docs: update version

* docs: fix relative links

* docs: fix relative links and spellings

* docs: fix relative link

* docs: fix relative link

* docs: link to tutorials in the usage + style formatting

* docs: docstring review for adapters

* docs: docstring review for errors

* docs: docstring review for cocohelper

* docs: docstring review for filters

* docs: docstring review for utils

* style: multi-line comments formatting

doc/src/contributing.md

@@ -27,7 +27,7 @@ If you want to submit a contribution, please follow the steps below:
 > Once the pull request is approved, a team member will take care of merging.
 
 ## Setup environment:
-Setting up your development environment requires you to fork the COCO Helper repository, 
+Setting up your development environment requires you to fork the COCOHelper repository, 
 clone the repository, install the dependencies, and execute the setup file.
 You can do it as:  
 

doc/src/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-You can install COCO-Helper from our ailab-pypi-server with:
+You can install COCOHelper from our ailab-pypi-server with:
 ```shell
 $ pip install cocohelper --extra-index-url  http://10.79.85.55:28080/simple --trusted-host 10.79.85.55
 ```

doc/src/usage.md

@@ -1,6 +1,12 @@
 # Usage
 
-## Load a coco dataset
+## Tutorials
+Have a look at our tutorials in the Jupyter notebooks available [here](notebooks/). 
+If you'd like to contribute with new tutorials, look at our [contributing guide](../doc/src/contributing.md).
+
+## Examples
+
+#### Load a coco dataset
 
 ```python
 from cocohelper import COCOHelper
@@ -10,14 +16,14 @@ ch = COCOHelper.load_dict('path/to/coco.json')
 ```
 
 
-## Visualize images
+#### Visualize images
 ```python
 from cocohelper.visualizer import COCOVisualizer
 
 COCOVisualizer(ch).visualize(img_id=1, show_bbox=True, show_segmentation=True)
 ```
 
-## Split train/val/test
+#### Split train/val/test
 ```python
 from cocohelper.splitters.proportional import ProportionalDataSplitter
 

notebooks/readme.md

@@ -0,0 +1,6 @@
+# Tutorials
+
+Here you can find Jupyter notebooks that will help you get familiar with COCOHelper. 
+If it's your first time, check `quick_start.ipynb`. Have a look at all the other notebooks, too!
+
+If you'd like to contribute with new tutorials, look at our [contributing guide](../doc/src/contributing.md).

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cocohelper"
-version = "0.3.2b"
+version = "0.3.3b"
 description = "Object Oriented library to manage MS-COCO-like datasets efficiently. "
 authors = [
     "delchiaro-bh <[email protected]>",

readme.md

@@ -5,7 +5,7 @@
 
   [![Python](https://img.shields.io/badge/python-v3.8.0+-success.svg)](https://www.python.org/)
   [![License](https://img.shields.io/badge/License-Apache_2.0-yellowgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0)
-  [![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](.github/contributing.md)
+  [![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](doc/src/contributing.md)
   [![Documentation](https://img.shields.io/badge/api-reference-blue.svg)](https://ailab-bh.github.io/cocohelper/apigen.html)
 </div>
 
@@ -21,8 +21,8 @@ Check our documentation and tutorials to learn how!
 
 **Quick Links**:
  - [Documentation](https://ailab-bh.github.io/cocohelper/)
- - [Contribution Guidelines](doc/src-man/contributing.md)
- - [Roadmap](doc/src-man/roadmap.md)
+ - [Contribution Guidelines](doc/src/contributing.md)
+ - [Roadmap](doc/src/roadmap.md)
 
 
 
@@ -35,13 +35,13 @@ and install through **pip**, **poetry**, or other python package managers.
 
 
 ## Usage
-You can find examples of usage in [usage.md](doc/src-man/usage.md) and [notebooks](notebooks/) folder.
+You can find examples of usage in [usage.md](doc/src/usage.md) and [notebooks](notebooks/) folder.
 
 
 
 ## Contributing
 Contributors are always welcome to help us fix an issue, add tests, improve
-code and documentation quality. If you'd like to contribute, please see our [contributing guide](doc/src-man/contributing.md).
+code and documentation quality. If you'd like to contribute, please see our [contributing guide](doc/src/contributing.md).
 
 Thanks a lot to all of our outstanding contributors!
 
@@ -57,8 +57,12 @@ You can cite COCOHelper using the following BibTeX entry:
 ```bibtex  
 @misc{cocohelper,  
   title={COCOHelper},  
-  author={Riccardo Del Chiaro, Elia Lotti, Andrea Panizza, Giacomo Veneri, Gabriele Valvano},  
+  author={Riccardo Del Chiaro, Andrea Panizza, Giacomo Veneri, Gabriele Valvano},  
   year={2022},  
   howpublished={https://github.com/baker-hughes/cocohelper},  
 }  
 ```
+
+#### Acknowledgments
+We thank the main authors and all the contributors for their help in developing the library. 
+We also thank Elia Lotti for his precious work on this project.

src/cocohelper/__init__.py

@@ -1,3 +1,6 @@
+"""
+A Python API to make working with the COCO dataset format simpler.
+"""
 from .helper import COCOHelper, COCOColsMapper, COCOHelperPaths
 
 # from . import filters

src/cocohelper/adapters/__init__.py

@@ -1,2 +1,5 @@
+"""
+Adapters to transform custom datasets into COCO format.
+"""
 from .dataset_adapter import DatasetAdapter
 from .binary_mask_adapter import BinaryMaskDatasetAdapter

src/cocohelper/adapters/binary_mask_adapter.py

@@ -1,3 +1,6 @@
+"""
+An adapter for converting datasets with binary masks to COCO format.
+"""
 from typing import List, Dict, Callable, Tuple, Optional, Union
 from scipy import ndimage
 import numpy as np
@@ -16,7 +19,8 @@ def __init__(
             mode: str = 'polygon',
             compression_factor: float = 1.0
     ):
-        """A DatasetAdapter to convert dataset with binary masks to COCO format.
+        """
+        A DatasetAdapter to convert dataset with binary masks to COCO format.
 
         Args:
             data_paths: A dictionary that maps image filenames to its masks
@@ -38,6 +42,7 @@ def __init__(
     def get_categories(self) -> List[dict]:
         """
         Get the list of categories.
+
         Returns:
             A list of categories
         """
@@ -47,7 +52,8 @@ def get_sample(
             self,
             idx: int
     ) -> Optional[Tuple[dict, List[dict]]]:
-        """Get the COCO representation for a specific sample and its index.
+        """
+        Get the COCO representation for a specific sample and its index.
 
         Args:
             idx: sample index.
@@ -95,7 +101,8 @@ def read_image(
             self,
             idx: int
     ) -> np.ndarray:
-        """Reads an image in from its positional id in the data paths.
+        """
+        Reads an image in from its positional id in the data paths.
 
         Args:
             idx: image index.
@@ -110,7 +117,9 @@ def read_image(
     def extract_bbox_from_binary_mask(
             binary_mask: np.ndarray
     ) -> List:
-        """Extracts bounding box from segmentation mask.
+        """
+        Extracts bounding box from segmentation mask.
+
         NB: we do not support rotated bounding boxes.
 
         Args:
@@ -133,7 +142,8 @@ def get_individual_instances(
             compression_factor: Union[float, Tuple[float, float]],
             **kwargs
     ) -> Tuple[List, List, List]:
-        """Separates disjoint objects inside the same array.
+        """
+        Separates disjoint objects inside the same array.
 
         Objects are separated based on two rules:
           1. objects have different labels in the input mask (e.g. one is

src/cocohelper/adapters/dataset_adapter.py

@@ -1,3 +1,6 @@
+"""
+The abstraction of an Adapter for converting datasets an arbitrary format to COCO format.
+"""
 from typing import List, Optional, Tuple
 from abc import ABC, abstractmethod
 import numpy as np
@@ -6,7 +9,8 @@
 class DatasetAdapter(ABC):
 
     def __iter__(self):
-        """DatasetAdapter interface that converts a dataset format to COCOHelper
+        """
+        DatasetAdapter interface that converts a dataset format to COCOHelper
         format.
 
         Returns:
@@ -16,7 +20,8 @@ def __iter__(self):
         return self
 
     def __next__(self):
-        """Get the next sample in the sequence.
+        """
+        Get the next sample in the sequence.
 
         Returns:
             self.
@@ -34,7 +39,8 @@ def __next__(self):
 
     @abstractmethod
     def get_categories(self) -> List[dict]:
-        """Get the categories.
+        """
+        Get the categories.
 
         Returns:
             A list of categories as dictionaries.
@@ -46,7 +52,8 @@ def get_sample(
             self,
             idx: int
     ) -> Optional[Tuple[dict, List[dict]]]:
-        """A method for loading samples. To be implemented.
+        """
+        A method for loading samples. To be implemented.
 
         Args:
             idx: index of the element to be fetched.
@@ -61,7 +68,8 @@ def read_image(
             self,
             idx: int
     ) -> np.ndarray:
-        """A method for reading images. To be implemented.
+        """
+        A method for reading images. To be implemented.
 
         Args:
             idx: index of the element to be fetched.

src/cocohelper/dataframe.py

@@ -1,3 +1,6 @@
+"""
+Extend pandas Dataframe to allow easier manipulation of COCO Datasets.
+"""
 from typing import Tuple, Hashable, Optional, Union
 from pandas._typing import IndexLabel
 from pandas import DataFrame
@@ -13,7 +16,8 @@ def __init__(
             name: str,
             col_mappers: Tuple[ColMap, ...] = tuple()
     ):
-        """Extends pandas Dataframe to easy column remapping and join with COCO
+        """
+        Extends pandas Dataframe to easy column remapping and join with COCO
         Datasets.
 
         Args:
@@ -46,7 +50,8 @@ def copy(
             self,
             deep: bool = True
     ) -> "COCODataFrame":
-        """Returns a copy of the COCODataFrame. The copy is deep by default.
+        """
+        Returns a copy of the COCODataFrame. The copy is deep by default.
 
         Args:
             deep: if True, the copy is deep.
@@ -192,6 +197,7 @@ def cocojoin(
     def _invert_join_how(how: str):
         """
         Inverts the join option.
+
         Args:
             how: input `how` parameter for the join
 

src/cocohelper/errors/__init__.py

@@ -0,0 +1,3 @@
+"""
+Custom exceptions for the library.
+"""

src/cocohelper/errors/not_found_error.py

@@ -1,10 +1,15 @@
+"""
+Exceptions for not found items in the COCO dataset.
+"""
+
 class COCOImageNotFoundError(Exception):
 
     def __init__(
             self,
             image_id: int
     ):
-        """Error raised when a certain image id does not exist in a dataset.
+        """
+        Exceptions raised when a certain image id does not exist in a dataset.
 
         Args:
             image_id: the id of the image.
@@ -19,7 +24,8 @@ def __init__(
             self,
             ann_id: int
     ):
-        """Error raised when a certain annotation id does not exist in a dataset.
+        """
+        Exceptions raised when a certain annotation id does not exist in a dataset.
 
         Args:
             ann_id: the id of the annotation.

src/cocohelper/errors/validation_error.py

@@ -1,4 +1,9 @@
+"""Exception raised when assertion of dataset validity fails.
+"""
+
 class COCOValidationError(Exception):
     def __init__(self):
-        """Error raised when the input COCO is not in a valid COCO format."""
+        """
+        Exceptions raised when the input COCO is not in a valid COCO format.
+        """
         super(COCOValidationError, self).__init__("The dataset has an invalid COCO format")

src/cocohelper/filters/__init__.py

@@ -1,3 +1,6 @@
+"""
+Base filters that can be used, composed or extended to extract specific information from dataframes.
+"""
 from .filter import Filter
 from .filter import ComposeFilter, AndFilter, OrFilter, NotFilter
 from .filter import ColumnFilter, ValueFilter, RangeFilter

src/cocohelper/filters/cocofilters/__init__.py

@@ -1 +1,4 @@
+"""
+Special and complex filters to obtain specific data from COCO tables using the COCOHelper interface.
+"""
 from .cocofilters import anns_filter, imgs_filter, cats_filter

src/cocohelper/filters/cocofilters/cocofilters.py

@@ -1,3 +1,6 @@
+"""
+Special and complex filters used to obtain specific data from COCO `images`, `annotations` and `categories` tables.
+"""
 from typing import Type, List, Optional, Tuple
 from cocohelper.filters.strategies import HAVING_VALUE, ValueFilterStrategy, RangeFilterStrategy, IN_RANGE
 from cocohelper.filters.filter import ValueFilter, RangeFilter, ComposeFilter, Filter, ColumnFilter
@@ -47,7 +50,8 @@ def cats_filter(
         composition: Type[ComposeFilter] = AndFilter,
         strategy: ValueFilterStrategy = HAVING_VALUE
 ) -> Filter:
-    """A Filter for the categories with the required characteristics.
+    """
+    A Filter for the categories with the required characteristics.
 
     Args:
         ids: a filter for the category id.
@@ -78,7 +82,8 @@ def imgs_filter(
         composition: Type[ComposeFilter] = AndFilter,
         strategy: ValueFilterStrategy = HAVING_VALUE
 ) -> Filter:
-    """A Filter for the images with the required characteristics.
+    """
+    A Filter for the images with the required characteristics.
 
     Args:
         ids: a filter for the image id.