Advanced Hyperspectral Imaging Analysis Tool
- Overview
- Features
- Quick Start
- Screenshots
- Documentation
- Requirements
- Typical Workflow
- Project Structure
- Running Tests
- Contributing
- License
Map_Spec is a desktop application for visualizing and analyzing hyperspectral data stored in Zarr format. Designed for researchers working with spectroscopy, photoluminescence (PL), reflection, and absorption measurements.
Perfect for:
- Analyzing spatially-resolved spectroscopic data
- Interactive region-of-interest (ROI) selection
- Background correction and contrast analysis
- Exporting selected regions to CSV for further processing
- Real-time rendering with progressive loading for large datasets
- Voltage-based coordinates with automatic pixel-to-voltage mapping
- Customizable colormaps (Viridis, Hot, Cool, Grayscale)
- Background correction mode with diverging colormap for contrast analysis
- Click-to-view spectra at any pixel location
- Wavelength filtering with interactive drag handles
- Multiple display modes: Raw spectrum, Background spectrum, Contrast spectrum (Signal/Background - 1)
- Smooth zooming and panning with QCustomPlot integration
- Drawing tools: Line, Rectangle, Polygon
- Multi-shape selection with visual feedback
- Pixel counting and selection statistics
- CSV export with coordinates, voltages, and intensities
- Chunk-based loading using Blosc compression
- Intelligent caching for frequently accessed data
- Multi-threaded workers for non-blocking UI
- Memory efficient handling of large 3D arrays
# Clone the repository
git clone https://github.com/AbdulRahman2257/Map_Spec.git
cd Map_Spec
# Run the automated build script
build.batThe script will:
- Auto-detect Qt and vcpkg installations
- Configure CMake with correct paths
- Build the project in Release mode
- Deploy Qt dependencies
- Create a desktop shortcut
Then simply double-click the desktop shortcut or run:
run.bat# Install dependencies (Ubuntu/Debian example)
sudo apt install qt6-base-dev libblosc-dev cmake
# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
# Run
./Map_SpecFor detailed platform-specific instructions, see docs/BUILDING.md
Interactive heatmap with real-time spectrum display
Wavelength filtering with draggable region selector
Polygon tool for selecting custom regions
- User Guide - Complete walkthrough from loading data to exporting results
- Troubleshooting - Common issues and solutions
- Developer Guide - Architecture, code structure, and contributing
- Building from Source - Platform-specific build instructions
- Testing Guide - Running and writing tests
- Zarr Format Specification - Expected data structure and compression
- OS: Windows 10/11, Linux (Ubuntu 20.04+)
- RAM: 4 GB minimum (8 GB recommended for large datasets)
- Qt 6.5+ (Widgets, PrintSupport modules)
- CMake 3.19+
- C++17 compatible compiler (MSVC 2019+, GCC 9+, Clang 10+)
- Blosc (compression library)
- vcpkg (recommended for Windows dependency management)
See docs/BUILDING.md for detailed installation instructions.
- Load Zarr File - Open a
.zarrdirectory containing your hyperspectral data - Explore Heatmap - Click pixels to view spectra, zoom/pan to navigate
- Apply Wavelength Filter - Drag region handles to focus on specific wavelengths
- Select Background - Click a pixel, press
Ctrl+Bto set as background - Switch to Contrast Mode - View Signal/Background ratio heatmap
- Draw ROI - Use polygon/rectangle tools to select regions
- Export Data - Save selected pixels to CSV for rescanning or analysis
Map_Spec/
+-- src/
| +-- core/ # Data management (ZarrManager, HeatmapLoadWorker)
| +-- ui/ # UI widgets (HeatmapWidget, SpectrumWidget)
+-- include/
| +-- Map_Spec/ # Public headers
+-- tests/
| +-- core/ # Unit tests (Qt Test framework)
| +-- ui/ # UI tests (future)
+-- external/
| +-- qcustomplot/ # Third-party plotting library (GPL v3)
+-- docs/ # Documentation
+-- build.bat # Automated Windows build script
+-- build_and_test.ps1 # PowerShell test runner
+-- CMakeLists.txt # CMake configuration
.\build_and_test.ps1mkdir build && cd build
cmake .. -DBUILD_TESTING=ON
cmake --build .
ctest --output-on-failureTest Coverage:
- ZarrMetadata structure validation
- ZarrChunkReader (Blosc decompression, binary conversion)
- ZarrManager (file loading, data access, caching)
- HeatmapLoadWorker (progressive loading, background correction)
will add tests for UI components in future releases.
We welcome contributions! Whether it's bug reports and fixes, new features (additional colormaps, export formats), documentation improvements, or more test coverage.
Please see docs/DEVELOPER_GUIDE.md for:
- Code architecture overview
- Coding standards
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- QCustomPlot (GPL v3) - Plotting library by Emanuel Eichhammer
- Blosc (BSD 3-Clause) - Compression library
- Qt 6 (LGPL v3) - Application framework
Full attribution in THIRD_PARTY_NOTICES.txt
- QCustomPlot - For the excellent plotting library
- Zarr community - For the flexible array storage format
- Qt Project - For the robust cross-platform framework
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: [email protected]
Made with care for the scientific community