API#

STAC client#

STAC utils.

class swisstopopy.stac.SwissTopoClient(region, *, region_crs=None)#

swisstopo client.

Parameters:

  • region (region-like) – Region to get the data for. Can any argument accepted by the pyregeon library.

  • region_crs (crs-like, optional) – Coordinate reference system (CRS) of the region. Required if region is a naive geometry or a list of bounding box coordinates. Ignored if region already has a CRS.

get_collection_gdf(collection_id, *, datetime=None, dst_crs=None)#

Get geo-data frame of tiles of a collection.

Parameters:

  • collection_id (str) – Collection ID to get the data for.

  • datetime (datetime-like, optional) – Datetime-like object forwarded to pystac_client.Client.search to filter the items. If None, all the items of the collection will be returned.

  • dst_crs (crs-like, optional) – Coordinate reference system (CRS) of the returned geo-data frame. If None, the CRS of the collection tiles will be used - note that this is not (necessarily) the same as the CRS of the tile data itself.

Returns:

collection_gdf – Geo-data frame of the collection tiles.

Return type:

geopandas.GeoDataFrame

swisstopopy.stac.get_latest(collection_gdf, *, tile_id_col='id', datetime_col='properties.datetime')#

Get the latest item for each tile and file metadata.

Parameters:

  • collection_gdf (geopandas.GeoDataFrame) – Collection geo-data frame.

  • tile_id_col (str, default "id") – Column name for the tile ID.

  • datetime_col (str, default "properties.datetime") – Column name for the datetime.

Returns:

collection_gdf – Collection geo-data frame with the latest item for each tile and file metadata.

Return type:

geopandas.GeoDataFrame

Geospatial utilities#

Buildings#

Building features.

Extract building features from OpenStreetMap and height data from the swissSURFACE3D Raster and swissALTI3D products provided by swisstopo’s STAC API.

swisstopopy.buildings.get_bldg_gdf(region, *, region_crs=None, item_datetime=None, **pooch_retrieve_kwargs)#

Get buildings geo-data frame with height information.

Parameters:

  • region (region-like) – Region to get the data for. Can any argument accepted by the pyregeon library.

  • region_crs (crs-like, optional) – Coordinate reference system (CRS) of the region. Required if region is a naive geometry or a list of bounding box coordinates. Ignored if region already has a CRS.

  • item_datetime (datetime-like, optional) – Datetime to filter swissSURFACE3D Raster and swissALTI3D data to use (must be the same for both collections), forwarded to pystac_client.Client.search. If None, the latest data for each tile is used.

  • pooch_retrieve_kwargs (mapping, optional) – Additional keyword arguments to pass to pooch.retrieve.

Returns:

bldg_gdf – Geo-data frame with building footprints and height information.

Return type:

geopandas.GeoDataFrame

Digital elevation model (DEM)#

Digital elevation model (DEM).

Generate a DEM for a region using the swissALTI3D product of the swisstopo STAC API.

swisstopopy.dem.get_dem_raster(region, dst_filepath, *, region_crs=None, alti3d_datetime=None, alti3d_res=0.5, pooch_retrieve_kwargs=None, rio_merge_kwargs=None)#

Get digital elevation model (DEM) raster.

Parameters:

  • region (region-like) – Region to get the data for. Can any argument accepted by the pyregeon library.

  • dst_filepath (path-like) – Output file path to save the raster to.

  • region_crs (crs-like, optional) – Coordinate reference system (CRS) of the region. Required if region is a naive geometry or a list of bounding box coordinates. Ignored if region already has a CRS.

  • alti3d_datetime (datetime-like, optional) – Datetime to filter swissALTI3D data, forwarded to pystac_client.Client.search. If None, the latest data for each tile is used.

  • alti3d_res ({0.5, 2}, default 0.5) – Resolution of the swissALTI3D data to get, can be 0.5 or 2 (meters).

  • pooch_retrieve_kwargs (mapping, optional) – Additional keyword arguments to respectively pass to pooch.retrieve and rasterio.merge.merge. If the latter is None, the default values from settings.RIO_MERGE_DST_KWARGS are used.

  • rio_merge_kwargs (mapping, optional) – Additional keyword arguments to respectively pass to pooch.retrieve and rasterio.merge.merge. If the latter is None, the default values from settings.RIO_MERGE_DST_KWARGS are used.

Return type:

None

Tree canopy raster#

Tree canopy.

swisstopopy.tree_canopy.get_tree_canopy_raster(*, region=None, surface3d_gdf=None, dst_filepath=None, dst_dir=None, region_crs=None, surface3d_datetime=None, count_threshold=32, dst_res=2, dst_tree_val=1, dst_nodata=0, dst_dtype='uint8', lidar_tree_values=3, cache_lidar=False, rasterize_lidar_kwargs=None, pooch_retrieve_kwargs=None, rio_merge_kwargs=None)#

Get tree canopy raster.

Parameters:

  • region (region-like, optional) – Region to get the data for. Can any argument accepted by the pyregeon library. Required unless surface3d_gdf is provided.

  • surface3d_gdf (geopandas.GeoDataFrame, optional) – Geo-data frame of swissSURFACE3D items to use directly instead of querying the STAC API for region. All the assets will be processed so it should already be filtered to the desired items. Ignored if region is provided but required otherwise.

  • dst_filepath (path-like, optional) – Output file path to save the merged raster to. Required unless dst_dir is provided.

  • dst_dir (path-like, optional) – Output directory to save individual tile rasters to. If provided, no merging is performed and individual tiles are written to this directory with the same basename as the LiDAR assets but a .tif extension. Ignored if dst_filepath but required otherwise.

  • region_crs (crs-like, optional) – Coordinate reference system (CRS) of the region. Required if region is a naive geometry or a list of bounding box coordinates. Ignored if region already has a CRS or when providing surface3d_gdf instead of region.

  • surface3d_datetime (datetime-like, optional) – Datetime to filter swissSURFACE3D data, forwarded to pystac_client.Client.search. If None, the latest data for each tile is used. Ignored when providing surface3d_gdf instead of region.

  • count_threshold (int, default 32) – Minimum number of vegetation LiDAR points to consider a pixel as tree canopy. Depends on the target pixel resolution dst_res. Note that swissSURFACE3D has a mean point density of 15-20 pts/m^2.

  • dst_res (numeric, default 2) – Target resolution of the raster.

  • dst_tree_val (int, default 1) – Value to assign to tree canopy pixels.

  • dst_nodata (int, default 0) – Value to assign to no data pixels.

  • dst_dtype (dtype-like, default "uint8") – Data type of the output raster.

  • lidar_tree_values (int or sequence of int, default 3.) – LiDAR classification values to use for tree canopy. If None, defaults to the “Vegetation” class value of swissSURFACE3D, i.e., 3.

  • cache_lidar (bool, default False) – Whether pooch should cache the LiDAR files. If False, the files are downloaded to a temporary directory.

  • rasterize_lidar_kwargs (mapping, optional) – Additional keyword arguments to respectively pass to swisstopopy.tree_canopy.rasterize_lidar, pooch.retrieve and rasterio.merge.merge. The merge kwargs are only used when dst_filepath is provided; if they are None, the default values from settings.RIO_MERGE_DST_KWARGS are used.

  • pooch_retrieve_kwargs (mapping, optional) – Additional keyword arguments to respectively pass to swisstopopy.tree_canopy.rasterize_lidar, pooch.retrieve and rasterio.merge.merge. The merge kwargs are only used when dst_filepath is provided; if they are None, the default values from settings.RIO_MERGE_DST_KWARGS are used.

  • rio_merge_kwargs (mapping, optional) – Additional keyword arguments to respectively pass to swisstopopy.tree_canopy.rasterize_lidar, pooch.retrieve and rasterio.merge.merge. The merge kwargs are only used when dst_filepath is provided; if they are None, the default values from settings.RIO_MERGE_DST_KWARGS are used.

Return type:

None