Tutorials

This section provides hands-on tutorials for working with hyperspectral imaging data from Mars. The tutorials are presented as interactive Jupyter notebooks that you can download and run locally.

Getting the Notebooks

The tutorial notebooks are in the notebooks/ directory of the repository. You can:

  1. Run them locally after cloning the repository:

    git clone https://github.com/thesfinox/mars-reconnaissance-orbiter.git
cd mars-reconnaissance-orbiter/notebooks
jupyter notebook  # or jupyter lab

  2. Download individual notebooks from the GitHub repository

  3. Read them below in the documentation (rendered from the actual notebooks)

Prerequisites

Before working through the tutorials, ensure you have:

  • Installed the HSI Mars package (see Installation Guide)

  • Basic knowledge of Python programming

  • Familiarity with NumPy and matplotlib

  • Understanding of basic machine learning concepts (helpful but not required)

Tutorial Notebooks

The following Jupyter notebooks provide step-by-step tutorials with executable code, visualisations, and detailed explanations.

1. Exploratory Data Analysis

Target Audience: Students in introductory machine learning courses

What you’ll learn:

  • Understanding hyperspectral imaging and the CRISM instrument on Mars

  • Loading and inspecting multidimensional data structures

  • Visualising spectral signatures and false-colour images

  • Analysing ground truth annotations for supervised learning

  • Statistical analysis and data quality assessment

  • Preprocessing considerations for machine learning

  • Feature engineering in high-dimensional spaces

  • The curse of dimensionality and how to address it

Learning Outcomes:

After completing this tutorial, you will be able to:

  • Load and work with hyperspectral data using the HSI Mars package

  • Create publication-quality visualisations of spectral data

  • Understand spectral signatures and their role in material identification

  • Prepare hyperspectral data for machine learning

  • Assess data quality and identify potential issues

  • Understand the challenges of high-dimensional remote sensing data

2. Basic Usage Examples

Target Audience: All users (beginners to advanced)

What you’ll learn:

  • Quick examples of basic package functionality

  • Loading hyperspectral images and accessing metadata

  • Creating visualisations and false-colour composites

  • Plotting spectral signatures

  • Working with ground truth annotations

  • Essential HSIMars class methods

Use this notebook for:

  • Quick reference of common operations

  • Testing your installation

  • Learning the basic API

  • Code snippets you can copy and adapt

Dataset Information

The tutorials use data from the Mars Reconnaissance Orbiter’s CRISM instrument. The dataset was published by:

Xi et al., “A Large-Scale Benchmark Dataset for Martian Surface Material Classification,” IEEE Geoscience and Remote Sensing Letters, 2025.

The dataset includes:

  • Hyperspectral images in ENVI format (.hdr and .img files)

  • Ground truth annotations for supervised learning (.mat files)

  • Multiple Mars surface sites with different geological features

Troubleshooting

ModuleNotFoundError

Ensure the package is installed:

uv sync  # if using uv
# or
pip install -e .  # if using pip
OpenCV Window Issues

The display() methods open OpenCV windows. On remote servers:

  • Set up X11 forwarding

  • Comment out display() calls

  • Use only matplotlib plotting methods

Memory Issues

Hyperspectral data can be large (400+ MB). If you run out of memory:

  • Close other applications

  • Work with a subset of the data

  • Use a machine with more RAM (8GB+ recommended)

Path Issues

Verify data files are in the correct location:

mars-reconnaissance-orbiter/
├── data/
│   ├── HC_frt0000580c_07_if164j_ter3.hdr
│   ├── HC_frt0000580c_07_if164j_ter3.img
│   └── HC_ground_truth.mat
└── notebooks/
    ├── exploratory_data_analysis.ipynb
    └── hsimars.ipynb