pystac.extensions.label#

Implements the Label Extension.

class pystac.extensions.label.LabelClasses(properties: Dict[str, Any])[source]#

Defines the list of possible class names (e.g., tree, building, car, hippo).

Use LabelClasses.create() to create a new instance from property values.

apply(classes: Sequence[str | int | float], name: str | None = None) → None[source]#

Sets the properties for this instance.

Parameters:

classes – The different possible class values.
name – The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.

property classes: Sequence[str | int | float]#: Gets or sets the class values.

classmethod create(classes: Sequence[str | int | float], name: str | None = None) → LabelClasses[source]#

Creates a new LabelClasses instance.

Parameters:

classes – The different possible class values.
name – The property key within the asset’s each Feature corresponding to class labels. If labels are raster-formatted, do not supply; required otherwise.

property name: str | None#: Gets or sets the property key within each Feature in the asset corresponding to class labels. If labels are raster-formatted, use None.

properties: Dict[str, Any]#

to_dict() → Dict[str, Any][source]#: Returns this label classes object as a dictionary.

class pystac.extensions.label.LabelCount(properties: Dict[str, Any])[source]#

Contains counts for categorical data.

Use LabelCount.create() to create a new instance.

apply(name: str, count: int) → None[source]#

Sets the properties for this instance.

Parameters:

name – One of the different possible classes within the property.
count – The number of occurrences of the class.

property count: int#: Get or sets the number of occurrences of the class.

classmethod create(name: str, count: int) → LabelCount[source]#

Creates a LabelCount instance.

Parameters:

name – One of the different possible classes within the property.
count – The number of occurrences of the class.

property name: str#: Gets or sets the class that this count represents.

properties: Dict[str, Any]#

to_dict() → Dict[str, Any][source]#: Returns this label count object as a dictionary.

class pystac.extensions.label.LabelExtension(item: Item)[source]#

A class that can be used to extend the properties of an Item with properties from the Label Extension.

To create an instance of LabeExtension, use the LabelExtension.ext() method. For example:

>>> item: pystac.Item = ...
>>> label_ext = LabelExtension.ext(item)

add_geojson_labels(href: str, title: str | None = None, properties: Dict[str, Any] | None = None) → None[source]#

Adds a GeoJSON label asset to this LabelItem.

Parameters:

href – Link to the asset object. Relative and absolute links are both allowed.
title – Optional displayed title for clients and users.
properties – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

add_labels(href: str, title: str | None = None, media_type: str | None = None, properties: Dict[str, Any] | None = None) → None[source]#

Adds a label asset to this LabelItem.

Parameters:

href – Link to the asset object. Relative and absolute links are both allowed.
title – Optional displayed title for clients and users.
media_type – Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.
properties – Optional, additional properties for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

add_source(source_item: Item, title: str | None = None, assets: List[str] | None = None) → None[source]#

Adds a link to a source item.

Parameters:

source_item – Source imagery that the LabelItem applies to.
title – Optional title for the link.
assets – Optional list of assets that determine what assets in the source item this label item data applies to.

Applies label extension properties to the extended Item.

Parameters:

label_description – A description of the label, how it was created, and what it is recommended for
label_type – An Enum of either vector label type or raster label type. Use one of LabelType.
label_properties – These are the names of the property field(s) in each Feature of the label asset’s FeatureCollection that contains the classes (keywords from label:classes if the property defines classes). If labels are rasters, this should be None.
label_classes – Optional, but required if using categorical data. A list of LabelClasses instances defining the list of possible class names for each label:properties. (e.g., tree, building, car, hippo)
label_tasks – Recommended to be a subset of ‘regression’, ‘classification’, ‘detection’, or ‘segmentation’, but may be an arbitrary value.
label_methods – Recommended to be a subset of ‘automated’ or ‘manual’, but may be an arbitrary value.
label_overviews – Optional list of LabelOverview instances that store counts (for classification-type data) or summary statistics (for continuous numerical/regression data).

classmethod ext(obj: Item, add_if_missing: bool = False) → LabelExtension[source]#

Extends the given STAC Object with properties from the Label Extension.

This extension can be applied to instances of Item.

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.

get_sources() → Iterable[Item][source]#

Gets any source items that describe the source imagery used to generate this LabelItem.

Returns:: A possibly empty list of source imagery items. Determined by links of this LabelItem that have rel=='source'.

property label_classes: List[LabelClasses] | None#

Gets or set a list of LabelClasses defining the list of possible class names for each label:properties. (e.g., tree, building, car, hippo).

Optional, but required if using categorical data.

property label_description: str#: Gets or sets a description of the label, how it was created, and what it is recommended for.

property label_methods: List[LabelMethod | str] | None#

Gets or set a list of methods used for labeling.

Usually a subset of ‘automated’ or ‘manual’, but may be arbitrary values.

property label_overviews: List[LabelOverview] | None#: Gets or set a list of LabelOverview instances that store counts (for classification-type data) or summary statistics (for continuous numerical/regression data).

property label_properties: List[str] | None#: Gets or sets the names of the property field(s) in each Feature of the label asset’s FeatureCollection that contains the classes (keywords from label:classes if the property defines classes). If labels are rasters, this should be None.

property label_tasks: List[LabelTask | str] | None#: Gets or set a list of tasks these labels apply to. Usually a subset of ‘regression’, ‘classification’, ‘detection’, or ‘segmentation’, but may be arbitrary values.

property label_type: LabelType#: Gets or sets an Enum of either vector label type or raster label type.

obj: Item#

schema_uri: str#

classmethod summaries(obj: Collection, add_if_missing: bool = False) → SummariesLabelExtension[source]#: Returns the extended summaries object for the given collection.

class pystac.extensions.label.LabelExtensionHooks[source]#

get_object_links(so: STACObject) → List[str | RelType] | None[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 = {'https://stac-extensions.github.io/label/v1.0.0/schema.json', 'label'}#

schema_uri: str = 'https://stac-extensions.github.io/label/v1.0.1/schema.json'#

stac_object_types = {STACObjectType.ITEM}#

class pystac.extensions.label.LabelMethod(value)[source]#

Enumerates recommended values for “label:methods” field.

AUTOMATED = 'automated'#

MANUAL = 'manual'#

class pystac.extensions.label.LabelOverview(properties: Dict[str, Any])[source]#

Stores counts (for classification-type data) or summary statistics (for continuous numerical/regression data).

Use LabelOverview.create() to create a new instance.

apply(property_key: str | None, counts: List[LabelCount] | None = None, statistics: List[LabelStatistics] | None = None) → None[source]#

Sets the properties for this instance.

Either counts or statistics, or both, can be placed in an overview; at least one is required.

Parameters:

property_key – The property key within the asset corresponding to class labels that these counts or statistics are referencing. If the label data is raster data, this should be None.
counts – Optional list of LabelCounts containing counts for categorical data.
statistics – Optional list of LabelStatistics containing statistics for regression/continuous numeric value data.

property counts: List[LabelCount] | None#: Gets or sets the list of LabelCounts containing counts for categorical data.

classmethod create(property_key: str | None, counts: List[LabelCount] | None = None, statistics: List[LabelStatistics] | None = None) → LabelOverview[source]#

Creates a new instance.

Either counts or statistics, or both, can be placed in an overview; at least one is required.

Parameters:

property_key – The property key within the asset corresponding to class labels.
counts – Optional list of LabelCounts containing counts for categorical data.
statistics – Optional list of LabelStatistics containing statistics for regression/continuous numeric value data.

merge_counts(other: LabelOverview) → LabelOverview[source]#

Merges the counts associated with this overview with another overview. Creates a new instance.

Parameters:: other – The other LabelOverview to merge.
Returns:: A new LabelOverview with the counts merged. This will drop any statistics associated with either of the LabelOverviews.

properties: Dict[str, Any]#

property property_key: str | None#: Gets or sets the property key within the asset corresponding to class labels.

property statistics: List[LabelStatistics] | None#: Gets or sets the list of LabelStatistics containing statistics for regression/continuous numeric value data.

to_dict() → Dict[str, Any][source]#: Returns this label overview as a dictionary.

class pystac.extensions.label.LabelRelType(value)[source]#

A list of rel types defined in the Label Extension.

See the Label Extension Links documentation for details.

SOURCE = 'source'#: Used to indicate a link to the source item to which a label item applies.

class pystac.extensions.label.LabelStatistics(properties: Dict[str, Any])[source]#

Contains statistics for regression/continuous numeric value data.

Use LabelStatistics.create() to create a new instance.

apply(name: str, value: float) → None[source]#

Sets the property values for this instance.

Parameters:

name – The name of the statistic being reported.
value – The value of the statistic

classmethod create(name: str, value: float) → LabelStatistics[source]#

Creates a new LabelStatistics instance.

Parameters:

name – The name of the statistic being reported.
value – The value of the statistic

property name: str#: Gets or sets the name of the statistic being reported.

properties: Dict[str, Any]#

to_dict() → Dict[str, Any][source]#: Returns this label statistics object as a dictionary.

property value: float#: Gets or sets the value of the statistic.

class pystac.extensions.label.LabelTask(value)[source]#

Enumerates recommended values for “label:tasks” field.

CLASSIFICATION = 'classification'#

DETECTION = 'detection'#

REGRESSION = 'regression'#

SEGMENTATION = 'segmentation'#

class pystac.extensions.label.LabelType(value)[source]#

Enumerates valid label types (“raster” or “vector”).

ALL = "['vector', 'raster']"#: Convenience attribute for checking if values are valid label types

RASTER = 'raster'#

VECTOR = 'vector'#

class pystac.extensions.label.SummariesLabelExtension(collection: Collection)[source]#

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

property label_classes: List[LabelClasses] | None#: Get or sets the summary of LabelExtension.label_classes values for this Collection.

property label_methods: List[LabelMethod | str] | None#: Get or sets the summary of LabelExtension.label_methods values for this Collection.

property label_properties: List[str] | None#: Get or sets the summary of LabelExtension.label_properties values for this Collection.

property label_tasks: List[LabelTask | str] | None#: Get or sets the summary of LabelExtension.label_tasks values for this Collection.

property label_type: List[LabelType] | None#: Get or sets the summary of LabelExtension.label_type values for this Collection.

summaries: Summaries#: The summaries for the Collection being extended.