earthlib.sensors

Sensor definitions for common earth observing instruments.

Sensor dataclass

Base class for defining EO sensor specifications.

Source code in earthlib/sensors.py

@dataclass
class Sensor:
    """Base class for defining EO sensor specifications."""

    name: str
    band_centers: np.ndarray | list[float]
    band_widths: np.ndarray | list[float] | None = None
    band_names: list[str] | None = None
    band_descriptions: list[str] | None = None
    scale: float = 1.0
    offset: float = 0.0
    collection: str | None = None
    wavelength_unit: Literal["micrometers", "nanometers"] = "micrometers"
    measurement_unit: Literal["reflectance", "radiance", "dn"] = "reflectance"

    def __post_init__(self) -> None:
        if not isinstance(self.band_centers, np.ndarray):
            self.band_centers = np.array(self.band_centers, dtype=np.float32)
        if self.band_widths is not None:
            if not isinstance(self.band_widths, np.ndarray):
                self.band_widths = np.array(self.band_widths, dtype=np.float32)

    @property
    def band_count(self) -> int:
        """The number of bands for the sensor."""
        return len(self.band_centers)

    def copy(self) -> "Sensor":
        """Returns a copy of the sensor object."""
        return Sensor(**asdict(self))

band_count property

The number of bands for the sensor.

copy()

Returns a copy of the sensor object.

Source code in earthlib/sensors.py

def copy(self) -> "Sensor":
    """Returns a copy of the sensor object."""
    return Sensor(**asdict(self))

get_band_descriptions(sensor)

Returns a list band name descriptions by sensor.

Parameters:

Name	Type	Description	Default
sensor	str	the name of the sensor (from earthlib.list_sensors()).	required

Returns:

Name	Type	Description
bands	list[str] | None	a list of sensor-specific band descriptions, or None when undescribed.

Source code in earthlib/sensors.py

def get_band_descriptions(sensor: str) -> list[str] | None:
    """Returns a list band name descriptions by sensor.

    Args:
        sensor: the name of the sensor (from earthlib.list_sensors()).

    Returns:
        bands: a list of sensor-specific band descriptions, or None when undescribed.
    """
    validate_sensor(sensor)
    bands = supported_sensors[sensor].band_descriptions
    return bands

get_band_indices(custom_bands, sensor)

Cross-references a list of bands passed as strings to the 0-based integer indices

Indices are returned in the order the bands were requested.

Parameters:

Name	Type	Description	Default
custom_bands	list[str] | str	a band name, or a list of band names.	required
sensor	str	a string sensor type for indexing the supported collections.	required

Returns:

Name	Type	Description
indices	list[int]	list of integer band indices.

Raises:

Type	Description
SensorError	when the sensor is invalid, has no named bands, or when a requested band is not one of the sensor's bands.

Example

indices = get_band_indices(["SR_B4", "SR_B3", "SR_B2"], "Landsat8")

Source code in earthlib/sensors.py

def get_band_indices(custom_bands: list[str] | str, sensor: str) -> list[int]:
    """Cross-references a list of bands passed as strings to the 0-based integer indices

    Indices are returned in the order the bands were requested.

    Args:
        custom_bands: a band name, or a list of band names.
        sensor: a string sensor type for indexing the supported collections.

    Returns:
        indices: list of integer band indices.

    Raises:
        SensorError: when the sensor is invalid, has no named bands, or when a
            requested band is not one of the sensor's bands.

    Example:
        ```python
        indices = get_band_indices(["SR_B4", "SR_B3", "SR_B2"], "Landsat8")
        ```
    """
    validate_sensor(sensor)
    sensor_bands = supported_sensors[sensor].band_names

    if sensor_bands is None:
        raise SensorError(f"Sensor {sensor} has no named bands.")

    requested = [custom_bands] if isinstance(custom_bands, str) else list(custom_bands)

    indices = list()
    for band in requested:
        if band not in sensor_bands:
            raise SensorError(
                f"Invalid band: {band}. Supported for {sensor}: "
                f"{', '.join(sensor_bands)}"
            )
        indices.append(sensor_bands.index(band))

    return indices

get_bands(sensor)

Returns a list of available band names by sensor.

Parameters:

Name	Type	Description	Default
sensor	str	the name of the sensor (from earthlib.list_sensors()).	required

Returns:

Name	Type	Description
bands	list[str] | None	a list of sensor-specific band names, or None when unnamed.

Source code in earthlib/sensors.py

def get_bands(sensor: str) -> list[str] | None:
    """Returns a list of available band names by sensor.

    Args:
        sensor: the name of the sensor (from earthlib.list_sensors()).

    Returns:
        bands: a list of sensor-specific band names, or None when unnamed.
    """
    validate_sensor(sensor)
    bands = supported_sensors[sensor].band_names
    return bands

get_collection_name(sensor)

Returns the earth engine collection name for a specific satellite sensor.

Parameters:

Name	Type	Description	Default
sensor	str	the name of the sensor (from earthlib.list_sensors()).	required

Returns:

Name	Type	Description
collection	str | None	the earth engine collection, or None for sensors that have none.

Source code in earthlib/sensors.py

def get_collection_name(sensor: str) -> str | None:
    """Returns the earth engine collection name for a specific satellite sensor.

    Args:
        sensor: the name of the sensor (from earthlib.list_sensors()).

    Returns:
        collection: the earth engine collection, or None for sensors that have none.
    """
    validate_sensor(sensor)
    collection = supported_sensors[sensor].collection
    return collection

get_scaler(sensor)

Returns the scaling factor to convert sensor data to percent reflectance (0-1).

Parameters:

Name	Type	Description	Default
sensor	str	the name of the sensor (from earthlib.list_sensors()).	required

Returns:

Name	Type	Description
scaler	float	the scale factor to multiply.

Source code in earthlib/sensors.py

def get_scaler(sensor: str) -> float:
    """Returns the scaling factor to convert sensor data to percent reflectance (0-1).

    Args:
        sensor: the name of the sensor (from earthlib.list_sensors()).

    Returns:
        scaler: the scale factor to multiply.
    """
    validate_sensor(sensor)
    scaler = supported_sensors[sensor].scale
    return scaler

get_sensor(sensor)

Get a copy of the sensor instance, indexed by key.

A copy is returned so callers cannot mutate the shared module-level sensor.

Parameters:

Name	Type	Description	Default
sensor	str	the name of the sensor (from earthlib.list_sensors()).	required

Returns:

Type	Description
Sensor	a copy of the sensor definition.

Raises:

Type	Description
SensorError	when an invalid sensor name is passed.

Example

landsat = get_sensor("Landsat8")

Source code in earthlib/sensors.py

def get_sensor(sensor: str) -> Sensor:
    """Get a copy of the sensor instance, indexed by key.

    A copy is returned so callers cannot mutate the shared module-level sensor.

    Args:
        sensor: the name of the sensor (from earthlib.list_sensors()).

    Returns:
        a copy of the sensor definition.

    Raises:
        SensorError: when an invalid sensor name is passed.

    Example:
        ```python
        landsat = get_sensor("Landsat8")
        ```
    """
    validate_sensor(sensor)
    return supported_sensors[sensor].copy()

list_sensors()

Returns a list of the supported sensor image collections.

Returns:

Name	Type	Description
sensors	list	a list of supported sensors using the names referenced by this package.

Source code in earthlib/sensors.py

def list_sensors() -> list:
    """Returns a list of the supported sensor image collections.

    Returns:
        sensors: a list of supported sensors using the names referenced by this package.
    """
    sensors = list(supported_sensors.keys())
    return sensors

validate_sensor(sensor)

Verify a string sensor ID is valid, raise an error otherwise.

Parameters:

Name	Type	Description	Default
sensor	str	the name of the sensor (from earthlib.list_sensors()).	required

Raises:

Type	Description
SensorError	when an invalid sensor name is passed

Source code in earthlib/sensors.py

def validate_sensor(sensor: str) -> None:
    """Verify a string sensor ID is valid, raise an error otherwise.

    Args:
        sensor: the name of the sensor (from earthlib.list_sensors()).

    Raises:
        SensorError: when an invalid sensor name is passed
    """
    supported = list_sensors()
    if sensor not in supported:
        raise SensorError(
            f"Invalid sensor: {sensor}. Supported: {', '.join(supported)}"
        )