geococo
=======

.. py:module:: geococo


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/geococo/cli/index
   /autoapi/geococo/coco_manager/index
   /autoapi/geococo/coco_models/index
   /autoapi/geococo/coco_processing/index
   /autoapi/geococo/utils/index
   /autoapi/geococo/window_schema/index


Functions
---------

.. autoapisummary::

   geococo.append_dataset
   geococo.create_dataset
   geococo.load_dataset
   geococo.save_dataset


Package Contents
----------------

.. py:function:: append_dataset(dataset, images_dir, src, window_bounds, labels, id_attribute = None, name_attribute = None, super_attribute = None)

   Move across a given geotiff, converting all intersecting labels to COCO
   annotations and appending them to a COCODataset model. This is done through
   rasterio.Window objects, the bounds of which you can set with window_bounds (also
   determines the size of the output images associated with the Annotation instances).
   The degree of overlap between these windows is determined by the dimensions of the
   given labels to maximize representation in the resulting dataset.

   The "iscrowd" attribute (see https://cocodataset.org/#format-data) is determined by
   whether    the respective labels are Polygon or MultiPolygon instances. The
   attribute arguments are column names of the GeoDataFrame and are used to supply
   (super)category names, category ids, or both. If only names are given, ids are
   autogenerated (and vice versa). Lastly, each call to this method will increment
   the dataset version: patch if using the same image_path, minor if using a new
   image_path, and major if using a new output_dir.

   :param dataset: CocoDataset model to append images and annotations to
   :param images_dir: output directory for all label images
   :param src: open rasterio reader for input raster
   :param labels: GeoDataFrame containing labels and class_info ('category_id')
   :param window_bounds: a list of window_bounds to attempt to use ()
   :param id_attribute: Column containing category_id values
   :param name_attribute: Column containing category_name values
   :param super_attribute: Column containing supercategory values
   :return: CocoDataset with n appended Image, Category and Annotation instances


.. py:function:: create_dataset(description, contributor, version = str(Version(major=0)), date_created = datetime.now())

   Instances and returns a new CocoDataset model with given kwargs.

   :param description: Description of your COCO dataset
   :param contributor: Main contributors of your COCO dataset, its images and its
       annotations
   :param version: Initial SemVer version (defaults to 0.0.0)
   :param date_created: Date when dataset was initially created, defaults to
       datetime.now()
   :return: An instance of CocoDataset without Image- and Annotation objects


.. py:function:: load_dataset(json_path)

   Dumps the contents of json_path as a string, interprets it as a CocoDataset model
   and returns it.

   :param json_path: path to the JSON file containing the json-encoded COCO dataset
   :return: An instance of CocoDataset with loaded Image- and Annotation objects from
       json_path


.. py:function:: save_dataset(dataset, json_path)

   JSON-encodes an instance of CocoDataset and saves it to json_path.

   :param dataset: An instance of CocoDataset
   :param json_path: where to save the JSON-encoded CocoDataset instance to