Interfaces

siapy.entities.images.interfaces

ImageBase

Bases: ABC

Abstract base class defining the interface for spectral image implementations.

This class defines the common interface that all image backend implementations must implement, including methods for opening files, accessing metadata and properties, and converting to different formats.

All concrete implementations (SpectralLibImage, RasterioLibImage, MockImage) must inherit from this class and implement all abstract methods.

filepath abstractmethod property

filepath: Path

Get the file path of the image.

RETURNS	DESCRIPTION
Path	A Path object representing the location of the image file. For in-memory images, this may return an empty Path.

metadata abstractmethod property

metadata: dict[str, Any]

Get the image metadata.

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing image metadata such as coordinate reference system, geotransform information, wavelength data, and other image properties. The specific contents depend on the underlying format and library.

shape abstractmethod property

shape: tuple[int, int, int]

Get the dimensions of the image.

RETURNS	DESCRIPTION
tuple[int, int, int]	A tuple (height, width, bands) representing the image dimensions.

bands abstractmethod property

bands: int

Get the number of spectral bands in the image.

RETURNS	DESCRIPTION
int	The number of spectral bands (channels) in the image.

default_bands abstractmethod property

default_bands: list[int]

Get the default band indices for RGB display.

RETURNS	DESCRIPTION
list[int]	A list of band indices typically used for red, green, and blue channels when displaying the image as an RGB composite.

wavelengths abstractmethod property

wavelengths: list[float]

Get the wavelengths corresponding to each spectral band.

RETURNS	DESCRIPTION
list[float]	A list of wavelength values (typically in nanometers) for each band. For non-spectral data, this may return band numbers or other identifiers.

camera_id abstractmethod property

camera_id: str

Get the camera or sensor identifier.

RETURNS	DESCRIPTION
str	A string identifying the camera or sensor used to capture the image. May return an empty string if no camera information is available.

open abstractmethod classmethod

open(*args: Any, **kwargs: Any) -> ImageBase

Open and load an image from a source.

PARAMETER	DESCRIPTION
*args	Positional arguments specific to the implementation. TYPE: Any DEFAULT: ()
**kwargs	Keyword arguments specific to the implementation. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ImageBase	An instance of the concrete image implementation.

Note

Each implementation defines its own signature for this method based on the specific requirements of the underlying library.

Source code in siapy/entities/images/interfaces.py

@classmethod
@abstractmethod
def open(cls: type["ImageBase"], *args: Any, **kwargs: Any) -> "ImageBase":
    """Open and load an image from a source.

    Args:
        *args: Positional arguments specific to the implementation.
        **kwargs: Keyword arguments specific to the implementation.

    Returns:
        An instance of the concrete image implementation.

    Note:
        Each implementation defines its own signature for this method
        based on the specific requirements of the underlying library.
    """
    pass

to_display abstractmethod

to_display(equalize: bool = True) -> Image

Convert the image to a PIL Image for display purposes.

PARAMETER	DESCRIPTION
equalize	Whether to apply histogram equalization to enhance contrast. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Image	A PIL Image object suitable for display, typically as an RGB composite created from the default bands with appropriate scaling and normalization.

Source code in siapy/entities/images/interfaces.py

@abstractmethod
def to_display(self, equalize: bool = True) -> Image.Image:
    """Convert the image to a PIL Image for display purposes.

    Args:
        equalize: Whether to apply histogram equalization to enhance contrast.

    Returns:
        A PIL Image object suitable for display, typically as an RGB composite created from the default bands with appropriate scaling and normalization.
    """
    pass

to_numpy abstractmethod

to_numpy(
    nan_value: float | None = None,
) -> NDArray[floating[Any]]

Convert the image to a numpy array.

PARAMETER	DESCRIPTION
nan_value	Optional value to replace NaN values with. If None, NaN values are preserved. TYPE: float | None DEFAULT: None

RETURNS	DESCRIPTION
NDArray[floating[Any]]	A 3D numpy array with shape (height, width, bands) containing the image data. The array dtype should be a floating-point type.

Source code in siapy/entities/images/interfaces.py

@abstractmethod
def to_numpy(self, nan_value: float | None = None) -> NDArray[np.floating[Any]]:
    """Convert the image to a numpy array.

    Args:
        nan_value: Optional value to replace NaN values with. If None, NaN values are preserved.

    Returns:
        A 3D numpy array with shape (height, width, bands) containing the image data. The array dtype should be a floating-point type.
    """
    pass

to_xarray abstractmethod

to_xarray() -> XarrayType

Convert the image to an xarray DataArray.

RETURNS	DESCRIPTION
XarrayType	An xarray DataArray with labeled dimensions and coordinates, suitable for advanced analysis and visualization. The array should include appropriate coordinate information and metadata attributes.

Source code in siapy/entities/images/interfaces.py

@abstractmethod
def to_xarray(self) -> "XarrayType":
    """Convert the image to an xarray DataArray.

    Returns:
        An xarray DataArray with labeled dimensions and coordinates, suitable for advanced analysis and visualization. The array should include appropriate coordinate information and metadata attributes.
    """
    pass