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[Union[str, int, float]], name: Optional[str] = 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[Union[str, int, float]]

Gets or sets the class values.

classmethod create(classes: Sequence[Union[str, int, float]], name: Optional[str] = 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: Optional[str]

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: Optional[str] = None, properties: Optional[Dict[str, Any]] = 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: Optional[str] = None, media_type: Optional[str] = None, properties: Optional[Dict[str, Any]] = 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: Optional[str] = None, assets: Optional[List[str]] = 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.

apply(label_description: str, label_type: LabelType, label_properties: Optional[List[str]] = None, label_classes: Optional[List[LabelClasses]] = None, label_tasks: Optional[List[Union[LabelTask, str]]] = None, label_methods: Optional[List[Union[LabelMethod, str]]] = None, label_overviews: Optional[List[LabelOverview]] = None) None[source]

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: Optional[List[LabelClasses]]

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: Optional[List[Union[LabelMethod, str]]]

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: Optional[List[LabelOverview]]

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: Optional[List[str]]

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: Optional[List[Union[LabelTask, str]]]

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]
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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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: Optional[str], counts: Optional[List[LabelCount]] = None, statistics: Optional[List[LabelStatistics]] = 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: Optional[List[LabelCount]]

Gets or sets the list of LabelCounts containing counts for categorical data.

classmethod create(property_key: Optional[str], counts: Optional[List[LabelCount]] = None, statistics: Optional[List[LabelStatistics]] = 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: Optional[str]

Gets or sets the property key within the asset corresponding to class labels.

property statistics: Optional[List[LabelStatistics]]

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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Enumerates recommended values for “label:tasks” field.

CLASSIFICATION = 'classification'
DETECTION = 'detection'
REGRESSION = 'regression'
SEGMENTATION = 'segmentation'
class pystac.extensions.label.LabelType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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: Optional[List[LabelClasses]]

Get or sets the summary of LabelExtension.label_classes values for this Collection.

property label_methods: Optional[List[Union[LabelMethod, str]]]

Get or sets the summary of LabelExtension.label_methods values for this Collection.

property label_properties: Optional[List[str]]

Get or sets the summary of LabelExtension.label_properties values for this Collection.

property label_tasks: Optional[List[Union[LabelTask, str]]]

Get or sets the summary of LabelExtension.label_tasks values for this Collection.

property label_type: Optional[List[LabelType]]

Get or sets the summary of LabelExtension.label_type values for this Collection.