API#

Classes#

The FeatureClass acts as a custom container built on top of geopandas.GeoDataFrame, allowing operations like accessing, modifying, appending, and deleting geospatial data while maintaining properties like CRS (Coordinate Reference System) and geometry type.

Initializes the geospatial data container by parsing the source and extracting the necessary attributes, such as CRS (Coordinate Reference System) and geometry type. The source can be an existing GeoDataFrame, a file path to a geodatabase (GDB), or it can be empty.

Parameters:

src (DataFrame, optional) –

Source of the data. It can be:

None, for initializing an empty GeoDataFrame
String or os.PathLike path pointing to a file or a geodatabase dataset
GeoDataFrame or similar type to initialize directly, or
Existing FeatureClass object to copy

Raises:

TypeError – Raised when the provided source type is unsupported or invalid

append(value: GeoDataFrame | FeatureClass) → None#

Appends rows to the end of the FeatureClass.

The appended data must be compatible with the GeoDataFrame data structure.

Parameters:: value (geopandas.GeoDataFrame | FeatureClass) – The value to append to the collection.

calculate(column: str, expression: str | Any, dt: None | dtype | Any = None) → None#

Performs calculations on a column in the dataset based on the provided expression.

The expression is stringified Python code that will be evaluated for each row. If column does not exist, a new column will be created. Other columns can be referenced using the syntax: $column_name$

Example:

fc.calculate(column="new_col", expression="int($existing_col$) * 42", dtype=numpy.uint8)

Parameters:

column (str) – Name of the column to calculate, will be created if it does not exist
expression (str | Any) – Expression to evaluate for each value in the input column, will be evaluated by the method call and then stringified
dt (type | np.dtype, optional) – Type to convert the results to

clear() → None#

Remove all rows from the FeatureClass, leaving an empty schema.

Note: This will delete all data from memory! Use with caution.

Use FeatureClass.save() to save to disk before deleting data.

copy() → FeatureClass#

Returns:: A new instance of FeatureClass containing a deep copy of the internal data.
Return type:: FeatureClass

property crs: CRS | None#

Returns:: The Coordinate Reference System (CRS) of the FeatureClass, defaults to None

property geom_type: None | Geometry#

The geometry type of the FeatureClass, e.g., shapely.Point, shapely.LineString, shapely.Polygon; defaults to None

Returns:

property geometry: None | GeoSeries#

Accessor for the geometry of the FeatureClass

Return type:: None | geopandas.GeoSeries

head(n: int = 10, silent: bool = False) → GeoDataFrame#

Returns the first n rows of the FeatureClass and prints them if silent is False.

Parameters:

n (int) – Number of rows to return from the FeatureClass, defaults to 10
silent (bool) – If True, suppresses printing the retrieved rows, defaults to False

Returns:

A GeoDataFrame containing the first n rows

Return type:

geopandas.GeoDataFrame

insert(index: int, value: GeoDataFrame | FeatureClass) → None#

Insert a GeoDataFrame or FeatureClass into the current structure at a specified index.

Ensures schema compatibility, geometry type consistency, and proper handling of mixed geometries.

Parameters:

index (int) – The position where the rows should be inserted
value (geopandas.GeoDataFrame | FeatureClass) – The GeoDataFrame or FeatureClass to insert – must have the same schema as the current data

Raises:

TypeError – If index is not an integer, if value is not an instance of geopandas.GeoDataFrame or FeatureClass, or if the geometry types within value are incompatible with the existing geometry type constraints
ValueError – If the schema of value does not match the schema of the existing data

list_fields() → list[str]#

Return a list of field names in the data.

This method retrieves the column names of the underlying data object and adds the index name as the first field in the list.

Returns:: A list of field names including the index name as the first item
Return type:: list[str]

save(gdb_path: PathLike | str, fc_name: str, feature_dataset: str = None, overwrite: bool = False) → None#

Save the current data object to a file geodatabase.

Saves with a specified feature class name within a specified feature dataset, optionally allowing overwriting of any existing data.

Parameters:

gdb_path (os.PathLike | str) – The path to the file geodatabase where the data will be saved
fc_name (str) – The name of the feature class within the geodatabase where the data will be written
feature_dataset (str, optional) – The name of the feature dataset within the geodatabase to contain the feature class; if not provided, the feature class will be saved at the root of the geodatabase
overwrite (bool, optional) – If True, existing data in the specified feature class will be overwritten, defaults to False

select_columns(columns: str | Sequence[str], geometry: bool = True) → FeatureClass#

Return a FeatureClass of only the specified columns.

Parameters:

columns (str | Sequence[str]) – The names of the columns to select, can be a list of names or a single name
geometry (bool) – Return the geometry column as well, defaults to True

select_rows(expr: str) → FeatureClass#

Return a FeatureClass of the rows that match a query expression.

Wrapper for pandas.DataFrame.query

Parameters:: expr (str) – The query expression to use for filtering the rows

Examples:

fc.select_rows("colA > colB")

ObjectID    colA    colB
42          10      9
99          201     0


fc.select_rows("colA == 'spam'")

ObjectID    colA
1           spam
2           spam

show(block: bool = True)#

Display the geometry in a simple Matplotlib plot

Parameters:: block (bool, optional) – If True, waits for user to close the plot, defaults to True

sort(field_name: str, ascending: bool = True) → None#

Sort the FeatureClass based on a specific field.

Wraps the geopandas.GeoDataFrame.sort_values() method.

Parameters:

field_name (str) – The name of the field in the dataset to sort by
ascending (bool, optional) – Defaults to True

class footbridge._core.FeatureDataset(contents: None | dict[str, FeatureClass] = None, crs: None | CRS | Any = None, enforce_crs: bool = True)#

A dict-like collection of FeatureClass objects with an enforced CRS.

A FeatureDataset is a mutable mapping that organizes feature classes and enforces consistency in their coordinate reference system (CRS).

__init__(contents: None | dict[str, FeatureClass] = None, crs: None | CRS | Any = None, enforce_crs: bool = True)#

Initialize a new FeatureDataset instance with an optional coordinate reference system (CRS).

The CRS can be specified as any value compatible with the CRS class constructor.

Parameters:

contents (dict[str, FeatureClass], optional) – A dict of FeatureClass names and their objects to initialize the FeatureDataset with
crs (pyproj.crs.CRS | Any, optional) – The coordinate reference system to initialize the FeatureDataset with
enforce_crs (bool) – Whether to enforce the CRS in the FeatureDataset, defaults to True

Raises:

TypeError – If the provided CRS value cannot be converted to a valid CRS object

property crs: CRS | None#

Returns:: The ordinate Reference System (CRS) of the FeatureDataset
Return type:: pyproj.crs.CRS

property enforce_crs: bool#

Returns:: A boolean value indicating whether CRS enforcement is enabled.
Return type:: bool

property fc_dict: dict[str, FeatureClass]#

Returns:: Return a dict of the FeatureClass names and their objects contained by the FeatureDataset
Return type:: dict[str, FeatureClass]

property fc_names: list[str]#

Returns:: Return a list of the FeatureClass names contained by the FeatureDataset
Return type:: list[str]

Equivalent to FeatureDataset.fc_dict().keys()

property fcs: list[FeatureClass]#

Returns:: Return a list of the FeatureClass objects and contained by the FeatureDataset
Return type:: list[FeatureClass]

Equivalent to FeatureDataset.fc_dict().values()

class footbridge._core.GeoDatabase(path: None | PathLike | str = None, contents: dict[str, FeatureClass | FeatureDataset] | None = None)#

A dict-like collection of FeatureDataset and FeatureClass objects.

The GeoDatabase class is a mutable mapping that allows storing and managing spatial datasets organized into FeatureClass and FeatureDataset objects. It provides methods to interact with the stored spatial data, including access, iteration, modification, and saving data to disk.

__init__(path: None | PathLike | str = None, contents: dict[str, FeatureClass | FeatureDataset] | None = None)#

Initialize a new GeoDatabase instance.

If a valid path is provided, attempts to load datasets and layers from the specified location on disk. If no path is provided, the instance starts with an empty collection of FeatureDataset objects.

Parameters:

path (os.PathLike | str, optional) – The file path to load datasets and layers from
contents (dict[str : FeatureClass | FeatureDataset], optional) – A dict of dataset names and their objects to initialize the GeoDatabase with

property fc_dict: dict[str, FeatureClass]#

Returns:: A dict of the FeatureClass names and their objects contained by the GeoDatabase
Return type:: dict[str, FeatureClass]

property fc_names: list[str]#

Returns:: A list of the FeatureClass names contained by the GeoDatabase
Return type:: list[str]

Equivalent to GeoDatabase.fc_dict.keys()

property fcs: list[FeatureClass]#

Returns:: A list of the FeatureClass objects contained by the GeoDatabase
Return type:: list[str]

Equivalent to GeoDatabase.fc_dict.values()

property fds: list[FeatureDataset]#

Returns:: A list of the FeatureDataset objects contained by the GeoDatabase
Return type:: list[FeatureDataset]

Equivalent to GeoDatabase.fds_dict.values()

property fds_dict: dict[str, FeatureDataset]#

Returns:: A dict of the FeatureDataset names and their objects contained by the GeoDatabase
Return type:: dict[str, FeatureDataset]

property fds_names: list[str]#

Returns:: A list of the FeatureDataset names contained by the GeoDatabase
Return type:: list[str]

Equivalent to GeoDatabase.fds_dict.keys()

save(path: PathLike | str, overwrite: bool = False)#

Save the current contents of the GeoDatabase to a specified geodatabase (.gdb) file.

Parameters:

path (os.PathLike | str) – The file system path where the file geodatabase will be saved
overwrite (bool) – Whether to overwrite existing file geodatabase at the specified path, defaults to False

Note:

If the provided path does not include .gdb, the extension will be automatically appended

Geoprocessing Functions#

footbridge._geoprocessing.buffer(fc: FeatureClass, distance: float, **kwargs: dict) → FeatureClass#

Buffer a feature class by a specified distance

Wraps geopandas.GeoSeries.buffer()

Parameters:

fc (FeatureClass) – Input feature class to buffer
distance (float) – Buffer distance in the units of the feature class’s CRS
kwargs (dict) – Keyword arguments of geopandas.GeoSeries.buffer

Returns:

The buffered feature class

Return type:

FeatureClass

footbridge._geoprocessing.clip(fc: FeatureClass, mask_fc: FeatureClass, **kwargs: dict) → FeatureClass#

Clip a feature class by a mask feature class.

Wraps geopandas.clip()

Parameters:

fc (FeatureClass) – Input feature class to be clipped
mask_fc (FeatureClass) – Feature class to use as the clipping boundary
kwargs (dict) – Keyword arguments of geopandas.clip

Returns:

The clipped feature class

Return type:

FeatureClass

footbridge._geoprocessing.overlay(fc1: FeatureClass, fc2: FeatureClass, how: Literal['intersection', 'union', 'identity', 'symmetric_difference', 'difference'] = 'intersection', **kwargs: dict) → FeatureClass#

Perform a spatial overlay between two FeatureClasses

Wraps geopandas.overlay(), see the documentation for more details on the different overlay methods

Parameters:

fc1 (FeatureClass) – First input feature class to be used in the overlay operation
fc2 (FeatureClass) – Second input feature class
how (str, defaults to intersection) – Method of spatial overlay
kwargs (dict) – Keyword arguments of geopandas.overlay

Returns:

The clipped feature class

Return type:

FeatureClass

Utility Functions#

footbridge.utils.fc_to_json(gdb_path: PathLike | str, fc_name: str, fp: None | PathLike | str = None, indent: None | int = None, **kwargs: dict) → None | FeatureCollection#: Wraps geopandas.GeoDataFrame.to_json()

footbridge.utils.fc_to_parquet(gdb_path: PathLike | str, fc_name: str, fp: PathLike | str, **kwargs: dict)#: Wraps geopandas.GeoDataFrame.to_parquet()

footbridge.utils.fc_to_shp(gdb_path: PathLike | str, fc_name: str, fp: None | PathLike | str, **kwargs: dict) → None#: Wraps geopandas.GeoDataFrame.to_file(filename, driver=”ESRI Shapefile”)

footbridge.utils.get_info(gdb_path: PathLike | str) → dict#

Return a dictionary view of the contents of a file geodatabase on disk.

Parameters:: gdb_path (os.PathLike | str) – Path to the geodatabase
Returns:: A dictionary where keys represent dataset types, and values are nested dictionaries with dataset names and their corresponding metadata.
Return type:: dict

footbridge.utils.list_rasters(gdb_path: PathLike | str) → list[str]#

Lists all raster datasets within a specified file geodatabase on disk.

If the geodatabase is empty or not valid, an empty list is returned.

Parameters:: gdb_path (os.PathLike | str) – The path to the geodatabase file
Returns:: A list of raster datasets in the specified geodatabase file
Return type:: list[str]

Reference:

rouault/dump_gdbtable

footbridge.utils.raster_to_tif(gdb_path: PathLike | str, raster_name: str, tif_path: None | PathLike | str = None, options: None | dict = None)#

Converts a raster stored in a file geodatabase to a GeoTIFF file.

Reads the raster from the input geodatabase, including masking data, and saves it as a GeoTIFF file at the specified output path.

Parameters:

gdb_path (os.PathLike | str) – The path to the input file geodatabase containing the raster
raster_name (str) – The name of the raster in the geodatabase to be converted
tif_path (os.PathLike | str, optional) – The optional path where the GeoTIFF file should be saved. If not provided, the output GeoTIFF file will be saved with the same name as the raster in the GDB directory. Defaults to None.
options (dict, optional) – Additional keyword arguments for writing the GeoTIFF file, see the documentation: https://gdal.org/en/stable/drivers/raster/gtiff.html#creation-options