natcap.invest.delineateit.delineateit

DelineateIt wrapper for pygeoprocessing’s watershed delineation routine.

natcap.invest.delineateit.delineateit.check_geometries(outlet_vector_path, dem_path, target_vector_path, skip_invalid_geometry=False)

Perform reasonable checks and repairs on the incoming vector.

This function will iterate through the vector at outlet_vector_path and validate geometries, putting the geometries into a new geopackage at target_vector_path.

The vector at target_vector_path will include features that:

  • Have valid geometries

  • Are simplified to 1/2 the DEM pixel size

  • Intersect the bounding box of the DEM

Any geometries that are empty or do not intersect the DEM will not be included in target_vector_path.

Parameters
  • outlet_vector_path (string) – The path to an outflow vector. The first layer of the vector only will be inspected.

  • dem_path (string) – The path to a DEM on disk.

  • target_vector_path (string) – The target path to where the output geopackage should be written.

  • skip_invalid_geometry (bool) – Whether to raise an exception when invalid geometry is found. If False, an exception will be raised when the first invalid geometry is found. If True, the invalid geometry will be not be included in the output vector but any other valid geometries will.

Returns

None

natcap.invest.delineateit.delineateit.detect_pour_points(flow_dir_raster_path_band, target_vector_path)

Create a pour point vector from D8 flow direction raster.

A pour point is the center point of a pixel which:
  • flows off of the raster, or

  • flows into a nodata pixel

Parameters
  • flow_dir_raster_path_band (tuple) –

    tuple of (raster path, band index) indicating the flow direction raster to use. Pixel values are D8 values [0 - 7] in this order:

    321 4x0 567

  • target_vector_path (string) – path to save pour point vector to.

Returns

None

natcap.invest.delineateit.delineateit.execute(args)

DelineateIt: Watershed Delineation.

This ‘model’ provides an InVEST-based wrapper around the pygeoprocessing routing API for watershed delineation.

Upon successful completion, the following files are written to the output workspace:

  • snapped_outlets.gpkg - A GeoPackage with the points snapped to a nearby stream.

  • watersheds.gpkg - a GeoPackage of watersheds determined by the D8 routing algorithm.

  • stream.tif - a GeoTiff representing detected streams based on the provided flow_threshold parameter. Values of 1 are streams, values of 0 are not.

Parameters
  • args['workspace_dir'] (string) – The selected folder is used as the workspace all intermediate and output files will be written.If the selected folder does not exist, it will be created. If datasets already exist in the selected folder, they will be overwritten. (required)

  • args['results_suffix'] (string) – This text will be appended to the end of output files to help separate multiple runs. (optional)

  • args['dem_path'] (string) – A GDAL-supported raster file with an elevation for each cell. Make sure the DEM is corrected by filling in sinks, and if necessary burning hydrographic features into the elevation model (recommended when unusual streams are observed.) See the ‘Working with the DEM’ section of the InVEST User’s Guide for more information. (required)

  • args['outlet_vector_path'] (string) – This is a vector representing geometries that the watersheds should be built around. Required if args['detect_pour_points'] is False; not used otherwise.

  • args['snap_points'] (bool) – Whether to snap point geometries to the nearest stream pixel. If True, args['flow_threshold'] and args['snap_distance'] must also be defined.

  • args['flow_threshold'] (int) – The number of upstream cells that must into a cell before it’s considered part of a stream such that retention stops and the remaining export is exported to the stream. Used to define streams from the DEM.

  • args['snap_distance'] (int) – Pixel Distance to Snap Outlet Points

  • args['skip_invalid_geometry'] (bool) – Whether to crash when an invalid geometry is passed or skip it, including all valid geometries in the vector to be passed to delineation. If False, this tool will crash if an invalid geometry is found. If True, invalid geometries will be left out of the vector to be delineated. Default: True

  • args['detect_pour_points'] (bool) – Whether to run the pour point detection algorithm. If True, detected pour points are used instead of outlet_vector_path geometries. Default: False

  • args['n_workers'] (int) – The number of worker processes to use with taskgraph. Defaults to -1 (no parallelism).

Returns

None

natcap.invest.delineateit.delineateit.snap_points_to_nearest_stream(points_vector_path, stream_raster_path_band, snap_distance, snapped_points_vector_path)

Adjust the location of points to the nearest stream pixel.

The new point layer will have all fields and field values copied over from the source vector. Any points that are outside of the stream raster will not be included in the output vector.

Parameters
  • points_vector_path (string) – A path to a vector on disk containing point geometries. Must be in the same projection as the stream raster.

  • stream_raster_path_band (tuple) – A tuple of (path, band index), where pixel values are 1 (indicating a stream pixel) or 0 (indicating a non-stream pixel).

  • snap_distance (number) – The maximum distance (in pixels) to search for stream pixels for each point. This must be a positive, nonzero value.

  • snapped_points_vector_path (string) – A path to where the output points will be written.

Returns

None

Raises

ValueError` when snap_distance is less than or equal to 0