Metadata¶

hs.ImageMeta is the top-level metadata object attached to each image. It stores the core layout and data type directly, while richer acquisition and file-format details are grouped into focused metadata classes.

Section	API	Description
Shape	`hs.ShapeMeta`	Image dimensions and interleave layout. `hs.ImageMeta.shape` and `hs.ImageMeta.interleave` are convenience accessors for this core layout information.
Camera	`hs.CameraMeta`	Camera and lens identity, model information, serial numbers, and acquisition configuration.
Spectral	`hs.SpectralMeta`	Band count, wavelength metadata, spectral binning, response width, and spectral coregistration error.
Spatial	`hs.SpatialMeta`	Optical and spatial sampling details such as focal length, slit width, spatial ROI, binning, field of view, and spatial coregistration error.
Radiometric	`hs.RadiometricMeta`	Measurement units, valid value limits, scaling, correction flags, gain, and radiometric quality information.
Temporal	`hs.TemporalMeta`	Exposure time, frame timing, averaging, trigger mode, and acquisition start/end timestamps.
Calibration	`hs.CalibrationMeta`	Calibration process, calibration date, and optional extra calibration information used by downstream processing.
Sensor	`hs.SensorMeta`	Sensor artifact annotations such as bad pixels, bad bands, and repaired pixels.
Encoding	`hs.EncodingMeta`	Pixel storage details such as byte order, scale factor, zero point, bit depth, and compression.
Display	`hs.DisplayMeta`	Visualization hints such as default RGB bands and human-readable band names.
Data Products	`hs.DataProductsMeta`	Processing level of the stored data (raw, partially/fully corrected, or reflectance), distinct from the physical unit recorded on `hs.RadiometricMeta`.
Extra	`hs.ImageMeta`	Free-form metadata entries that are not represented by the structured API fields, accessed with `hs.ImageMeta.extra()` the [] index operator.

Image metadata¶

class hs.ImageMeta(shape, interleave=None, dtype=None, camera=None, spectral=None, spatial=None, radiometric=None, temporal=None, calibration=None, sensor=None, encoding=None, display=None, description=None, data_offset=None, data_products=None, **py_kwargs)¶

Header information.

The header type contains a union of the metadata supported by the different HSI file formats. PAM files ignore certain entries, while ENVI and the custom yaml format support the full set of keys.

Parameters:

shape (Shape | ShapeMeta)
interleave (Interleave | None)
dtype (DType)
camera (CameraMeta | None)
spectral (SpectralMeta | None)
spatial (SpatialMeta | None)
radiometric (RadiometricMeta | None)
temporal (TemporalMeta | None)
calibration (CalibrationMeta | None)
sensor (SensorMeta | None)
encoding (EncodingMeta | None)
display (DisplayMeta | None)
description (str | None)
data_offset (int | None)
data_products (DataProductsMeta | None)
py_kwargs (Any)

extra()¶

Returns:: Dictionary of extra metadata.
Return type:: dict[str, Any]

n_planes()¶: Get the number of planes in the image, i.e. the dimension of the outer axis. Depends on the interleave.

plane_shape()¶: Get the natural plane shape, i.e. the shape of the two innermost dimensions of the interleave shape.

calibration¶

Calibration provenance metadata.

Type:: CalibrationMeta

camera¶

Camera identification and optics metadata.

Type:: CameraMeta

data_offset¶

Get optional data offset (used for binary files with embedded headers).

Getter:
Type:: int | None

data_products¶

Data product processing-level metadata.

Type:: DataProductsMeta

description¶

Description. An arbitrary string that describes the image.

Getter:
Type:: str | None

display¶

Display hint metadata.

Type:: DisplayMeta

dtype¶

Image data type.

Type:: DType

encoding¶

Pixel encoding metadata.

Type:: EncodingMeta

interleave¶

Image interleave mode.

Type:: Interleave

radiometric¶

Radiometric characteristics metadata.

Type:: RadiometricMeta

sensor¶

Sensor artifact metadata.

Type:: SensorMeta

shape¶

Image shape.

Type:: Shape

shape_meta¶

Shape and memory layout metadata.

Type:: ShapeMeta

spatial¶

Spatial characteristics metadata.

Type:: SpatialMeta

spectral¶

Spectral characteristics metadata.

Type:: SpectralMeta

temporal¶

Temporal acquisition metadata.

Type:: TemporalMeta

Legacy compatibility accessors¶

These attributes are kept for older code and map onto the grouped metadata objects shown above.

ImageMeta.byte_order¶

Data byte-ordering.

Type:: Endianness

ImageMeta.capture¶

Camera acquisition parameters (compatibility shim).

Type:: CaptureMeta | None

ImageMeta.default_bands¶

Bands indexes used for displaying false color images.

Getter:: Get current bands
Type:: list[int] | None

ImageMeta.measurement_info¶

Radiometric measurement info (compatibility shim).

Type:: MeasurementInfo | None

ImageMeta.wavelength_info¶

Information about data wavelengths.

Getter:
Type:: WavelengthMeta | None

Shape and layout¶

class hs.Shape(bands, samples, lines)

Describes the shape of a hyper-spectral image.

Parameters:

lines (int)
samples (int)
bands (int)

bands

The spectral bands of the image. None when the dimension is unbounded, for example for a continuously streaming source with no fixed number of bands.

Type:: int | None

lines

This is the width of the image. For line-scan cameras, it is the length of a single line. None when the dimension is unbounded, for example for a continuously streaming source with no fixed width.

Type:: int | None

samples

This is usually the height of the image. If the image was captured using a line-scan hyper-spectral camera, this is also the number of line images captured. None when the dimension is unbounded, for example for a continuously streaming source with no fixed number of lines.

Type:: int | None

class hs.ShapeMeta(streaming_dim, plane_dim, interleave)¶

Parameters:

streaming_dim (Optional[int])
plane_dim (list[int])
interleave (Interleave)

interleave¶

Image interleave mode.

Type:: Interleave

plane_dim¶

Shape of each image plane.

Type:: list[int]

streaming_dim¶

Number of image planes in the streaming dimension. None when the dimension is unbounded, for example for a continuously streaming source with no fixed number of planes.

Type:: int | None

class hs.Interleave¶

Data interleave mode.

Defines the memory layout of the file. To achieve good performance, as suitable interleave mode should be used for a given application.

BSQ: The full image for each spectral band is stored consecutively in memory. This format is
effective for spatial access.
BIP: All spectral bands for each pixel is stored consecutively, followed by a line of pixels.
This format is effective for spectral access.
BIL: Each line of pixels is stored consecutively for each band. This format achieves improved
spatial access along the width of the image while retaining good performance for spectral access as well.

A good default for images is the BIL format which is balanced between spatial and spectral access.

axis_num(axis)¶

BIL = BIL¶

BIP = BIP¶

BSQ = BSQ¶

class hs.Axis

Named axes, independent of memory ordering.

Bands = Axis.Bands

Lines = Axis.Lines

Samples = Axis.Samples

Metadata categories¶

class hs.CameraMeta(id=None, architecture=None, manufacturer=None, model_name=None, serial=None, lens_manufacturer=None, lens_model=None, lens_serial=None, configuration=None, pixel_pitch_um=None)¶

Camera identification and optics metadata (P4001 §7, Camera section).

architecture¶

Camera architecture, such as line-imaging spectrometer, scanned point spectrometer, array camera, or tunable-filter camera.

Type:: str | None

configuration¶

Name, description, or reference for the camera configuration used during acquisition.

Type:: str | None

id¶

Identifier for the camera or camera system used to acquire the image.

Type:: str | None

lens_manufacturer¶

Lens manufacturer name.

Type:: str | None

lens_model¶

Lens model name.

Type:: str | None

lens_serial¶

Lens serial number.

Type:: str | None

manufacturer¶

Camera manufacturer name.

Type:: str | None

model_name¶

Camera model name.

Type:: str | None

pixel_pitch_um¶

Camera pixel pitch in micrometers, when known.

Type:: float | None

serial¶

Camera serial number.

Type:: str | None

class hs.SpectralMeta(number_of_bands=None, binning=None, wavelengths=None, response_fwhm=None, coregistration_error=None)¶

Spectral characteristics metadata (P4001 §7, Spectral section).

binning¶

Spectral binning factor. Omitted when no spectral binning was applied.

Type:: int | None

coregistration_error¶

Spectral coregistration error as a percentage.

Type:: float | None

number_of_bands¶

Number of spectral bands, when not implied by wavelength metadata or image shape.

Type:: int | None

response_fwhm¶

Spectral response function width per band, typically expressed in the same unit as the wavelengths.

Type:: list[float] | None

wavelengths¶

Center wavelength for each spectral band, including wavelength units.

Type:: WavelengthMeta | None

class hs.SpatialMeta(focal_length_mm=None, slit_width_um=None, spatial_roi=None, binning=None, fov=None, psf_width=None, coregistration_error=None)¶

Spatial characteristics metadata (P4001 §7, Spatial section).

binning¶

Spatial binning factor. Omitted when no spatial binning was applied.

Type:: int | None

coregistration_error¶

Spatial coregistration error as a percentage.

Type:: float | None

focal_length_mm¶

Focal length in millimeters.

Type:: float | None

fov¶

Field of view angle.

Type:: float | None

psf_width¶

Sampling point spread function width.

Type:: float | None

slit_width_um¶

Slit width in micrometers.

Type:: float | None

spatial_roi¶

Spatial region of interest applied during acquisition, expressed in pixel coordinates.

Type:: tuple[int, int] | None

class hs.RadiometricMeta(unit=Ellipsis, dark_corrected=None, negative_truncated=None, linearity_error=None, aperture=None, read_noise=None, effective_throughput=None, adc_gain=None, limits=None, scaling=None)¶

Radiometric characteristics metadata (P4001 §7, Radiometric section).

adc_gain¶

ADC gain in electrons per digital number for raw or uncalibrated data.

Type:: float | None

aperture¶

Aperture setting used for acquisition.

Type:: float | None

dark_corrected¶

Whether dark correction has been applied to the image data.

Type:: bool | None

effective_throughput¶

Effective throughput per band, used for radiometric noise estimation.

Type:: list[float] | None

limits¶

Valid or expected measurement limits for pixel values.

Type:: MeasurementLimits | None

linearity_error¶

Mean linearity error as a percentage.

Type:: float | None

negative_truncated¶

Whether negative values were clipped or truncated to zero.

Type:: bool | None

read_noise¶

Read noise in electrons.

Type:: float | None

scaling¶

Scale factor applied to values before storage.

Type:: float | None

unit¶

Radiometric unit of measurement for pixel values.

Assigning one of the deprecated variants (Raw, Absorbance, Arbitrary) raises a DeprecationWarning.

Type:: MeasurementUnit

class hs.TemporalMeta(exposure_time_ms=None, frame_time_ms=None, n_averages=None, trigger_mode=None, start_time=None, end_time=None)¶

Temporal acquisition metadata (P4001 §7, Temporal section).

end_time¶

End time of the collection.

Type:: datetime.datetime | None

exposure_time_ms¶

Integration or exposure time in milliseconds.

Type:: float | None

frame_time_ms¶

Acquisition frame period in milliseconds.

Type:: float | None

n_averages¶

Number of acquisitions averaged into each output frame.

Type:: int | None

start_time¶

Start time of the collection.

Type:: datetime.datetime | None

trigger_mode¶

Triggering mode used during acquisition.

Type:: TriggerMode | None

class hs.CalibrationMeta(calibration_process=None, calibration_date=None, additional_info=None)¶

Calibration provenance metadata (P4001 §7, Calibration Information section).

additional_info¶

Additional calibration data required for downstream post-processing.

Type:: Any | None

calibration_date¶

Date and time of the sensor calibration.

Type:: datetime.datetime | None

calibration_process¶

Description of the sensor calibration process used for the image.

Type:: str | None

class hs.SensorMeta(bad_pixels=None, bad_bands=None, repaired_pixels=None)¶

Sensor artifact metadata (P4001 §7, Sensor Artifacts section).

bad_bands¶

Indices of spectral bands known to be bad or unreliable.

Type:: list[int] | None

bad_pixels¶

Indices of pixels known to be bad or unreliable.

Type:: list[int] | None

repaired_pixels¶

Indices of pixels where artifact repair has been applied.

Type:: list[int] | None

class hs.EncodingMeta(byte_order=Ellipsis, scale_factor=None, zero_point=None, bits_per_pixel=None)¶

Pixel encoding metadata (P4001 §7, Pixel Encoding section).

bits_per_pixel¶

Number of significant bits per pixel, for example ADC bit depth.

Type:: int | None

byte_order¶

Byte ordering used for multi-byte pixel values.

Type:: Endianness

compression¶

Compression settings used for encoded pixel data. None when the pixel data is stored uncompressed. Otherwise an object describing the compression method and its parameters; the only method currently produced is JPEG, which carries a quality field.

Type:: object | None

scale_factor¶

Scale factor applied to the data in its measurement unit before storage.

Type:: float | None

zero_point¶

Numerical offset added to scaled output values before storage.

Type:: float | None

class hs.DisplayMeta(default_bands=None, band_names=None)¶

Display hint metadata (P4001 §7, Display section).

band_names¶

Human-readable names for spectral bands.

Type:: list[str] | None

default_bands¶

Band indices suggested for quick RGB visualization.

Type:: list[int] | None

class hs.DataProductsMeta(output_data=None)¶

Data product processing-level metadata (P4001 §7, Data Products Basics section).

output_data¶

Processing level of the stored data (raw, partially/fully corrected, or reflectance).

Type:: OutputDataType | None

class hs.OutputDataType¶

Data product processing level (P4001 §7, Data Products Basics section).

This is distinct from RadiometricMeta::unit, which records the physical unit of the stored values (DN, reflectance, radiance, …). OutputDataType instead records how far the data has been processed towards that unit, e.g. distinguishing raw sensor data from data that has been partially or fully corrected.

AbsoluteRadiometric = OutputDataType.AbsoluteRadiometric¶

PartiallyCorrectedData = OutputDataType.PartiallyCorrectedData¶

RawData = OutputDataType.RawData¶

Reflectance = OutputDataType.Reflectance¶

RelativeRadiometric = OutputDataType.RelativeRadiometric¶

Spectral metadata¶

class hs.WavelengthMeta(band_data, unit)¶

Data wavelength information.

Describes the wavelength for each band in the represented data. All units supported by the ENVI format are supported.

band_data¶

Value for each band.

Type:: list[float]

unit¶

Unit of each wavelength.

Type:: WavelengthUnit

class hs.WavelengthUnit¶

Wavelength units.

Angstroms = WavelengthUnit.Angstroms¶

Centimeter = WavelengthUnit.Centimeter¶

GHz = WavelengthUnit.GHz¶

Index = WavelengthUnit.Index¶

MHz = WavelengthUnit.MHz¶

Meter = WavelengthUnit.Meter¶

Micrometer = WavelengthUnit.Micrometer¶

Millimeter = WavelengthUnit.Millimeter¶

Nanometer = WavelengthUnit.Nanometer¶

Unknown = WavelengthUnit.Unknown¶

WaveNumber = WavelengthUnit.WaveNumber¶

Radiometric metadata¶

class hs.MeasurementInfo(unit, limits=None, scaling=None)¶

Radiometric measurement info (kept for FFI and migration compatibility; prefer RadiometricMeta).

limits¶

Valid or expected measurement limits for pixel values.

Type:: MeasurementLimits | None

scaling¶

Scale factor applied to values before storage.

Type:: float | None

unit¶

Radiometric unit of measurement for pixel values.

Assigning one of the deprecated variants (Raw, Absorbance, Arbitrary) raises a DeprecationWarning.

Type:: MeasurementUnit

class hs.MeasurementLimits(min, max)¶

Valid or expected measurement limits for pixel values.

max¶

Maximum valid or expected pixel value.

Type:: float

min¶

Minimum valid or expected pixel value.

Type:: float

class hs.MeasurementUnit¶

Radiometric unit of measurement for pixel values (P4001 §7, Radiometric section).

The non-deprecated variants are the values IEEE 4001-2025 (7.1.1, Table 5) defines for “Radiometric unit of measurement”, plus [MeasurementUnit::Unknown] for the not-yet-set case.

This records only the unit the stored values are expressed in. How far the data has been processed to reach that unit is a separate axis, recorded as [OutputDataType] on [DataProductsMeta].

Absorbance = MeasurementUnit.Absorbance¶

Arbitrary = MeasurementUnit.Arbitrary¶

Dn = MeasurementUnit.Dn¶

Microflick = MeasurementUnit.Microflick¶

RadianceNmSr = MeasurementUnit.RadianceNmSr¶

RadianceUmSr = MeasurementUnit.RadianceUmSr¶

Raw = MeasurementUnit.Raw¶

Reflectance = MeasurementUnit.Reflectance¶

Unknown = MeasurementUnit.Unknown¶

Note

The Raw, Absorbance, and Arbitrary members are deprecated: IEEE 4001-2025 (7.1.1, Table 5) does not define them as radiometric units. Assigning one to hs.RadiometricMeta.unit raises a DeprecationWarning.

Raw conflated the unit with the processing level; use Dn together with hs.DataProductsMeta.output_data set to hs.OutputDataType.RawData. For Absorbance and Arbitrary, use Unknown and record the unit as extra metadata on hs.ImageMeta.

Acquisition metadata¶

class hs.CaptureMeta(exposure_time_micro, capture_bit_depth, gain_db)¶

Camera acquisition parameters (kept for FFI and migration compatibility; prefer TemporalMeta, EncodingMeta, and RadiometricMeta).

Parameters:

exposure_time_micro (int)
capture_bit_depth (int)
gain_db (float)

capture_bit_depth¶

Capture bit depth.

Type:: int

exposure_time_micro¶

Integration or exposure time in microseconds.

Type:: int

gain_db¶

Camera gain in decibels.

Type:: float

class hs.TriggerMode¶

Trigger mode for temporal acquisition (P4001 §7, Temporal section).

ExternalSignal = TriggerMode.ExternalSignal¶

InternalClock = TriggerMode.InternalClock¶

SoftwareTrigger = TriggerMode.SoftwareTrigger¶

Encoding metadata¶

class hs.Endianness¶

Specifies the byte-ordering of multi-byte types in files.

Big = Endianness.Big¶

Little = Endianness.Little¶