hypertool 0.4.1

Command-line tool for hyperspectral image processing

Hypertool

A command-line tool for visualization and processing of hyperspectral images in ENVI format (HDR/RAW).

Features

• Interactive visualization of hyperspectral images using napari
• RGB composite generation with automatic or custom band selection
• Multi-band layer visualization
• Classification workflow: ROI-based masking and cropping
• Segmentation workflow: Pixel-level annotation and paired image+mask cropping
• Support for ENVI, NumPy, and TIFF formats

See docs/architecture.md for the project architecture, module relationships, and extension guide.

Installation

Quick Install (Development)

pip install -e .

From Git (Production/Pipeline)

# Latest version
pip install git+https://github.com/your-username/hypertool.git

# Specific version
pip install git+https://github.com/your-username/hypertool.git@v2.1.0

For detailed installation instructions (private repositories, CI/CD, etc.), see INSTALL.md.

Usage

View Command

Visualize hyperspectral images in napari with different display modes.

# RGB mode with default bands from HDR metadata
python hypertool.py view image.hdr

# RGB mode with custom bands (0-based indices)
python hypertool.py view image.hdr --bands "50,100,150"

# View all bands as separate layers
python hypertool.py view image.hdr --mode all

# View a specific range of bands
python hypertool.py view image.hdr --mode range --start 50 --end 100

# Disable automatic normalization
python hypertool.py view image.hdr --no-normalize

Preview Command

Generate a PNG preview of a hyperspectral image using the default RGB bands from the HDR metadata.

# Default bands from HDR metadata
hypertool preview image.hdr

# Custom output path
hypertool preview image.hdr -o thumbnails/sample.png

# Custom band selection (0-based indices)
hypertool preview image.hdr --bands "50,100,150"

# Raw output without normalization
hypertool preview image.hdr --no-normalize

Parameters:

• --output/-o: Output PNG path (default: <image>_preview.png)
• --bands: Custom RGB band indices as comma-separated 0-based integers
• --no-normalize: Disable percentile (2-98) normalization

Workflows

Classification Workflow (ROI-based)

For image classification tasks where each crop gets a single label.

1. ROI-Mask Command

Create standardized ROI masks using geometric shapes.

# Create 6 circular masks (manual save)
python hypertool.py roi-mask image.hdr --shape circle --size 35 --num 6

# Create with auto-save on close
python hypertool.py roi-mask image.hdr --shape circle --size 35 --num 6 -o rois.csv

# Other shapes
python hypertool.py roi-mask image.hdr --shape square --size 30 --num 5 -o rois.csv
python hypertool.py roi-mask image.hdr --shape triangle --size 20 --num 3 -o rois.csv

Parameters:

• --shape: Shape type (square, circle, triangle)
• --size: Size on 1-100 scale (automatically converted to pixels)
• --num: Number of shapes to create (distributed in grid layout)
• --output/-o: Optional auto-save path (saves on napari close)

Steps:

1. Adjust mask positions in napari
2. Option A: Close napari (auto-saves if -o specified) Option B: Export manually via File > Save Selected Layer(s)
3. Create a labels.csv mapping each ROI index to its class

2. Crop Command (ROI mode)

Extract ROI crops from CSV.

# Crop using ROIs (bounding box only)
python hypertool.py crop image.hdr rois.csv ./output

# Apply shape mask (pixels outside shape = 0)
python hypertool.py crop image.hdr rois.csv ./output --apply-mask

# Custom prefix and NumPy format
python hypertool.py crop image.hdr rois.csv ./output --prefix sample --format numpy

Segmentation Workflow (Pixel-level)

For semantic segmentation tasks where each pixel gets a label.

Option A: Geometric Shapes (Recommended for uniform regions)

For regions with consistent geometric shapes (e.g., petri dishes, samples in trays).

Step 1: Create ROI shapes

python hypertool.py roi-mask image.hdr --shape circle --size 35 --num 6 -o rois.csv

• Move circles to position in napari
• Close napari (auto-saves to rois.csv)

Step 2: Convert ROIs to pixel mask

python hypertool.py roi-to-pixel-mask image.hdr rois.csv \
    --classes "tipo_A,tipo_B" -o masks.npy --save-metadata

• A reference image opens showing numbered ROIs
• Enter ROI numbers for each class interactively
• Background is automatically assigned to everything else
• --save-metadata creates masks.json with class mapping

Step 3: Crop image+mask pairs

python hypertool.py crop image.hdr masks.npy -o ./output

Result:

output/
├── images/          # Hyperspectral crops
│   ├── crop_0.npy
│   └── ...
└── masks/           # Segmentation masks (0=bg, 1=tipo_A, 2=tipo_B)
    ├── crop_0.npy
    └── ...

masks.json           # Class mapping metadata

Example interactive session:

ROI reference displayed...

tipo_A (label=1) ROI numbers (comma-separated): 0,1,2
✓ tipo_A → ROIs: [0, 1, 2]

tipo_B (label=2) ROI numbers (comma-separated): 3,4,5
✓ tipo_B → ROIs: [3, 4, 5]

Proceed with mask generation? [Y/n]: y
✓ Pixel mask saved to: masks.npy

Option B: Free Annotation (For irregular shapes)

For complex or irregular regions that can't be represented by geometric shapes.

Step 1: Create pixel masks manually

python hypertool.py pixel-mask image.hdr --classes "background,healthy,diseased"

• Opens napari with empty Labels layer
• Use paint/fill tools to annotate regions
• Save via File > Save Selected Layer(s) or use --output

Step 2: Crop image+mask pairs

python hypertool.py crop image.hdr masks.npy ./output

Output structure:

output/
├── images/
│   ├── crop_0.npy
│   ├── crop_1.npy
│   └── ...
└── masks/
    ├── crop_0.npy
    ├── crop_1.npy
    └── ...

Command Summary

Command	Purpose	Workflow
view	Visualize hyperspectral images	Both
preview	Export PNG preview of an image	Both
roi-mask	Create geometric ROI shapes	Classification / Segmentation
roi-to-pixel-mask	Convert ROI shapes to pixel masks	Segmentation
pixel-mask	Free-hand pixel annotation	Segmentation
crop	Extract crops (auto-detects mode)	Both

Crop Command Auto-Detection

The crop command automatically detects the workflow:

• CSV input → Classification workflow (ROI-based)

  • Creates: Individual cropped images

• NPY/TIF input → Segmentation workflow (pixel-mask)

  • Creates: Paired image + mask crops in separate directories

CSV Format (Classification Workflow)

The ROI CSV file exported from napari must contain:

• index: ROI identifier
• shape-type: Type of shape (rectangle, ellipse, polygon)
• vertex-index: Vertex number within the shape
• axis-0: Y coordinate
• axis-1: X coordinate

Requirements

• Python 3.8+
• spectral
• napari
• numpy
• pandas
• click
• scikit-image
• tifffile (optional, for TIF export)
• matplotlib

Documentation

• Architecture & Extension Guide

Notes

• Band indices are 0-based in the CLI
• The tool automatically detects BIL/BSQ/BIP interleave formats
• Percentile normalization (2nd-98th) is applied by default for visualization
• Segmentation masks use integer labels: 0=background, 1=class1, 2=class2, etc.
• For segmentation, connected regions are automatically detected and cropped