###################
The connector class
###################

GeoGrapher is built around the :class:`Connector` class.

The :class:`Connector` class represents a remote sensing computer vision dataset composed of
vector features and rasters. A :class:`Connector` connects the features and rasters
by a bipartite graph encoding the containment or intersection relationships between
them and is a container for tabular information about the features and rasters
as well as for metadata about the dataset.

The :attr:`vectors` and :attr:`rasters` attributes
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

A :class:`Connector` 's most important attributes are the :attr:`vectors` and
:attr:`rasters` GeoDataFrames.

.. _vectors:

:attr:`vectors`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :attr:`vectors` attribute is a GeoDataFrame that contains the vector
features. It is indexed by unique identifiers (str or int) and contains the
following columns:

    - ``'geometry'``: (shapely geometry) geometry of a vector feature
    - autogenerated ``'raster_count'`` column containing the number of rasters\
        fully containing a vector feature
    - optionally, column(s) containing class information needed for\
        generating labels, see :doc:`here <label_makers>`
    - optionally, other columns for vector feature information

::

    connector.vectors
    # (returns GeoDataFrame)

.. _rasters:

:attr:`rasters`
~~~~~~~~~~~~~~~~~~~~~~~~

The :attr:`rasters` attribute is a GeoDataFrame that contains tabular
information about the rasters, TODOTODOLINK Should be indexed by the
raster names and contain the following columns:

    - ``'geometry'``: (shapely.geometry.Polygon) polygon defining the raster
        bounds (in the connector's standardized :term:`crs`)
    - ``'orig_crs_epsg_code'``: (int) the EPSG code of the :term:`crs` the
        georeferenced raster is in
    - optionally, other columns for raster attributes

::

    connector.rasters
    # (returns GeoDataFrame)

The `connector.raster_count_col_name` (which defaults to `"raster_count"`) column
in `connector.vectors` automatically contains
the number of rasters in `rasters` that fully contain a vector feature.



Querying the graph
++++++++++++++++++

The graph can be queried with the ``rasters_containing_vector``,
``rasters_intersecting_vector``, ``vectors_contained_in_raster``,
``vectors_intersecting_raster`` methods::

    connector.rasters_containing_vector(vector_name)
    # (returns list of rasters containing vector feature)

``attrs``: Further attributes
+++++++++++++++++++++++++++++

The ``attrs`` attribute is a dictionary for custom attributes that can
contain e.g. metadata about the dataset::

    connector.attrs['some_field'] = some_value

    connector.attrs
    # (returns dictionary)

Location of rasters on disk
++++++++++++++++++++++++++++

The ``rasters_dir`` attribute points to the directory containing the rasters::

    connector.rasters_dir
    # (returns ``pathlib.Path`` to rasters, usually data_dir / 'rasters')

Creating and loading connectors
+++++++++++++++++++++++++++++++

.. _from_scratch:

Creating an empty connector
~~~~~~~~~~~~~~~~~~~~~~~~~~~

To create a new connector use the ``from_scratch`` class method::

    from geographer import Connector
    connector = Connector.from_scratch(
        data_dir=<DATA_DIR>)

The newly created connector is empty: the :attr:`vectors` and :attr:`rasters`
attributes are empty GeoDataFrames.

.. _init_existing_connector:

Initializing an existing connector
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To initialize an existing connector use the ``from_data_dir`` class method::

    connector = Connector.from_data_dir(data_dir=<DATA_DIR>)

Saving a connector
~~~~~~~~~~~~~~~~~~

Use the ``save`` method to save the connector::

    connector.save()

This saves the connector's components (:attr:`vectors`, :attr:`rasters`,
the graph, and the ``attrs``) to the ``connector``'s ``connector_dir``.

.. note::

    Geopandas can not save empty GeoDataFrames as geojson files. Therefore,
    to save a connector both the :attr:`vectors` and :attr:`rasters`
    GeoDataFrames need to be non-empty.

Adding or dropping vector features
++++++++++++++++++++++++++++++++++

Adding or dropping vector features to/from a connector::

    connector.add_to_vectors(new_vectors)
    # (concatenates the new_vectors to connector.vectors
    # and updates the graph)
    connector.drop_vectors(list_of_vectors)
    # (concatenates the new_rasters to connector.rasters
    # and updates the graph)

The names of the ``new_vectors`` in the GeoDataFrame's index must be unique.
You can supply an optional a :doc:`LabelMaker <label_makers>` to the ``label_maker``
argument to automatically update the labels of any rasters intersecting added
or dropped features.

.. important::

    Always use the ``add_to_vectors`` and ``drop_vectors`` methods
    to add or drop vector features to/from a connector or to modify the geometries
    of the :attr:`vectors` in a way that would change the containment/intersection
    relations! If you directly manipulate the :attr:`vectors` GeoDataFrame the
    graph encoding the relations will not be updated and therefore incorrect.

Adding or dropping rasters
++++++++++++++++++++++++++++++++

Adding or dropping rasters to/from the connector::

    connector.add_to_rasters(new_rasters)
    connector.drop_rasters(list_of_raster_names)

As with adding or dropping vector features, you can supply an optional a
:doc:`LabelMaker <label_makers>` to the ``label_maker`` argument to
automatically update the labels to reflect the added or dropped rasters.

.. note ::

    The connector only knows about the :attr:`rasters` GeoDataFrame, not
    whether the rasters actually exist in the ``connector.rasters_dir``
    directory.  You can use the ``rasters_from_tif_dir`` function in
    ``utils/utils.py`` to create a GeoDataFrame from a directory of
    GeoTiffs, which you can then pass as the ``new_rasters`` argument.