pygeoprocessing.routing package

Submodules

• pygeoprocessing.routing.routing module
• pygeoprocessing.routing.watershed module

Module contents

pygeoprocessing.routing.delineate_watersheds_d8()

Delineate watersheds for a vector of geometries using D8 flow dir.

Parameters

• d8_flow_dir_raster_path_band (tuple) – A (path, band_id) tuple to a D8 flow direction raster. This raster must be a tiled raster with block sizes being a power of 2.

• outflow_vector_path (str) – The path to a vector on disk containing features with valid geometries from which watersheds will be delineated. Only those parts of the geometry that overlap valid flow direction pixels will be included in the output watersheds vector.

• target_watersheds_vector_path (str) – The path to a vector on disk where the target watersheds will be stored. Must have the extension .gpkg.

• working_dir=None (str or None) – The path to a directory on disk within which various intermediate files will be stored. If None, a folder will be created within the system’s temp directory.

• write_diagnostic_vector=False (bool) – If True, a set of vectors will be written to working_dir, one per watershed. Each vector includes geometries for the watershed being represented and for the watershed seed pixels the geometry overlaps. Useful in debugging issues with feature overlap of the DEM. Setting this parameter to True will dramatically increase runtime when outflow geometries cover many pixels.

• remove_temp_files=True (bool) – Whether to remove the created temp directory at the end of the watershed delineation run.

• target_layer_name='watersheds' (str) – The string name to use for the watersheds layer. This layer name may be named anything except for “polygonized_watersheds”.

Returns

None

pygeoprocessing.routing.distance_to_channel_d8()

Calculate distance to channel with D8 flow.

Parameters

• flow_dir_d8_raster_path_band (tuple) –

  a path/band index tuple indicating the raster that defines the D8 flow direction raster for this call. The pixel values are integers that correspond to outflow in the following configuration:

  3 2 1
  4 x 0
  5 6 7
  

• channel_raster_path_band (tuple) – a path/band tuple of the same dimensions and projection as flow_dir_d8_raster_path_band[0] that indicates where the channels in the problem space lie. A channel is indicated if the value of the pixel is 1. Other values are ignored.

• target_distance_to_channel_raster_path (str) – path to a raster created by this call that has per-pixel distances from a given pixel to the nearest downhill channel.

• weight_raster_path_band (tuple) – optional path and band number to a raster that will be used as the per-pixel flow distance weight. If None, 1 is the default distance between neighboring pixels. This raster must be the same dimensions as flow_dir_mfd_raster_path_band.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.distance_to_channel_mfd()

Calculate distance to channel with multiple flow direction.

Parameters

• flow_dir_mfd_raster_path_band (tuple) – a path/band index tuple indicating the raster that defines the mfd flow accumulation raster for this call. This raster should be generated by a call to pygeoprocessing.routing.flow_dir_mfd.

• channel_raster_path_band (tuple) – a path/band tuple of the same dimensions and projection as flow_dir_mfd_raster_path_band[0] that indicates where the channels in the problem space lie. A channel is indicated if the value of the pixel is 1. Other values are ignored.

• target_distance_to_channel_raster_path (str) – path to a raster created by this call that has per-pixel distances from a given pixel to the nearest downhill channel.

• weight_raster_path_band (tuple) – optional path and band number to a raster that will be used as the per-pixel flow distance weight. If None, 1 is the default distance between neighboring pixels. This raster must be the same dimensions as flow_dir_mfd_raster_path_band.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.extract_streams_mfd()

Classify a stream raster from MFD flow accumulation.

This function classifies pixels as streams that have a flow accumulation value >= flow_threshold and can trace further upstream with a fuzzy propotion if trace_threshold_proportion is set < 1.0

Parameters

• flow_accum_raster_path_band (tuple) – a string/integer tuple indicating the flow accumulation raster to use as a basis for thresholding a stream. Values in this raster that are >= flow_threshold will be classified as streams. This raster should be derived from dem_raster_path_band using pygeoprocessing.routing.flow_accumulation_mfd.

• flow_dir_mfd_path_band (str) – path to multiple flow direction raster, required to join divergent streams.

• flow_threshold (float) – the value in flow_accum_raster_path_band to indicate where a stream exists.

• target_stream_raster_path (str) – path to the target stream raster. This raster will be the same dimensions and projection as dem_raster_path_band and will contain 1s where a stream is defined, 0 where the flow accumulation layer is defined but no stream exists, and nodata otherwise.

• trace_threshold_proportion (float) – this value indicates what proportion of the flow_threshold is enough to classify a pixel as a stream after the stream has been traced from a flow_threshold drain. Setting this value < 1.0 is useful for classifying streams in regions that have highly divergent flow directions.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.fill_pits()

Fill the pits in a DEM.

This function defines pits as hydrologically connected regions that do not drain to the edge of the raster or a nodata pixel. After the call pits are filled to the height of the lowest pour point.

Parameters

• dem_raster_path_band (tuple) – a path, band number tuple indicating the DEM calculate flow direction.

• target_filled_dem_raster_path (str) – path the pit filled dem, that’s created by a call to this function. It is functionally a single band copy of dem_raster_path_band with the pit pixels raised to the pour point. For runtime efficiency, this raster is tiled and its blocksize is set to (1<<BLOCK_BITS, 1<<BLOCK_BITS) even if dem_raster_path_band[0] was not tiled or a different block size.

• working_dir (str) – If not None, indicates where temporary files should be created during this run. If this directory doesn’t exist it is created by this call. If None, a temporary directory is created by tempdir.mkdtemp which is removed after the function call completes successfully.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.flow_accumulation_d8()

D8 flow accumulation.

Parameters

• flow_dir_raster_path_band (tuple) –

  a path, band number tuple for a flow accumulation raster whose pixels indicate the flow out of a pixel in one of 8 directions in the following configuration:

  3 2 1
  4 x 0
  5 6 7
  

• target_flow_accum_raster_path (str) – path to flow accumulation raster created by this call. After this call, the value of each pixel will be 1 plus the number of upstream pixels that drain to that pixel. Note the target type of this raster is a 64 bit float so there is minimal risk of overflow and the possibility of handling a float dtype in weight_raster_path_band.

• weight_raster_path_band (tuple) – optional path and band number to a raster that will be used as the per-pixel flow accumulation weight. If None, 1 is the default flow accumulation weight. This raster must be the same dimensions as flow_dir_mfd_raster_path_band.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.flow_accumulation_mfd()

Multiple flow direction accumulation.

Parameters

• flow_dir_mfd_raster_path_band (tuple) – a path, band number tuple for a multiple flow direction raster generated from a call to flow_dir_mfd. The format of this raster is described in the docstring of that function.

• target_flow_accum_raster_path (str) – a path to a raster created by a call to this function that is the same dimensions and projection as flow_dir_mfd_raster_path_band[0]. The value in each pixel is 1 plus the proportional contribution of all upstream pixels that flow into it. The proportion is determined as the value of the upstream flow dir pixel in the downslope direction pointing to the current pixel divided by the sum of all the flow weights exiting that pixel. Note the target type of this raster is a 64 bit float so there is minimal risk of overflow and the possibility of handling a float dtype in weight_raster_path_band.

• weight_raster_path_band (tuple) – optional path and band number to a raster that will be used as the per-pixel flow accumulation weight. If None, 1 is the default flow accumulation weight. This raster must be the same dimensions as flow_dir_mfd_raster_path_band. If a weight nodata pixel is encountered it will be treated as a weight value of 0.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.flow_dir_d8()

D8 flow direction.

Parameters

• dem_raster_path_band (tuple) – a path, band number tuple indicating the DEM calculate flow direction. This DEM must not have hydrological pits or else the target flow direction is undefined.

• target_flow_dir_path (str) –

  path to a byte raster created by this call of same dimensions as dem_raster_path_band that has a value indicating the direction of downhill flow. Values are defined as pointing to one of the eight neighbors with the following convention:

  3 2 1
  4 x 0
  5 6 7
  

• working_dir (str) – If not None, indicates where temporary files should be created during this run. If this directory doesn’t exist it is created by this call.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.

pygeoprocessing.routing.flow_dir_mfd()

Multiple flow direction.

Parameters

• dem_raster_path_band (tuple) – a path, band number tuple indicating the DEM calculate flow direction. This DEM must not have hydrological pits or else the target flow direction will be undefined.

• target_flow_dir_path (str) –

  path to a raster created by this call of a 32 bit int raster of the same dimensions and projections as dem_raster_path_band[0]. The value of the pixel indicates the proportion of flow from that pixel to its neighbors given these indexes:

  3 2 1
  4 x 0
  5 6 7
  

  The pixel value is formatted as 8 separate 4 bit integers compressed into a 32 bit int. To extract the proportion of flow from a particular direction given the pixel value ‘x’ one can shift and mask as follows 0xF & (x >> (4*dir)), where dir is one of the 8 directions indicated above.

• working_dir (str) – If not None, indicates where temporary files should be created during this run. If this directory doesn’t exist it is created by this call.

• raster_driver_creation_tuple (tuple) – a tuple containing a GDAL driver name string as the first element and a GDAL creation options tuple/list as the second. Defaults to a GTiff driver tuple defined at geoprocessing.DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS.

Returns

None.