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):
        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.listSensors()).	required

Returns:

Name	Type	Description
bands	list	a list of sensor-specific band names.

Source code in earthlib/sensors.py

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

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

    Returns:
        bands: a list of sensor-specific band names.
    """
    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

Parameters:

Name	Type	Description	Default
custom_bands	list	a list of band names.	required
sensor	str	a string sensor type for indexing the supported collections.	required

Returns:

Name	Type	Description
indices	list	list of integer band indices.

Source code in earthlib/sensors.py

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

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

    Returns:
        indices: list of integer band indices.
    """
    validate_sensor(sensor)
    sensor_bands = supported_sensors[sensor].band_names
    indices = list()

    if type(custom_bands) in (list, tuple):
        for band in custom_bands:
            if band in sensor_bands:
                indices.append(sensor_bands.index(band))

    elif isinstance(custom_bands, str):
        indices.append(sensor_bands.index(custom_bands))

    indices.sort()
    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	a list of sensor-specific band names.

Source code in earthlib/sensors.py

def get_bands(sensor: str) -> list:
    """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.
    """
    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	a string with the earth engine collection.

Source code in earthlib/sensors.py

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

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

    Returns:
        collection: a string with the earth engine collection.
    """
    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	str	the scale factor to multiply.

Source code in earthlib/sensors.py

def get_scaler(sensor: str) -> str:
    """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 the sensor instance, indexed by key.

Source code in earthlib/sensors.py

def get_sensor(sensor: str) -> Sensor:
    """Get the sensor instance, indexed by key."""
    validate_sensor(sensor)
    return supported_sensors[sensor]

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)}"
        )