Hyperspectral
Example scripts related to the Hypervision HSI cameras.
Showcasing for example: loading of hyperspectral data files, capture of datacubes from Hypervision HSI cameras cameras and reflectance calibration.
HV SDK
The HV SDK is our high-level interface to HSI related functionality with both Python and C/C++ APIs.
You can find a number of usage examples (as well as the API reference) here.
Under development
The HV SDK is still under development.
Availability of an alpha version is expected before the end of March 2025 (with live data capture support coming in August 2025).
Currently only python bindings are available, but C/C++ support is under development.
Python
Reading PAM datacubes
import numpy as np
def read_pam_file(file_path, chan_rmv=None):
try:
# Open the .pam file for reading
with open(file_path, "rb") as file:
# Function to parse the PAM header until the "ENDHDR" marker
def parse_pam_header(file):
header = {}
while True:
line = file.readline().decode("utf-8").strip()
if not line:
break
if line == "ENDHDR":
break
parts = line.split(" ", 1)
if len(parts) == 2:
key, value = parts
header[key] = value
elif len(parts) == 1:
# Handle lines with no key (just a value)
header[line] = None
return header
# Parse the PAM header until "ENDHDR"
header = parse_pam_header(file)
# Get image properties from the header
width = int(header["WIDTH"]) # Actual width of image
channels = int(header["DEPTH"]) # Corresponds to the number of spectral channels
maxval = int(header["MAXVAL"])
height = int(header["HEIGHT"]) # Corresponds to the number of scan lines
# Read the binary data with the number of channels determined by depth
data = np.fromfile(file, dtype=np.uint8, count=width * height * channels)
# image_data = data.reshape(width, height, channels, order='F') # Fortran-style
image_data = data.reshape(channels, height, width, order='C') # C-style
print("Shape of cube: ", image_data.shape)
if chan_rmv != None:
image_data = image_data[chan_rmv:-chan_rmv]
return image_data
except FileNotFoundError:
print(f"File not found: {file_path}")
return None
except Exception as e:
print(f"An error occurred: {e}")
return None
PAM interleave
The above example expects PAM files captured using the Buteo Lab scanner which have a BIL interleave type.
Reflectance transformation
def refl_trans(fl, white_avg, dark_avg): #
"""Performs reflectance transformation on a hyperspectral image cube"""
# Return reflectance cube
cube = read_pam_file(fl)
cube = (cube - dark_avg) / (white_avg - dark_avg)
# <<The transpose gives the correct orientation of the real image with format of (H, W, C), assuming the Buteo conveyor belt moves toward the right>>
cube = np.transpose(cube, axes = (2, 1, 0))[::-1,::-1,:]
# TODO: handle NaN because of possible division by zero on (white - dark)
return cube
Capturing datacubes
Under development
Coming soon
Matlab
Reading PAM datacubes
msp_HSI_buteo.m
function cube = msp_HSI_buteo(file_path)
% msp_HSI_buteo - Reads and reshapes a hyperspectral image cube from a .pam file.
%
% This function reads a SWIR hyperspectral image stored in a .pam file and
% reshapes it into a 3D cube format.
%
% Author: msp
% Date: February 2025
%
% Input:
% file_path - String specifying the path to the .pam file.
%
% Output:
% cube - A 3D hyperspectral image cube (height x width x bands).
%
% Note:
% - The function assumes a specific file format where the first 11 lines
% form a header that is ignored.
% - The reshaping assumes a fixed image size of 1296 (height) × variable width × 900 (bands).
%
% Open file for reading
fileID = fopen(file_path, 'r');
if fileID == -1
error('Error: Could not open file %s', file_path);
end
% Read and store the first 11 lines as header
header = [];
for i = 1:11
header = [header, fgets(fileID)]; % Read header, one line at a time
end
byte_length = numel(header); % Byte length of header (not used)
% Read the rest of the .pam file (excluding header)
data = uint8(fread(fileID)); % Read as unsigned 8-bit integer
% Close the file
fclose(fileID);
% Reshape data into a 3D hyperspectral cube
cube = reshape(data, 1296, [], 900); % SWIR Buteo assumed dimensions
% Clear unnecessary variable
clear data;
end
PAM interleave
The above example expects PAM files captured using the Buteo Lab scanner which have a BIL interleave type.
Reflectance transformation
msp_refl_trans.m
function cube_refl = msp_refl_trans(cube, mean_white, mean_dark)
% msp_refl_trans - Performs reflectance transformation on a hyperspectral image cube.
%
% This function converts raw hyperspectral intensity values into reflectance values
% using a white reference and a dark reference.
%
% Author: msp
% Date: February 2025
%
% Input:
% cube - A 3D hyperspectral image cube (height x width x bands).
% mean_white - A reference white image (same dimensions as cube or a single spectrum).
% mean_dark - A reference dark image (same dimensions as cube or a single spectrum).
%
% Output:
% cube_refl - The hyperspectral cube transformed to reflectance values.
% Compute reflectance transformation
cube_refl = single(cube - uint8(mean_dark)) ./ single(uint8(mean_white - mean_dark));
% Handle NaN and Inf values (caused by division by zero)
cube_refl(isnan(cube_refl) | isinf(cube_refl)) = 0;
cube_refl = single(cube_refl);
end