# Hyperseed 🌱
An experimental Python tool for hyperspectral seed image analysis. Inspired by (Reddy, et.al 2023, Sensors)[https://pmc.ncbi.nlm.nih.gov/articles/PMC9961513/]
## 🌟 Features
- **ENVI Format Support**: Read and process ENVI format hyperspectral data from Specim SWIR cameras
- **Automatic Calibration**: White/dark reference correction with automatic bad pixel interpolation
- **Intelligent Outlier Removal**: Automatically detect and remove reference objects, calibration targets, and anomalies
- **Advanced Preprocessing**: Multiple spectral preprocessing methods (SNV, derivatives, baseline correction, etc.)
- **Smart Segmentation**: Multiple algorithms for accurate seed detection and isolation
- **Spectral Extraction**: Extract average spectral signatures from individual seeds
- **Spatial Preservation**: Maintain seed coordinates and morphological properties
- **Comprehensive Visualizations**: Auto-generate distribution, segmentation, and spectral plots
- **Batch Processing**: Process multiple datasets efficiently with parallel support
- **Flexible Configuration**: YAML-based configuration system
- **User-Friendly CLI**: Intuitive command-line interface with rich output
## 📋 Requirements
- Python 3.10 or higher
- 8GB+ RAM recommended
- Optional: GPU with Metal (macOS) or CUDA support for acceleration
## 🚀 Installation
### From Source
```bash
# Clone the repository
git clone [repository-url]
cd hyperseed
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
```
### Using pip from Github Source
```bash
pip install --no-cache-dir --force-reinstall https://github.com/nishad/hyperseed/archive/main.zip
```
## 📖 Quick Start
### Basic Usage
Analyze a single hyperspectral dataset:
```bash
hyperseed analyze dataset/sample_001 --output results.csv --export-plots
```
### Recommended Usage
```bash
# Optimal settings for seed analysis with visualizations
hyperseed analyze dataset/sample_data \
--output results.csv \
--min-pixels 50 \
--preprocess minimal \
--export-plots
```
### Advanced Usage
```bash
# Batch process multiple datasets in parallel
hyperseed batch dataset/ \
--output-dir results/ \
--min-pixels 50 \
--parallel 4
# Disable outlier removal if needed
hyperseed analyze dataset/sample \
--output results.csv \
--no-outlier-removal
# Generate and use custom configuration
hyperseed config --output my_config.yaml --preset minimal
hyperseed analyze dataset/sample --config my_config.yaml
```
## 📁 Expected Data Structure
Hyperseed expects hyperspectral data in the following directory structure:
```
dataset/
├── capture/
│ ├── data.raw # Main hyperspectral data
│ ├── data.hdr # ENVI header file
│ ├── WHITEREF_data.raw # White reference
│ ├── WHITEREF_data.hdr
│ ├── DARKREF_data.raw # Dark reference
│ └── DARKREF_data.hdr
├── calibrations/bpr/ # Optional bad pixel maps
│ ├── bprmap.bpr
│ └── bprmap.hdr
└── metadata/ # Optional metadata
└── data.xml
```
## ⚙️ Configuration
Create a configuration file to customize the analysis pipeline:
```yaml
# config.yaml
calibration:
apply_calibration: true
clip_negative: true
clip_max: 1.0
preprocessing:
method: minimal # Options: minimal, standard, advanced, none
snv: false
smoothing: true
smoothing_window: 11
baseline_correction: false
segmentation:
algorithm: watershed # Options: threshold, watershed, connected, combined
min_pixels: 50
reject_overlapping: true
remove_outliers: true # Automatic outlier removal (enabled by default)
outlier_min_area: 50
outlier_max_area: 2000
output:
format: csv
include_plots: true
include_coordinates: true
```
## 📊 Output Format
The tool generates multiple outputs:
### CSV Spectra File
```csv
seed_id,index,centroid_y,centroid_x,area,eccentricity,solidity,band_1000nm,band_1005nm,...
1,0,234.5,156.2,435,0.34,0.92,0.234,0.237,...
2,1,345.6,234.1,421,0.28,0.94,0.229,0.232,...
```
### Visualization Plots (when using --export-plots)
- `*_distribution.png`: Spatial and area distribution of seeds
- `*_segmentation.png`: Numbered seed visualization with boundaries
- `*_spectra.png`: Individual and mean spectral curves
- `*_spectra_statistics.png`: Statistical analysis of spectral variability
## 🔬 Processing Pipeline
1. **Data Loading**: Read ENVI format hyperspectral data
2. **Calibration**: Apply white/dark reference correction with bad pixel interpolation
3. **Preprocessing**: Apply spectral preprocessing methods (minimal recommended for segmentation)
4. **Segmentation**: Detect and isolate individual seeds using smart algorithms
5. **Validation**: Filter seeds based on size and shape criteria
6. **Outlier Removal**: Automatically remove reference objects and anomalies
7. **Extraction**: Extract average spectrum for each valid seed
8. **Export**: Save results with comprehensive spatial and spectral information
## Command-Line Documentation
For detailed usage instructions, see the [CLI Documentation](CLI_DOCUMENTATION.md).
## 🛠️ Development
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=hyperseed
# Run specific test module
pytest tests/test_preprocessing.py -v
```
### Code Quality
```bash
# Format code
black hyperseed/
# Check code style
ruff check hyperseed/
# Type checking
mypy hyperseed/
```
## 📚 API Usage
```python
from hyperseed import ENVIReader, Settings
from hyperseed.core.calibration import ReflectanceCalibrator
from hyperseed.core.preprocessing import PreprocessingPipeline
from hyperseed.core.segmentation import SeedSegmenter
from hyperseed.core.extraction import SpectralExtractor
# Load data
reader = ENVIReader("path/to/data.hdr")
data = reader.read_data()
wavelengths = reader.get_wavelengths()
# Calibrate (automatically handles bad pixel correction)
calibrator = ReflectanceCalibrator(clip_negative=True, clip_max=1.0)
calibrated, reader = calibrator.calibrate_from_directory("path/to/dataset")
# Preprocess
settings = Settings()
preprocessor = PreprocessingPipeline(settings.preprocessing)
processed = preprocessor.fit_transform(calibrated)
# Segment
segmenter = SeedSegmenter(settings.segmentation)
mask, n_seeds = segmenter.segment(processed)
# Extract spectra
extractor = SpectralExtractor()
results = extractor.extract(calibrated, mask, wavelengths)
# Save results
extractor.save_csv("results.csv")
```
Raw data
{
"_id": null,
"home_page": null,
"name": "hyperseed",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "hyperspectral, image-analysis, seed-analysis, spectroscopy, remote-sensing, machine-learning, computer-vision",
"author": "Nishad Thalhath, Deepa Kasaragod",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/58/f1/98e52113e0742379683e21332234b667c05f1332286ecb75a72b6b979556/hyperseed-0.1.0a3.tar.gz",
"platform": null,
"description": "# Hyperseed \ud83c\udf31\n\nAn experimental Python tool for hyperspectral seed image analysis. Inspired by (Reddy, et.al 2023, Sensors)[https://pmc.ncbi.nlm.nih.gov/articles/PMC9961513/]\n\n## \ud83c\udf1f Features\n\n- **ENVI Format Support**: Read and process ENVI format hyperspectral data from Specim SWIR cameras\n- **Automatic Calibration**: White/dark reference correction with automatic bad pixel interpolation\n- **Intelligent Outlier Removal**: Automatically detect and remove reference objects, calibration targets, and anomalies\n- **Advanced Preprocessing**: Multiple spectral preprocessing methods (SNV, derivatives, baseline correction, etc.)\n- **Smart Segmentation**: Multiple algorithms for accurate seed detection and isolation\n- **Spectral Extraction**: Extract average spectral signatures from individual seeds\n- **Spatial Preservation**: Maintain seed coordinates and morphological properties\n- **Comprehensive Visualizations**: Auto-generate distribution, segmentation, and spectral plots\n- **Batch Processing**: Process multiple datasets efficiently with parallel support\n- **Flexible Configuration**: YAML-based configuration system\n- **User-Friendly CLI**: Intuitive command-line interface with rich output\n\n## \ud83d\udccb Requirements\n\n- Python 3.10 or higher\n- 8GB+ RAM recommended\n- Optional: GPU with Metal (macOS) or CUDA support for acceleration\n\n## \ud83d\ude80 Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone [repository-url]\ncd hyperseed\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n```\n\n### Using pip from Github Source\n\n```bash\npip install --no-cache-dir --force-reinstall https://github.com/nishad/hyperseed/archive/main.zip\n```\n\n## \ud83d\udcd6 Quick Start\n\n### Basic Usage\n\nAnalyze a single hyperspectral dataset:\n\n```bash\nhyperseed analyze dataset/sample_001 --output results.csv --export-plots\n```\n\n### Recommended Usage\n\n```bash\n# Optimal settings for seed analysis with visualizations\nhyperseed analyze dataset/sample_data \\\n --output results.csv \\\n --min-pixels 50 \\\n --preprocess minimal \\\n --export-plots\n```\n\n### Advanced Usage\n\n```bash\n# Batch process multiple datasets in parallel\nhyperseed batch dataset/ \\\n --output-dir results/ \\\n --min-pixels 50 \\\n --parallel 4\n\n# Disable outlier removal if needed\nhyperseed analyze dataset/sample \\\n --output results.csv \\\n --no-outlier-removal\n\n# Generate and use custom configuration\nhyperseed config --output my_config.yaml --preset minimal\nhyperseed analyze dataset/sample --config my_config.yaml\n```\n\n## \ud83d\udcc1 Expected Data Structure\n\nHyperseed expects hyperspectral data in the following directory structure:\n\n```\ndataset/\n\u251c\u2500\u2500 capture/\n\u2502 \u251c\u2500\u2500 data.raw # Main hyperspectral data\n\u2502 \u251c\u2500\u2500 data.hdr # ENVI header file\n\u2502 \u251c\u2500\u2500 WHITEREF_data.raw # White reference\n\u2502 \u251c\u2500\u2500 WHITEREF_data.hdr\n\u2502 \u251c\u2500\u2500 DARKREF_data.raw # Dark reference\n\u2502 \u2514\u2500\u2500 DARKREF_data.hdr\n\u251c\u2500\u2500 calibrations/bpr/ # Optional bad pixel maps\n\u2502 \u251c\u2500\u2500 bprmap.bpr\n\u2502 \u2514\u2500\u2500 bprmap.hdr\n\u2514\u2500\u2500 metadata/ # Optional metadata\n \u2514\u2500\u2500 data.xml\n```\n\n## \u2699\ufe0f Configuration\n\nCreate a configuration file to customize the analysis pipeline:\n\n```yaml\n# config.yaml\ncalibration:\n apply_calibration: true\n clip_negative: true\n clip_max: 1.0\n\npreprocessing:\n method: minimal # Options: minimal, standard, advanced, none\n snv: false\n smoothing: true\n smoothing_window: 11\n baseline_correction: false\n\nsegmentation:\n algorithm: watershed # Options: threshold, watershed, connected, combined\n min_pixels: 50\n reject_overlapping: true\n remove_outliers: true # Automatic outlier removal (enabled by default)\n outlier_min_area: 50\n outlier_max_area: 2000\n\noutput:\n format: csv\n include_plots: true\n include_coordinates: true\n```\n\n## \ud83d\udcca Output Format\n\nThe tool generates multiple outputs:\n\n### CSV Spectra File\n```csv\nseed_id,index,centroid_y,centroid_x,area,eccentricity,solidity,band_1000nm,band_1005nm,...\n1,0,234.5,156.2,435,0.34,0.92,0.234,0.237,...\n2,1,345.6,234.1,421,0.28,0.94,0.229,0.232,...\n```\n\n### Visualization Plots (when using --export-plots)\n- `*_distribution.png`: Spatial and area distribution of seeds\n- `*_segmentation.png`: Numbered seed visualization with boundaries\n- `*_spectra.png`: Individual and mean spectral curves\n- `*_spectra_statistics.png`: Statistical analysis of spectral variability\n\n## \ud83d\udd2c Processing Pipeline\n\n1. **Data Loading**: Read ENVI format hyperspectral data\n2. **Calibration**: Apply white/dark reference correction with bad pixel interpolation\n3. **Preprocessing**: Apply spectral preprocessing methods (minimal recommended for segmentation)\n4. **Segmentation**: Detect and isolate individual seeds using smart algorithms\n5. **Validation**: Filter seeds based on size and shape criteria\n6. **Outlier Removal**: Automatically remove reference objects and anomalies\n7. **Extraction**: Extract average spectrum for each valid seed\n8. **Export**: Save results with comprehensive spatial and spectral information\n\n## Command-Line Documentation\n\nFor detailed usage instructions, see the [CLI Documentation](CLI_DOCUMENTATION.md).\n\n## \ud83d\udee0\ufe0f Development\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=hyperseed\n\n# Run specific test module\npytest tests/test_preprocessing.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack hyperseed/\n\n# Check code style\nruff check hyperseed/\n\n# Type checking\nmypy hyperseed/\n```\n\n## \ud83d\udcda API Usage\n\n```python\nfrom hyperseed import ENVIReader, Settings\nfrom hyperseed.core.calibration import ReflectanceCalibrator\nfrom hyperseed.core.preprocessing import PreprocessingPipeline\nfrom hyperseed.core.segmentation import SeedSegmenter\nfrom hyperseed.core.extraction import SpectralExtractor\n\n# Load data\nreader = ENVIReader(\"path/to/data.hdr\")\ndata = reader.read_data()\nwavelengths = reader.get_wavelengths()\n\n# Calibrate (automatically handles bad pixel correction)\ncalibrator = ReflectanceCalibrator(clip_negative=True, clip_max=1.0)\ncalibrated, reader = calibrator.calibrate_from_directory(\"path/to/dataset\")\n\n# Preprocess\nsettings = Settings()\npreprocessor = PreprocessingPipeline(settings.preprocessing)\nprocessed = preprocessor.fit_transform(calibrated)\n\n# Segment\nsegmenter = SeedSegmenter(settings.segmentation)\nmask, n_seeds = segmenter.segment(processed)\n\n# Extract spectra\nextractor = SpectralExtractor()\nresults = extractor.extract(calibrated, mask, wavelengths)\n\n# Save results\nextractor.save_csv(\"results.csv\")\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "An experimental tool for hyperspectral seed image analysis",
"version": "0.1.0a3",
"project_urls": {
"Bug Tracker": "https://github.com/nishad/hyperseed/issues",
"Documentation": "https://nishad.github.io/hyperseed",
"Homepage": "https://github.com/nishad/hyperseed"
},
"split_keywords": [
"hyperspectral",
" image-analysis",
" seed-analysis",
" spectroscopy",
" remote-sensing",
" machine-learning",
" computer-vision"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8330b3248479544db1bcd07a813169e8f5e96e9924519dfa83c41a48e15c5c49",
"md5": "830338ed24156ba6ac034ef5c7715ae0",
"sha256": "ad2bc4b6bffe79bae359fde40d6b1f5c34c37bf2a11b9a418a2d8339647ec5d7"
},
"downloads": -1,
"filename": "hyperseed-0.1.0a3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "830338ed24156ba6ac034ef5c7715ae0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 101258,
"upload_time": "2025-10-29T06:20:49",
"upload_time_iso_8601": "2025-10-29T06:20:49.726127Z",
"url": "https://files.pythonhosted.org/packages/83/30/b3248479544db1bcd07a813169e8f5e96e9924519dfa83c41a48e15c5c49/hyperseed-0.1.0a3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "58f198e52113e0742379683e21332234b667c05f1332286ecb75a72b6b979556",
"md5": "39fea8539f8ac2de1bc383d6cfc6148e",
"sha256": "320e61c0bfc522412407eec4f934d2a799e68ceead316a66da68e6836a43ef50"
},
"downloads": -1,
"filename": "hyperseed-0.1.0a3.tar.gz",
"has_sig": false,
"md5_digest": "39fea8539f8ac2de1bc383d6cfc6148e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 80981,
"upload_time": "2025-10-29T06:20:51",
"upload_time_iso_8601": "2025-10-29T06:20:51.293500Z",
"url": "https://files.pythonhosted.org/packages/58/f1/98e52113e0742379683e21332234b667c05f1332286ecb75a72b6b979556/hyperseed-0.1.0a3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 06:20:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nishad",
"github_project": "hyperseed",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hyperseed"
}
JSON
