Deformation Narrator 🛰️

Turn an InSAR displacement time-series into a paragraph a non-specialist can read.

deformation-narrator is a small library that wraps an InSAR analyst's intuition around a multimodal LLM. You give it a stack of co-registered interferograms (or a velocity map), it gives you back something like:

"Subsidence accelerated between Jan and Mar 2024, peaking near the eastern edge of the basin at ~14 mm/yr LoS. The signal correlates with groundwater pumping season; no coseismic step is visible."

It is not a replacement for proper InSAR analysis. It is a way to surface candidate findings, draft figure captions, and triage long time-series before a human looks closer.

Pipeline

   stack of ifgs            features              VLM
   ┌──────────────┐    ┌──────────────────┐   ┌─────────┐    natural-language
   │ N x H x W    │ ─▶ │ velocity, accel, │ ─▶│ adapter │ ─▶ report (and JSON
   │ unwrapped    │    │ coherence, masks │   │  + LLM  │    structured fields)
   └──────────────┘    └──────────────────┘   └─────────┘

The "features" stage is classical InSAR — velocity fitting, acceleration test, APS/orbital removal. The VLM stage is prompt-driven and pluggable.

Install

pip install deformation-narrator

For development:

git clone https://github.com/EchoFish/deformation-narrator.git
cd deformation-narrator
pip install -e ".[dev]"

Usage

import numpy as np
from defnar import Stack, Narrator

stack = Stack.from_directory("/data/ifg_stack/")
narrator = Narrator(model="gpt-4o-mini")
report = narrator.describe(stack)
print(report.text)
print(report.fields)   # {"max_velocity_mm_yr": -13.8, "regime": "subsidence", ...}

You can also point at a single velocity raster:

from defnar import describe_velocity_map

text = describe_velocity_map("velocity.tif", reference_point=(34.05, -118.25))

What works, what doesn't

• ✅ Subsidence / uplift narration when the signal is reasonably clean
• ✅ Catching obvious atmospheric artefacts before they become "deformation"
• ✅ Drafting figure captions
• ⚠️ Coseismic events — works but the model loves to hallucinate magnitudes; structured outputs are more trustworthy than free text here
• ❌ Slow creep / sub-mm signal — VLMs cannot reliably see this from a colormap

License

Apache-2.0. See LICENSE.