API documentation#

raster_footprint.create_mask(data_array: ndarray[tuple[Any, ...], dtype[Any]], *, nodata: int | float | None = None) → ndarray[tuple[Any, ...], dtype[uint8]]#

Produces a mask of valid data locations in a NumPy array.

Locations in data_array matching the given nodata value are set to 0; all other array locations are set to 255. If nodata is not provided, all array locations are set to 255.

Parameters:

  • data_array (numpy.NDArray[Any]) – A NumPy 2D or 3D array of raster data.

  • nodata (Optional[Union[int, float]]) – The nodata value. If not provided, all array locations are set to 255. Defaults to None.

Returns:

A 2D NumPy array containing 0s and 255s for nodata/data pixels.

Return type:

numpy.NDArray[numpy.uint8]

raster_footprint.densify_by_distance(point_list: List[Tuple[float, float]], distance: float, *, precision: int = 7) → List[Tuple[float, float]]#

Increases the number of points in a list according to a distance interval.

New points are inserted between each pair of adjacent existing points with the spacing controlled by the distance argument. For example, if two adjacent points in the list are separated by 10 units and a distance of 2 is provided, 4 new points will be inserted between the two original points (one new point every 2 units of distance).

Derived from code found at https://stackoverflow.com/questions/64995977/generating-equidistance-points-along-the-boundary-of-a-polygon-but-cw-ccw

Parameters:

  • point_list (List[Tuple[float, float]]) – The list of points to be densified.

  • distance (float) – The interval at which to insert additional points.

  • precision (Optional[int]) – The number of decimal places to include in the point coordinates. Defaults to 7.

Returns:

The densified point list.

Return type:

List[Tuple[float, float]]

raster_footprint.densify_by_factor(point_list: List[Tuple[float, float]], factor: int, *, precision: int = 7) → List[Tuple[float, float]]#

Increases the number of points in a list by a factor.

Equidistant points are added between each pair of adjacent existing points. The number of points added is controlled by the factor argument. For example, a list of 5 points and a factor of 2 will result in a list of 9 points (one new point added between each original set of adjacent points).

Derived from code found at https://stackoverflow.com/questions/64995977/generating-equidistance-points-along-the-boundary-of-a-polygon-but-cw-ccw

Parameters:

  • point_list (List[Tuple[float, float]]) – The list of points to be densified.

  • factor (int) – The factor by which to densify the points.

  • precision (Optional[int]) – The number of decimal places to include in the point coordinates. Defaults to 7.

Returns:

The densified point list.

Return type:

List[Tuple[float, float]]

raster_footprint.densify_geometry(geometry: T, *, factor: int | None = None, distance: float | None = None, precision: int = 7) → T#

Adds vertices to a polygon or each polygon in a multipolygon.

Parameters:

  • geometry (T) – The polygon or multipolygon to densify.

  • factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. Mutually exclusive with distance. Defaults to None.

  • distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with factor. Defaults to None.

  • precision (Optional[int]) – The number of decimal places to include in the densified geometry coordinates. Defaults to 7.

Returns:

The densified polygon or multipolygon.

Return type:

T

raster_footprint.densify_multipolygon(multipolygon: MultiPolygon, *, factor: int | None = None, distance: float | None = None, precision: int = 7) → MultiPolygon#

Adds vertices to each polygon in a multipolygon.

Vertices are added according to one of the mutually exclusive factor or distance arguments.

Parameters:

  • multipolygon (MultiPolygon) – The multipolygon to densify.

  • factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. mutually exclusive with distance. Defaults to None.

  • distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with factor. Defaults to None.

  • precision (Optional[int]) – The number of decimal places to include in the densified multipolygon vertex coordinates. Defaults to 7.

Returns:

The densified multipolygon.

Return type:

MultiPolygon

raster_footprint.densify_polygon(polygon: Polygon, *, factor: int | None = None, distance: float | None = None, precision: int = 7) → Polygon#

Adds vertices to a polygon.

Vertices are added according to one of the mutually exclusive factor or distance arguments.

Parameters:

  • polygon (Polygon) – The polygon to densify.

  • factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. Mutually exclusive with distance. Defaults to None.

  • distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with factor. Defaults to None.

  • precision (Optional[int]) – The number of decimal places to include in the densified polygon vertex coordinates. Defaults to 7.

Returns:

The densified polygon.

Return type:

Polygon

raster_footprint.footprint_from_data(data: ndarray[tuple[Any, ...], dtype[Any]], transform: Affine, source_crs: CRS, *, destination_crs: CRS = CRS.from_epsg(4326), nodata: int | float | None = None, precision: int = 7, densify_factor: int | None = None, densify_distance: float | None = None, simplify_tolerance: float | None = None, convex_hull: bool = False, holes: bool = False) → Dict[str, Any] | None#

Produces a GeoJSON dictionary containing a polygon or multipolygon surrounding valid data locations in the given data array.

Parameters:

  • data (NDArray[Any]) – A 2D or 3D NumPy array of raster data.

  • transform (Affine) – An affine.Affine object defining the affine transformation from the mask pixel coordinate system to the given crs coordinate system.

  • source_crs (CRS) – A rasterio.crs.CRS object defining the coordinate reference system of the given mask.

  • destination_crs (CRS) – A rasterio.crs.CRS object defining the desired coordinate reference system of output footprint. Defaults to EPSG:4326 (WGS84).

  • nodata (Optional[Union[int, float]]) – The nodata value to use for creating a data/nodata mask array. If not provided, a footprint for the entire raster, including nodata pixels, is returned.

  • precision (Optional[int]) – The number of decimal places to include in the final footprint polygon vertex coordinates. Defaults to 7.

  • densify_factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. Mutually exclusive with densify_distance. Defaults to None.

  • densify_distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with densify_factor. Defaults to None.

  • simplify_tolerance (Optional[float]) – The maximum distance between original polygon vertices and the simplified polygon(s). Unit is geographic decimal degrees. Defaults to None.

  • convex_hull (bool) – Whether to compute the convex hull of any created polygons. The convex hull is applied prior to densification and simplification. Defaults to False.

  • holes (bool) – Whether to include holes in the created polygons. Has no effect if convex_hull is True. Defaults to False.

Returns:

A GeoJSON dictionary containing the footprint polygon or multipolygon.

Return type:

Optional[Dict[str, Any]]

raster_footprint.footprint_from_href(href: str, *, destination_crs: CRS = CRS.from_epsg(4326), nodata: int | float | None = None, precision: int = 7, densify_factor: int | None = None, densify_distance: float | None = None, simplify_tolerance: float | None = None, convex_hull: bool = False, holes: bool = False, bands: List[int] | None = None, with_nodata: bool = False) → Dict[str, Any] | None#

Produces a GeoJSON dictionary containing a polygon or multipolygon surrounding valid data locations in a raster file located at the given href.

The file pointed to by href must be openable by rasterio.

Parameters:

  • href (str) – An href to a raster data file.

  • destination_crs (CRS) – A rasterio.crs.CRS object defining the desired coordinate reference system of output footprint. Defaults to EPSG:4326 (WGS84).

  • nodata (Optional[Union[int, float]]) – Explicitly sets the nodata value to use for creating a data/nodata mask array. If not provided, the nodata value in the source file metadata is used. If not provided and a nodata value does not exist in the source file metadata, a footprint for the entire raster, including nodata pixels, is returned.

  • precision (Optional[int]) – The number of decimal places to include in the final footprint polygon vertex coordinates. Defaults to 7.

  • densify_factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. Mutually exclusive with densify_distance. Defaults to None.

  • densify_distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with densify_factor. Defaults to None.

  • simplify_tolerance (Optional[float]) – The maximum distance between original polygon vertices and the simplified polygon(s). Unit is geographic decimal degrees. Defaults to None.

  • convex_hull (bool) – Whether to compute the convex hull of any created polygons. The convex hull is applied prior to densification and simplification. Defaults to False.

  • holes (bool) – Whether to include holes in the created polygons. Has no effect if convex_hull is True. Defaults to False.

  • with_nodata (bool) – If True, a footprint for the entire raster, including nodata pixels, is returned. Defaults to False.

  • bands (List[int]) – The bands to use to compute the footprint. Defaults to [1]. If an empty list is provided, the bands will be ORd together; e.g., for a pixel to be outside of the footprint, all bands must have nodata in that pixel.

Returns:

A GeoJSON dictionary containing the footprint polygon or multipolygon.

Return type:

Optional[Dict[str, Any]]

raster_footprint.footprint_from_mask(mask: ndarray[tuple[Any, ...], dtype[uint8]], transform: Affine, source_crs: CRS, *, destination_crs: CRS = CRS.from_epsg(4326), precision: int = 7, densify_factor: int | None = None, densify_distance: float | None = None, simplify_tolerance: float | None = None, convex_hull: bool = False, holes: bool = False) → Dict[str, Any] | None#

Produces a GeoJSON dictionary containing a polygon or multipolygon geometry surrounding valid data locations in the given mask array.

A polygon or multipolygon geometry surrounding valid data pixels is extracted from the given mask array. The geometry polygon(s) are densified with additional vertices, reprojected to the destination_crs, and then simplified by reducing the number of vertices. Densifying the polygon(s) prior to reprojection reduces projection distortion error. Simplification removes vertices that are redundant in defining the polygon(s) to within the given simplify_tolerance.

Parameters:

  • mask (NDArray[uint8]) – A 2D NumPy array containing 0s and 255s for nodata/data (invalid/valid) pixels.

  • transform (Affine) – An affine.Affine object defining the affine transformation from the mask pixel coordinate system to the given crs coordinate system.

  • source_crs (CRS) – A rasterio.crs.CRS object defining the coordinate reference system of the given mask.

  • destination_crs (CRS) – A rasterio.crs.CRS object defining the desired coordinate reference system of output footprint. Defaults to EPSG:4326 (WGS84).

  • precision (Optional[int]) – The number of decimal places to include in the final footprint polygon vertex coordinates. Defaults to 7.

  • densify_factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. Mutually exclusive with densify_distance. Defaults to None.

  • densify_distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with densify_factor. Defaults to None.

  • simplify_tolerance (Optional[float]) – The maximum distance between original polygon vertices and the simplified polygon(s). Unit is geographic decimal degrees. Defaults to None.

  • convex_hull (bool) – Whether to compute the convex hull of any created polygons. The convex hull is applied prior to densification and simplification. Defaults to False.

  • holes (bool) – Whether to include holes in the created polygons. Has no effect if convex_hull is True. Defaults to False.

Returns:

A GeoJSON dictionary containing the footprint polygon or multipolygon.

Return type:

Optional[Dict[str, Any]]

raster_footprint.footprint_from_rasterio_reader(reader: DatasetReader, *, destination_crs: CRS = CRS.from_epsg(4326), nodata: int | float | None = None, precision: int = 7, densify_factor: int | None = None, densify_distance: float | None = None, simplify_tolerance: float | None = None, convex_hull: bool = False, holes: bool = False, bands: List[int] | None = None, with_nodata: bool = False) → Dict[str, Any] | None#

Produces a GeoJSON dictionary containing a polygon or multipolygon surrounding valid data locations from a rasterio.io.DatasetReader object, i.e., an opened dataset object returned by a rasterio.open() call.

Parameters:

  • reader (DatasetReader) – A rasterio.io.DatasetReader object.

  • destination_crs (CRS) – A rasterio.crs.CRS object defining the desired coordinate reference system of output footprint. Defaults to EPSG:4326 (WGS84).

  • nodata (Optional[Union[int, float]]) – Explicitly sets the nodata value to use for creating a data/nodata mask array. If not provided, the nodata value in the source file metadata is used. If not provided and a nodata value does not exist in the source file metadata, a footprint for the entire raster, including nodata pixels, is returned.

  • precision (Optional[int]) – The number of decimal places to include in the final footprint polygon vertex coordinates. Defaults to 7.

  • densify_factor (Optional[int]) – The factor by which to increase the number of polygon vertices, e.g., a factor of 2 will double the number of vertices. Mutually exclusive with densify_distance. Defaults to None.

  • densify_distance (Optional[float]) – The interval at which to insert additional polygon vertices, e.g., a distance of 2 will insert a new vertex every 2 units of distance between existing vertices. Mutually exclusive with densify_factor. Defaults to None.

  • simplify_tolerance (Optional[float]) – The maximum distance between original polygon vertices and the simplified polygon(s). Unit is geographic decimal degrees. Defaults to None.

  • convex_hull (bool) – Whether to compute the convex hull of any created polygons. The convex hull is applied prior to densification and simplification. Defaults to False.

  • holes (bool) – Whether to include holes in the created polygons. Has no effect if convex_hull is True. Defaults to False.

  • with_nodata (bool) – If True, a footprint for the entire raster, including nodata pixels, is returned. Defaults to False.

  • bands (List[int]) – The bands to use to compute the footprint. Defaults to [1]. If an empty list is provided, the bands will be ORd together; e.g., for a pixel to be outside of the footprint, all bands must have nodata in that pixel.

Returns:

A GeoJSON dictionary containing the footprint polygon or multipolygon.

Return type:

Optional[Dict[str, Any]]

raster_footprint.get_mask_geometry(mask: ndarray[tuple[Any, ...], dtype[uint8]], *, transform: Affine = (1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0), convex_hull: bool = False, holes: bool = False) → Polygon | MultiPolygon | None#

Creates a polygon or multipolygon surrounding valid data pixels.

Polygons are created around each contiguous region of valid data pixels in the given mask, where a valid data pixel has a value of 255.

Parameters:

  • mask (numpy.NDArray[numpy.uint8]) – A 2D NumPy array containing 0s and 255s for nodata/data (invalid/valid) pixels.

  • transform (Affine) – An affine.Affine object defining the affine transformation from pixel coordinates to a desired coordinate system. Defaults to an identity transform, which returns polygons based on pixel coordinates.

  • convex_hull (bool) – Whether to return the convex hull of the created polygons. Defaults to False.

  • holes (bool) – Whether to include holes in the created polygons. Has no effect if convex_hull is True. Defaults to False.

Returns:

A polygon or multipolygon enclosing valid data pixels in the given mask. The polygon vertex coordinates are transformed according to the given transform.

Return type:

Optional[Union[Polygon, MultiPolygon]

raster_footprint.reproject_geometry(geometry: T, source_crs: CRS, destination_crs: CRS, *, precision: int | None = 7) → T#

Reprojects a polygon or multipolygon from a source CRS to a destination CRS.

Reprojected polygon vertex coordinates are rounded to precision. Duplicate points caused by rounding are removed.

Parameters:

  • geometry (T) – The polygon or multipolygon to reproject.

  • source_crs (CRS) – A rasterio.crs.CRS object defining the coordinate reference system of the input geometry.

  • destination_crs (CRS) – A rasterio.crs.CRS object defining the coordinate reference system of the output geometry.

  • precision (Optional[int]) – The number of decimal places to include in the final polygon vertex coordinates. Defaults to 7.

Returns:

The reprojected polygon or multipolygon.

Return type:

T

raster_footprint.simplify_geometry(geometry: T, *, tolerance: float | None = None) → T#

Reduces the number of vertices in a polygon or each polygon of a multipolygon such that the outline of each simplified polygon is no further away from any of its original vertices than tolerance.

Parameters:

  • geometry (T) – The polygon or multipolygon to simplify.

  • tolerance (Optional[float]) – The maximum distance between original polygon vertices and the simplified polygon. Unit is geographic decimal degrees. Defaults to None.

Returns:

The simplified polygon or multipolygon.

Return type:

T