geographer package

Subpackages

Submodules

geographer.add_drop_rasters_mixin module

Mixin that implements adding/dropping rasters.

class geographer.add_drop_rasters_mixin.AddDropRastersMixIn[source]

Bases: object

Mix-in that implements methods to add and drop rasters.

add_to_rasters(new_rasters, label_maker=None)[source]

Add rasters to connector’s rasters attribute.

Adds the new_rasters to the connector’s rasters keeping track of which (vector) geometries are contained in which rasters.

Parameters:

  • new_rasters (GeoDataFrame) – GeoDataFrame of raster information conforming to the connector’s rasters format

  • label_maker (LabelMaker | None) – If given generate labels for new rasters.

drop_rasters(raster_names, remove_rasters_from_disk=True, label_maker=None)[source]

Drop rasters from rasters and from dataset.

Remove rows from the connector’s rasters, delete the corresponding vertices in the graph, and delete the raster from disk (unless remove_rasters_from_disk is set to False).

Parameters:

  • raster_names (Sequence[str]) – raster_names/ids of rasters to be dropped.

  • remove_rasters_from_disk (bool) – If true, delete rasters and labels from disk (if they exist). Defaults to True.

  • label_maker (LabelMaker | None) – If given, will use label_makers delete_labels method. Defaults to None.

geographer.add_drop_vectors_mixin module

Mixin that implements adding/dropping vector features.

class geographer.add_drop_vectors_mixin.AddDropVectorsMixIn[source]

Bases: object

Mix-in that implements adding or dropping vector features.

add_to_vectors(new_vectors, label_maker=None)[source]

Add vector features to connector’s vectors attribute.

Add (or overwrite) vector features in new_vectors and update graph encoding intersection/containment relations.

Parameters:

  • new_vectors (GeoDataFrame) – GeoDataFrame of vector features conforming to the connector’s vectors format

  • label_maker (LabelMaker | None) – If given generate new labels for rasters containing vector features that were added. Defaults to None.

drop_vectors(vector_names, label_maker=None)[source]

Drop vector features from connector’s vectors attribute.

Drop vector features from connector’s vectors attribute and update graph encoding intersection/containment relations.

Parameters:

  • vector_names (Sequence[str | int]) – vector_names/identifiers of vector features to be dropped.

  • label_maker (LabelMaker | None) – If given generate new labels for rasters containing vector features that were dropped. Defaults to None.

geographer.connector module

The Connector class organizes and handles remote sensing datasets.

class geographer.connector.Connector(load_from_disk, data_dir, vectors=None, rasters=None, task_vector_classes=None, background_class=None, crs_epsg_code=4326, raster_count_col_name='raster_count', **kwargs)[source]

Bases: AddDropVectorsMixIn, AddDropRastersMixIn, BipartiteGraphMixIn

Dataset class that connects vector features and raster data.

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

Parameters:

  • load_from_disk (bool)

  • data_dir (Path | str)

  • vectors (GeoDataFrame | None)

  • rasters (GeoDataFrame | None)

  • task_vector_classes (Sequence[str] | None)

  • background_class (str | None)

  • crs_epsg_code (int)

  • raster_count_col_name (str)

  • kwargs (Any)

__getattr__(key)[source]

Check for key in attrs dict.

Return type:

Any

Parameters:

key (str)

__init__(load_from_disk, data_dir, vectors=None, rasters=None, task_vector_classes=None, background_class=None, crs_epsg_code=4326, raster_count_col_name='raster_count', **kwargs)[source]

Initialize Connector.

Note

We advise you to use the following more convenient constructor methods to initialize a Connector instead of using __init__ directly.

To initialize a new connector use

  • the from_scratch() class method, or

  • the empty_connector_same_format_as() method

To initialize an existing connector use
Parameters:

  • load_from_disk (bool) – whether to load an existing connector from disk or create a new one.

  • task_vector_classes (Sequence[str] | None) – list of vector feature classes for the machine learning task (excluding mask and background classes). Defaults to None, i.e. the single class “object”

  • vectors (GeoDataFrame | None) – vectors. Defaults to None, i.e. (if not loading from disk) an empty vectors.

  • rasters (GeoDataFrame | None) – rasters. Defaults to None, i.e. (if not loading from disk) an empty rasters.

  • crs_epsg_code (int) – EPSG code connector works with. Defaults to STANDARD_CRS_EPSG_CODE

  • data_dir (Path | str) – data directory containing rasters_dir, labels_dir, connector_dir.

  • kwargs (Any) – optional keyword args for subclass implementations.

  • background_class (str | None)

  • raster_count_col_name (str)

add_to_rasters(new_rasters, label_maker=None)

Add rasters to connector’s rasters attribute.

Adds the new_rasters to the connector’s rasters keeping track of which (vector) geometries are contained in which rasters.

Parameters:

  • new_rasters (GeoDataFrame) – GeoDataFrame of raster information conforming to the connector’s rasters format

  • label_maker (LabelMaker | None) – If given generate labels for new rasters.

add_to_vectors(new_vectors, label_maker=None)

Add vector features to connector’s vectors attribute.

Add (or overwrite) vector features in new_vectors and update graph encoding intersection/containment relations.

Parameters:

  • new_vectors (GeoDataFrame) – GeoDataFrame of vector features conforming to the connector’s vectors format

  • label_maker (LabelMaker | None) – If given generate new labels for rasters containing vector features that were added. Defaults to None.

property all_vector_classes

All allowed classes in vectors.

Includes those not related to the ML task (e.g. the background class)

property connector_dir: Path

Directory in which the connector files are saved.

property crs_epsg_code: int

EPSG code of connector’s crs.

Setting crs_epsg_code will set automatically set the connector’s rasters and vectors crs.

property data_dir: str

Data directory.

does_raster_contain_vector(raster_name, vector_name)

Return whether a raster fully contains a vector feature.

Return type:

bool

Parameters:

  • raster_name (str) – Name of raster

  • vector_name (str) – name of vector feature

Returns:

True or False depending on whether the raster contains the vector feature or not

does_raster_intersect_vector(raster_name, vector_name)

Return whether a vector feature intersects a raster.

Return type:

bool

Parameters:

  • raster_name (str) – Name of raster

  • vector_name (str) – name of vector feature

Returns:

True or False depending on whether the raster intersects the vector feature or not

does_vector_intersect_raster(vector_name, raster_name)

Return whether a vector feature intersects a raster.

Return type:

bool

Parameters:

  • raster_name (str) – Name of raster

  • vector_name (str) – name of vector feature

Returns:

True or False depending on whether the vector feature intersects the raster or not

drop_rasters(raster_names, remove_rasters_from_disk=True, label_maker=None)

Drop rasters from rasters and from dataset.

Remove rows from the connector’s rasters, delete the corresponding vertices in the graph, and delete the raster from disk (unless remove_rasters_from_disk is set to False).

Parameters:

  • raster_names (Sequence[str]) – raster_names/ids of rasters to be dropped.

  • remove_rasters_from_disk (bool) – If true, delete rasters and labels from disk (if they exist). Defaults to True.

  • label_maker (LabelMaker | None) – If given, will use label_makers delete_labels method. Defaults to None.

drop_vectors(vector_names, label_maker=None)

Drop vector features from connector’s vectors attribute.

Drop vector features from connector’s vectors attribute and update graph encoding intersection/containment relations.

Parameters:

  • vector_names (Sequence[str | int]) – vector_names/identifiers of vector features to be dropped.

  • label_maker (LabelMaker | None) – If given generate new labels for rasters containing vector features that were dropped. Defaults to None.

empty_connector_same_format(data_dir)[source]

Return an empty connector of the same format.

Return an empty connector of the same format (i.e. same columns in vectors and rasters).

Return type:

Connector

Parameters:

  • data_dir (Path | str) – data directory containing rasters_dir, labels_dir, connector_dir.

  • rasters_dir – path to directory containing rasters.

  • labels_dir – path to directory containing labels.

  • connector_dir – path to directory containing (geo)json connector component files.

Returns:

new empty connector

classmethod from_data_dir(data_dir)[source]

Initialize a connector from a data directory.

Return type:

TypeVar(ConnectorType, bound= Connector)

Parameters:

data_dir (Path | str) – data directory containing ‘connector_files’, ‘rasters’, and ‘labels’ subdirectories

Returns:

initialized connector

classmethod from_scratch(**kwargs)[source]

Initialize a new connector.

Return type:

Connector

Parameters:

kwargs (Any)

Ars:
**kwargs: same keyword arguments as in __init__()

except for load_from_disk

Returns:

initialized connector

Parameters:

kwargs (Any)

Return type:

Connector

property graph_str: str

Return a string representation of the internal graph.

Note that the representation might change if the internal representation changes.

have_raster_for_vector(vector_name)

Check if there is a raster fully containing the vector feature.

Return type:

bool

Parameters:

vector_name (str) – Name of vector feature

Returns:

True if there is a raster in the dataset fully containing the vector feature, False otherwise.

is_vector_contained_in_raster(vector_name, raster_name)

Return True if a vector feature is fully contained in a raster.

Return type:

bool

Parameters:

  • raster_name (str) – Name of raster

  • vector_name (str) – name of vector feature

Returns:

True or False depending on whether the vector feature contains the raster or not

property labels_dir: Path

Directory containing the segmentation labels.

property raster_count_col_name: str

Name of column in vectors containing raster counts.

property raster_data_dirs: list[Path]

All directories containing raster data.

Includes e.g. segmentation labels.

property rasters: GeoDataFrame

Raster rasters geodataframe, see rasters.

rasters_containing_vector(vector_name, mode='names')

Return rasters in which a given vector feature is fully contained.

If multiple vector features are given, return raster which contain at least one of the vector features.

Return type:

list[str]

Parameters:

  • vector_name (str | list[str]) – name/id (or list of names) of vector feature(s)

  • mode (Literal['names', 'paths']) – One of ‘names’ or ‘paths’. In the former case the raster names are

  • 'names'. (returned in the latter case paths to the rasters. Defaults to)

Returns:

raster_names/identifiers of all rasters in connector containing the vector feature(s)

property rasters_dir: Path

Directory containing the rasters.

rasters_intersecting_vector(vector_name, mode='names')

Return rasters intersecting several vector feature(s).

If more than one vector feature is given, return rasters intersecting at least one of the vector features.

Return type:

list[str]

Parameters:

  • vector_name (str | list[str]) – name/id (or list) of vector feature(s)

  • mode (Literal['names', 'paths']) – One of ‘names’ or ‘paths’. In the former case the raster names are

  • 'names'. (returned in the latter case paths to the rasters. Defaults to)

Returns:

vector_names/identifiers of all vector features in connector with non-empty intersection with the raster.

rectangle_bounding_raster(raster_name)

Return shapely geometry bounding a raster.

The geometry is with respect to the connector’s (standard) crs.

Return type:

BaseGeometry

Parameters:

raster_name (str) – the raster_name/identifier of the raster

Returns:

shapely geometry giving the bounds of the raster in the standard crs of the connector

save()[source]

Save connector to disk.

property set_raster_count_col_name: str

Name of column in vectors containing raster counts.

property task_vector_classes

All classes for the ML task.

property vectors: GeoDataFrame

Vector features geodataframe, see vectors.

vectors_contained_in_raster(raster_name)

Return vector features fully containing a given raster.

If several rasters are given return vector features fully containing any of the rasters.

Return type:

list[str]

Parameters:

raster_name (str | list[str]) – name/id of raster or list of names/ids of rasters

Returns:

vector_names/identifiers of all vector features in connector contained in the raster(s).

vectors_intersecting_raster(raster_name)

Return vector features intersecting one or (any of) several rasters.

Return type:

list[str]

Parameters:

raster_name (str | list[str]) – name/id of raster or list names/ids

Returns:

list of vector_names/ids of all vector features in connector which have non-empty intersection with the raster(s)

geographer.connector.INFERRED_PATH_ATTR_FILENAMES = {'_graph_path': 'graph.json', '_rasters_path': 'rasters.geojson', '_vectors_path': 'vectors.geojson', 'attrs_path': 'attrs.json'}

Attribute self.key will be self.connector_dir / val.

geographer.creator_from_source_dataset_base module

ABC for creating or updating a dataset from an existing source dataset.

class geographer.creator_from_source_dataset_base.DSCreatorFromSource(**data)[source]

Bases: ABC, SaveAndLoadBaseModelMixIn, BaseModel

ABC for creating or updating a dataset from an existing one.

Parameters:

  • source_data_dir (Path)

  • target_data_dir (Path)

  • name (str)

  • extra_data (Any)

Return type:

None

field name: str [Required]

Name of dataset creator. Used as part of filename when saving.

Validated by:

  • validate_connectors

field source_data_dir: Path [Required]
Validated by:

  • validate_connectors

  • validate_source_data_dir

field target_data_dir: Path [Required]
Validated by:

  • validate_connectors

create(*args, **kwargs)[source]

Create a new dataset by cutting the source dataset.

Return type:

Connector

classmethod from_json_file(json_file_path, constructor_symbol_table=None)

Load and return saved BaseModel.

Return type:

Any

Parameters:

  • json_file_path (Path | str)

  • constructor_symbol_table (dict[str, Any] | None)

save()[source]

Save to update folder in source_data_dir.

update(*args, **kwargs)[source]

Update the target dataset from the source dataset.

Return type:

Connector

property source_connector

Connector in source_data_dir.

property target_connector

Connector in target_data_dir.

class geographer.creator_from_source_dataset_base.DSCreatorFromSourceWithBands(**data)[source]

Bases: DSCreatorFromSource, ABC

ABC for creating/updating a dataset from an existing one.

Includes a bands field.

Parameters:

  • source_data_dir (Path)

  • target_data_dir (Path)

  • name (str)

  • bands (dict[str, list[int] | None] | None)

  • extra_data (Any)

Return type:

None

field bands: Optional[dict[str, Optional[list[int]]]] = None

keys: raster directory names, values: list of band indices to keep, starting with 1

Validated by:

  • validate_connectors

field name: str [Required]

Name of dataset creator. Used as part of filename when saving.

Validated by:

  • validate_connectors

field source_data_dir: Path [Required]
Validated by:

  • validate_connectors

  • validate_source_data_dir

field target_data_dir: Path [Required]
Validated by:

  • validate_connectors

create(*args, **kwargs)

Create a new dataset by cutting the source dataset.

Return type:

Connector

classmethod from_json_file(json_file_path, constructor_symbol_table=None)

Load and return saved BaseModel.

Return type:

Any

Parameters:

  • json_file_path (Path | str)

  • constructor_symbol_table (dict[str, Any] | None)

save()

Save to update folder in source_data_dir.

update(*args, **kwargs)

Update the target dataset from the source dataset.

Return type:

Connector

property source_connector

Connector in source_data_dir.

property target_connector

Connector in target_data_dir.

geographer.errors module

Custom Error classes.

exception geographer.errors.GeoGrapherError[source]

Bases: Exception

Base class for exceptions.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception geographer.errors.NoRastersForVectorFoundError[source]

Bases: GeoGrapherError

No rasters found or none could be downloaded.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception geographer.errors.RasterAlreadyExistsError[source]

Bases: GeoGrapherError

Raster already exists in dataset.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception geographer.errors.RasterDownloadError[source]

Bases: GeoGrapherError

Error occurs while downloading raster.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

geographer.global_constants module

Global constants.

geographer.raster_bands_getter_mixin module

Mix-in that provides methods to get raster bands.

class geographer.raster_bands_getter_mixin.RasterBandsGetterMixIn[source]

Bases: object

Mix-in that provides methods to get raster bands.

Module contents