Metadata-Version: 2.4
Name: cme-recon-tool
Version: 0.1.0
Summary: Interactive two-view CME reconstruction tool with WCS-aware solar image loading.
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: astropy<7,>=6.0
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: glymur<1,>=0.13
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pillow<12,>=10
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-multipart<1,>=0.0.9
Requires-Dist: scikit-image<1,>=0.22
Requires-Dist: scipy<2,>=1.11
Requires-Dist: sunpy[map]<7,>=6.0
Requires-Dist: uvicorn[standard]<1,>=0.30
Provides-Extra: test
Requires-Dist: httpx<1,>=0.27; extra == "test"
Provides-Extra: publish
Requires-Dist: build<2,>=1.2; extra == "publish"
Requires-Dist: twine<7,>=5; extra == "publish"

# CME Reconstruction Tool

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

![CME Reconstruction Tool interface](docs/app-screenshot.png)

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:

```bash
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:

```bash
brew install openjpeg
```

Install the frontend:

```bash
cd /path/to/cme_recon_tool/frontend
npm install
```

## Launch

From the repo root, start the backend:

```bash
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:

```bash
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:

```bash
# 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:

```text
/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.
