Tutorials and Examples

This section contains complete, copyable HV SDK workflows. The examples use Python and cover the common path from opening a datacube, calibration, and visualization through PCA, classification, regression, and streamed camera pipelines.

SDK version

These tutorials and downloadable scripts target the HV SDK v1 Python API, currently 1.0.0-beta.2. If you have older examples that use import hsi, see the v1 migration guide.

Refer to the HV SDK Usage Guide for conceptual details about lazy operations, interleave, calibration, and streaming. And for the complete API reference, see the official HV SDK documentation, which also contains several guides on how to work with the framework.

Example Sections

Goal	Start here
Open, inspect, calibrate, or visualize a datacube	Basics
Clean spectra, select bands, bin, crop, save processed cubes, or run simple spectral analysis	Preprocessing and Analysis
Load HV Explorer annotations, extract ROI spectra, or plot ROIs on preview images	Annotations and ROIs
Fit PCA models, inspect loadings and scores, or explore dominant spectral variation	Principal Component Analysis
Train pixel classifiers from ROIs or exported spectra, classify by spectral-angle matching, or prepare classifier models for camera pipelines	Classification
Predict continuous values such as fat, moisture, or concentration	Regression
Build live or simulated camera pipelines, stream frames, calibrate streamed data, test simulated stage-controller workflows, or apply saved models line by line	Streaming

Example Data

The downloadable scripts use the same sample datacubes as the HV Explorer tutorial. Download the cubes, dark/white references, and annotation files from HV Explorer example data, then point HSI_EXAMPLE_BASE_DIR to the folder where you stored them.

Running Downloaded Scripts

Downloaded scripts read paths from environment variables, so you can test them without editing the files. Set HSI_EXAMPLE_BASE_DIR to the folder containing your example datacubes, dark reference, white reference, annotations, and model files:

export HSI_EXAMPLE_BASE_DIR=/path/to/HSI_data/nuts
python 01_open_and_inspect_a_datacube.py

Install the Python packages used by most examples in the same environment as the HV SDK:

python -m pip install numpy matplotlib scikit-learn joblib

The streamed classifier visualization example also needs OpenCV and a graphical display:

python -m pip install opencv-python

Environment variables

Variable	Used by	Meaning
HSI_EXAMPLE_BASE_DIR	All downloaded scripts	Folder containing the example datacubes and references.
HSI_EXAMPLE_CUBE	Single-cube examples	Cube filename for examples that use one cube.
HSI_EXAMPLE_TRAIN_CUBE / HSI_EXAMPLE_TEST_CUBE	PCA and classification	Training and test cube filenames.
HSI_EXAMPLE_DARK_REF / HSI_EXAMPLE_WHITE_REF	Calibrated examples	Dark and white reference capture filenames.
HSI_EXAMPLE_ANNOTATIONS	ROI examples	HV Explorer annotations JSON.
HSI_EXAMPLE_MEAN_SPECTRA	Classification	Exported mean spectra CSV, default mix1_spectra.csv.
HSI_EXAMPLE_CLASSIFIER_MODEL	Classification and streaming	Saved classifier model path.
HSI_EXAMPLE_HV_EXPLORER_MODEL	Classification	.pkl classifier exported from HV Explorer.
HSI_EXAMPLE_HV_EXPLORER_ANNOTATIONS	Classification	Annotations .json exported alongside the HV Explorer model.
HSI_EXAMPLE_REGRESSION_MODEL	Regression and streaming	Saved regression model path.
HSI_EXAMPLE_REGRESSION_VMIN / HSI_EXAMPLE_REGRESSION_VMAX	Regression	Display range for regression prediction maps.
HSI_EXAMPLE_PCA_MODEL	PCA	Saved PCA model path.
HSI_EXAMPLE_ROI_PCA_MODEL	PCA	Saved ROI-fitted PCA model path.
HSI_EXAMPLE_OUTPUT	Saving examples	Output path for scripts that write processed data.
HSI_EXAMPLE_MILK_TRAIN_CUBE	Regression	Milk training cube filename.
HSI_EXAMPLE_MILK_TEST_CUBE	Regression and streaming	Milk test cube filename.
HSI_EXAMPLE_MILK_ANNOTATIONS	Regression	Milk annotations JSON.
HSI_EXAMPLE_TARGET_PROPERTY	Regression	Numeric annotation property to predict.
HSI_EXAMPLE_CAMERA_IP	Streaming	Camera IP address. If unset, camera examples use simulated data when possible.
HSI_EXAMPLE_VIDEO_DEVICE	qamlib streaming	Optional direct V4L2 device for the qamlib example.
HSI_EXAMPLE_N_LINES	Streaming	Number of lines to capture in finite camera examples.
HSI_EXAMPLE_EXPOSURE_US / HSI_EXAMPLE_FRAMERATE	Streaming	Camera exposure and framerate overrides.
HSI_EXAMPLE_HORIZONTAL_CROP / HSI_EXAMPLE_BANDS	Streaming	SDK camera crop and band selection overrides.
HSI_EXAMPLE_QAMLIB_CROP	qamlib streaming	Direct V4L2 crop as left,top,width,height.

Generated output files

Several examples save fitted models or processed output files:

• pca_model.joblib: created by the first PCA example.
• roi_pca_model.joblib: created by the ROI PCA fitting example.
• pixel_classifier.joblib: created by the first classification example.
• regression_model.joblib: created by the first regression example.

Use the corresponding environment variables above when you want those files to be written somewhere specific, for example /tmp/pixel_classifier.joblib.

Common Failures

• The script still uses the default data folder. Make sure you exported the variable, use export HSI_EXAMPLE_BASE_DIR=/path/to/HSI_data/nuts.
• A saved model file is missing. Run the first example in that section, or set the matching model path variable such as HSI_EXAMPLE_CLASSIFIER_MODEL, HSI_EXAMPLE_REGRESSION_MODEL, or HSI_EXAMPLE_PCA_MODEL.
• A model gives strange results on a new cube. Check that training and prediction use the same preprocessing, band count, band order, and wavelength calibration.
• Camera calibration fails or gives odd values. Make sure the dark and white references use the same interleave as the camera stream; the streaming examples convert references to BIL before calibration.
• Regression maps look flat or all one color. A few extrapolated values may dominate the color scale. Use HSI_EXAMPLE_REGRESSION_VMIN and HSI_EXAMPLE_REGRESSION_VMAX to set the displayed range.

Where To Go Next

• Use the HV SDK Usage Guide for conceptual details about lazy operations, interleave, calibration, and streaming.
• Use the official API documentation for full class and function references.
• Use HV Explorer to create ROIs, then export those annotations for supervised training workflows.