hypertool 0.3.1__tar.gz

hypertool-0.3.1/.gitignore

@@ -0,0 +1,54 @@
+deploy.sh
+hypertool/_version.py
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Napari
+.napari/
+
+# Test files
+roi_reference.png
+

hypertool-0.3.1/INSTALL.md

@@ -0,0 +1,130 @@
+# Installation Guide
+
+## For Development
+
+If you're working on hypertool itself:
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/hypertool.git
+cd hypertool
+
+# Install in editable mode (changes reflect immediately)
+pip install -e .
+
+# Or with conda environment
+conda env create -f conda_env.yml
+conda activate napari
+pip install -e .
+```
+
+## For Production/Pipeline Use
+
+### Option 1: Install from Git (Private Repository)
+
+```bash
+# With SSH
+pip install git+ssh://git@github.com:Dannyzimmer/hypertool.git
+
+# With HTTPS + token
+pip install git+https://{GITHUB_TOKEN}@github.com/Dannyzimmer/hypertool.git
+
+# Specific version
+pip install git+https://github.com/Dannyzimmer/hypertool.git@v0.1.0
+```
+
+### Option 2: Install from Local Path
+
+```bash
+# From local directory
+pip install /path/to/hypertool
+
+# In editable mode (for development)
+pip install -e /path/to/hypertool
+```
+
+### Option 3: Add to requirements.txt
+
+In your pipeline's `requirements.txt`:
+
+```
+# From Git
+git+https://github.com/Dannyzimmer/hypertool.git@v0.1.0
+
+# From local path (development)
+-e /path/to/hypertool
+```
+
+## Verify Installation
+
+```bash
+# Check command is available
+hypertool --help
+
+# Check version
+python -c "from hypertool import __version__; print(__version__)"
+```
+
+## Usage in Python Code
+
+### As CLI command
+
+```python
+import subprocess
+
+result = subprocess.run([
+    'hypertool', 'crop', 
+    'image.hdr', 'masks.npy', 
+    '-o', './output'
+], check=True)
+```
+
+### As imported functions
+
+```python
+from hypertool.cli import (
+    crop_from_pixel_mask,
+    load_pixel_mask,
+    save_pixel_mask
+)
+
+# Use functions directly
+mask = load_pixel_mask('masks.npy')
+# ... process ...
+save_pixel_mask(mask, 'output.npy', 'npy')
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Install hypertool
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  run: |
+    pip install git+https://${GITHUB_TOKEN}@github.com/your-username/hypertool.git@v2.1.0
+```
+
+### GitLab CI
+
+```yaml
+before_script:
+  - pip install git+https://oauth2:${CI_JOB_TOKEN}@gitlab.com/your-username/hypertool.git@v2.1.0
+```
+
+## Uninstall
+
+```bash
+pip uninstall hypertool
+```
+
+## Troubleshooting
+
+### Missing dependencies
+
+If you get import errors, ensure all dependencies are installed:
+
+```bash
+pip install -r requirements.txt
+```

hypertool-0.3.1/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2026 Daniel Pérez Rodríguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

hypertool-0.3.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include requirements.txt
+include conda_env.yml
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

hypertool-0.3.1/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: hypertool
+Version: 0.3.1
+Summary: Command-line tool for hyperspectral image processing
+Author: Daniel Pérez Rodríguez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dannyzimm/hypertool
+Project-URL: Repository, https://github.com/dannyzimm/hypertool
+Keywords: hyperspectral,imaging,segmentation,classification,napari
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: spectral>=0.23.1
+Requires-Dist: napari[all]>=0.4.18
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: scikit-image>=0.21.0
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: tifffile>=2023.0.0
+Dynamic: license-file
+
+# 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
+
+## Installation
+
+### Quick Install (Development)
+
+```bash
+pip install -e .
+```
+
+### From Git (Production/Pipeline)
+
+```bash
+# 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](INSTALL.md).
+
+## Usage
+
+### View Command
+
+Visualize hyperspectral images in napari with different display modes.
+
+```bash
+# 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
+```
+
+## 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.
+
+```bash
+# 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.
+
+```bash
+# 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**
+```bash
+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**
+```bash
+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**
+```bash
+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**
+```bash
+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**
+```bash
+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 |
+| `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)
+- PyQt5
+- matplotlib
+
+## 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

hypertool-0.3.1/README.md

@@ -0,0 +1,241 @@
+# 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
+
+## Installation
+
+### Quick Install (Development)
+
+```bash
+pip install -e .
+```
+
+### From Git (Production/Pipeline)
+
+```bash
+# 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](INSTALL.md).
+
+## Usage
+
+### View Command
+
+Visualize hyperspectral images in napari with different display modes.
+
+```bash
+# 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
+```
+
+## 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.
+
+```bash
+# 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.
+
+```bash
+# 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**
+```bash
+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**
+```bash
+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**
+```bash
+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**
+```bash
+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**
+```bash
+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 |
+| `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)
+- PyQt5
+- matplotlib
+
+## 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