HYSPI

What it does Install Quick run ROI modes Citation

HYSPI is a lightweight Python toolkit for converting hyperspectral hand scans into analysis-ready spectral data. It automatically detects anatomical hand landmarks using MediaPipe, generates reproducible palm or fingertip regions of interest (ROIs), applies those masks to hyperspectral image cubes, and exports the mean spectrum for each sample as a CSV file.

HYSPI is designed to make ROI generation consistent, transparent, and fully scriptable. Instead of manually drawing regions for every scan, researchers can point HYSPI to a directory of hyperspectral images, select an ROI definition, and process entire datasets with a reproducible workflow.

By standardizing the preprocessing pipeline, HYSPI helps reduce variability in spectral extraction, making downstream statistical analysis and machine learning workflows more reliable and easier to reproduce.

HYSPI is intended for research use only. It is not a medical device, does not provide clinical decision support, and should not be used as a substitute for professional clinical judgment.

What HYSPI Does

• Detects hand landmarks with MediaPipe.
• Builds ROI masks for palm, fingertips, or clip-aware palm analysis.
• Reads TIVITA-style hyperspectral .dat cubes stored as big-endian float32.
• Extracts the mean spectrum from all pixels inside each mask.
• Writes traceable CSV files with patient/sample IDs derived from folder paths.
• Logs failed detections and keeps the batch moving.

Install With uv

HYSPI is packaged for uv. Clone the repository and sync the environment:

git clone https://github.com/UMEssen/HYSPI.git
cd HYSPI
uv sync

Check that the CLI is wired:

uv run hyspy --help
uv run python -m hyspy --help

Folder Shape

HYSPI searches recursively from --folder-path. Your exact study layout can be deeper or flatter than this example; the important part is that each scan folder contains the cube and, when needed, the matching RGB image.

data/
  patient_001/
    scan_01/
      SpecCube.dat
      RGB-Image.png
    scan_02/
      SpecCube.dat
  patient_002/
    visit_1/
      SpecCube.dat

For cube-based detection, SpecCube.dat is enough. For clip, use RGB-Image.png for landmark detection and keep SpecCube.dat in the same sample folder for spectra extraction.

Quick Run

For a standard palm-circle ROI directly from cubes:

uv run hyspy \
  --folder-path ./data \
  --ROI palm_circle \
  --file-ending SpecCube.dat \
  --output-folder ./results

For clip-aware palm analysis, detect on RGB images and extract spectra from the matching cube:

uv run hyspy \
  --folder-path ./data \
  --ROI clip \
  --file-ending RGB-Image.png \
  --cube-ending SpecCube.dat \
  --output-folder ./results

You can also run HYSPI as a Python module, which is handy in managed environments:

uv run python -m hyspy \
  --folder-path ./data \
  --ROI finger \
  --file-ending SpecCube.dat \
  --output-folder ./results \
  --id-from-path last-n \
  --id-depth 2

CLI Arguments

Argument	Required	Default	Meaning
--folder-path	Yes	-	Root folder containing samples.
--ROI	Yes	-	One of clip, finger, palm_circle, palm_polygon.
--file-ending	Yes	-	Detection file suffix, usually SpecCube.dat or RGB-Image.png.
--output-folder	Yes	-	Where result CSVs and error.csv are written.
--cube-ending	No	SpecCube.dat	Cube suffix used for spectra extraction.
--id-from-path	No	relative	ID mode: relative, full-path, or last-n.
--id-depth	No	2	Number of trailing folder levels for last-n.
--log-level	No	INFO	One of DEBUG, INFO, WARNING, ERROR.

ROI Modes

ROI	How It Works
palm_circle	Circle centered from wrist, index MCP, and pinky MCP landmarks.
palm_polygon	Palm triangle from wrist, index MCP, and pinky MCP landmarks.
finger	Small circles over index, middle, ring, and pinky fingertips.
clip	Palm circle plus color filtering for covered/occluded palm images; use RGB input.

Mask files are written beside each sample as mask_<ROI>.png, so you can inspect what was used for extraction instead of trusting a black box.

Outputs

The main output is HSI_spectra_<ROI>.csv in --output-folder.

Column	Meaning
patient_id	Parent-level identifier derived from the sample path.
sample_id	Folder containing the detected image/cube.
sample_path	Relative path from --folder-path.
band_0, band_1, ...	Mean spectral value for each wavelength band.

If hand detection fails for a sample, HYSPI records the sample folder in error.csv and skips that sample during spectra extraction. This makes failed cases easy to review without killing a long batch run.

Troubleshooting

Symptom	Try This
No hand detected	Use RGB input if available, inspect crop/orientation, rerun with --log-level DEBUG.
Empty spectra CSV	Check that masks exist and --cube-ending matches the actual cube filename.
Mask/cube index errors	Confirm the mask was generated from the corresponding sample image/cube.
Clip ROI looks odd	Use RGB-Image.png; the clip filter is color-based and expects RGB-like input.

For first-time debugging, start with one or two samples and --log-level DEBUG. Once the masks look sane, scale up to the full cohort.

Citation

If HYSPI helps your work, please cite the publication behind the pipeline:

Kohnke, J., Pattberg, K., Nensa, F. et al. A proof of concept for microcirculation monitoring using machine learning based hyperspectral imaging in critically ill patients: a monocentric observational study. Critical Care 28, 230 (2024). https://doi.org/10.1186/s13054-024-05023-w

@article{kohnke2024microcirculation,
  title = {A proof of concept for microcirculation monitoring using machine learning based hyperspectral imaging in critically ill patients: a monocentric observational study},
  author = {Kohnke, Judith and Pattberg, Kevin and Nensa, Felix and others},
  journal = {Critical Care},
  volume = {28},
  pages = {230},
  year = {2024},
  doi = {10.1186/s13054-024-05023-w},
  url = {https://doi.org/10.1186/s13054-024-05023-w}
}

License

HYSPI is released under the MIT License. See LICENSE.