CoreSpecViewer is a modular PyQt5 application designed for the full hyperspectral core‑scanning workflow — from Specim Lumo raw data to reflectance processing, masking, feature extraction, correlation mapping, thumbnail generation, and hole‑level review.
The system is designed for geoscientists and hyperspectral imaging specialists, with an emphasis on clarity, reproducibility, and modularity.
| Workflow Stage | Demonstration |
|---|---|
| Open and process Specim Lumo data |  |
| Mask and unwrap regions |  |
| Feature extraction & visualisation |  |
| Spectral library browsing |  |
| Full hole visualisation |  |
| Multi-box procession |  |
Each GIF illustrates one major part of the CoreSpecViewer workflow: open → mask → analyse → compare.
CoreSpecViewer provides:
- Raw data handling for Specim Lumo exports (
RawObject) - Processed reflectance cubes with memory‑mapped
.npydatasets (ProcessedObject) - Hole‑level aggregation & navigation (
HoleObject,HolePage) - Batch “multibox” processing with logging (
multi_box.py) - Spectral feature extraction, continuum removal, peak estimation
- Correlation & winner‑takes‑all mapping
- Interactive GUI with masking, cropping, unwrapping, picking
- Central shared state across all pages via
CurrentContext - Ribbon‑based UI with workflow‑grouped tools
CoreSpecViewer/
├─ CoreSpecViewer.py # Thin launcher
|
├─ resources/ # Spectral library and demo GIFs
│
├─ app/ # Main application package
│ ├─ main.py # Main Qt application entrypoint
│ ├─ config.py # User/application configuration
│ │
│ ├─ interface/ # Ribbon, toolbars, QAction wiring, dialogs
│ │ ├─ tools.py # Translation layer: data model → spectral functions
│ │ └─ tool_dispatcher.py # Safe GUI event routing for canvas tools
│ │
│ ├─ models/ # Data layer: core objects + context
│ │ ├─ dataset.py # Generic dataset container
│ │ ├─ processed_object.py # ProcessedObject
│ │ ├─ raw_object.py # RawObject
│ │ ├─ hole_object.py # HoleObject
│ │ └─ context.py # CurrentContext shared across the app
│ │
│ ├─ ui/ # Qt pages (Raw, Visualise, Library, Hole, etc.)
│ │ ├─ base_page.py # BasePage inherited by specific page classes
│ │ ├─ hole_page.py # HolePage
│ │ ├─ raw_page.py # RawPage
│ │ ├─ lib_page.py # LibraryPage
│ │ ├─ vis_page.py # VisualisePage
│ │ ├─ catalogue_window.py # File browser window
│ │ ├─ ribbon.py # Ribbon component
│ │ ├─ multi_box.py # Multi-box automated processing
│ │ └─ util_windows.py # Canvas widgets, dialogs, busy cursor, tables
│ │
│ └─ spectral/ # Spectral maths, IO
│ └─ spectral_functions.py # Continuum removal, Pearson, feature extraction
You will need to download and install one of:
There are two ways to run CoreSpecViewer:
- Clone the repo and create the Conda environment
- Lightweight pip install – quick testing, but no spectral library database is included
In the Miniforge/Miniconda/Anaconda prompt window:
Clone the repository:
git clone https://github.com/Russjas/CoreSpecViewer.git
cd CoreSpecViewer
Create the Conda environment:
conda env create -f environment.yml
conda activate specviewenv
Launch the application:
python CoreSpecViewer.py
This setup includes all required resources, including the spectral library database.
For quick testing or running the viewer in a clean environment:
pip install git+https://github.com/Russjas/CoreSpecViewer.git
corespecviewer
Important: The spectral library database is not shipped with the pip package.
- Only the application code is included.
- The LibraryPage will display a warning on launch (missing DB).
- All core processing and visualisation tools still function:
- opening raw and processed datasets
- masking, cropping, processing
- visualisation workflows
- hole and box navigation
If you want full spectral-library functionality:
- Download the database from the GitHub repository (resources directory).
- Place it anywhere on your system.
- Use the OpenDB button on the Library page.
Clone + Conda (recommended): includes DB, best for full workflow and development.
pip install: no DB included, best for quick testing and clean environments.
You will see:
- A Ribbon (Raw / Masking / Visualise / Hole)
- A Tab widget (Raw / Visualise / Libraries / Hole)
- Shared app state through a
CurrentContextinstance
- Load Specim Lumo raw directories
- Automatic discovery of
.hdr,.raw, white/dark references - Raw RGB preview
- Reflectance correction
- Auto‑crop tools
- Save processed cubes (
.npy + .json) and thumbnails
- Display RGB, indices, masks
- Popout spectral plots, both reflectance and continuum-removed
- Feature maps (position, depth, width, asymmetry…)
- Correlation maps & winner‑takes‑all mineral mapping
- Temporary vs committed product workflows
- Safe tool‑dispatcher preventing event conflicts
- Supports overlays, legends, scaling, and mask fusion
- SQLite‑backed spectral library viewer
- Ships with an ECOSTRESS mineral subset
Reference:
Meerdink, S. K., Hook, S. J., Roberts, D. A., & Abbott, E. A. (2019).
The ECOSTRESS spectral library version 1.0.
Remote Sensing of Environment, 230, 111196.
https://doi.org/10.1016/j.rse.2019.05.015 - View wavelength curves
- Build exemplar collections
- Push exemplars directly into mapping routines
A major feature enabling hole‑level interpretation.
- Load a directory of processed boxes
- Thumbnail table of all boxes
- Dual product thumbnails (
savgol/choice of dataset) - Clicking a box updates
CurrentContext.po - Integrates cleanly with Raw/Visualise pages
- Metadata panel for hole details
- Open Scan
- Auto‑crop
- Process to reflectance
- Refresh thumbnails
- Mask by correlation with selected pixel
- Polygon mask/rectangle mask
- Unwrap tool
- Mask refinement
- Reset mask
- Feature maps
Reference:
Thiele, S. T., Lorenz, S., Kirsch, M., Acosta, I., Tusa, L., Hermann, E., Möckel, R., & Gloaguen, R. (2021).
Multi-scale, multi-sensor data integration for automated 3-D geological mapping.
Ore Geology Reviews, 136, 104252.
https://doi.org/10.1016/j.oregeorev.2021.104252 - Correlation / WTA mineral mapping
- Spectral plotting
- Show/hide legends
- Export maps
- Next Box
- Return to Raw view
- Commit temporary maps
- Save updated products
- Process Raw Multibox
- Automatically finds Lumo‑style directories
- Processes all into a target folder
- Logs success/errors to
processing_log.csv
-
Represents a single Lumo raw scan directory
-
Reads ENVI headers, metadata, white/dark references using a Spectral Python (SPy) backbone.
-
Converts to
ProcessedObject
- Represents a processed reflectance cube
- Uses memory‑mapped
.npydatasets - Stores:
- RGB thumbnails
- Mask
- Derived products
- Temporary vs committed maps
- Processing logs
- A directory of many processed boxes
- Provides navigation, thumbnails, and hole metadata
- The state container used across all pages
- Holds:
.ro— RawObject.po— ProcessedObject.ho— HoleObject.active— which object is currently primary
The modular design allows you to:
- Add custom loaders to integrate other data acquisition sources into the data model
- Add new spectral indices or feature extractors
- Add new map types to the Visualise page
- Extend HolePage with depth profiles or QC tools
- Build new Ribbon tools following the existing patterns
- Add new dataset types using the
Datasetabstraction
Free hyperspectral core scanning data can be downloaded from a number of sources, including:
Geological Survey Ireland
Alberta Energy Regulator
This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
Because it depends on PyQt5, redistribution and derivative works must also comply with GPL v3 terms.
Developed by Russell Rogers
If this has been useful in your research please cite as
Rogers, R. (2025). CoreSpecViewer: An Open-Source Hyperspectral Drill-Core Visualisation and Interpretation Tool (Version 1.1.0) [Computer software]. https://doi.org/10.5281/zenodo.17711871
CoreSpecViewer is an open-source research tool for hyperspectral drill-core visualisation and interpretation. It is not certified as a commercial mineralogical analysis product.
Outputs may include uncertainties and should be interpreted within the broader context of geological knowledge and dataset characteristics.
CoreSpecViewer is provided as is, without warranty, and the authors and contributors are not liable for any use of the software or results obtained from it.