Image Utilities

API Documentation

siapy.utils.images

The image utilities module provides functions for saving, loading, and processing spectral images with support for both Spectral Python (SPy) and Rasterio backends.

Image I/O Operations

Spectral Python backend

The SPy backend saves images in ENVI format.

import numpy as np

from siapy.utils.images import spy_create_image, spy_save_image

# Create sample data
rng = np.random.default_rng(42)
image = rng.random((100, 150, 50))  # height, width, bands

# Save image in ENVI format
spy_save_image(
    image=image,
    save_path="output/my_image.hdr",
    metadata={"description": "Sample hyperspectral image"},
    overwrite=True,
    dtype=np.float32,
)

# Create image and get SpectralImage object back
spectral_img = spy_create_image(
    image=image,
    save_path="output/created_image.hdr",
    metadata={
        "lines": image.shape[0],
        "samples": image.shape[1],
        "bands": image.shape[2],
        "wavelength": [400 + i * 5 for i in range(image.shape[2])],
    },
)

Rasterio backend

The Rasterio backend provides geospatial capabilities and supports various formats.

import numpy as np

from siapy.utils.images import rasterio_create_image, rasterio_save_image

# Create sample data
rng = np.random.default_rng(42)
image = rng.random((100, 150, 5))

# Save as GeoTIFF with Rasterio
rasterio_save_image(
    image=image,
    save_path="output/rasterio_image.tif",
    metadata={"description": "Hyperspectral data", "wavelength": [400, 450, 500, 550, 600]},
)

# Create image and get SpectralImage object back
spectral_img = rasterio_create_image(
    image=image,
    save_path="output/created_rasterio.tif",
    metadata={"wavelength": [400, 450, 500, 550, 600]},
)

Radiance to Reflectance Conversion

Converting radiance measurements to reflectance using reference panels is essential for quantitative spectral analysis.

from siapy.entities import SpectralImage
from siapy.entities.shapes import Shape
from siapy.utils.images import (
    calculate_correction_factor_from_panel,
    convert_radiance_image_to_reflectance,
    spy_save_image,
)

# Load radiance image
radiance_img = SpectralImage.spy_open(header_path="radiance_data.hdr")

# Method 1: Using labeled geometric shape for panel area
panel_shape = Shape.from_rectangle(x_min=200, y_min=350, x_max=300, y_max=400, label="reference_panel")
radiance_img.geometric_shapes.append(panel_shape)

correction_factor = calculate_correction_factor_from_panel(
    image=radiance_img,
    panel_reference_reflectance=0.2,  # 20% reflectance panel
    panel_shape_label="reference_panel",
)

# Method 2: Using entire image (when image contains only panel)
# panel_img = SpectralImage.spy_open(header_path="panel_only.hdr")
# correction_factor = calculate_correction_factor_from_panel(
#     image=panel_img,
#     panel_reference_reflectance=0.2
# )

# Convert radiance to reflectance
reflectance_img = convert_radiance_image_to_reflectance(image=radiance_img, panel_correction=correction_factor)

# Save reflectance image with enhanced metadata
metadata = radiance_img.metadata.copy()
metadata.update({"data_type": "reflectance", "reference_panel": "20% Spectralon", "processing_date": "2025-06-19"})
spy_save_image(image=reflectance_img, save_path="output/reflectance.hdr", metadata=metadata)

Additional Utility Functions

from siapy.entities import SpectralImage
from siapy.utils.images import blockfy_image, calculate_image_background_percentage, spy_merge_images_by_specter

# Merge VNIR and SWIR images
vnir_image = SpectralImage.spy_open(header_path="vnir_data.hdr")
swir_image = SpectralImage.spy_open(header_path="swir_data.hdr")

merged_image = spy_merge_images_by_specter(
    image_original=vnir_image,
    image_to_merge=swir_image,
    save_path="output/merged_vnir_swir.hdr",
    auto_metadata_extraction=True,
)

# Image blocking for large dataset processing
large_image = SpectralImage.spy_open(header_path="large_image.hdr")

blocks = blockfy_image(
    image=large_image,
    p=50,  # block height
    q=50,  # block width
)

# Background analysis
bg_percentage = calculate_image_background_percentage(large_image)
print(f"Background pixels: {bg_percentage:.2f}%")