cme-recon-tool 0.1.0

Interactive two-view CME reconstruction tool with WCS-aware solar image loading.

CME Reconstruction Tool

Semi-automatic two-view solar image reconstruction for JP2/FITS images.

This app supports interactive stereoscopic reconstruction of identifiable solar image features from two calibrated viewpoints. The target can be a CME front, loop, ray, jet, or any other structure that can reasonably be matched between views; the inputs just need supported JP2/FITS image data with WCS and observer metadata sufficient to define the viewing geometry. The result should be interpreted with the usual limits of two-view 3D reconstruction: paired picks are assumed to trace the same physical feature at nearly the same time, which can break down for evolving structures, line-of-sight integration, occultation, cadence or wavelength differences, and ambiguous morphology. When that correspondence is defensible, the app provides paired picking, trace matching, 3D point inspection, and layered same-vantage image context.

Features

• Load JP2/FITS solar images from server paths or local uploads, independent of instrument when the image headers provide the required geometry.
• Stack multiple image layers per field, with per-layer visibility, opacity, colormap, linear/log scaling, and percentile levels.
• Use WCS-aware 2D image panels for manual paired picks or semi-automatic trace matching.
• View textured plane-of-sky image layers, observer lines of sight, and accepted 3D points in a Three.js scene.
• Lasso candidate matches or accepted points for bulk selection and cleanup.
• Export and restore JSON state, including image paths, layer display settings, and accepted points.
• Export accepted points as CSV.

Installation

The Python backend dependencies are declared in pyproject.toml. The browser UI dependencies are declared separately in frontend/package.json.

Required tools:

• Python 3.10, 3.11, or 3.12
• Node.js with npm
• OpenJPEG for JP2 support if glymur cannot find it on your system

Install the backend from the repo root:

cd /path/to/cme_recon_tool
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"

On macOS, if JP2 loading fails with an OpenJPEG/glymur error, install OpenJPEG once:

brew install openjpeg

Install the frontend:

cd /path/to/cme_recon_tool/frontend
npm install

Launch

From the repo root, start the backend:

cd /path/to/cme_recon_tool
source .venv/bin/activate
CME_RECON_DATA_ROOTS="/path/to/solar/images" python -m uvicorn cme_recon_tool.backend.app:app --reload --host 127.0.0.1 --port 8000

In another terminal, start the frontend:

cd /path/to/cme_recon_tool/frontend
npm install
npm run dev -- --host 127.0.0.1 --port 5173

Open http://127.0.0.1:5173.

The backend and frontend must use different ports. Use port 8000 for FastAPI and port 5173 for Vite.

Convenience scripts are also available from the repo root:

# terminal 1
CME_RECON_DATA_ROOTS="/path/to/solar/images" ./run_backend.sh

# terminal 2
./run_frontend.sh

Sample Inputs

Example server paths might look like:

/path/to/solar/images/viewpoint_a_feature.jp2
/path/to/solar/images/viewpoint_b_feature.fts

The server-side file picker is restricted to the app's data/ directory and paths listed in CME_RECON_DATA_ROOTS.

Workflow

1. Load two images from server paths or upload two JP2/FITS files.
2. Use the default Manual mode for paired source/target clicks, or switch to Trace to draw a source feature and review candidate matches.
3. Accept good points or use lasso selection to filter candidates/accepted points.
4. Inspect the accepted 3D points in the Three.js scene.
5. Export JSON or CSV.