HiRISE Data Explorer

This repository provides Python tools for filtering, retrieving, and mapping images captured by the High Resolution Imaging Science Experiment (HiRISE) camera onboard the Mars Reconnaissance Orbiter (MRO). Designed for planetary scientists, researchers, and enthusiasts, this toolkit streamlines the process of exploring multi-year image data and identifying areas of interest on the Martian surface.

🔑 Key Features

1. Custom Filters and Image Retrieval
   Effortlessly filter and retrieve large sets of HiRISE images based on user-defined criteria. These custom filters allow you to refine queries by location, date, viewing geometry, and more.

2. DBSCAN Clustering for Imaging Hotspots
   Identify multi-year imaging hotspots using Density-Based Spatial Clustering of Applications with Noise (DBSCAN). By grouping overlapping or closely spaced images, you can reveal areas of Mars with repeated HiRISE coverage.

3. Branch and Bound Stack Selection
   Leverage the geometric capabilities of Shapely and computational efficiency of the "Branch and Bound" algorithm to handle overlapping images. Automatically choose the best stacks from intersecting footprints and easily incorporate them into your data analysis or map displays.

4. Visualization with PyGMT and QGIS
   Explore and share your results via robust visualization tools. Plot clustered hotspots with PyGMT or import your data into QGIS for advanced cartographic work and interactive spatial analysis.

🚀 Getting Started

1. Clone the repository:

   git clone https://github.com/ZipZaap/DataExplorer.git

2. Create a virtual envirnement & install the required dependencies

   conda env create -f requirements.yml

📂 Repository Structure

├───configs/
│   ├──config.yaml ---------------------- # File with default parameters
│   ├──config_parser.py ----------------- # Defines Config() class which stores the defaults
│   └──validators.py -------------------- # Defines validation logic and logging behavior
|
├───Core/
│   ├──mars_index.py -------------------- # Image filtering tools
│   ├──mars_plotter.py ------------------ # Tools for visualiztion in QGIS/PyGMT
│   └──util.py--------------------------- # Misc utility functions
|
├───results/
|   ├───csv/ ---------------------------- # Storage for filtered dataframes
│   ├───geojson/ ------------------------ # Storage for QGIS .geojson files
│   ├───maps/ --------------------------- # Storage PyGMT .png visualizations
|   ├───index/ -------------------------- # Storage for PDS .TAB & .LBL files
|   ├───rdr/ ---------------------------- # Storage for downloaded .JP2 files
│   └───preview/ ------------------------ # Storage ofr preview .thumb.jpg files
|
├───main.ipynb -------------------------- # Jupyter Notebook with examples
├───requirements.yml -------------------- # Core dependencies
└───README.md

Note

Folders for storing QGIS/PyGMT visualizations and PDS index files (that contain the image metadata) are created and populated automatically, unless an exisiting storage path is specified in configs.yaml.

🛠️ Basic Usage

1. As module import

   from Core.mars_index import ImageIndex
   
   # initialize the class instance
   index = ImageIndex()
   
   # perfrom latitude filtering without commiting the changes
   index.latitude_filter(commit=False)
   
   # visualize image footprints with PyGMT and image centroids with QGIS
   index.show_on_map(engine='pygmt', target='img_footprint', title='latitude_flt')
   index.show_on_map(engine='qgis', target='img_centroid', title='latitude_flt')
   
   # filter again, this time using custom LAT and saving the changes
   index.latitude_filter(min_lat=80);
   
   # apply the rest of the filters with their default parameters; suppress the output
   index.scale_filter();
   index.season_filter();
   index.density_filter();
   index.temporal_filter();
   
   # Map the remaining clusters with PyGMT
   index.show_on_map('cluster', color='greenyellow')
   
   # Choose a cluster to preview
   index.show_preview(cluster_id=3)
   
   # (Optionally) Choose an image to exlcude based on preview and
   # download the .JP2 products from the HiRISE archive
   exclude='ESP_123456_7890_RED'
   index.download_images(cluster_id=3, exclude=exclude, allign=True, reload=False)

2. As standalone script

   python filter.py

Tip

You can define a custom filter sequence, set defaults or adjust the PyGMT visualization by editing config.yaml.

⚙️ Available filters

Filter	Description
latitude_filter	Performs location-based filtering by retaining images acquired above a given latitude.
scale_filter	Performs resolution-based filtering by retaining images acquired with a given map scale.
season_filter	Performs seasonal filtering by retaining images captured at solar longitudes corresponding to the specified season.
density_filter	Performs density-based filtering by retaining only those images that have other images in their immediate proximity. The clustering is performed on map-projected image centroids. The resulting grouping represents the imaging hotspots.
keyword_filter	Performs semantic filtering, based on the rationale description associated with HiRISE products. This operation is performed at the cluster level, i.e. if any image within a cluster contains a user-defined keyword in its description, the entire cluster is retained.
temporal_filter	Performs temporal filtering by only retaining clusters that either contain a specified number of (optionally consecuitive) unique mars years, or include a user-defined mars year sequence. This step helps to isolate locations with multi-year image coverage.

Tip

For detailed descriptions of method parameters, available parameter values, and their corresponding types, refer to the docstrings provided in mars_index.py.

🛰️ Example use-case

In this example use-case we're looking to investigate the seasonal ice dynamics of the North Polar Layered Deposits (NPLD). For these purposes we need to isolate the HiRISE images of NPLD scraps, specifically focusing on locations that have continuos multi-year coverage. We use the following set of parameters:

{
 'latitude_filter': {'min_lat': 78},
 'scale_filter': {'scale': 0.25},
 'season_filter': {'season': 'Northern summer'},
 'density_filter': {'min_samples': 2, 'epsilon': 2000},
 'keyword_filter': {'keywords': ['scarp']},
 'temporal_filter': {'min_years': 5, 'max_gap': 0, mys': []},
}

Clustering up-close

DBSCAN clustering visualized as image centroids (left) and image footprints (right). Each color represents a separate cluster, with outliers labelled in gray. Segment co-ordinates : (225° < LAT < 240°, 83.5° < LON < 84.5°).

Note

This approach works well for the HiRISE dataset since the images are not randomly distributed but are instead concentrated around locations of scientific interest identified by the HiRISE team, making them inherently well suited to unsupervised clustering.

Demo workflow

The filters can be divided by type into two categories: those that operate on separate images and those that operate on clusters. In the example workflow below the cyan rectangles represent the footprints of individual images, and the purple circles - the cluster centroids:

Type	[1] Latitude filter	[2] Season filter	[3] Scale filter
IMAGE
	[4] Density filter	[5] Keyword filter	[6] Temporal filter
CLUSTER

Tip

Click on images to get a better look

Preview tool

The HiRISE archive's lightweight .jpg thumbnails are great for inital quality control, allowing us to efficiently visuzalise and discard unsuitable data without the costly overhead of downloading massive .JP2 files. In the example below the user might choose to completely ignore the Mars Years 36 & 37 due to incomplete acqusition.

🌎 QGIS

Alternatively, the user can opt for a more interactive approach by visualizing the image footprints in QGIS. To support this, we also provide a stereographic map of the Martian North Pole that can serve as a base layer.

📝 License

Distributed under the MIT License. See LICENSE for more information.

✉️ Contact

Martynchuk Oleksii - martyn.chuckie@gmail.com

🤝 Acknowledgements

This project was made possible thanks to the support and resources provided by:

• Technische Universität Berlin (TU Berlin)
• German Aerospace Center (DLR) Berlin
• HiRISE (High Resolution Imaging Science Experiment) team at the University of Arizona
• HEIBRIDS School for Data Science

Additional thanks to the open‑source community and all contributors who help improve this project.