pystac.extensions.eo

Implements the Electro-Optical Extension.

class pystac.extensions.eo.AssetEOExtension(asset: Asset)[source]

A concrete implementation of EOExtension on an Asset that extends the Asset fields to include properties defined in the Electro-Optical Extension.

This class should generally not be instantiated directly. Instead, call EOExtension.ext() on an Asset to extend it.

additional_read_properties: Iterable[dict[str, Any]] | None = None

If present, this will be a list containing 1 dictionary representing the properties of the owning Item.

asset_href: str

The href value of the Asset being extended.

properties: dict[str, Any]

The Asset fields, including extension properties.

class pystac.extensions.eo.Band(properties: dict[str, Any])[source]

Represents Band information attached to an Item that implements the eo extension.

Use Band.create() to create a new Band.

apply(name: str, common_name: str | None = None, description: str | None = None, center_wavelength: float | None = None, full_width_half_max: float | None = None, solar_illumination: float | None = None) None[source]

Sets the properties for this Band.

Parameters:
  • name – The name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).

  • common_name – The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.

  • description – Description to fully explain the band.

  • center_wavelength – The center wavelength of the band, in micrometers (μm).

  • full_width_half_max – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).

  • solar_illumination – The solar illumination of the band, as measured at half the maximum transmission, in W/m2/micrometers.

static band_description(common_name: str) str | None[source]

Returns a description of the band for one with a common name.

Parameters:

common_name – The common band name. Must be one of the list of accepted common names.

Returns:

If a recognized common name, returns a description including the band range. Otherwise returns None.

Return type:

str or None

static band_range(common_name: str) tuple[float, float] | None[source]

Gets the band range for a common band name.

Parameters:

common_name – The common band name. Must be one of the list of accepted common names.

Returns:

The band range for this name as (min, max), or None if this is not a recognized common name.

Return type:

Tuple[float, float] or None

property center_wavelength: float | None

Get or sets the center wavelength of the band, in micrometers (μm).

Returns:

float

property common_name: str | None
Get or sets the name commonly used to refer to the band to make it easier

to search for bands across instruments. See the list of accepted common names.

Returns:

Optional[str]

classmethod create(name: str, common_name: str | None = None, description: str | None = None, center_wavelength: float | None = None, full_width_half_max: float | None = None, solar_illumination: float | None = None) Band[source]

Creates a new band.

Parameters:
  • name – The name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).

  • common_name – The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.

  • description – Description to fully explain the band.

  • center_wavelength – The center wavelength of the band, in micrometers (μm).

  • full_width_half_max – Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).

  • solar_illumination – The solar illumination of the band, as measured at half the maximum transmission, in W/m2/micrometers.

property description: str | None

Get or sets the description to fully explain the band. CommonMark 0.29 syntax MAY be used for rich text representation.

Returns:

str

property full_width_half_max: float | None
Get or sets the full width at half maximum (FWHM). The width of the band,

as measured at half the maximum transmission, in micrometers (μm).

Returns:

[float]

property name: str

Get or sets the name of the band (e.g., “B01”, “B02”, “B1”, “B5”, “QA”).

Returns:

str

properties: dict[str, Any]
property solar_illumination: float | None
Get or sets the solar illumination of the band,

as measured at half the maximum transmission, in W/m2/micrometers.

Returns:

[float]

to_dict() dict[str, Any][source]

Returns this band as a dictionary.

Returns:

The serialization of this Band.

Return type:

dict

class pystac.extensions.eo.EOExtension[source]

An abstract class that can be used to extend the properties of an Item or Asset with properties from the Electro-Optical Extension. This class is generic over the type of STAC Object to be extended (e.g. Item, Asset).

To create a concrete instance of EOExtension, use the EOExtension.ext() method. For example:

>>> item: pystac.Item = ...
>>> eo_ext = EOExtension.ext(item)
apply(bands: list[Band] | None = None, cloud_cover: float | None = None, snow_cover: float | None = None) None[source]

Applies Electro-Optical Extension properties to the extended Item or Asset.

Parameters:
  • bands – A list of available bands where each item is a Band object. If given, requires at least one band.

  • cloud_cover – The estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.

  • snow_cover – The estimate of snow cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.

property bands: list[Band] | None

Gets or sets a list of available bands where each item is a Band object (or None if no bands have been set). If not available the field should not be provided.

property cloud_cover: float | None

Get or sets the estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.

Returns:

float or None

classmethod ext(obj: T, add_if_missing: bool = False) EOExtension[T][source]

Extends the given STAC Object with properties from the Electro-Optical Extension.

This extension can be applied to instances of Item or Asset.

Raises:

pystac.ExtensionTypeError – If an invalid object type is passed.

classmethod get_schema_uri() str[source]

Gets the schema URI associated with this extension.

classmethod get_schema_uris() list[str][source]

Gets a list of schema URIs associated with this extension.

name: Literal['eo'] = 'eo'
property snow_cover: float | None

Get or sets the estimate of snow cover as a percentage (0-100) of the entire scene. If not available the field should not be provided.

Returns:

float or None

classmethod summaries(obj: Collection, add_if_missing: bool = False) SummariesEOExtension[source]

Returns the extended summaries object for the given collection.

class pystac.extensions.eo.EOExtensionHooks[source]
migrate(obj: dict[str, Any], version: STACVersionID, info: STACJSONDescription) None[source]

Migrate a STAC Object in dict format from a previous version. The base implementation will update the stac_extensions to the latest schema ID. This method will only be called for STAC objects that have been identified as a previous version of STAC. Implementations should directly manipulate the obj dict. Remember to call super() in order to change out the old ‘stac_extension’ entry with the latest schema URI.

prev_extension_ids = {'eo', 'https://stac-extensions.github.io/eo/v1.0.0/schema.json'}
schema_uri: str = 'https://stac-extensions.github.io/eo/v1.1.0/schema.json'
stac_object_types = {Feature}
class pystac.extensions.eo.ItemAssetsEOExtension(item_asset: AssetDefinition)[source]
asset_defn: AssetDefinition
properties: dict[str, Any]

The properties that this extension wraps.

The extension which implements PropertiesExtension can use _get_property and _set_property to get and set values on this instance. Note that _set_properties mutates the properties directly.

class pystac.extensions.eo.ItemEOExtension(item: Item)[source]

A concrete implementation of EOExtension on an Item that extends the properties of the Item to include properties defined in the Electro-Optical Extension.

This class should generally not be instantiated directly. Instead, call EOExtension.ext() on an Item to extend it.

get_assets(name: str | None = None, common_name: str | None = None) dict[str, Asset][source]

Get the item’s assets where eo:bands are defined.

Parameters:
  • name – If set, filter the assets such that only those with a matching eo:band.name are returned.

  • common_name – If set, filter the assets such that only those with a matching eo:band.common_name are returned.

Returns:

A dictionary of assets that match name

and/or common_name if set or else all of this item’s assets were eo:bands are defined.

Return type:

Dict[str, Asset]

item: Item

The Item being extended.

properties: dict[str, Any]

The Item properties, including extension properties.

class pystac.extensions.eo.SummariesEOExtension(collection: Collection)[source]

A concrete implementation of SummariesExtension that extends the summaries field of a Collection to include properties defined in the Electro-Optical Extension.

property bands: list[Band] | None

Get or sets the summary of EOExtension.bands values for this Collection.

property cloud_cover: RangeSummary[float] | None

Get or sets the summary of EOExtension.cloud_cover values for this Collection.

property snow_cover: RangeSummary[float] | None

Get or sets the summary of EOExtension.snow_cover values for this Collection.

pystac.extensions.eo.validated_percentage(v: float | None) float | None[source]