This repository provides a desktop viewer (GUI) and preprocessing utilities for inspecting HyperTex hyperspectral textile captures (Specim FX17 sensor) and managing ground-truth annotations and HDF5 dataset creation.
HyperTex contains Specim FX17 hyperspectral captures of textile materials (pure fibres and blends). Each annotated pixel is represented by a 10-channel target array corresponding to fibre composition percentages.
gui.py— Desktop GUI viewer built with Tkinter, Matplotlib, OpenCV, and Pillow. Features include:- False-colour RGB rendering with selectable RGB bands.
- Interactive cursor-driven reflectance and raw-signal spectral plots.
- Fibre composition classification inspector per pixel.
- Ground-Truth (GT) overlay toggle (Show GT).
- JSON → NPY: Batch converts LabelMe polygon annotations into 10-channel target NPY composition maps.
- Dataset → HDF5: Packages selected sample captures and ground-truth maps into
/dataand/gtgroups in HDF5 format for training.
utils.py— ENVI header/data loader, LabelMe annotation parser, ground-truth map generator, color mapping utilities, and HDF5 export utilities.bands_fx17.txt— Wavelength calibration file for the 224 spectral bands of the Specim FX17 sensor.classes.txt/classes_en.txt— Predefined list of the 10 textile fibre classes.images/— GUI logos and icon assets (inesctec-logo.png,iilab-logo.png,logo.png).data/— Optional directory used to store downloaded HyperTex samples for visualization and processing
Ensure you have a Python 3.9+ environment active.
Then install the dependencies:
pip install -r requirements.txtThis repository provides software tools for working with the HyperTex datasets.
Dataset files are distributed separately through:
- HyperTex: Original hyperspectral captures, annotations, metadata, calibration files, RGB visualizations, and ground-truth composition maps.
- Dataset: https://zenodo.org/records/21489250
- HyperTex-Splits: Standardized train-test partitions distributed in HDF5 format and supplementary dataset documentation.
- Dataset: https://zenodo.org/records/21869714
Links to the dataset records will be maintained through this repository and updated as resources become publicly available.
This repository does not include hyperspectral data files. Sample captures are distributed separately through the HyperTex dataset.
For the examples presented in this README, download the sample from the Hypertex dataset:
AllSamples-Combo_1_2023-10-10_11-02-02
Run gui.py from within the hypertex-ui directory:
python gui.py- The application opens with the example sample in
data/loaded by default. - Click Set Directory to choose a custom directory containing raw HyperTex sample folders.
- Click Set HDF5 File to directly inspect samples stored inside an
.hdf5dataset file. - Select a sample capture from the directory table to inspect its false-colour image, reflectance spectra, and raw signal spectra. Move your mouse across the image to examine spectra at specific pixel coordinates.
- Check Show GT to overlay the processed ground-truth composition mask on top of the image.
For raw annotated captures:
- Click JSON → NPY in the interface to convert all
.jsonLabelMe polygon annotations in the active directory into 10-channel.npycomposition maps.
- Click Dataset → HDF5.
- Select the samples to include in the dataset from the interactive list.
- Choose the output
.hdf5file path. The viewer will generate an HDF5 dataset containing/data/<sample_id>and/gt/<sample_id>groups ready for use inhypertex-ml.
Note: Ground-truth maps (.npy) must exist before exporting to HDF5. Run JSON → NPY first if needed.
Each original HyperTex sample folder has the following layout:
<sample_id>/
├── <sample_id>.json # LabelMe polygon annotations & fibre percentages
├── <sample_id>.npy # Derived ground-truth composition map (10 channels)
└── capture/
├── REFLECTANCE_<sample_id>.hdr # ENVI reflectance header
├── REFLECTANCE_<sample_id>.dat # ENVI reflectance cube
├── <sample_id>.hdr # ENVI raw-signal header
└── <sample_id>.raw # ENVI raw-signal cube
Each target pixel in the NPY ground truth and HDF5 dataset contains 10 values representing the composition percentage of each fibre class (summing to 1.0):
| Channel Index | Class Name |
|---|---|
| 1 | Unknown |
| 2 | Cotton |
| 3 | Wool |
| 4 | Lyocell |
| 5 | Viscose |
| 6 | Polyester |
| 7 | Linen |
| 8 | Elastane |
| 9 | Polyamide |
| 10 | Acrylic |
Example: [0.0, 0.7, 0.0, 0.0, 0.0, 0.3, 0.0, 0.0, 0.0, 0.0] represents 70% Cotton and 30% Polyester.
- Language: Python
- GUI Framework: Tkinter
- Visualization: Matplotlib, OpenCV, Pillow
- Hyperspectral Processing: spectral
- Data Storage: HDF5 (h5py)
- Numerical Computing: NumPy
This project is currently under active development.
Core functionalities for visualization, annotation processing, and HDF5 dataset generation are stable and actively used within the HyperTex project. Additional features and improvements may be introduced in future releases.
- Large hyperspectral captures may require significant memory.
- Viewer responsiveness depends on dataset size and system resources.
- HDF5 export requires pre-generated NPY ground-truth files.
This project is licensed under the "BSD 3-Clause License" see LICENSE for the full text.
Documentation, datasets, source code, and related resources associated with the HyperTex project are maintained through the project repositories and Zenodo records.
Links to companion datasets, source code, publications, and supplementary materials will be updated as additional resources become publicly available.
Before contributing, please review the project governance documents:
These documents define contribution workflows, expected behaviour, and security reporting procedures.
-Tony Ferreira - Developer, INESC TEC
For questions regarding this software or the HyperTex dataset:
Tony Ferreira tony.ferreira@inesctec.pt