API Reference

This is the auto-generated API reference documentation.

Core

The top-level stactools namespace.

These core functions and classes provide building blocks for working with STAC catalogs and creating new STAC metadata.

Input and output

Input/output utility functions and definitions.

class stactools.core.io.FsspecStacIO(headers=None)

A subclass of pystac.DefaultStacIO that uses fsspec for reads and writes.

Parameters:

headers (dict[str, str] | None) –

read_text(source, *args, **kwargs)

A concrete implementation of StacIO.read_text.

Converts the source argument to a string (if it is not already) and delegates to FsspecStacIO.read_text_from_href() for opening and reading the file.

Parameters:

• source (str | PathLike) –

• args (Any) –

• kwargs (Any) –

Return type:

str

read_text_from_href(href, **kwargs)

Reads a file as a utf-8 string using fsspec.

Parameters:

• href (str) – The href to read.

• **kwargs – Additional keyword arguments to be passed to fsspec.open.

Returns:

The read text, decoded as utf-8 if necessary.

Return type:

str

write_text(dest, txt, *args, **kwargs)

A concrete implementation of StacIO.write_text.

Converts the dest argument to a string (if it is not already) and delegates to FsspecStacIO.write_text_from_href() for opening and reading the file.

Parameters:

• dest (str | PathLike) –

• txt (str) –

• args (Any) –

• kwargs (Any) –

Return type:

None

write_text_to_href(href, txt, **kwargs)

Writes text to an href using fsspec.

Parameters:

• href (str) – The href to write to.

• txt (str) – The text to write.

• **kwargs – Additional keyword arguments to be passed to fsspec.open.

Return type:

None

stactools.core.io.ReadHrefModifier

Type alias for a function parameter that allows users to manipulate HREFs.

Used for reading, e.g. appending an Azure SAS Token or translating to a signed URL.

alias of Callable[[str], str]

stactools.core.io.read_text(href, read_href_modifier=None, **kwargs)

Reads a string from an href.

If read_href_modifier is provided, then href will be passed through this function before use. This function uses the default pystac.StacIO.

Parameters:

• href (str) – The href to be read

• read_href_modifier (ReadHrefModifier, optional) – A function to modify the provided href. Defaults to None.

• **kwargs – Arbitrary keyword arguments that may be utilized by the concrete implementation.

Returns:

The text as read from the href.

Return type:

str

stactools.core.io.use_fsspec()

Sets the default pystac.StacIO to FsspecStacIO.

Return type:

None

class stactools.core.io.xml.XmlElement(element)

Thin wrapper around lxml etree.Element with some convenience functions.

Parameters:

element (_Element) –

find(xpath)

Find a child XmlElement by xpath.

Parameters:

xpath (str) – The xpath to use for search.

Returns:

The found element, or None if not found.

Return type:

Optional[XmlElement]

find_attr(attr, xpath)

Finds and returns an attribute of an element.

Parameters:

• attr (str) – The attribute name.

• xpath (str) – The xpath of the element to find.

Returns:

The value of the attribute, or None if the element was not found.

Return type:

Optional[str]

find_or_throw(xpath, get_exception)

Find a child XmlElement by xpath, or throw an exception if not found.

Parameters:

• xpath (str) – The xpath to use for search.

• get_exception (Callable[[str], Exception]) – A callable that builds the exception to be thrown when the xpath does not match any elements.

Returns:

The child xml element identified by the xpath.

Return type:

XmlElement

Raises:

Exception – If no element is found.

find_text(xpath)

Finds an element by xpath and returns its contained text.

Parameters:

xpath (str) – The xpath to use for search.

Returns:

The text inside of the found element, or None if the element was not found.

Return type:

Optional[str]

find_text_or_throw(xpath, get_exception)

Finds an element by xpath and returns its contained text, or throws an error if no element is found.

Parameters:

• xpath (str) – The xpath to use for search.

• get_exception (Callable[[str], Exception]) – A callable that builds the exception to be thrown when the xpath does not match any elements.

Returns:

The text inside of the found element, or None if the element was not found.

Return type:

Optional[str]

Raises:

Exception – If no element is found.

findall(xpath)

Finds all children that match the given xpath.

Parameters:

xpath (str) – The xpath to use for search.

Returns:

The found elements.

Return type:

list[XmlElement]

classmethod from_file(href, read_href_modifier=None, **kwargs)

Reads an XmlElement from an href.

Optionally modifies the href with read_href_modifier. Uses stactools.core.io.read_text() to read the text.

Parameters:

• href (str) – The href to read.

• read_href_modifier (Optional[stactools.core.io.ReadHrefModifier]) – An optional callable that will be used to modify the href. Defaults to None.

• kwargs (Any) –

Returns:

The read XmlElement.

Return type:

XmlElement

get_attr(attr)

Returns the value of a given attribute of this element.

Parameters:

attr (str) – The name of the attribute.

Returns:

The value of the attribute, or None if the attribute is not present on this element.

Return type:

Optional[str]

property text: str | None

Returns the text of this element.

Returns:

The text value of this element, decoded as utf-8 if necessary, or None if there is no text.

Return type:

Optional[str]

General utilities

General utility functions.

stactools.core.utils.deprecate(from_, to, version)

Warn with DeprecationWarning and a pre-canned message.

The message is something like:

Foo is deprecated and will be removed in v0.42.0. Use Bar instead.

Parameters:

• from_ (str) – The current function/method/class name.

• to (str) – The name that should be used instead.

• version (str) – The version at which the function/method/class will be removed.

Return type:

None

stactools.core.utils.gdal_driver_is_enabled(name)

Checks to see if the named GDAL driver is enabled.

Checks for the name in rasterio.Env.drivers().

Parameters:

name (str) – The name of the driver.

Returns:

True if the driver is enabled, False otherwise.

Return type:

bool

stactools.core.utils.href_exists(href)

Returns true if there is a file at the given href.

Uses fssepc and its exists method.

Parameters:

href (str) – The href to check.

Returns:

True if the href exists, False if not.

Return type:

bool

stactools.core.utils.ignore_not_georeferenced()

Suppress rasterio’s warning when opening a dataset that contains no georeferencing information.

Return type:

Generator[None, None, None]

stactools.core.utils.map_opt(fn, v)

DEPRECATED: use pystac.utils.map_opt() instead.

Parameters:

• fn (Callable[[T], U]) –

• v (T | None) –

Return type:

U | None

Antimeridian support

Antimeridian utilities.

Most of the functionality in this module is implemented in antimeridian.

class stactools.core.utils.antimeridian.Strategy(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Strategy for handling antimeridian-crossing polygons.

NORMALIZE = 2

Keep the polygon as one polygon, but extend its values to be greater than 180 or less than -180.

SPLIT = 1

Split the polygon into multiple polygons so none cross the antimeridian.

stactools.core.utils.antimeridian.enclose_poles(polygon)

Updates an anti-meridian-crossing polygon to enclose the poles.

This works by detecting anti-meridian crossings and adding points to extend the geometry up to the north (or down to the south) pole. This is useful for (e.g.) polar-orbiting satellites who have swaths that go over the poles.

Deprecated since version v0.4.8: Use the antimeridian package instead.

Parameters:

polygon (shapely.geometry.Polygon) – An input polygon.

Returns:

The same polygon, modified to enclose the poles.

Return type:

shapely.geometry.Polygon

Raises:

• ValueError – Raised if the polygon was split. This is to keep the return

• type the same until this function is removed. –

stactools.core.utils.antimeridian.fix_item(item, strategy)

Modifies an item in-place to deal with antimeridian issues.

If the item’s geometry is not a Polygon` or a MultiPolygon, raises a ValueError.

Parameters:

• item (pystac.Item) – The item to be modified.

• strategy (Strategy) –

Returns:

The input item, whether it was modified or not.

Return type:

Item

stactools.core.utils.antimeridian.normalize(polygon)

‘Normalizes’ a WGS84 lat/lon polygon, or returns None if no changes were made.

This converts the polygon’s x coordinates to all be the same sign, even if the polygon crosses the antimeridian. E.g.:

canonical = Polygon(((170, 40), (170, 50), (-170, 50), (-170, 40), (170, 40)))
normalized = stactools.core.utils.antimeridian.normalize(canonical)
assert normalized.equals(shapely.geometry.box(170, 40, 190, 50))

Inspired by https://towardsdatascience.com/around-the-world-in-80-lines-crossing-the-antimeridian-with-python-and-shapely-c87c9b6e1513.

Note

Will not work on polygons that enclose the north or south poles.

Deprecated since version v0.4.8: “Normalization” does not conform to the GeoJSON specification, and its use is discouraged.

Parameters:

polygon (shapely.geometry.Polygon) – The input polygon.

Returns:

The normalized polygon.

Return type:

Optional[shapely.geometry.Polygon]

stactools.core.utils.antimeridian.normalize_multipolygon(multi_polygon)

‘Normalizes’ a WGS84 lat/lon multi polygon, or returns None if no changes were made.

For each polygon in the multi-polygon, this converts the x coordinates to all be the same sign, even if the polygon crosses the antimeridian. Although the x coordinate sign within each polygon will be made the same, the sign may differ between polygons depending on their position relative to the antimeridian.

Note

Will not work on polygons that enclose the north or south poles.

Deprecated since version v0.4.8: “Normalization” does not conform to the GeoJSON specification, and its use is discouraged.

Parameters:

multi_polygon (shapely.geometry.MultiPolygon) – The input multi-polygon.

Returns:

The normalized multi-polygon.

Return type:

Optional[shapely.geometry.MultiPolygon]

stactools.core.utils.antimeridian.split(polygon)

Splits a single WGS84 polygon into a multipolygon across the antimeridian.

Deprecated since version v0.4.8: Use the antimeridian package instead.

Parameters:

polygon (shapely.geometry.Polygon) – The input polygon.

Returns:

The output polygons, or None if no split occurred.

Return type:

Optional[shapely.geometry.MultiPolygon]

stactools.core.utils.antimeridian.split_multipolygon(multi_polygon)

Splits multiple WGS84 polygons into a multipolygon across the antimeridian.

Deprecated since version v0.4.8: Use the antimeridian package instead.

Parameters:

multi_polygon (shapely.geometry.MultiPolygon) – The input multi polygon.

Returns:

The output polygons. Will not return None, but the Optional return type is kept to preserve backwards compatibility until this function is removed.

Return type:

Optional[shapely.geometry.MultiPolygon]

Converting assets

Format conversion utilities.

stactools.core.utils.convert.DEFAULT_PROFILE = {'blocksize': 512, 'compress': 'deflate', 'driver': 'COG'}

The default profile to use when writing Cloud-Optimized GeoTIFFs (COGs).

stactools.core.utils.convert.cogify(infile, outfile, band=None, profile=None)

Creates a Cloud-Optimized GeoTIFF (COG) from a GDAL-readable file.

A band number can optionally be provided to extract a single band from a multiband file. To create COGs from subdatasets, use stactools.core.utils.convert.cogify_subdatasets().

Parameters:

• infile (str) – The input file.

• outfile (str) – The output COG to be written.

• band (Optional[int]) – The band number in the input file to extract. If not provided, a multi-band COG will be created.

• profile (Optional[dict[str, Any]]) – An optional profile to use on the output file. If not provided, stactools.core.utils.convert.DEFAULT_PROFILE will be used.

Return type:

None

stactools.core.utils.convert.cogify_subdatasets(infile, outdir, subdataset_names=None)

Creates Cloud-Optimized GeoTIFFs for all subdatasets in a multi-dataset raster file.

The created files will be named the same as the source file, with a _SUBDATASET suffix. E.g. if the source file is named foo.hdf and the subdataset is named bar, the output COG will be named foo_bar.tif. Only 2D (and not 3D) subdatasets are supported.

Parameters:

• infile (str) – The input file containing subdatasets.

• outdir (str) – The output directory where the COGs will be created.

• subdataset_names (List[str] | None) –

Returns:

A two tuple (paths, names):

• The first element is a list of the output COG paths

• The second element is a list of subdataset names

Return type:

Tuple[List[str], List[str]]

Running subprocesses

Run subprocesses.

stactools.core.utils.subprocess.call(command)

Call a command using subprocess.Popen.

The standard output of the call will be logged at the INFO level.

Parameters:

command (list[str]) – The command to execute.

Returns:

The return code of the process.

Return type:

int

Adding items to catalogs

Add items to catalogs.

stactools.core.add.add_item(source_item, target_catalog, move_assets=False)

Adds an item to a catalog.

Parameters:

• source_item (pystac.Item) – The Item that will be added. This item is not mutated in this operation.

• target_catalog (pystac.Catalog) – The destination catalog. This catalog will be mutated in this operation.

• move_assets (bool) – If true, move the asset files alongside the target item.

Return type:

None

Adding the raster extension

stactools.core.add_raster.add_raster_to_item(item, statistics=True, histogram=True)

Adds the raster extension to an item.

Parameters:

• item (Item) – The PySTAC Item to extend.

• statistics (bool) – Compute band statistics (min/max). Defaults to True

• histogram (bool) – Compute band histogram. Defaults to True

Returns:

Returns an updated Item. This operation mutates the Item.

Return type:

Item

Copying

stactools.core.copy.move_all_assets(catalog, asset_subdirectory=None, make_hrefs_relative=True, copy=False, ignore_conflicts=False)

Moves assets in a catalog to be alongside the item or collections that own them.

Parameters:

• catalog (Catalog or Collection) – The PySTAC Catalog or Collection to perform the asset transformation on.

• asset_subdirectory (str or None) – A subdirectory that will be used to store the assets. If not supplied, the assets will be moved or copied to the same directory as their owner.

• make_assets_relative (bool) – If True, will make the asset HREFs relative to the assets. If false, the asset will be an absolute href.

• copy (bool) – If False this function will move the asset file; if True, the asset file will be copied.

• ignore_conflicts (bool) – If the asset destination file already exists, this function will throw an error unless ignore_conflicts is True.

• make_hrefs_relative (bool) –

Returns:

Returns the updated catalog or collection. This operation mutates the catalog or collection.

Return type:

Catalog or Collection

stactools.core.copy.move_asset_file(owner, asset_href, asset_subdirectory=None, copy=False, ignore_conflicts=False)

Moves an asset file to be alongside its owner.

Parameters:

• owner (Item or Collection) – The PySTAC Item or Collection to perform the asset transformation on.

• asset_href (str) – The absolute HREF to the asset file.

• asset_subdirectory (str or None) – A subdirectory that will be used to store the assets. If not supplied, the assets will be moved or copied to the same directory as their owner.

• copy (bool) – If False this function will move the asset file; if True, the asset file will be copied.

• ignore_conflicts (bool) – If the asset destination file already exists, this function will throw an error unless ignore_conflicts is True.

Returns:

The new absolute href for the asset file.

Return type:

str

stactools.core.copy.move_asset_file_to_item(item, asset_href, asset_subdirectory=None, copy=False, ignore_conflicts=False)

Moves an asset file to be alongside an item.

Parameters:

• item (Item) – The PySTAC Item to perform the asset transformation on.

• asset_href (str) – The absolute HREF to the asset file.

• asset_subdirectory (str or None) – A subdirectory that will be used to store the assets. If not supplied, the assets will be moved or copied to the same directory as their item.

• copy (bool) – If False this function will move the asset file; if True, the asset file will be copied.

• ignore_conflicts (bool) – If the asset destination file already exists, this function will throw an error unless ignore_conflicts is True.

Returns:

The new absolute href for the asset file.

Return type:

str

stactools.core.copy.move_assets(owner=None, asset_subdirectory=None, make_hrefs_relative=True, copy=False, ignore_conflicts=False, item=None)

Moves an Item or Collection’s assets to be alongside it.

Parameters:

• owner (Item or Collection) – The PySTAC Item or Collection to perform the asset transformation on.

• asset_subdirectory (str or None) – A subdirectory that will be used to store the assets. If not supplied, the assets will be moved or copied to the same directory as the item.

• make_assets_relative (bool) – If True, will make the asset HREFs relative to the assets. If false, the asset will be an absolute href. Defaults to True.

• copy (bool) – If False this function will move the asset file; if True, the asset file will be copied.

• ignore_conflicts (bool) – If the asset destination file already exists, this function will throw an error unless ignore_conflicts is True.

• make_hrefs_relative (bool) –

• item (Item | None) –

Returns:

Returns an updated item or collection. This operation mutates the Item.

Return type:

Item

Creating

stactools.core.create.item(href, *, asset_key='data', roles=['data'], read_href_modifier=None)

Creates a STAC Item from the asset at the provided href.

The read_href_modifer argument can be used to modify the href for the rasterio read, e.g. if you need to sign a url.

This function is intentionally minimal in its signature and capabilities. If you need to customize your Item, do so after creation.

Parameters:

• href (str) – The href of the asset that will be used to create the item.

• asset_key (str) – The unique key of the asset

• roles (List[str]) – The semantic roles of the asset

• read_href_modifier (Optional[ReadHrefModifier]) – An optional callable that will be used to modify the href before reading.

Returns:

A PySTAC Item.

Return type:

pystac.Item

Laying out STAC catalogs

stactools.core.layout.layout_catalog(catalog, item_path_template, create_subcatalogs=False, remove_existing_subcatalogs=False, move_assets=False)

Modifies the layout of a STAC.

Given a catalog and a layout template, modifies the layout of the STAC to either generate subcatalogs based on item properties, or create subdirectories to organize item properties. Both of these are based on the template string provided. See the LayoutTemplate PySTAC API docs for more information on template strings.

Parameters:

• catalog (pystac.Catalog or pystac.Collection) – The Catalog or Collection to change the layout of.

• item_path_template (str) – A string that represents a path of item properties, e.g. "${year}/${month}"

• create_subcatalogs (bool) – If True, create subcatalogs for each of the template directory levels using the item properties to determine which catalog it belongs to.

• remove_existing_subcatalogs (bool) – If True, apply the subcatalogs to all items throughout the catalog and clear any child catalogs, using the newly generated subcatalogs or item paths.

• move_assets (bool) – If True, the assets of the Items will be moved alongside of the Items. Otherwise the asset will remain in place, with the moved Item’s asset HREFs reflecting the existing location.

Returns:

The passed in Catalog or Collection. This operation mutates the catalog or collection.

Return type:

pystac.Catalog or pystac.Collection

Merging

stactools.core.merge.merge_all_items(source_catalog, target_catalog, move_assets=False, ignore_conflicts=False, as_child=False, child_folder=None)

Merge all items from source_catalog into target_catalog.

Calls stactools.core.merge.merge_items on any items that have the same ID between the two catalogs. Any items that don’t exist in the target_catalog will be added to the target_catalog. If the target_catalog is a Collection, it will be set as the collection of any new items.

Parameters:

• source_catalog (pystac.Catalog or pystac.Collection) – The catalog or collection that items will be drawn from to merge into the target catalog. This catalog is not mutated in this operation.

• target_catalog (pystac.Catalog or pystac.Collection) – The target catalog that will be merged into. This catalog will not be mutated in this operation.

• move_assets (bool) – If true, move the asset files alongside the target item.

• ignore_conflicts (bool) – If True, assets with the same keys will not be merged, and asset files that would be moved to overwrite an existing file will not be moved. If False, either of these situations will throw an error.

• as_child (bool) – If True, a child catalog will be added with the content of the source catalog. Otherwise, items will be added directly to the destination catalog.

• child_folder (Optional[str]) – Name of the subfolder to use in case the as_child option is set to True. If None, the id of the catalog will be used as folder name.

Returns:

The target_catalog

Return type:

pystac.Catalog or pystac.Collection

stactools.core.merge.merge_items(source_item, target_item, move_assets=False, ignore_conflicts=False)

Merges the assets from source_item into target_item.

The geometry and bounding box of the items will also be merged.

Parameters:

• source_item (pystac.Item) – The Item that will be merged into target_item. This item is not mutated in this operation.

• target_item (pystac.Item) – The target item that will be merged into. This item will be mutated in this operation.

• move_assets (bool) – If true, move the asset files alongside the target item.

• ignore_conflicts (bool) – If True, assets with the same keys will not be merged, and asset files that would be moved to overwrite an existing file will not be moved. If False, either of these situations will throw an error.

Return type:

None

Reprojection

stactools.core.projection.epsg_from_utm_zone_number(utm_zone_number, south)

Returns the EPSG code for a UTM zone number.

Parameters:

• utm_zone_number (int) – The UTM zone number.

• south (bool) – Whether this UTM zone is a south zone.

Returns:

The EPSG code number for the UTM zone.

Return type:

int

stactools.core.projection.reproject_geom(src_crs, dest_crs, geom, precision=None)

DEPRECATED.

Deprecated since version 0.5.0: Use reproject_shape() instead.

Reprojects a geometry represented as GeoJSON from the src_crs to the dest crs.

Parameters:

• src_crs (pyproj.crs.CRS, rasterio.crs.CRS, or str) – Projection of input data.

• dest_crs (pyproj.crs.CRS, rasterio.crs.CRS, or str) – Projection of output data.

• geom (dict) – The GeoJSON geometry

• precision (int, optional) – The precision of the reprojection operation.

Returns:

The reprojected geometry

Return type:

dict

stactools.core.projection.reproject_shape(src_crs, dst_crs, geom, precision=None)

Projects a shapely.Geometry and rounds the projected vertex coordinates to precision.

Duplicate points caused by rounding are removed.

Parameters:

• src_crs (rasterio.crs.CRS) – The CRS of the input geometry.

• dst_crs (rasterio.crs.CRS) – The CRS of the output geometry.

• geom (GeoInterface) – GeoJSON like dict or shapely geometry object to reproject

• precision (int) – The number of decimal places to include in the final Geometry vertex coordinates.

Returns:

the reprojected shapely geometry object

Return type:

geom

stactools.core.projection.transform_from_bbox(bbox, shape)

Calculate the affine transformation from the bbox and shape.

Only take the first 6 elements, as that is all that is necessary.

Parameters:

• bbox (list[float]) – The bounding box of the transform.

• shape (list[int]) – The shape of the transform.

Returns:

The six-element GDAL transform.

Return type:

list[float]

Raster footprint generation

Generate convex hulls of valid raster data for use in STAC Item geometries.

class stactools.core.utils.raster_footprint.FootprintMergeStrategy(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Strategy for handling the aggregation of differing asset footprints.

FIRST = 1

Use the footprint of the first matching asset.

INTERSECTION = 3

Use the mutual intersection of all matching asset footprints.

UNION = 2

Union the geometries of all matching assets.

class stactools.core.utils.raster_footprint.RasterFootprint(data_array, crs, transform, *, dst_crs='EPSG:4326', precision=7, densification_factor=None, densification_distance=None, simplify_tolerance=None, no_data=None)

An object for creating a convex hull polygon around all areas within an raster that have data values (i.e., they do not have the nodata value). This convex hull is termed the “footprint” of the raster data and is returned by the footprint() method as a polygon in a GeoJSON dictionary for use as the geometry attribute of a STAC Item.

Two important operations during this calculation are the densification of the footprint in the native CRS and simplification of the footprint after reprojection. If the initial low-vertex polygon in the native CRS is not densified, this can result in a reprojected polygon that does not accurately represent the data footprint. For example, a MODIS asset represented by a rectangular 5 point Polygon in a sinusoidal projection will reproject to a parallelogram in EPSG 4326, when it would be more accurately represented by a polygon with two parallel sides and two curved sides. The difference between these representations is greater the further away from the meridian and equator the asset is located.

After reprojection, the footprint may have more points than desired. This can be simplified to a polygon with fewer points that maintain a maximum distance to the original geometry.

Parameters:

• data_array (numpy.NDArray[Any]) – The raster data used for the footprint calculation.

• crs (CRS) – Coordinate reference system of the raster data.

• dst_crs (CRS) – Coordinate reference system of the footprint data. Defaults to EPSG 4236.

• transform (Affine) – Matrix defining the transformation from pixel to CRS coordinates.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the footprint polygon before projection. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_distance.

• densification_distance (Optional[float]) – The distance by which to increase point density within the footprint polygon before projection. If the distance is set to 2 and the segment length between two polygon vertices is 10, 4 new vertices would be created along the segment. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_factor.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – The nodata value in data_array. If set to None, this will return a footprint including nodata values.

crs: CRS

Coordinate reference system of the raster data.

data_array: ndarray[Any, dtype[Any]]

2D or 3D array of raster data.

data_extent(mask)

Produces the data footprint in the native CRS.

Parameters:

mask (numpy.NDArray[numpy.uint8]) – A 2D array containing 0s and 1s for nodata/data pixels.

Returns:

A native CRS polygon of the convex hull of data pixels.

Return type:

Optional[Polygon]

classmethod data_footprints_for_data_assets(item, *, asset_names=[], dst_crs='EPSG:4326', precision=7, densification_factor=None, densification_distance=None, simplify_tolerance=None, no_data=None, bands=[1], skip_errors=True)

Accepts an Item and an optional list of asset names within that Item, and produces an iterator over the same asset names (if they exist) and dictionaries representing GeoJSON Polygons of the data footprints of the assets.

See RasterFootprint for details on the data footprint calculation.

Parameters:

• item (Item) – The PySTAC Item to update.

• asset_names (List[str]) – The names of the assets for which to attempt to extract footprints. The first successful footprint will be used. If the list is empty, all assets will be tried until one is successful.

• dst_crs (CRS) – Coordinate reference system of the footprint data. Defaults to EPSG 4236.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the footprint polygon before projection. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_distance.

• densification_distance (Optional[float]) – The distance by which to increase point density within the footprint polygon before projection. If the distance is set to 2 and the segment length between two polygon vertices is 10, 4 new vertices would be created along the segment. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_factor.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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.

• skip_errors (bool) – If False, raise an error for a missing href or footprint calculation failure.

Returns:

Iterator of the asset name and dictionary representing a GeoJSON Polygon of the data footprint for each asset.

Return type:

Iterator[Tuple[str, Dict[str, Any]]]

data_mask()

Produces a mask of valid data in the source image. Nodata pixels values are set to 0, data pixels are set to 1.

Returns:

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

Return type:

numpy.NDArray[numpy.uint8]

densification_distance: float | None

Optional distance for densifying polygon vertices before reprojection.

densification_factor: int | None

Optional factor for densifying polygon vertices before reprojection.

densify_polygon(polygon)

Adds vertices to the footprint polygon in the native CRS using either self.densification_factor or self.densification_distance.

Parameters:

polygon (Polygon) – Footprint polygon in the native CRS.

Returns:

Densified footprint polygon in the native CRS.

Return type:

Polygon

dst_crs: CRS = 'EPSG:4326'

Coordinate reference system of the footprint.

footprint()

Produces the footprint surrounding data (not nodata) pixels in the source image. If the footprint is unable to be computed, None is returned.

Returns:

A GeoJSON dictionary containing the footprint polygon.

Return type:

Optional[Dict[str, Any]]

classmethod from_href(href, *, dst_crs='EPSG:4326', precision=7, densification_factor=None, densification_distance=None, simplify_tolerance=None, no_data=None, bands=[1])

Produces a RasterFootprint instance from an image href.

The href can point to any file that is openable by rasterio.

Parameters:

• href (str) – The href of the image to process.

• dst_crs (CRS) – Coordinate reference system of the footprint data. Defaults to EPSG 4236.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the footprint polygon before projection. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_distance.

• densification_distance (Optional[float]) – The distance by which to increase point density within the footprint polygon before projection. If the distance is set to 2 and the segment length between two polygon vertices is 10, 4 new vertices would be created along the segment. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_factor.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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 RasterFootprint instance.

Return type:

RasterFootprint

classmethod from_rasterio_dataset_reader(reader, *, dst_crs='EPSG:4326', precision=7, densification_factor=None, densification_distance=None, simplify_tolerance=None, no_data=None, bands=[1])

Produces a RasterFootprint instance from a rasterio.io.DatasetReader object, i.e., an opened dataset object returned by a rasterio.open() call.

Parameters:

• reader (DatasetReader) – A rasterio dataset reader object for the image to process.

• dst_crs (CRS) – Coordinate reference system of the footprint data. Defaults to EPSG 4236.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the footprint polygon before projection. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_distance.

• densification_distance (Optional[float]) – The distance by which to increase point density within the footprint polygon before projection. If the distance is set to 2 and the segment length between two polygon vertices is 10, 4 new vertices would be created along the segment. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_factor.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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 RasterFootprint instance.

Return type:

RasterFootprint

no_data: int | float | None

Optional value defining pixels to exclude from the footprint.

precision: int

Number of decimal places in the final footprint coordinates.

reproject_polygon(polygon)

Projects a polygon and rounds the projected vertex coordinates to self.precision.

Duplicate points caused by rounding are removed.

Parameters:

polygon (Polygon) – Footprint polygon in the native CRS.

Returns:

Footprint polygon in ‘dst_crs’.

Return type:

Polygon

simplify_polygon(polygon)

Reduces the number of polygon vertices such that the simplified polygon shape is no further away than the original polygon vertices than self.simplify_tolerance.

Parameters:

polygon (Polygon) – Polygon to be simplified.

Returns:

Reduced vertex polygon.

Return type:

Polygon

simplify_tolerance: float | None

Optional maximum allowable error when simplifying the reprojected polygon.

transform: Affine

Transformation matrix from pixel to CRS coordinates.

classmethod update_geometry_from_asset_footprint(item, *, asset_names=[], dst_crs='EPSG:4326', precision=7, densification_factor=None, densification_distance=None, simplify_tolerance=None, no_data=None, bands=[1], skip_errors=True, footprint_merge_strategy=FootprintMergeStrategy.FIRST)

Accepts an Item and an optional list of asset names within that Item, and updates the geometry of that Item in-place with the data footprint derived from the first of the assets that exists in the Item. The Item bbox is also updated in-place to bound the new footprint extents.

See RasterFootprint for details on the data footprint calculation.

Parameters:

• item (Item) – The PySTAC Item to update.

• asset_names (List[str]) – The names of the assets for which to attempt to extract footprints. The first successful footprint will be used. If the list is empty, all assets will be tried until one is successful.

• dst_crs (CRS) – Coordinate reference system of the footprint data. Defaults to EPSG 4236.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the footprint polygon before projection. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_distance.

• densification_distance (Optional[float]) – The distance by which to increase point density within the footprint polygon before projection. If the distance is set to 2 and the segment length between two polygon vertices is 10, 4 new vertices would be created along the segment. Higher densities produce higher fidelity footprints in areas of high projection distortion. Mutually exclusive with densification_factor.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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.

• skip_errors (bool) – If False, raise an error for a missing href or footprint calculation failure.

• footprint_aggregator (FootprintMergeStrategy) – Provides a means to control how the footprints of assets are aggregated; see FootprintMergeStrategy for details; defaults to using the FIRST strategy

• footprint_merge_strategy (FootprintMergeStrategy) –

Returns:

True if the Item geometry was successfully updated, False if not.

Return type:

bool

stactools.core.utils.raster_footprint.data_footprint(href, *, precision=7, densification_factor=None, simplify_tolerance=None, no_data=None, bands=[1])

DEPRECATED.

Deprecated since version 0.4.4: Call footprint() on a RasterFootprint instance created with RasterFootprint.from_href() instead.

Produces a data footprint from the href of a raster file.

See RasterFootprint for details on the data footprint calculation.

Parameters:

• href (str) – The href of the image to process.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the polygon before projection to EPSG 4326. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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 dictionary representing a GeoJSON Polygon of the data footprint of the raster data retrieved from the given href.

Return type:

Optional[Dict[str, Any]]

stactools.core.utils.raster_footprint.data_footprints_for_data_assets(item, *, asset_names=[], precision=7, densification_factor=None, simplify_tolerance=None, no_data=None, bands=[1], skip_errors=True)

DEPRECATED.

Deprecated since version 0.4.4: Use RasterFootprint.data_footprints_for_data_assets() instead.

Accepts an Item and an optional list of asset names within that Item, and produces an iterator over the same asset names (if they exist) and dictionaries representing GeoJSON Polygons of the data footprints of the assets.

See RasterFootprint for details on the data footprint calculation.

Parameters:

• item (Item) – The PySTAC Item to update.

• asset_names (List[str]) – The names of the assets for which to attempt to extract footprints. The first successful footprint will be used. If the list is empty, all assets will be tried until one is successful.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the polygon before projection to EPSG 4326. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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.

• skip_errors (bool) – If False, raise an error for a missing href or footprint calculation failure.

Returns:

Iterator of the asset name and dictionary representing a GeoJSON Polygon of the data footprint for each asset.

Return type:

Iterator[Tuple[str, Dict[str, Any]]]

stactools.core.utils.raster_footprint.densify_by_distance(point_list, distance)

Densifies the number of points in a list of points by inserting new points at intervals between each set of successive points. For example, if two successive points in the list are separated by 10 units and a distance of 2 is provided, 4 new points will be added 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. A smaller densification distance should be used when reprojection results in greater curvature from the original geometry.

Returns:

A list of the densified points.

Return type:

List[Tuple[float, float]]

stactools.core.utils.raster_footprint.densify_by_factor(point_list, factor)

Densifies the number of points in a list of points by a factor. For example, a list of 5 points and a factor of 2 will result in 10 points (one new point between each original 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. A larger densification factor should be used when reprojection results in greater curvature from the original geometry.

Returns:

A list of the densified points.

Return type:

List[Tuple[float, float]]

stactools.core.utils.raster_footprint.densify_reproject_simplify(polygon, crs, *, dst_crs='EPSG:4326', densification_factor=None, precision=7, simplify_tolerance=None)

Densifies the input polygon, reprojects it, and simplifies the resulting polygon.

See RasterFootprint for details on densification and simplification.

Parameters:

• polygon (Polygon) – The input polygon.

• crs (CRS) – The CRS of the input polygon.

• dst_crs (CRS) – The CRS of the output polygon. Defaults to EPSG 4326

• densification_factor (Optional[int]) – The factor by which to increase point density within the polygon before projection. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion.

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

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

Returns:

The reprojected Polygon.

Return type:

Polygon

stactools.core.utils.raster_footprint.reproject_polygon(polygon, crs, precision=7, dst_crs='EPSG:4326')

DEPRECATED.

Deprecated since version 0.5.0: Use projection.reproject_shape() instead.

Projects a polygon and rounds the projected vertex coordinates to precision.

Duplicate points caused by rounding are removed.

Parameters:

• polygon (Polygon) – The polygon to reproject.

• crs (CRS) – The CRS of the input polygon.

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

• dst_crs (CRS) – The CRS of the output polygon. Defaults to EPSG 4326

Returns:

Polygon in ‘dst_crs’. Default to EPSG 4326

Return type:

Polygon

stactools.core.utils.raster_footprint.update_geometry_from_asset_footprint(item, *, asset_names=[], precision=7, densification_factor=None, simplify_tolerance=None, no_data=None, bands=[1], skip_errors=True)

DEPRECATED.

Deprecated since version 0.4.4: Use RasterFootprint.update_geometry_from_asset_footprint() instead.

Accepts an Item and an optional list of asset names within that Item, and updates the geometry of that Item in-place with the data footprint derived from the first of the assets that exists in the Item. The Item bbox is also updated in-place to bound the new footprint extents.

See RasterFootprint for details on the data footprint calculation.

Parameters:

• item (Item) – The PySTAC Item to update.

• asset_names (List[str]) – The names of the assets for which to attempt to extract footprints. The first successful footprint will be used. If the list is empty, all assets will be tried until one is successful.

• precision (int) – The number of decimal places to include in the final footprint coordinates.

• densification_factor (Optional[int]) – The factor by which to increase point density within the polygon before projection to EPSG 4326. A factor of 2 would double the density of points (placing one new point between each existing pair of points), a factor of 3 would place two points between each point, etc. Higher densities produce higher fidelity footprints in areas of high projection distortion.

• simplify_tolerance (Optional[float]) – Distance, in degrees, within which all locations on the simplified polygon will be to the original polygon.

• no_data (Optional[Union[int, float]]) – Explicitly sets the nodata value if not in source image metadata. If set to None, this will return a footprint including nodata values.

• 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.

• skip_errors (bool) – If False, raise an error for a missing href or footprint calculation failure.

Returns:

True if the Item geometry was successfully updated, False if not.

Return type:

bool

Geometry

class stactools.core.geometry.GeoInterface(*args, **kwargs)

A simple protocol for things that have a __geo_interface__ method.

The __geo_interface__ protocol is described here, and is used within shapely to extract geometries from objects.

stactools.core.geometry.bounding_box(geom)

Extracts and returns the bounding box of a GeoJSON geometry.

Parameters:

geom (dict) – A GeoJSON Feature, GeoJSON FeatureCollection, GeoJSON geometry, STAC Item, or STAC ItemCollection.

Returns:

A list of float values containing the bounding box of the GeoJSON geometry in the format [min X, min Y, max X, max Y]

Return type:

list

stactools.core.geometry.mutual_intersection(geoms)

Finds the mutual intersection of a set of geometries.

Parameters:

geoms (List[Geometry]) – A non-empty list of geometries to intersect

Returns:

The mutual intersection of all geometries

Return type:

Geometry

Testing

Utilities for tests, usually used in stactools-packages.

Command line testing

class stactools.testing.cli_test.CliTestCase(methodName='runTest')

A command-line interface test case.

abstract create_subcommand_functions()

Return list of ‘create_command’ functions from implementations.

Returns:

The commands to run.

Return type:

list[Callable[[click.Group], click.Command]]

run_command(cmd)

Runs a command, returning its result.

If there is output, print it to stdout.

Parameters:

cmd (str) – The command to run.

Returns:

The command-line invocation result.

Return type:

click.Result

setUp()

Sets up a mock cli group for testing.

Return type:

None

use_debug_logging()

Enable debug logging for these tests.

Return type:

None

Fetching and using test data

class stactools.testing.test_data.ExternalData(url, compress=None, s3=None, planetary_computer=False)

External data configurations for fetching and storing remote files.

Parameters:

• url (str) – URL at which the external data is found.

• compress (str) – Compression method that has been used on external data. If provided, data is extracted after it is fetched. Only zip is supported. Defaults to None.

• s3 (Dict[str, Any]) – Dictionary containing keyword arguments to use when instantiating s3fs.S3FileSystem. Defaults to None.

• planetary_computer (bool) – Whether external data is on planetary computer and needs to be signed. Defaults to False.

class stactools.testing.test_data.TestData(path, external_data={}, external_subpath='data-files/external')

A structure for getting paths to test data files, and fetching external data for local testing.

Initializing this from, e.g., /home/user/my-package/tests/__init__.py:

test_data = TestData(__file__)

Means that get_path will be relative to /home/user/my-package/tests.

test_data.get_path("data-files/basic")
# "/home/user/my-package/tests/data-files/basic"

When caching external data that base path is appended with test_data.external_subpath which by default is ‘data-files/external’.

For instance with the following external data configuration the external data file will be fetched from the URL, extracted from its zip file and locally stored at: /home/user/my-package/tests/data-files/external/AST_L1T_00305032000040446_20150409135350_78838.hdf

test_data.external_data = {
    'AST_L1T_00305032000040446_20150409135350_78838.hdf': {
        'url':
            ('https://ai4epublictestdata.blob.core.windows.net/'
            'stactools/aster/AST_L1T_00305032000040446_20150409135350_78838.zip'),
        'compress': 'zip'
    }
}
test_data.get_external_data("AST_L1T_00305032000040446_20150409135350_78838.hdf")

Parameters:

• path (str) – The path to any file in the directory where data is (or will be) stored. The directory information is taken from this path and used as the base for relative paths for the local data. It is stored on the class as self.base_path

• external_data (Dict[str, ExternalData]) – External data configurations for fetching and storing remote files. This is defined as a dictionary with the following structure: the key is the relative path (relative to self.base_path / self.external_subpath) for cached data after it is fetched from remote and the value is the configuration as defined in ExternalData.

• external_subpath (str) – The subpath under self.base_path that is used for storing external data files. Defaults to ‘data-files/external’

get_external_data(rel_path)

Returns the path to the local cached version of the external data.

If data is not yet cached, this method fetches it, caches it, then returns the path to the local cached version.

Parameters:

rel_path (str) – This is both the filename that the local data will be stored at _and_ a key in the external_data dictionary where the corresponding value is the configuration information for the external data.

Returns:

The absolute path to the local cached version of the

external data file.

Return type:

str

get_path(rel_path)

Returns an absolute path to a local data file.

Parameters:

rel_path (str) – The relative path to the test data file. The path is assumed to be relative to self.base_path.

Returns:

The absolute path joining self.base_path and rel_path

Return type:

str

previous

Command line interface (CLI)

next

Determining Footprints from Raster Data