HV Explorer
Python based helper tool developed by qtec for visualizing and manipulating HSI data cubes.
Features
It supports importing and exporting to/from difference datacube file formats (currently PAM, ENVI and TIFF). The data can then be visualized as individual slices of the cube shown as full images (of a single selectable spectral band) with different color maps or by composing false "RGB" image from selected bands.
Moreover, it can also plot the mean spectra of multiple rectangular regions of the images for comparison. The spectra can then, if desired, be normalized using SNV (Standard Normal Variate) and/or smoothed (using Gaussian or Savitzky Golay smoothing methods). Optionally, the spectral derivatives (1st or 2nd orders) can be plotted. The spectra of the selected regions can be exported in the CSV format.
Multiple images can be opened and compared at once due to HV SDK's efficient data loading which minimizes RAM usage (Buteo data cubes are often 1Gbyte in size which can overload normal programs).
The HV Explorer supports several common HSI image transformations, including reflectance calibration (using white/black references), dimensionality reduction (PCA), clustering, noise reduction, dead pixel removal, band math, etc.
The HV Explorer currently requires the datacubes to be have been captured beforehand through the Buteo Lab scanner interface (or by other means), but support for capturing live data directly from the Hypervision cameras is expected soon.
Both Linux and Windows versions are available.
HV Explorer showing spectral curve of meat and fat regions
The HV Explorer 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).
Some features such as dead pixel removal and band math are still not fully implemented and will be added in subsequent releases.
Windows11 or Linux (Python 3.10 or higher required)
Minimum RAM: 8Gb (16Gb recommended)
Installation
Windows
Simply download the HV-Explorer-Setup-<version>.exe from the latest release and follow the instructions.
Linux
installation script
Automatically performs all the steps described below in the uv section.
Use curl to download the script and execute it with sh:
curl -LsSf https://gitlab.com/api/v4/projects/67863505/packages/generic/qtec-hv-explorer/<version>/install.sh | sh
If your system doesn't have curl, you can use wget:
wget -qO- https://gitlab.com/api/v4/projects/67863505/packages/generic/qtec-hv-explorer/<version>/install.sh | sh
uv
uv can install/update the package directly from the repository. You need to have the tool installed, then run:
uv tool install qtec-hv-explorer --index https://gitlab.com/api/v4/projects/67863505/packages/pypi/simple --index-strategy unsafe-best-match --prerelease=allow
or from a directory with the wheel files:
uv tool install qtec-hv-explorer --find-links ./
To create an application shortcut, copy HV-Explorer.desktop
and hv-explorer.svg from the release to the appropriate locations or use the
example commands below:
cp <download_path>/HV-Explorer.desktop ~/.local/share/applications/
sudo cp <download_path>/hv-explorer.svg /usr/share/icons/
Tutorial
Start by opening the HV Explorer, the following interface will be appear:
HV Explorer interface
Loading datacubes
Click on the File explorer icon on the left side, and navigate to the
folder containing the datacube to be loaded.
In this example we have used the mixed nuts example data:
mix1_1296x1000x900_imageCube.
Alternatively use the Open button on the tool bar at the top to get a
"file dialog".
HV Explorer: file explorer interface
The datacube will be loaded.
By default an image of the "middle" band of the cube will be shown (in this
case the cube has 900 bands so band 450 is shown).
An inferno color map is used by default (color maps help enhance contrast in order
to aid the visualization of grey scale data).
It is possible to move the image around and zoom in/out by using the mouse.
HV Explorer: image loaded
Demo
HV Explorer: loading datacubes
Note that HV SDK (the HV Explorer backend) supports
all three types of interleave for the
PAM file format.
However, in order to determine the interleave and properly load the files, it
expects the interleave type to be specified in the TUPLTYPE part of the header.
Preview Inspector
Click on the Preview Inspector icon on the right side in order to change the
preview settings: select a different color map or change the band/channel shown.
It is also possible to change bewteen visualizing the Gray bands/channels or
creating a "false RGB" Color image representation composed of the specified
bands/channels.
HV Explorer: image preview settings
There are also in-build presets which select the appropriate bands/channels in order to generate a proper RGB visualization of the datacube, however this requires setting up information about the wavelengths covered by the datacube (otherwise the preset option is disabled in the interface).
This can be done by opening the Operation Inspector icon on the right side.
Then click the "plus" icon in order to add a new operation and choose the
WavelengthSpec operation.
Now type in the start and end wavelengths for the datacube, in this example the
data was captured using a
Hypervision 1700
camera with all bands present, so the minimum wavelength is 430nm and the maximum
wavelength is 1700nm.
HV Explorer: wavelength information
This information is now available in the Metadata Inspector, along with image
dimensions (lines, samples and bands), interleave type
and data type ((un)signed integer/float with 8, 16, 32 or64 bits).
The image dimensions are defined as:
- lines: number of raw images, corresponding to "image height"
- samples: spatial width
- bands: number of channels/wavelengths
HV Explorer: metadata information
Now a False RGB color preset can be choosen in the Preview Inspector.
The bands used for the red, green and blue channels can be changed, if desired, in order to generate a different visual representation of the data.
Note that the generated image doesn't seem to be a good representation of the expected color image, it is too redish, this is due to missing "white balancing", which will be performed in the next step.
HV Explorer: false RGB color image (missing white balancing)
Demo
HV Explorer: Preview inspector
Reflectance calibration
As mentioned above, the color balance of the False RGB image is not correct. This can be adjusted by converting the data into a reflectance model using both a white and a black reference image. The white reference image will adjust the color balance between the different wavelengths as well as correct for differences in illumination through the FOV (field of view). The black reference image will adjust the black level. See the Reflectance model section for in-depth information about the process.
The reflectance calibration can be performed by opening the Operation Inspector
and adding a Calibration operation.
Then selecting the White reference and Dark reference files.
For this example we have used:
- black reference: dark_ref_1296x100x900_imageCube
- white reference: white_ref_1296x100x900_imageCube
The false RGB color image now looks like a more real color representation of the data.
Note that is it also possible to use a White Reference which is embedded in
the original datacube by selecting Inline instead of File and then adjusting
the start and end positions of the white target in the image.
HV Explorer: reflectance calibration (correct false RGB color)
Note that doing a reflectance calibration will transform the data type from the
original unsigned 8-bit integer into a 32-bit float (clipped between 0 and 1).
This can be verified through the Metadata Inspector.
HV Explorer: 32-bit float datatype
Therefore if the new datacube (reflectance calibrated) is to be exported into, for example PAM, it has to be first converted back into an unsigned integer type of either 8 or 16-bit (since this is what PAM supports).
This can be done using a Scaling operation.
Just selected the desired datatype, in this case 8 or 16-bit unsigned, and then
adjust the Scale to an appropriate value (255 for 8-bit and 65535 for 16-bit).
HV Explorer: reflectance calibration (correct false RGB color)
Demo
HV Explorer: Reflectance calibration
Spectral plot
Now we will move into showning how to plot spectral information.
Click on the rectangle spectrum icon on the top of the image.
This will add a rectangular selection box to the bottom left corner of the image.
HV Explorer: rectangle spectrum selection
Move and resize the box as desired in order to select the region from which spectral data is desired (the data inside the box will be averaged). Add as many selection boxes as desired.
HV Explorer: rectangle selection placement
Now open the Spectral analysis panel on the left.
A list of the created selection boxes is displayed, each with a color and a name.
HV Explorer: Spectral analysis panel
Change the names and colors as necessary by double clicking.
HV Explorer: spectra color picker
Now click on the Spectral chart icon on the tool bar at the top.
This will open a plot view for the spectral data contained in the selection boxes.
Since we have inputed Wavelength information as an operation the plot displays
the wavelengths (in nm) in the Y-axis, otherwise the band/channel number would
be displayed.
HV Explorer: Spectral chart
SNV (Standard Normal Variate) can be enabled/disabled in order to perform normalization of the spectra to facilitate the comparison of different spectra.
HV Explorer: SNV (Standard Normal Variate)
First or second order derivatives can be shown instead of the pure spectra.
Smoothing of the spectra can be enabled, if desired, by using the Filter type
option, the available filters are Gaussian or Savitzky Golay.
HV Explorer: derivatives
Clicking on the different spectra inside the Spectral analysis panel will
"highlight" both the selected spectra in the Spectral chart plot as well as
the corresponding selection box in the image.
HV Explorer: highlighted spectra and selection box
Comparing spectra
Now we add more selection boxes in order to try and compare the spectra of almonds versus walnuts.
Note that even though SNV is enabled is not very easy to spot the differences between the spectra as their general shape is quite similar. With the buggest differences being in the area around 1150nm and 1400nm.
HV Explorer: spectra of almonds versus walnuts
These differences can be visualized easier if we use the 1st derivative. There are big difference around 1150nm, 1200nm and 1350nm.
HV Explorer: spectra of almonds versus walnuts (1st derivative)
It is possible to remove a selection box from the image (and therefore removing
the corresponding data from the plot) by selecting it in the Spectral analysis
panel and then clicking on the minus icon.
HV Explorer: remove spectra
Exporting spectral data
It is possible to export the spectra data by clicking on the export icon in
the Spectral analysis panel.
The data can be exported in the csv, xlsx and json formats.
HV Explorer: export spectra
Datacube slice view
It is also possible to show a slice of the datacube so that all the wavelengths/bands/channels of a single image line are shown as a grey scale image. This corresponds to the original image captured by the camera which has been "stacked" in order to generate the datacube from the scanned lines.
This is done by clicking on the slice icon on the top of the image.
A line, which can be dragged left/right will be shown, demonstrating where the
slice is being made.
HV Explorer: datacube slice view
Exporting datacubes
Datacubes can be exported by clicking on the Export icon on the top toolbar.
This is useful for for example converting between datacube file formats
(PAM, TIFF and ENVI
currently supported) or changing the interleave type.
It can also be used to export a processed datacube (which has, for example, been
calibrated for reflectance, cropped or had other operations performed on it).
Note that HV SDK supports all three types of interleave for the three supported file formats, however external applications might expect a specific interleave type depending on the file extension. Therefore, when exporting, it is quite important to choose a proper interleave type for the desired file type. ENVI supports all 3 types of interleave while TIFF is natively BSQ and PAM is natively BIP.
A final consideration before exporting a datacube is the current Data type
(which can be inspected using the Metadata Inspector).
As described in the Reflectance calibration section
the data type of the cube might have been transformed by the Operations applied
to it (for example the Reflectance calibration generates 32-bit floating point
data in the [0-1] range) and some of the file formats support only specific data
types.
PAM, for example, only supports either 8 or 16-bit integer data.
The Data type can be modified using a Scaling operation.
Just selected the desired datatype, in this case 8 or 16-bit unsigned, and then
adjust the Scale to an appropriate value (255 for 8-bit and 65535 for 16-bit).
Besides file format support, changing the Data type is also highly revelant when
considering storage efficiency versus loss of detail in the data: a 32-bit float
contains pottentially 4x more detailed data but takes 4x the storage space (which
might already be quite high for 1Gb datacubes containing 8-bit data).
HV Explorer: exporting datacubes
PCA
Coming soon
Support
Report bugs by writing an email to: hv-explorer-support