Python API¶

class InsarExtension(
    Generic[T],
    PropertiesExtension,
    ExtensionManagementMixin[pystac.Item | pystac.Collection],
):
    """
    Item/Asset/ItemAssetDefinition InSAR properties.
    For Collection-level support, use InsarExtension.summaries(collection, ...).
    """

    name: Literal["insar"] = "insar"

    @classmethod
    def get_schema_uri(cls) -> str:
        """Return the published schema URI for this extension."""
        return SCHEMA_URI

    @classmethod
    def ext(cls, obj: T, add_if_missing: bool = False) -> InsarExtension[T]:
        """
        Extend an Item, Asset, or ItemAssetDefinition with InSAR properties.

        Applies to:
          - Item (properties)
          - Asset (extra_fields), including Item and Collection assets
          - ItemAssetDefinition (collection.item_assets[*].properties)
        """
        if isinstance(obj, pystac.Item):
            cls.ensure_has_extension(obj, add_if_missing)
            return cast("InsarExtension[T]", ItemInsarExtension(obj))
        if isinstance(obj, pystac.Asset):
            cls.ensure_owner_has_extension(obj, add_if_missing)
            return cast("InsarExtension[T]", AssetInsarExtension(obj))
        if isinstance(obj, pystac.ItemAssetDefinition):
            cls.ensure_owner_has_extension(obj, add_if_missing)
            return cast("InsarExtension[T]", ItemAssetsInsarExtension(obj))
        if isinstance(obj, pystac.Collection):
            raise pystac.ExtensionTypeError(
                "InSAR extension does not apply to type 'Collection'. "
                "Hint: Did you mean to use `InsarExtension.summaries` instead?"
            )
        raise pystac.ExtensionTypeError(cls._ext_error_message(obj))

    @classmethod
    def summaries(
        cls, obj: pystac.Collection, add_if_missing: bool = False
    ) -> SummariesInsarExtension:
        """
        Return the InSAR summaries helper for a collection.
        """
        cls.ensure_has_extension(obj, add_if_missing)
        return SummariesInsarExtension(obj)

    def apply(
        self,
        *,
        perpendicular_baseline: float | int | None = None,
        temporal_baseline: float | int | None = None,
        height_of_ambiguity: float | int | None = None,
        reference_datetime: datetime | None = None,
        secondary_datetime: datetime | None = None,
        processing_dem: str | None = None,
        geocoding_dem: str | None = None,
    ) -> None:
        """
        Sets the properties for the InSAR extension.

        Args:
            perpendicular_baseline: The perpendicular baseline in meters.
            temporal_baseline: The temporal baseline in days.
            height_of_ambiguity: The height of ambiguity in meters.
            reference_datetime: The reference acquisition datetime.
            secondary_datetime: The secondary acquisition datetime.
            processing_dem: The DEM used during interferogram processing.
            geocoding_dem: The DEM used during geocoding.
        """
        self.perpendicular_baseline = perpendicular_baseline
        self.temporal_baseline = temporal_baseline
        self.height_of_ambiguity = height_of_ambiguity
        self.reference_datetime = reference_datetime
        self.secondary_datetime = secondary_datetime
        self.processing_dem = processing_dem
        self.geocoding_dem = geocoding_dem

    @property
    def perpendicular_baseline(self) -> float | None:
        """
        Gets or sets the perpendicular baseline in meters.

        Returns:
            The perpendicular baseline in meters, or None if not set.
        """
        return self._get_property(PERP_BASELINE_PROP, float)

    @perpendicular_baseline.setter
    def perpendicular_baseline(self, v: float | int | None) -> None:
        """
        Sets the perpendicular baseline in meters.

        Args:
            v: The perpendicular baseline in meters, or None to remove the property.
        """
        self._set_property(
            PERP_BASELINE_PROP,
            _validated_number(v, PERP_BASELINE_PROP),
            pop_if_none=True,
        )

    @property
    def temporal_baseline(self) -> float | None:
        """
        Gets or sets the temporal baseline in days.
        """
        return self._get_property(TEMP_BASELINE_PROP, float)

    @temporal_baseline.setter
    def temporal_baseline(self, v: float | int | None) -> None:
        """
        Sets the temporal baseline in days.

        Args:
            v: The temporal baseline in days, or None to remove the property.
        """
        self._set_property(
            TEMP_BASELINE_PROP,
            _validated_number(v, TEMP_BASELINE_PROP),
            pop_if_none=True,
        )

    @property
    def height_of_ambiguity(self) -> float | None:
        """
        Gets or sets the height of ambiguity in meters.
        """
        return self._get_property(HOA_PROP, float)

    @height_of_ambiguity.setter
    def height_of_ambiguity(self, v: float | int | None) -> None:
        """
        Sets the height of ambiguity in meters.

        Args:
            v: The height of ambiguity in meters, or None to remove the property.
        """
        self._set_property(
            HOA_PROP,
            _validated_number(v, HOA_PROP),
            pop_if_none=True,
        )

    @property
    def reference_datetime(self) -> datetime | None:
        """
        Gets or sets the reference acquisition datetime.
        """
        return map_opt(str_to_datetime, self._get_property(REF_DT_PROP, str))

    @reference_datetime.setter
    def reference_datetime(self, v: datetime | None) -> None:
        """
        Sets the reference acquisition datetime.
        """
        self._set_property(REF_DT_PROP, map_opt(datetime_to_str, v), pop_if_none=True)

    @property
    def secondary_datetime(self) -> datetime | None:
        """
        Gets or sets the secondary acquisition datetime.
        """
        return map_opt(str_to_datetime, self._get_property(SEC_DT_PROP, str))

    @secondary_datetime.setter
    def secondary_datetime(self, v: datetime | None) -> None:
        """
        Sets the secondary acquisition datetime.
        """
        self._set_property(SEC_DT_PROP, map_opt(datetime_to_str, v), pop_if_none=True)

    @property
    def processing_dem(self) -> str | None:
        """
        Gets or sets the processing DEM.
        """
        return self._get_property(PROC_DEM_PROP, str)

    @processing_dem.setter
    def processing_dem(self, v: str | None) -> None:
        """
        Sets the processing DEM.

        Args:
            v: The processing DEM, or None to remove the property.
        """
        self._set_property(
            PROC_DEM_PROP,
            _validated_str(v, PROC_DEM_PROP),
            pop_if_none=True,
        )

    @property
    def geocoding_dem(self) -> str | None:
        """
        Gets or sets the geocoding DEM.
        """
        return self._get_property(GEOC_DEM_PROP, str)

    @geocoding_dem.setter
    def geocoding_dem(self, v: str | None) -> None:
        """
        Sets the geocoding DEM.

        Args:
            v: The geocoding DEM, or None to remove the property.
        """
        self._set_property(
            GEOC_DEM_PROP,
            _validated_str(v, GEOC_DEM_PROP),
            pop_if_none=True,
        )

class SummariesInsarExtension(SummariesExtension):
    def _get_singleton_list_value(self, key: str) -> Any | None:
        lst = self.summaries.get_list(key)
        if lst is None:
            return None
        if len(lst) == 0:
            return None
        return lst[0]

    def _set_singleton_list_value(self, key: str, value: Any | None) -> None:
        if value is None:
            self.summaries.remove(key)
            return
        self.summaries.add(key, [value])

    def apply(
        self,
        *,
        reference_datetime: datetime | None = None,
        processing_dem: str | None = None,
        geocoding_dem: str | None = None,
    ) -> None:
        self.reference_datetime = reference_datetime
        self.processing_dem = processing_dem
        self.geocoding_dem = geocoding_dem

    @property
    def reference_datetime(self) -> datetime | None:
        raw = self._get_singleton_list_value(REF_DT_PROP)
        if raw is None:
            return None
        if isinstance(raw, str):
            return str_to_datetime(raw)
        raise ValueError(
            f"Invalid {REF_DT_PROP} summary: expected RFC3339 string in list, "
            f"got {type(raw).__name__}"
        )

    @reference_datetime.setter
    def reference_datetime(self, v: datetime | None) -> None:
        self._set_singleton_list_value(REF_DT_PROP, map_opt(datetime_to_str, v))

    @property
    def processing_dem(self) -> str | None:
        raw = self._get_singleton_list_value(PROC_DEM_PROP)
        if raw is None:
            return None
        if isinstance(raw, str):
            return raw
        raise ValueError(
            f"Invalid {PROC_DEM_PROP} summary: expected string in list, got {type(raw).__name__}"
        )

    @processing_dem.setter
    def processing_dem(self, v: str | None) -> None:
        self._set_singleton_list_value(PROC_DEM_PROP, _validated_str(v, PROC_DEM_PROP))

    @property
    def geocoding_dem(self) -> str | None:
        raw = self._get_singleton_list_value(GEOC_DEM_PROP)
        if raw is None:
            return None
        if isinstance(raw, str):
            return raw
        raise ValueError(
            f"Invalid {GEOC_DEM_PROP} summary: expected string in list, got {type(raw).__name__}"
        )

    @geocoding_dem.setter
    def geocoding_dem(self, v: str | None) -> None:
        self._set_singleton_list_value(GEOC_DEM_PROP, _validated_str(v, GEOC_DEM_PROP))

class ItemInsarExtension(InsarExtension[pystac.Item]):
    item: pystac.Item
    properties: dict[str, Any]

    def __init__(self, item: pystac.Item):
        self.item = item
        self.properties = item.properties

    def __repr__(self) -> str:
        return f"<ItemInsarExtension Item id={self.item.id}>"

class AssetInsarExtension(InsarExtension[pystac.Asset]):
    asset_href: str
    properties: dict[str, Any]

    def __init__(self, asset: pystac.Asset):
        self.asset_href = asset.href
        self.properties = asset.extra_fields

    def __repr__(self) -> str:
        return f"<AssetInsarExtension Asset href={self.asset_href}>"

class ItemAssetsInsarExtension(InsarExtension[pystac.ItemAssetDefinition]):
    asset_defn: pystac.ItemAssetDefinition
    properties: dict[str, Any]

    def __init__(self, item_asset: pystac.ItemAssetDefinition):
        self.asset_defn = item_asset
        self.properties = item_asset.properties

    def __repr__(self) -> str:
        return "<ItemAssetsInsarExtension ItemAssetDefinition>"

class InsarExtensionHooks(ExtensionHooks):
    """Register InSAR schema identifiers and supported STAC object types."""

    schema_uri: str = SCHEMA_URI
    prev_extension_ids: ClassVar[set[str]] = {"insar"}
    stac_object_types: ClassVar[set[pystac.STACObjectType]] = {
        pystac.STACObjectType.COLLECTION,
        pystac.STACObjectType.ITEM,
    }