Composites

The composites module handles satellite imagery acquisition and annual composite generation from various sources via Google Earth Engine or local files.

composites

Composite builders for satellite imagery acquisition.

Handles creating annual composites from various satellite sources via Google Earth Engine or loading local GeoTIFF files.

CompositeBuilder

Bases: ABC

Abstract base class for satellite composite builders.

Subclasses must implement :meth:build and :meth:get_band_mapping.

Source code in agribound/composites/base.py

class CompositeBuilder(ABC):
    """Abstract base class for satellite composite builders.

    Subclasses must implement :meth:`build` and :meth:`get_band_mapping`.
    """

    @abstractmethod
    def build(self, config: AgriboundConfig) -> str:
        """Build an annual composite and download it as a local GeoTIFF.

        Parameters
        ----------
        config : AgriboundConfig
            Pipeline configuration.

        Returns
        -------
        str
            Path to the downloaded composite GeoTIFF.
        """

    @abstractmethod
    def get_band_mapping(self, source: str) -> dict[str, str]:
        """Return the band name mapping for a satellite source.

        Parameters
        ----------
        source : str
            Satellite source name.

        Returns
        -------
        dict[str, str]
            Mapping of canonical names (R, G, B, NIR) to source band names.
        """

    def get_resolution(self, source: str) -> float | None:
        """Return the native resolution in meters for a source.

        Parameters
        ----------
        source : str
            Satellite source name.

        Returns
        -------
        float or None
            Resolution in meters, or *None* for local sources.
        """
        return SOURCE_REGISTRY.get(source, {}).get("resolution_m")

build abstractmethod

build(config: AgriboundConfig) -> str

Build an annual composite and download it as a local GeoTIFF.

Parameters:

Name	Type	Description	Default
config	AgriboundConfig	Pipeline configuration.	required

Returns:

Type	Description
str	Path to the downloaded composite GeoTIFF.

Source code in agribound/composites/base.py

@abstractmethod
def build(self, config: AgriboundConfig) -> str:
    """Build an annual composite and download it as a local GeoTIFF.

    Parameters
    ----------
    config : AgriboundConfig
        Pipeline configuration.

    Returns
    -------
    str
        Path to the downloaded composite GeoTIFF.
    """

get_band_mapping abstractmethod

get_band_mapping(source: str) -> dict[str, str]

Return the band name mapping for a satellite source.

Parameters:

Name	Type	Description	Default
source	str	Satellite source name.	required

Returns:

Type	Description
dict[str, str]	Mapping of canonical names (R, G, B, NIR) to source band names.

Source code in agribound/composites/base.py

@abstractmethod
def get_band_mapping(self, source: str) -> dict[str, str]:
    """Return the band name mapping for a satellite source.

    Parameters
    ----------
    source : str
        Satellite source name.

    Returns
    -------
    dict[str, str]
        Mapping of canonical names (R, G, B, NIR) to source band names.
    """

get_resolution

get_resolution(source: str) -> float | None

Return the native resolution in meters for a source.

Parameters:

Name	Type	Description	Default
source	str	Satellite source name.	required

Returns:

Type	Description
float or None	Resolution in meters, or None for local sources.

Source code in agribound/composites/base.py

def get_resolution(self, source: str) -> float | None:
    """Return the native resolution in meters for a source.

    Parameters
    ----------
    source : str
        Satellite source name.

    Returns
    -------
    float or None
        Resolution in meters, or *None* for local sources.
    """
    return SOURCE_REGISTRY.get(source, {}).get("resolution_m")

get_composite_builder

get_composite_builder(source: str) -> CompositeBuilder

Factory function to get the appropriate composite builder.

Parameters:

Name	Type	Description	Default
source	str	Satellite source name.	required

Returns:

Type	Description
CompositeBuilder	Builder instance for the given source.

Raises:

Type	Description
ValueError	If the source is not recognized.

Source code in agribound/composites/base.py

def get_composite_builder(source: str) -> CompositeBuilder:
    """Factory function to get the appropriate composite builder.

    Parameters
    ----------
    source : str
        Satellite source name.

    Returns
    -------
    CompositeBuilder
        Builder instance for the given source.

    Raises
    ------
    ValueError
        If the source is not recognized.
    """
    if source not in SOURCE_REGISTRY:
        raise ValueError(f"Unknown source {source!r}. Available: {list(SOURCE_REGISTRY.keys())}")

    if source == "local":
        from agribound.composites.local import LocalCompositeBuilder

        return LocalCompositeBuilder()
    elif source in ("google-embedding", "tessera-embedding"):
        from agribound.composites.local import EmbeddingCompositeBuilder

        return EmbeddingCompositeBuilder()
    else:
        from agribound.composites.gee import GEECompositeBuilder

        return GEECompositeBuilder()

list_sources

list_sources() -> dict[str, dict[str, Any]]

List all available satellite sources and their metadata.

Returns:

Type	Description
dict[str, dict]	Dictionary mapping source names to their metadata.

Examples:

>>> from agribound import list_sources
>>> sources = list_sources()
>>> for name, info in sources.items():
...     print(f"{name}: {info['resolution_m']}m")

Source code in agribound/composites/base.py

def list_sources() -> dict[str, dict[str, Any]]:
    """List all available satellite sources and their metadata.

    Returns
    -------
    dict[str, dict]
        Dictionary mapping source names to their metadata.

    Examples
    --------
    >>> from agribound import list_sources
    >>> sources = list_sources()
    >>> for name, info in sources.items():
    ...     print(f"{name}: {info['resolution_m']}m")
    """
    return dict(SOURCE_REGISTRY)