SPINDLE

Spectral Information Distillation for Lightweight Exploration

Overview

Imaging spectroscopy data is generally very large due to the measurement of tens or hundreds of wavelengths (colors).

This code supports science-driven summarization of imaging spectroscopy (or "hyperspectral") data. Its goals are to:

1. Achieve 100-1000x lossy image compression
2. Enable rapid visualization for tactical decision making

Note: This repository is actively being developed, so not all functionality will interact seamlessly.

Commmon Processing Flow

SPINDLE has capabilities to support summarizing data onboard, visualizing/rehydrating after transmission, and visualization.

Config

The configuration file (config.yaml) defines key parameters for the entire workflow, including which wavelength ranges to process, the bit budget allocated to each spectral region, and settings for data download and compression. It should be populated with input from end-users of the summarized data (i.e., the science team).

Construct L2-Onboard Data

This step converts raw radiance measurements (L1B) to reflectance values (L2-Onboard) by correcting for solar illumination angle, Sun-Earth distance, and the solar spectrum. Note that for M3 data, is a simplified version of the full processing chain (e.g., does not include topography, thermal corrections, ground truth correction, etc.)

# Image used in Pieters et al., 2011: https://doi.org/10.1029/2010JE003727

python ~/Builds/spindle/spindle/data/m3_proc_L1B_to_L2.py \
--l1b_fpath ~/Data/spindle/M3/CH1M3_0003/20081118_20090214/200901/L1B/M3G20090125T172601_V03_RDN.IMG \
--solar_irr_fpath ~/Data/spindle/M3/CH1M3_0004/CALIB/M3G20110224_RFL_SOLAR_SPEC.TAB.txt \
--obs_fpath ~/Data/spindle/M3/CH1M3_0003/20081118_20090214/200901/L1B/M3G20090125T172601_V03_OBS.IMG \
--config_fpath ~/Builds/spindle/spindle/config.yaml \
--output_image_fpath ~/Data/spindle/M3/CH1M3_0003/20081118_20090214/200901/L2O/M3G20090125T172601_V03_RDN

Summarize L2O Image with PQ Quantization (from the FAISS Repository)

This step performs lossy compression using Product Quantization (PQ), which clusters similar pixel spectra together and represents each cluster with a single centroid value. This compresses data by reducing full hyperspectral images to a small set of integer "codes" and a compact "codebook" using FAISS. After compression, it saves out the index, codebooks, and quantized images.

INPUT_DIR=/Users/wronk/Data/spindle/M3/CH1M3_0003/20081118_20090214/200901
IMAGE_NAME=M3G20090125T172601_V03
QUANTIZER_TYPE=PQ
SUMMARIZED_DIR=${INPUT_DIR}/${QUANTIZER_TYPE}/${IMAGE_NAME}_${QUANTIZER_TYPE}

python ~/Builds/spindle/spindle/quant/quantize_image_pq.py \
--input_hdr_img ${INPUT_DIR}/L2O/${IMAGE_NAME}_RDN.img \
--config_fpath ~/Builds/spindle/spindle/config.yaml \
--index_dir ${SUMMARIZED_DIR} \
--viz_codes_dir ${SUMMARIZED_DIR} \
--low_value_threshold 1e-2 \
--m_subq 1 \
--random_state 0 \
--log_level INFO

Generate Image (PNG) for Basic Exploratory Analysis

This step creates a quick-look RGB composite image by combining three grayscale visualizations (each representing a different wavelength range) into a single color image.

python ~/Builds/spindle/spindle/viz/generate_composite_image.py \
--r ${SUMMARIZED_DIR}/wavelengths_750_1100_viz.png \
--g ${SUMMARIZED_DIR}/wavelengths_1100_1400_viz.png \
--b ${SUMMARIZED_DIR}/wavelengths_1400_2000_viz.png \
--out-rgb-png ${SUMMARIZED_DIR}/composite_output.png \
--log-level INFO

Rehydrate Data (as HDR) for Detailed Visualization in Existing Tools

This step reconstructs the a representative hyperspectral image from the compressed codes and codebook by mapping each integer code back to its corresponding centroid spectrum. The output is saved in ENVI HDR format, which can be loaded into standard hyperspectral analysis tools (e.g., WISER) for more detailed investigation.

python ~/Builds/spindle/spindle/viz/rehydrate_summarized_data.py \
--input_pattern "${SUMMARIZED_DIR}/wavelengths_*_*_analysis.tiff" \
--output_path "${SUMMARIZED_DIR}/rehydrated.img" \
--reference_hdr "${INPUT_DIR}/L2O/M3G20090125T172601_V03_RDN.img" \
--log_level INFO

M3 Data

Bulk Download from PDS

1. Get CSV of all desired products from PDS Beta website: https://pds-imaging.jpl.nasa.gov/beta/search
2. Download CSV with names, URIs, etc.
3. Use download script pds_pull_data.py like:

python ~/Builds/spindle/spindle/data/pds_pull_data.py \
--config_path ~/Builds/spindle/spindle/config.yaml \
--max_retries 5 \
--error_log_path ~/Builds/spindle/experiments/pds_download_errors.log

Solar Irradiance Files on PDS

Global: CH1M3_0004/CALIB/M3G20110224_RFL_SOLAR_SPEC.TAB.txt Target: CH1M3_0004/CALIB/M3T20110224_RFL_SOLAR_SPEC.TAB.txt