The connector class

GeoGrapher is built around the Connector class.

The Connector class represents a remote sensing computer vision dataset composed of vector features and rasters. A 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 vectors and rasters attributes

A Connector ‘s most important attributes are the vectors and rasters GeoDataFrames.

vectors

The 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 here

  • optionally, other columns for vector feature information

connector.vectors
# (returns GeoDataFrame)

rasters

The 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 crs)

  • 'orig_crs_epsg_code': (int) the EPSG code of the 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

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 vectors and rasters attributes are empty GeoDataFrames.

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 (vectors, 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 vectors and 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 LabelMaker 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 vectors in a way that would change the containment/intersection relations! If you directly manipulate the 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 LabelMaker to the label_maker argument to automatically update the labels to reflect the added or dropped rasters.

Note

The connector only knows about the 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.