From acc1313f64c0b620f7310d6012afb4c50eac1cec Mon Sep 17 00:00:00 2001
From: James Le Houx <37665786+jameslehoux@users.noreply.github.com>
Date: Tue, 17 Nov 2026 21:55:54 +0000
Subject: [PATCH] feat(v0.3.0): multi-scan gap closing, lazy HDF5 streaming, 4D
HTML explorer, ImageD11/NeXus exports, and DINOv2 benchmarks
---
CHANGELOG.md | 14 +
CITATION.cff | 15 +-
CONTRIBUTING.md | 10 +-
README.md | 93 ++-
braggtrack/__init__.py | 4 +-
braggtrack/cli/detect_events.py | 131 ++--
braggtrack/cli/embed_dataset.py | 56 +-
braggtrack/cli/report_dataset.py | 140 ++++
braggtrack/cli/run_pipeline.py | 108 ++-
braggtrack/cli/segment_dataset.py | 18 +-
braggtrack/cli/track_dataset.py | 64 +-
braggtrack/io/__init__.py | 32 +-
braggtrack/io/crystallography.py | 146 ++++
braggtrack/io/export.py | 256 +++++++
braggtrack/io/lazy.py | 144 ++++
braggtrack/segmentation/dino_segment.py | 39 +-
braggtrack/semantic/dino.py | 3 +
braggtrack/semantic/mips.py | 6 +-
braggtrack/tracking/__init__.py | 4 +
braggtrack/tracking/gap_closing.py | 275 +++++++
braggtrack/tracking/lifecycle.py | 15 +-
braggtrack/tracking/metrics.py | 14 +-
braggtrack/viz/__init__.py | 17 +
braggtrack/viz/_style.py | 45 ++
braggtrack/viz/html_report.py | 696 ++++++++++++++++++
braggtrack/viz/kinematics.py | 103 +++
braggtrack/viz/lineage.py | 216 ++++++
braggtrack/viz/mips.py | 104 +++
braggtrack/viz/precursors.py | 149 ++++
docs/architecture.md | 54 +-
docs/benchmarks.md | 115 +++
docs/figures/benchmark_comparison.png | Bin 0 -> 182861 bytes
.../fracture_lineage_and_precursors.png | Bin 0 -> 358773 bytes
notebooks/braggtrack_demo.ipynb | 14 +-
paper.bib | 16 +-
paper.md | 124 ++--
pyproject.toml | 3 +-
scripts/benchmark_suite.py | 477 ++++++++++++
scripts/check_report_and_export_acceptance.py | 223 ++++++
scripts/ci_report.py | 8 +-
scripts/generate_paper_figures.py | 261 +++++++
tests/test_benchmark_suite.py | 69 ++
tests/test_gap_closing.py | 151 ++++
tests/test_lazy_and_export.py | 199 +++++
tests/test_report_and_export_acceptance.py | 26 +
tests/test_segmentation_dino.py | 24 +
tests/test_viz_and_report.py | 134 ++++
47 files changed, 4551 insertions(+), 264 deletions(-)
create mode 100644 braggtrack/cli/report_dataset.py
create mode 100644 braggtrack/io/crystallography.py
create mode 100644 braggtrack/io/export.py
create mode 100644 braggtrack/io/lazy.py
create mode 100644 braggtrack/tracking/gap_closing.py
create mode 100644 braggtrack/viz/__init__.py
create mode 100644 braggtrack/viz/_style.py
create mode 100644 braggtrack/viz/html_report.py
create mode 100644 braggtrack/viz/kinematics.py
create mode 100644 braggtrack/viz/lineage.py
create mode 100644 braggtrack/viz/mips.py
create mode 100644 braggtrack/viz/precursors.py
create mode 100644 docs/benchmarks.md
create mode 100644 docs/figures/benchmark_comparison.png
create mode 100644 docs/figures/fracture_lineage_and_precursors.png
create mode 100644 scripts/benchmark_suite.py
create mode 100644 scripts/check_report_and_export_acceptance.py
create mode 100644 scripts/generate_paper_figures.py
create mode 100644 tests/test_benchmark_suite.py
create mode 100644 tests/test_gap_closing.py
create mode 100644 tests/test_lazy_and_export.py
create mode 100644 tests/test_report_and_export_acceptance.py
create mode 100644 tests/test_viz_and_report.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6424c7..6fffb35 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to BraggTrack will be documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.3.0] - 2026-11-17
+
+### Added
+- **Multi-scan beam-dropout gap closing (`braggtrack.tracking.gap_closing`)**: Added Jaqaman-style augmented linear assignment (`GapClosingConfig`, `GapCloseRecord`, `resolve_track_gaps`) with diffusive displacement scaling (`pos_d2 / delta_scans`), bidirectional spurious jump-edge severing, semantic cosine gating, and chronological track ID propagation (`--max-gap` across `track_dataset`, `detect_events`, and `run_pipeline`).
+- **Chunked & lazy HDF5 streaming (`braggtrack.io.lazy`)**: Added context-managed `LazyVolume` (`open_lazy_volume`, `read_roi`, `iter_z_chunks`) and exact two-pass `otsu_threshold_chunked`, wired into `segment_dataset` Pass 1, `embed_dataset`, `detect_events`, and `crop_spot_cube` to avoid full-volume `float64` allocations on gigabyte-scale detector stacks.
+- **Crystallographic scattering geometry & downstream exports (`braggtrack.io.crystallography`, `braggtrack.io.export`)**: Added `DetectorGeometry` (`spot_to_scattering`, `annotate_crystallographic_columns`) converting spot centroids into `(omega_deg, two_theta_deg, eta_deg, d_spacing_angstrom, qx/qy/qz/q_mag_inv_angstrom)` via Bragg's law, plus direct `ImageD11` columnfile export/parsing (`export_imaged11_flt`, `read_imaged11_flt`) and self-describing NeXus `NXprocess` HDF5 archival export (`export_nexus_process`).
+- **Publication visualization package & interactive HTML 4D Explorer (`braggtrack.viz`, `braggtrack-report`)**: Added `plot_spot_mip_card`, `plot_scan_projection_overlay`, `plot_lineage_dag`, `plot_kinematics_dashboard`, `plot_precursor_timeline`, and `generate_html_report` (zero-CDN offline `report.html` with stdlib-encoded base64 3-view MIP thumbnails, pan/zoom SVG Lineage DAG, filter pills, and synchronized strain/precursor inspector), plus the 9th CLI entry point `braggtrack-report` and `--report` flag on `braggtrack-run`.
+- **Quantitative 5-scenario real DINOv2 benchmark suite (`scripts/benchmark_suite.py`, `docs/benchmarks.md`)**: Added multi-trial bootstrap-CI benchmark harness comparing **Geometry-Only**, **Mock-Hash**, and **Real `facebook/dinov2-small`** across crossing tilted reflections, beam-flux jitter, mosaic rocking broadening, staggered beam dropouts (`max_gap=2`), and 4D chemomechanical fracture/precursor contrast, alongside publication figures (`docs/figures/`) and an ESRF-ID03 `facebook/dinov2-small` case study.
+- **9th CI acceptance gate (`scripts/check_report_and_export_acceptance.py`)**: Wired automated verification of `--max-gap`, `report.html` + static figures, `ImageD11` `.flt` round-trip parsing, and NeXus `NXprocess` HDF5 schema into `scripts/ci_report.py`.
+
+### Fixed
+- Fixed patch-grid shape mismatch and far-edge clipping in `segment_dino` when HuggingFace ViT processors resize non-multiple slices (e.g. `250x250 -> 224x224`, `16x16` tokens vs `250 // 14 = 17`), and honored `BRAGGTRACK_DINO_BACKEND` when `backend="auto"` in `braggtrack.semantic.dino`.
+- Fixed `@Finegan2017` citation key/year mismatch (`2017`, DOI `10.1039/C7EE00385D`) and added `@Jaqaman2008` in `paper.bib` and `paper.md`; synced `CITATION.cff`, `CONTRIBUTING.md`, `docs/architecture.md`, and `README.md` to `v0.3.0`.
+
## [0.2.0] - 2026-11-17
### Added
diff --git a/CITATION.cff b/CITATION.cff
index 8b445ef..8d1e56b 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -2,22 +2,25 @@ cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "BraggTrack"
type: software
-version: 0.1.0
+version: 0.3.0
date-released: "2026-05-16"
license: MIT
repository-code: "https://github.com/BASE-Laboratory/BraggTrack"
url: "https://github.com/BASE-Laboratory/BraggTrack"
abstract: >-
- Semantic 4D kinematics and fracture tracking for operando
- X-ray diffraction. BraggTrack segments Bragg reflections in
- 3D reciprocal-space volumes and tracks them across time using
- classical image processing and self-supervised vision-transformer
- embeddings.
+ Semantic 4D kinematics, multi-scan gap closing, and chemomechanical
+ fracture tracking for operando X-ray diffraction. BraggTrack segments
+ Bragg reflections in 3D reciprocal-space volumes, tracks trajectories
+ and split/merge lineage using classical crystallography and
+ vision-transformer embeddings, and exports ImageD11, NeXus HDF5, and
+ interactive HTML 4D lineage reports.
keywords:
- X-ray diffraction
- operando crystallography
- 3D segmentation
- object tracking
+ - grain fracture
+ - synchrotron
- materials science
- Python
authors:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1833647..f9b3376 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,13 +4,15 @@ Thanks for helping improve BraggTrack.
## Before you open a PR
-1. Install the package in editable mode with dev/runtime dependencies you need (`pip install -e .` plus `numpy`, `scipy`, `scikit-image`, `networkx`; add `h5py` / `torch` / `transformers` as required).
-2. Run **`python scripts/pre_pr_check.py`** (conflict markers and optional sync hint against `origin/main`).
-3. Run **`python scripts/ci_report.py`** (unit tests + Week 1–4 acceptance scripts).
+1. Install the package in editable mode with developer dependencies (`pip install -e ".[dev]"` for full PyTorch, notebook, pytest, and Ruff tooling, or `pip install -e .` for the lightweight core).
+2. Run **`ruff check braggtrack/ tests/ scripts/`** and **`ruff format --check braggtrack/ tests/ scripts/`**.
+3. Run **`python scripts/pre_pr_check.py`** (conflict markers and optional sync hint against `origin/main`).
+4. Run **`python scripts/ci_report.py`** (unit tests + all 9 acceptance gates covering IO, smoke, segmentation, tracking, embedding, DINO, events/pipeline, and interactive report + ImageD11/NeXus exports).
## Where things live
-- **[Architecture](docs/architecture.md)** — package layers, data flow, extension points.
+- **[Architecture](docs/architecture.md)** — package layers (`io`, `segmentation`, `semantic`, `tracking`, `viz`, `cli`), data flow, extension points.
+- **[Benchmarks](docs/benchmarks.md)** — 5-scenario quantitative evaluation (`scripts/benchmark_suite.py`) and ESRF-ID03 `facebook/dinov2-small` case study.
- **[Coding practices](docs/coding-practices.md)** — style, testing, optional deps, CI expectations.
- **Sample scan data** — versioned under [`data/sample_operando/`](data/sample_operando/README.md) (not the repo root).
diff --git a/README.md b/README.md
index 8f43b53..d61abd5 100644
--- a/README.md
+++ b/README.md
@@ -4,15 +4,24 @@
[](https://colab.research.google.com/github/BASE-Laboratory/BraggTrack/blob/main/notebooks/braggtrack_demo.ipynb)
-Semantic 4D kinematics, grain lineage (`1 -> 2+` fracture splits & `2+ -> 1` coalescence merges), and persistent fracture precursor tracking for operando X-ray diffraction using classical 3D crystallography and foundation vision transformers.
+Semantic 4D kinematics, multi-scan beam-dropout gap closing, grain lineage (`1 -> 2+` fracture splits & `2+ -> 1` coalescence merges), and persistent fracture precursor tracking for operando X-ray diffraction using classical 3D crystallography and foundation vision transformers.
+
+
+
+
## Key Capabilities
-- **Beamline-ready NeXus/HDF5 I/O & calibration (`braggtrack.io`)** — Auto-discovers 3D detector cubes across standard NeXus paths, ESRF-ID03 LIMA files (`/entry_0000/ESRF-ID03/pco_nf/data`), and arbitrary HDF5 trees (`auto_discover=True`), with optional physical `(mu, chi, d)` coordinate calibration via `AxisCalibration`.
-- **Stabilised 3D Bragg reflection segmentation (`braggtrack.segmentation`)** — Intensity-domain Otsu foreground masking with cross-scan rolling-median smoothing (`smooth_thresholds`), 3D LoG peak enhancement, robust `h`-maxima seeding, 3D watershed, nearby-basin merging, and physical or voxel-space covariance/eigenvalue extraction. Includes an experimental dense patch-feature + HDBSCAN slice-stitching segmenter (`--method dino`).
+- **Beamline-scale NeXus/HDF5 I/O, lazy ROI streaming & crystallographic mapping (`braggtrack.io`)** — Auto-discovers 3D detector cubes across standard NeXus paths, ESRF-ID03 LIMA files (`/entry_0000/ESRF-ID03/pco_nf/data`), and arbitrary HDF5 trees (`auto_discover=True`). Streams `z`-slabs via `LazyVolume` (`otsu_threshold_chunked`, `read_roi`), calibrates `(mu, chi, d)` via `AxisCalibration`, maps transmission geometry `(2theta, eta, d, |Q|)` via `DetectorGeometry`, and exports directly to **`ImageD11` (`.flt`)** and **NeXus `NXprocess` HDF5 (`.nxs`)**.
+- **Stabilised 3D Bragg reflection segmentation (`braggtrack.segmentation`)** — Streaming Otsu foreground masking with cross-scan rolling-median smoothing (`smooth_thresholds`), 3D LoG peak enhancement, robust `h`-maxima seeding, 3D watershed, nearby-basin merging, and physical or voxel-space covariance/eigenvalue extraction. Includes an experimental dense patch-feature + HDBSCAN slice-stitching segmenter (`--method dino`).
- **Multi-view foundation vision descriptors (`braggtrack.semantic`)** — Orthogonal $(\mu, \chi, d)$ maximum-intensity projections (MIPs) encoded with ungated **`facebook/dinov2-small`** by default (zero HuggingFace login required), drop-in support for **DINOv3** (`facebook/dinov3-vitb16-pretrain-lvd1689m`), or a deterministic zero-GPU `mock` backend for CI.
-- **4D grain kinematics, split/merge lineage & fracture precursors (`braggtrack.tracking`)** — Vectorised geometry + semantic Hungarian association into a NetworkX trajectory DAG, per-grain lattice strain ($\Delta d / d_0$) and angular misorientation ($\Delta\mu$, $\Delta\chi$), intensity-partitioned `1 -> 2+` split and `2+ -> 1` merge DAG edges, and persistent multi-scan fracture precursor ranking combining 3D shape anisotropy, covariance spread growth, and spot ROI sub-peak / DINO patch-token dispersion.
-- **One-command reproducible pipeline (`braggtrack-run`)** — Runs validation, segmentation, semantic embedding, tracking, kinematics, and fracture event analysis end-to-end, emitting SHA-256 input checksums, stage timings, and `run_manifest.json`.
+- **4D grain kinematics, multi-scan gap closing, split/merge lineage & precursors (`braggtrack.tracking`)** — Vectorised geometry + semantic Hungarian association, Jaqaman-style multi-scan gap closing (`--max-gap`) across transient beam dropouts, per-grain lattice strain ($\Delta d / d_0$) and angular misorientation ($\Delta\mu$, $\Delta\chi$), intensity-partitioned `1 -> 2+` split and `2+ -> 1` merge DAG edges, and persistent multi-scan fracture precursor ranking combining 3D shape anisotropy, covariance spread growth, and spot ROI sub-peak / DINO patch-token dispersion.
+- **Publication figures & offline interactive HTML 4D Explorer (`braggtrack.viz`, `braggtrack-report`)** — Generates Okabe–Ito styled lineage DAGs, strain/misorientation dashboards, precursor heatmaps, 3-view MIP cards, and a single-file interactive `report.html` with embedded base64 MIP thumbnails that opens offline on air-gapped beamline networks.
+- **One-command reproducible pipeline (`braggtrack-run`)** — Runs validation, segmentation, semantic embedding, tracking, kinematics, fracture event analysis, HTML reporting, and `ImageD11`/NeXus export end-to-end, emitting SHA-256 input checksums, stage timings, and `run_manifest.json`.
+
+
+
+
---
@@ -25,7 +34,7 @@ pip install -e .
# With PyTorch + HuggingFace Transformers for real DINOv2 / DINOv3 backbones
pip install -e ".[torch]"
-# With Jupyter, Matplotlib, and Pandas for interactive notebooks
+# With Jupyter, Matplotlib, and Pandas for interactive notebooks & static figures
pip install -e ".[notebook]"
# Full developer environment (torch + notebook + pytest + ruff)
@@ -38,10 +47,14 @@ pip install -e ".[dev]"
BraggTrack ships with three real ESRF ID03 operando Ni-rich cathode scans under [`data/sample_operando/`](data/sample_operando/README.md) (`100 x 250 x 250` `uint16` cubes). Omit the dataset path to run on the bundled scans automatically, or pass your own directory of `scanXXXX/` folders:
-### One-command end-to-end pipeline
+### One-command end-to-end pipeline (with interactive HTML report & NeXus/`ImageD11` exports)
```bash
-braggtrack-run --outdir artifacts/pipeline
+braggtrack-run --outdir artifacts/pipeline \
+ --max-gap 1 \
+ --report \
+ --export-nexus artifacts/pipeline/results.nxs \
+ --export-imaged11 artifacts/pipeline/peaks.flt
```
Produces:
@@ -50,26 +63,29 @@ Produces:
- `artifacts/pipeline/embedding/` (`embeddings.npz`, `embedding_manifest.json`)
- `artifacts/pipeline/tracking/` (`tracks.csv`, `kinematics.csv`, `kinematics_summary.json`, `tracking_summary.json`, QC notebook)
- `artifacts/pipeline/events/` (`events.csv`, `events.json`, `precursors.csv`, `events_summary.json`)
+- `artifacts/pipeline/report/` (`report.html` interactive 4D Explorer + `figures/*.png`)
+- `artifacts/pipeline/results.nxs` & `artifacts/pipeline/peaks.flt`
- `artifacts/pipeline/run_manifest.json` (SHA-256 input checksums, git SHA, config, stage timings)
-### Stage-by-stage CLI commands
+### Stage-by-stage CLI commands (9 Entry Points)
| CLI Entry Point | Module Equivalent | Purpose |
|---|---|---|
| `braggtrack-inspect` | `python -m braggtrack.cli.inspect_datasets` | Discover `scan*` folders, primary 3D HDF5 dataset paths, and metadata |
| `braggtrack-validate` | `python -m braggtrack.cli.validate_dataset` | Validate sequence ordering, monotonic timestamps, and axis contracts |
| `braggtrack-segment-synthetic` | `python -m braggtrack.cli.segment_synthetic` | Run fast synthetic 3D segmentation smoke test |
-| `braggtrack-segment-dataset` | `python -m braggtrack.cli.segment_dataset` | Segment 3D Bragg spots across scans with smoothed thresholds & optional calibration |
-| `braggtrack-embed-dataset` | `python -m braggtrack.cli.embed_dataset` | Compute orthogonal MIP embeddings (`auto`, `mock`, or `torch` DINOv2/DINOv3) |
-| `braggtrack-track-dataset` | `python -m braggtrack.cli.track_dataset` | Build trajectory DAG, export `tracks.csv` + `kinematics.csv` (+ optional `--detect-events`) |
-| `braggtrack-events` | `python -m braggtrack.cli.detect_events` | Resolve `1 -> 2+` splits, `2+ -> 1` merges, and ROI-based fracture precursors |
-| `braggtrack-run` | `python -m braggtrack.cli.run_pipeline` | Execute the full pipeline with optional `--config config.json` and `run_manifest.json` |
+| `braggtrack-segment-dataset` | `python -m braggtrack.cli.segment_dataset` | Segment 3D Bragg spots via chunked Otsu + smoothed thresholds & optional calibration |
+| `braggtrack-embed-dataset` | `python -m braggtrack.cli.embed_dataset` | Stream lazy 3D spot ROIs & compute orthogonal MIP embeddings (`auto`, `mock`, `torch`) |
+| `braggtrack-track-dataset` | `python -m braggtrack.cli.track_dataset` | Build trajectory DAG (`--max-gap`), export `tracks.csv`, `kinematics.csv`, `.flt`, `.nxs` |
+| `braggtrack-events` | `python -m braggtrack.cli.detect_events` | Resolve `1 -> 2+` splits, `2+ -> 1` merges, and lazy-ROI fracture precursors |
+| `braggtrack-report` | `python -m braggtrack.cli.report_dataset` | Render publication PNG/PDF figures and self-contained interactive `report.html` |
+| `braggtrack-run` | `python -m braggtrack.cli.run_pipeline` | Execute the full pipeline with optional `--config config.json`, `--report`, and exports |
---
-## Physical Axis Calibration (`mu`, `chi`, `d`)
+## Physical Axis Calibration (`mu`, `chi`, `d`) & Crystallographic Geometry (`2theta`, `eta`, `|Q|`)
-Cropped detector cubes store integer voxel indices `[0..N)`. For physically meaningful lattice strain $\varepsilon = (d(t) - d_0) / d_0$ and angular misorientation in degrees, supply an `AxisCalibration` JSON file (or CLI flags) when segmenting:
+Cropped detector cubes store integer voxel indices `[0..N)`. For physically meaningful lattice strain $\varepsilon = (d(t) - d_0) / d_0$ and angular misorientation in degrees, supply an `AxisCalibration` JSON file when segmenting:
```json
{
@@ -82,30 +98,36 @@ Cropped detector cubes store integer voxel indices `[0..N)`. For physically mean
}
```
-```bash
-braggtrack-segment-dataset data/sample_operando \
- --calibration-json calibration.json \
- --outdir artifacts/segmentation
-```
+For transmission 3DXRD / `ImageD11` indexing workflows, supply a `DetectorGeometry` JSON file (`--detector-json`) to annotate `omega_deg`, `two_theta_deg`, `eta_deg`, `d_spacing_angstrom`, and `(qx, qy, qz, q_mag_inv_angstrom)` and export `.flt` columnfiles:
-If HDF5 scans already include 1D `mu`, `chi`, `d` coordinate datasets or `/entry/calibration` attributes, `extract_axis_calibration()` detects them automatically.
+```json
+{
+ "distance_mm": 150.0,
+ "pixel_size_y_mm": 0.075,
+ "pixel_size_x_mm": 0.075,
+ "beam_center_y_px": 1024.0,
+ "beam_center_x_px": 1024.0,
+ "wavelength_angstrom": 0.2898,
+ "omega_origin_deg": 0.0,
+ "omega_step_deg": 0.05
+}
+```
---
-## Vision Backbone Options (DINOv2 Default & Optional DINOv3)
+## Vision Backbone Options & Quantitative Benchmarks
- **Default (`facebook/dinov2-small`)**: Public and ungated on HuggingFace — works out of the box with `pip install -e ".[torch]"` without tokens or license gates.
-- **DINOv3 (`facebook/dinov3-vitb16-pretrain-lvd1689m`)**: Supported via `--model` / `--dino-model` after accepting Meta's license on HuggingFace and setting `HF_TOKEN` (or running `huggingface-cli login`):
- ```bash
- braggtrack-embed-dataset --backend torch --model facebook/dinov3-vitb16-pretrain-lvd1689m
- ```
+- **DINOv3 (`facebook/dinov3-vitb16-pretrain-lvd1689m`)**: Supported via `--model` / `--dino-model` after accepting Meta's license on HuggingFace and setting `HF_TOKEN`.
- **Offline / CI (`mock`)**: Deterministic SHA-256 multi-view projection encoder requiring zero GPU or network access (`--backend mock` or `BRAGGTRACK_DINO_BACKEND=mock`).
+See [`docs/benchmarks.md`](docs/benchmarks.md) for the full 5-scenario benchmark evaluation (`scripts/benchmark_suite.py`) comparing **Geometry-Only**, **Mock-Hash**, and **Real `facebook/dinov2-small`** alongside the ESRF-ID03 case study.
+
---
## Notebooks
-- [`notebooks/braggtrack_demo.ipynb`](notebooks/braggtrack_demo.ipynb) — End-to-end tutorial on the bundled ESRF-ID03 scans: discovery, stabilised 3D segmentation, physics & semantic tracking, per-grain kinematics, α/β ablation, and synthetic 4D grain fracture + precursor ranking.
+- [`notebooks/braggtrack_demo.ipynb`](notebooks/braggtrack_demo.ipynb) — End-to-end tutorial on the bundled ESRF-ID03 scans: discovery, lazy/chunked segmentation, physics & semantic tracking, multi-scan gap closing, per-grain kinematics, `braggtrack.viz` lineage & precursor plots, and crystallographic geometry mapping.
- [`notebooks/dino_segmentation_comparison.ipynb`](notebooks/dino_segmentation_comparison.ipynb) — Side-by-side comparison of stabilised classical 3D watershed vs. experimental DINO patch-clustering segmentation.
---
@@ -120,9 +142,12 @@ ruff format --check braggtrack/ tests/ scripts/
# Unit test suite with coverage
pytest tests/ -v --cov=braggtrack
-# Full CI gate runner (unit tests + IO, smoke, segmentation, tracking, embedding, DINO, and events acceptance)
+# Full CI gate runner (unit tests + all 9 acceptance gates)
python scripts/ci_report.py
+# Quantitative 5-scenario benchmark suite (add --include-torch for real DINOv2)
+python scripts/benchmark_suite.py --trials 5
+
# Pre-PR hygiene check
python scripts/pre_pr_check.py
```
@@ -131,16 +156,16 @@ python scripts/pre_pr_check.py
## Troubleshooting & FAQ
-- **`MissingH5DependencyError` or custom HDF5 dataset paths:** `h5py` is installed by default with `pip install -e .`. `load_primary_volume()` automatically inspects standard NeXus paths, `/entry_0000/ESRF-ID03/pco_nf/data`, and falls back to the largest 3D numeric dataset in the file. Pass `--allow-synthetic-fallback` only when testing schema plumbing on empty/metadata-only HDF5 stubs.
+- **`MissingH5DependencyError` or custom HDF5 dataset paths:** `h5py` is installed by default with `pip install -e .`. `load_primary_volume()` and `LazyVolume` automatically inspect standard NeXus paths, `/entry_0000/ESRF-ID03/pco_nf/data`, and fall back to the largest 3D numeric dataset in the file. Pass `--allow-synthetic-fallback` only when testing schema plumbing on empty/metadata-only HDF5 stubs.
- **`401 Unauthorized` / gated HuggingFace model error:** You passed a gated model ID (such as `facebook/dinov3-*`) without authenticating. Either omit `--model` to use the ungated default (`facebook/dinov2-small`), or accept the model license on HuggingFace and export `HF_TOKEN`.
-- **Unphysical strain percentages in `kinematics.csv`:** Check `"calibrated_axes"` in `kinematics_summary.json`. When `false`, `centroid_d` is measured in cropped detector pixels (`y` index) rather than Angstroms — pass `--calibration-json` (or `--d-origin` / `--d-step`) to compute true crystallographic $\Delta d / d_0$.
+- **Unphysical strain percentages in `kinematics.csv`:** Check `"calibrated_axes"` in `kinematics_summary.json`. When `false`, `centroid_d` is measured in cropped detector pixels (`y` index) rather than Angstroms — pass `--calibration-json` (or `--detector-json`) to compute physical crystallographic quantities.
## Repository Layout & Contributing
-- **`braggtrack/`** — Installable Python library (`io`, `segmentation`, `semantic`, `tracking`, `cli`).
+- **`braggtrack/`** — Installable Python library (`io`, `segmentation`, `semantic`, `tracking`, `viz`, `cli`).
- **`data/sample_operando/`** — Bundled ESRF-ID03 operando test scans (`scan0001`–`scan0003`).
-- **`docs/`** — [Architecture](docs/architecture.md) and [Coding Practices](docs/coding-practices.md).
-- **`scripts/`** — Acceptance gates, semantic α/β ablation (`ablation_semantic.py`), and CI runner (`ci_report.py`).
+- **`docs/`** — [Architecture](docs/architecture.md), [Benchmarks](docs/benchmarks.md), [Coding Practices](docs/coding-practices.md), and publication figures (`docs/figures/`).
+- **`scripts/`** — 9 acceptance gates, 5-scenario benchmark suite (`benchmark_suite.py`), semantic α/β ablation (`ablation_semantic.py`), and CI runner (`ci_report.py`).
- **`artifacts/`** — Generated pipeline outputs (gitignored; never commit).
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [paper.md](paper.md) for the manuscript overview.
diff --git a/braggtrack/__init__.py b/braggtrack/__init__.py
index 20123fa..14eeacb 100644
--- a/braggtrack/__init__.py
+++ b/braggtrack/__init__.py
@@ -5,6 +5,6 @@
try:
__version__ = version("braggtrack")
except PackageNotFoundError:
- __version__ = "0.2.0.dev0"
+ __version__ = "0.3.0.dev0"
-__all__ = ["io", "segmentation", "semantic", "tracking"]
+__all__ = ["io", "segmentation", "semantic", "tracking", "viz"]
diff --git a/braggtrack/cli/detect_events.py b/braggtrack/cli/detect_events.py
index 321dfaf..9eb799d 100644
--- a/braggtrack/cli/detect_events.py
+++ b/braggtrack/cli/detect_events.py
@@ -4,6 +4,7 @@
import argparse
import json
+from contextlib import ExitStack
from pathlib import Path
from typing import Any
@@ -13,14 +14,16 @@
from braggtrack.cli.track_dataset import _load_embeddings_npz, _merge_embeddings
from braggtrack.io import (
BeamlineAdapter,
+ LazyVolume,
MissingH5DependencyError,
discover_operando_scans,
- load_primary_volume,
+ open_lazy_volume,
resolve_dataset_root,
)
from braggtrack.semantic import DEFAULT_DINO_MODEL, make_patch_encoder
from braggtrack.semantic.dino import _requested_backend, _resolve_backend
from braggtrack.tracking import (
+ GapClosingConfig,
GeometrySemanticCost,
PositionShapeCost,
PrecursorConfig,
@@ -66,6 +69,8 @@ def build_parser() -> argparse.ArgumentParser:
parser.add_argument("--gate-chi", type=float, default=float("inf"))
parser.add_argument("--gate-d", type=float, default=float("inf"))
parser.add_argument("--max-cost", type=float, default=float("inf"))
+ parser.add_argument("--max-gap", type=int, default=0, help="Max missing intermediate scans to bridge (0 disables)")
+ parser.add_argument("--gap-max-cost", type=float, default=25.0, help="Max penalized cost for gap-closing bridges")
parser.add_argument("--cost-alpha", type=float, default=1.0)
parser.add_argument("--cost-beta", type=float, default=0.0)
parser.add_argument("--split-max-distance", type=float, default=25.0)
@@ -83,13 +88,14 @@ def build_parser() -> argparse.ArgumentParser:
def _try_load_roi_inputs(
+ stack: ExitStack,
root_arg: str | None,
scan_dirs: list[Path],
scan_names: list[str],
*,
allow_synthetic_fallback: bool,
-) -> tuple[dict[int, np.ndarray], dict[int, np.ndarray], dict[int, str | None]]:
- volumes: dict[int, np.ndarray] = {}
+) -> tuple[dict[int, Any], dict[int, np.ndarray], dict[int, str | None]]:
+ volumes: dict[int, Any] = {}
label_volumes: dict[int, np.ndarray] = {}
timestamps: dict[int, str | None] = {}
@@ -123,13 +129,13 @@ def _try_load_roi_inputs(
if sf is None or idx not in label_volumes:
continue
try:
- vol = load_primary_volume(sf.path)
+ vol: LazyVolume = stack.enter_context(open_lazy_volume(sf.path))
except MissingH5DependencyError:
- vol = synth_volume_from_file(sf.path)
+ vol = LazyVolume.from_array(synth_volume_from_file(sf.path))
except (KeyError, ValueError):
if not allow_synthetic_fallback:
continue
- vol = synth_volume_from_file(sf.path)
+ vol = LazyVolume.from_array(synth_volume_from_file(sf.path))
if vol.shape == label_volumes[idx].shape:
volumes[idx] = vol
@@ -175,63 +181,69 @@ def main(argv: list[str] | None = None) -> int:
print(json.dumps({"error": "Missing embeddings.npz", "path": str(npz)}))
return 1
- volumes, label_volumes, scan_timestamps = _try_load_roi_inputs(
- args.root,
- used_scan_dirs,
- scan_names,
- allow_synthetic_fallback=bool(args.allow_synthetic_fallback),
- )
+ with ExitStack() as stack:
+ volumes, label_volumes, scan_timestamps = _try_load_roi_inputs(
+ stack,
+ args.root,
+ used_scan_dirs,
+ scan_names,
+ allow_synthetic_fallback=bool(args.allow_synthetic_fallback),
+ )
- geo = PositionShapeCost(
- position_weight=args.position_weight,
- shape_weight=args.shape_weight,
- gate_mu=args.gate_mu,
- gate_chi=args.gate_chi,
- gate_d=args.gate_d,
- )
- cost_fn = (
- GeometrySemanticCost(geo, cost_alpha=args.cost_alpha, cost_beta=args.cost_beta)
- if args.cost_beta != 0.0
- else geo
- )
- sm_cfg = SplitMergeConfig(
- max_distance=args.split_max_distance,
- gate_mu=args.gate_mu,
- gate_chi=args.gate_chi,
- gate_d=args.gate_d,
- min_intensity_ratio=args.min_intensity_ratio,
- max_intensity_ratio=args.max_intensity_ratio,
- min_fragment_share=args.min_fragment_share,
- )
+ geo = PositionShapeCost(
+ position_weight=args.position_weight,
+ shape_weight=args.shape_weight,
+ gate_mu=args.gate_mu,
+ gate_chi=args.gate_chi,
+ gate_d=args.gate_d,
+ )
+ cost_fn = (
+ GeometrySemanticCost(geo, cost_alpha=args.cost_alpha, cost_beta=args.cost_beta)
+ if args.cost_beta != 0.0
+ else geo
+ )
+ gap_cfg = GapClosingConfig(max_gap=args.max_gap, max_cost=args.gap_max_cost) if args.max_gap > 0 else None
+ sm_cfg = SplitMergeConfig(
+ max_distance=args.split_max_distance,
+ gate_mu=args.gate_mu,
+ gate_chi=args.gate_chi,
+ gate_d=args.gate_d,
+ min_intensity_ratio=args.min_intensity_ratio,
+ max_intensity_ratio=args.max_intensity_ratio,
+ min_fragment_share=args.min_fragment_share,
+ )
- G = build_tracks(
- scan_tables,
- cost_fn=cost_fn,
- max_cost=args.max_cost,
- split_merge_config=sm_cfg,
- scan_timestamps=scan_timestamps or None,
- )
- metrics = compute_tracking_metrics(G, n_scans=len(scan_tables))
- lineage_events = list(G.graph.get("lineage_events", []))
- track_rows = tracks_to_table(G)
- for tr in track_rows:
- tr.pop("embedding", None)
+ G = build_tracks(
+ scan_tables,
+ cost_fn=cost_fn,
+ max_cost=args.max_cost,
+ gap_closing_config=gap_cfg,
+ split_merge_config=sm_cfg,
+ scan_timestamps=scan_timestamps or None,
+ )
+ metrics = compute_tracking_metrics(G, n_scans=len(scan_tables))
+ lineage_events = list(G.graph.get("lineage_events", []))
+ track_rows = tracks_to_table(G)
+ for tr in track_rows:
+ tr.pop("embedding", None)
- resolved_backend = _resolve_backend(_requested_backend(args.backend)) # type: ignore[arg-type]
- patch_encoder = make_patch_encoder(resolved_backend, model_name=args.model) if (volumes and label_volumes) else None
+ resolved_backend = _resolve_backend(_requested_backend(args.backend)) # type: ignore[arg-type]
+ patch_encoder = (
+ make_patch_encoder(resolved_backend, model_name=args.model) if (volumes and label_volumes) else None
+ )
- prec_cfg = PrecursorConfig(
- score_threshold=args.precursor_threshold,
- min_persistence=max(1, args.precursor_persistence),
- )
- candidates, obs_scores = compute_fracture_precursors(
- track_rows,
- prec_cfg,
- volumes=volumes or None,
- label_volumes=label_volumes or None,
- patch_encoder=patch_encoder,
- lineage_events=lineage_events,
- )
+ prec_cfg = PrecursorConfig(
+ score_threshold=args.precursor_threshold,
+ min_persistence=max(1, args.precursor_persistence),
+ )
+ candidates, obs_scores = compute_fracture_precursors(
+ track_rows,
+ prec_cfg,
+ volumes=volumes or None,
+ label_volumes=label_volumes or None,
+ patch_encoder=patch_encoder,
+ lineage_events=lineage_events,
+ )
event_rows = events_to_table(lineage_events)
prec_rows = precursors_to_table(candidates)
@@ -262,6 +274,7 @@ def main(argv: list[str] | None = None) -> int:
"scan_names": scan_names,
"n_scans": len(scan_tables),
"total_tracks": metrics["total_tracks"],
+ "gap_closed_count": metrics["gap_closed_count"],
"split_count": metrics["split_count"],
"merge_count": metrics["merge_count"],
"event_count": len(event_rows),
diff --git a/braggtrack/cli/embed_dataset.py b/braggtrack/cli/embed_dataset.py
index b819c01..f1baec7 100644
--- a/braggtrack/cli/embed_dataset.py
+++ b/braggtrack/cli/embed_dataset.py
@@ -10,9 +10,10 @@
from braggtrack.cli._utils import load_feature_csv, synth_volume_from_file
from braggtrack.io import (
+ LazyVolume,
MissingH5DependencyError,
discover_operando_scans,
- load_primary_volume,
+ open_lazy_volume,
resolve_dataset_root,
)
from braggtrack.semantic import DEFAULT_DINO_MODEL, crop_spot_cube, make_multiview_encoder, orthogonal_mips
@@ -83,38 +84,39 @@ def main(argv: list[str] | None = None) -> int:
return 1
try:
- volume = load_primary_volume(scan_file.path)
+ lazy_vol = open_lazy_volume(scan_file.path)
except MissingH5DependencyError:
- volume = synth_volume_from_file(scan_file.path)
+ lazy_vol = LazyVolume.from_array(synth_volume_from_file(scan_file.path))
except (KeyError, ValueError):
if not args.allow_synthetic_fallback:
raise
- volume = synth_volume_from_file(scan_file.path)
-
- if volume.shape != labels_full.shape:
- print(
- json.dumps(
- {
- "error": "Volume/labels shape mismatch",
- "scan": name,
- "volume": list(volume.shape),
- "labels": list(labels_full.shape),
- }
+ lazy_vol = LazyVolume.from_array(synth_volume_from_file(scan_file.path))
+
+ with lazy_vol:
+ if lazy_vol.shape != labels_full.shape:
+ print(
+ json.dumps(
+ {
+ "error": "Volume/labels shape mismatch",
+ "scan": name,
+ "volume": list(lazy_vol.shape),
+ "labels": list(labels_full.shape),
+ }
+ )
)
- )
- return 1
+ return 1
+
+ label_ids: list[int] = []
+ vectors: list[np.ndarray] = []
- label_ids: list[int] = []
- vectors: list[np.ndarray] = []
-
- for row in rows:
- lid = int(row["label"])
- mip_mu, mip_chi, mip_d = orthogonal_mips(
- crop_spot_cube(volume, labels_full, lid, row, margin=max(0, args.margin))[0]
- )
- vec = enc.embed(mip_mu, mip_chi, mip_d)
- label_ids.append(lid)
- vectors.append(vec)
+ for row in rows:
+ lid = int(row["label"])
+ mip_mu, mip_chi, mip_d = orthogonal_mips(
+ crop_spot_cube(lazy_vol, labels_full, lid, row, margin=max(0, args.margin))[0]
+ )
+ vec = enc.embed(mip_mu, mip_chi, mip_d)
+ label_ids.append(lid)
+ vectors.append(vec)
if not vectors:
dim = 384
diff --git a/braggtrack/cli/report_dataset.py b/braggtrack/cli/report_dataset.py
new file mode 100644
index 0000000..f6ac4fc
--- /dev/null
+++ b/braggtrack/cli/report_dataset.py
@@ -0,0 +1,140 @@
+"""Generate publication figures and an interactive HTML 4D beamtime explorer from BraggTrack outputs."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+from braggtrack.viz import (
+ generate_html_report,
+ plot_kinematics_dashboard,
+ plot_lineage_dag,
+ plot_precursor_timeline,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "artifact_dir",
+ nargs="?",
+ default="artifacts/pipeline",
+ help="Pipeline or tracking output directory containing tracks.csv / events / manifest",
+ )
+ parser.add_argument(
+ "--dataset-root",
+ default=None,
+ help="Optional raw HDF5 dataset root for embedding 3-axis MIP spot thumbnails",
+ )
+ parser.add_argument(
+ "--outdir",
+ default=None,
+ help="Optional report output directory (defaults to /report)",
+ )
+ parser.add_argument(
+ "--no-figures",
+ action="store_true",
+ help="Skip static Matplotlib PNG/PDF generation and emit only the self-contained HTML explorer",
+ )
+ parser.add_argument(
+ "--max-mip-tracks",
+ type=int,
+ default=16,
+ help="Maximum priority tracks for lazy 3-view MIP thumbnail extraction",
+ )
+ return parser
+
+
+def _read_csv_rows(path: Path) -> list[dict[str, str]]:
+ if not path.exists() or path.stat().st_size == 0:
+ return []
+ with path.open(newline="") as f:
+ return list(csv.DictReader(f))
+
+
+def main(argv: list[str] | None = None) -> int:
+ args = build_parser().parse_args(argv)
+ in_root = Path(args.artifact_dir)
+ if not in_root.is_dir():
+ print(json.dumps({"error": "Artifact directory not found", "artifact_dir": str(in_root)}))
+ return 1
+
+ out_root = Path(args.outdir) if args.outdir else (in_root / "report")
+ out_root.mkdir(parents=True, exist_ok=True)
+
+ trk_dir = in_root / "tracking" if (in_root / "tracking").is_dir() else in_root
+ evt_dir = in_root / "events" if (in_root / "events").is_dir() else trk_dir
+ track_rows = _read_csv_rows(evt_dir / "tracks.csv") or _read_csv_rows(trk_dir / "tracks.csv")
+ if not track_rows:
+ print(json.dumps({"error": "No tracks.csv found under artifact directory", "artifact_dir": str(in_root)}))
+ return 1
+
+ html_path = generate_html_report(
+ in_root,
+ out_root / "report.html",
+ dataset_root=args.dataset_root,
+ max_mip_tracks=max(0, args.max_mip_tracks),
+ )
+
+ figures: dict[str, str] = {}
+ if not args.no_figures:
+ try:
+ import matplotlib
+
+ matplotlib.use("Agg", force=False)
+ import matplotlib.pyplot as plt
+
+ fig_dir = out_root / "figures"
+ fig_dir.mkdir(parents=True, exist_ok=True)
+ event_rows = _read_csv_rows(evt_dir / "events.csv") or _read_csv_rows(trk_dir / "events.csv")
+ prec_rows = _read_csv_rows(evt_dir / "precursors.csv") or _read_csv_rows(trk_dir / "precursors.csv")
+ prec_obs_rows = _read_csv_rows(evt_dir / "precursor_observations.csv")
+
+ calibrated = False
+ ts_path = trk_dir / "tracking_summary.json"
+ if ts_path.exists():
+ try:
+ calibrated = bool(json.loads(ts_path.read_text()).get("calibrated_axes", False))
+ except (OSError, json.JSONDecodeError):
+ calibrated = False
+
+ fig_dag, _ = plot_lineage_dag(track_rows, events=event_rows, save_path=fig_dir / "lineage_dag.png")
+ plt.close(fig_dag)
+ figures["lineage_dag"] = str((fig_dir / "lineage_dag.png").resolve())
+
+ fig_kin, _ = plot_kinematics_dashboard(
+ track_rows,
+ events=event_rows,
+ calibrated=calibrated,
+ save_path=fig_dir / "kinematics_dashboard.png",
+ )
+ plt.close(fig_kin)
+ figures["kinematics_dashboard"] = str((fig_dir / "kinematics_dashboard.png").resolve())
+
+ if prec_obs_rows:
+ fig_prec, _ = plot_precursor_timeline(
+ prec_obs_rows,
+ candidates=prec_rows,
+ save_path=fig_dir / "precursor_timeline.png",
+ )
+ plt.close(fig_prec)
+ figures["precursor_timeline"] = str((fig_dir / "precursor_timeline.png").resolve())
+ except ImportError:
+ pass
+
+ summary: dict[str, Any] = {
+ "schema_version": "report.v1",
+ "html_report": str(html_path.resolve()),
+ "figures": figures,
+ "track_row_count": len(track_rows),
+ }
+ (out_root / "report_summary.json").write_text(json.dumps(summary, indent=2))
+ print(json.dumps(summary, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/braggtrack/cli/run_pipeline.py b/braggtrack/cli/run_pipeline.py
index 12ef93e..756f5b1 100644
--- a/braggtrack/cli/run_pipeline.py
+++ b/braggtrack/cli/run_pipeline.py
@@ -14,7 +14,7 @@
from typing import Any
import braggtrack
-from braggtrack.cli import detect_events, embed_dataset, segment_dataset, track_dataset
+from braggtrack.cli import detect_events, embed_dataset, report_dataset, segment_dataset, track_dataset
from braggtrack.io import BeamlineAdapter, discover_operando_scans, resolve_dataset_root, validate_sequence
from braggtrack.semantic import DEFAULT_DINO_MODEL
@@ -48,8 +48,12 @@ def build_parser() -> argparse.ArgumentParser:
)
parser.add_argument("--smooth-window", type=int, default=5, help="Cross-scan rolling median threshold window")
parser.add_argument("--calibration-json", default=None, help="Optional AxisCalibration JSON path")
+ parser.add_argument(
+ "--detector-json", default=None, help="Optional DetectorGeometry JSON path for (2theta, eta, Q)"
+ )
parser.add_argument("--cost-alpha", type=float, default=1.0, help="Geometry weight in semantic cost")
parser.add_argument("--cost-beta", type=float, default=0.25, help="Semantic embedding weight in tracking cost")
+ parser.add_argument("--max-gap", type=int, default=0, help="Max missing intermediate scans to bridge (0 disables)")
parser.add_argument(
"--split-max-distance", type=float, default=25.0, help="Max centroid distance for splits/merges"
)
@@ -61,6 +65,13 @@ def build_parser() -> argparse.ArgumentParser:
default=True,
help="Run split/merge lineage and fracture precursor detection stage (default: enabled)",
)
+ parser.add_argument(
+ "--report",
+ action="store_true",
+ help="Generate static publication figures and interactive HTML 4D explorer under /report",
+ )
+ parser.add_argument("--export-imaged11", default=None, help="Optional ImageD11 .flt export path")
+ parser.add_argument("--export-nexus", default=None, help="Optional NeXus NXprocess .nxs/.h5 export path")
parser.add_argument(
"--allow-synthetic-fallback",
action="store_true",
@@ -102,12 +113,17 @@ def _merge_config_overrides(args: argparse.Namespace) -> dict[str, Any]:
"method": args.method,
"smooth_window": args.smooth_window,
"calibration_json": args.calibration_json,
+ "detector_json": args.detector_json,
"cost_alpha": args.cost_alpha,
"cost_beta": args.cost_beta,
+ "max_gap": args.max_gap,
"split_max_distance": args.split_max_distance,
"precursor_threshold": args.precursor_threshold,
"precursor_persistence": args.precursor_persistence,
"detect_events": bool(args.detect_events),
+ "report": bool(args.report),
+ "export_imaged11": args.export_imaged11,
+ "export_nexus": args.export_nexus,
"allow_synthetic_fallback": bool(args.allow_synthetic_fallback),
"segmentation_extra_args": [],
"tracking_extra_args": [],
@@ -132,6 +148,7 @@ def main(argv: list[str] | None = None) -> int:
emb_dir = outdir / "embedding"
trk_dir = outdir / "tracking"
evt_dir = outdir / "events"
+ rep_dir = outdir / "report"
timings: dict[str, float] = {}
t_total0 = time.perf_counter()
@@ -190,7 +207,7 @@ def main(argv: list[str] | None = None) -> int:
if rc_seg != 0:
return rc_seg
- # 3. Embed dataset (whenever cost_beta != 0 or detect_events is enabled)
+ # 3. Embed dataset (whenever cost_beta != 0)
need_embed = float(cfg["cost_beta"]) != 0.0
if need_embed:
t0 = time.perf_counter()
@@ -222,6 +239,8 @@ def main(argv: list[str] | None = None) -> int:
str(cfg["cost_alpha"]),
"--cost-beta",
str(cfg["cost_beta"]),
+ "--max-gap",
+ str(cfg["max_gap"]),
"--split-max-distance",
str(cfg["split_max_distance"]),
"--precursor-threshold",
@@ -233,6 +252,12 @@ def main(argv: list[str] | None = None) -> int:
trk_argv.extend(["--embedding-dir", str(emb_dir)])
if cfg.get("detect_events"):
trk_argv.append("--detect-events")
+ if cfg.get("detector_json"):
+ trk_argv.extend(["--detector-json", str(cfg["detector_json"])])
+ if cfg.get("export_imaged11"):
+ trk_argv.extend(["--export-imaged11", str(cfg["export_imaged11"])])
+ if cfg.get("export_nexus") and not cfg.get("detect_events"):
+ trk_argv.extend(["--export-nexus", str(cfg["export_nexus"])])
trk_argv.extend(str(x) for x in cfg.get("tracking_extra_args", []))
rc_trk = track_dataset.main(trk_argv)
timings["track"] = round(time.perf_counter() - t0, 4)
@@ -256,6 +281,8 @@ def main(argv: list[str] | None = None) -> int:
str(cfg["cost_alpha"]),
"--cost-beta",
str(cfg["cost_beta"]),
+ "--max-gap",
+ str(cfg["max_gap"]),
"--split-max-distance",
str(cfg["split_max_distance"]),
"--precursor-threshold",
@@ -272,34 +299,57 @@ def main(argv: list[str] | None = None) -> int:
if rc_evt != 0:
return rc_evt
- total_sec = round(time.perf_counter() - t_total0, 4)
- manifest = {
- "schema_version": "manifest.v1",
- "created_at": datetime.now(timezone.utc).isoformat(),
- "braggtrack_version": braggtrack.__version__,
- "git_sha": _resolve_git_sha(),
- "python_version": sys.version.split()[0],
- "platform": platform.platform(),
- "dataset_root": str(root.resolve()),
- "outdir": str(outdir.resolve()),
- "config": cfg,
- "inputs": input_files,
- "stage_timings_sec": timings,
- "total_duration_sec": total_sec,
- "artifacts": {
- "validation_summary": str((outdir / "validation_summary.json").resolve()),
- "segmentation_summary": str((seg_dir / "segmentation_summary.json").resolve()),
- "embedding_summary": str((emb_dir / "embedding_summary.json").resolve()) if need_embed else None,
- "tracking_summary": str((trk_dir / "tracking_summary.json").resolve()),
- "kinematics_csv": str((trk_dir / "kinematics.csv").resolve()),
- "kinematics_summary": str((trk_dir / "kinematics_summary.json").resolve()),
- "events_summary": str((evt_dir / "events_summary.json").resolve()) if cfg.get("detect_events") else None,
- "events_csv": str((evt_dir / "events.csv").resolve()) if cfg.get("detect_events") else None,
- "precursors_csv": str((evt_dir / "precursors.csv").resolve()) if cfg.get("detect_events") else None,
- },
- }
+ if cfg.get("export_nexus") and cfg.get("detect_events"):
+ from braggtrack.io import DetectorGeometry, export_nexus_process
+
+ dgeom = DetectorGeometry.from_json(cfg["detector_json"]) if cfg.get("detector_json") else None
+ export_nexus_process(outdir, cfg["export_nexus"], geometry=dgeom)
+
manifest_path = outdir / "run_manifest.json"
- manifest_path.write_text(json.dumps(manifest, indent=2))
+
+ def _build_manifest(cur_total_sec: float) -> dict[str, Any]:
+ return {
+ "schema_version": "manifest.v1",
+ "created_at": datetime.now(timezone.utc).isoformat(),
+ "braggtrack_version": braggtrack.__version__,
+ "git_sha": _resolve_git_sha(),
+ "python_version": sys.version.split()[0],
+ "platform": platform.platform(),
+ "dataset_root": str(root.resolve()),
+ "outdir": str(outdir.resolve()),
+ "config": cfg,
+ "inputs": input_files,
+ "stage_timings_sec": timings,
+ "total_duration_sec": cur_total_sec,
+ "artifacts": {
+ "validation_summary": str((outdir / "validation_summary.json").resolve()),
+ "segmentation_summary": str((seg_dir / "segmentation_summary.json").resolve()),
+ "embedding_summary": str((emb_dir / "embedding_summary.json").resolve()) if need_embed else None,
+ "tracking_summary": str((trk_dir / "tracking_summary.json").resolve()),
+ "kinematics_csv": str((trk_dir / "kinematics.csv").resolve()),
+ "kinematics_summary": str((trk_dir / "kinematics_summary.json").resolve()),
+ "events_summary": str((evt_dir / "events_summary.json").resolve())
+ if cfg.get("detect_events")
+ else None,
+ "events_csv": str((evt_dir / "events.csv").resolve()) if cfg.get("detect_events") else None,
+ "precursors_csv": str((evt_dir / "precursors.csv").resolve()) if cfg.get("detect_events") else None,
+ "html_report": str((rep_dir / "report.html").resolve()) if cfg.get("report") else None,
+ },
+ }
+
+ total_sec = round(time.perf_counter() - t_total0, 4)
+ manifest_path.write_text(json.dumps(_build_manifest(total_sec), indent=2))
+
+ # 6. Optional interactive HTML & static figure report
+ if cfg.get("report"):
+ t0 = time.perf_counter()
+ rc_rep = report_dataset.main([str(outdir), "--dataset-root", str(root), "--outdir", str(rep_dir)])
+ timings["report"] = round(time.perf_counter() - t0, 4)
+ if rc_rep != 0:
+ return rc_rep
+ total_sec = round(time.perf_counter() - t_total0, 4)
+ manifest_path.write_text(json.dumps(_build_manifest(total_sec), indent=2))
+
print(json.dumps({"manifest": str(manifest_path.resolve()), "total_duration_sec": total_sec}, indent=2))
return 0
diff --git a/braggtrack/cli/segment_dataset.py b/braggtrack/cli/segment_dataset.py
index aaaf79e..9f6ff29 100644
--- a/braggtrack/cli/segment_dataset.py
+++ b/braggtrack/cli/segment_dataset.py
@@ -16,6 +16,8 @@
discover_primary_volume_path,
extract_axis_calibration,
load_primary_volume,
+ open_lazy_volume,
+ otsu_threshold_chunked,
resolve_dataset_root,
)
from braggtrack.segmentation import (
@@ -191,12 +193,20 @@ def _load_one(scan_obj: object) -> tuple[np.ndarray, str, str | None, AxisCalibr
src = "synthetic_fallback"
return vol, src, dpath, scan_cal
- # First pass: compute scalar per-scan Otsu thresholds in O(1) volume memory.
+ # First pass: compute scalar per-scan Otsu thresholds via streaming z-slabs.
raw_thresholds: list[float] = []
for scan in scans:
- vol_tmp, _, _, _ = _load_one(scan)
- raw_thresholds.append(otsu_threshold(vol_tmp.ravel()) * float(args.threshold_fraction))
- del vol_tmp
+ scan_path = scan.path # type: ignore[attr-defined]
+ try:
+ with open_lazy_volume(scan_path) as lazy_tmp:
+ thr = otsu_threshold_chunked(lazy_tmp)
+ except MissingH5DependencyError:
+ thr = otsu_threshold(synth_volume_from_file(scan_path))
+ except (KeyError, ValueError):
+ if not args.allow_synthetic_fallback:
+ raise
+ thr = otsu_threshold(synth_volume_from_file(scan_path))
+ raw_thresholds.append(thr * float(args.threshold_fraction))
if args.method == "classical" and args.smooth_window > 1 and len(raw_thresholds) > 1:
effective_thresholds = [float(x) for x in smooth_thresholds(raw_thresholds, window=args.smooth_window)]
diff --git a/braggtrack/cli/track_dataset.py b/braggtrack/cli/track_dataset.py
index 2472cf2..c73c107 100644
--- a/braggtrack/cli/track_dataset.py
+++ b/braggtrack/cli/track_dataset.py
@@ -10,7 +10,15 @@
import numpy as np
from braggtrack.cli._utils import load_feature_csv, write_csv, write_qc_notebook
+from braggtrack.io import (
+ AxisCalibration,
+ DetectorGeometry,
+ annotate_crystallographic_columns,
+ export_imaged11_flt,
+ export_nexus_process,
+)
from braggtrack.tracking import (
+ GapClosingConfig,
GeometrySemanticCost,
PositionShapeCost,
PrecursorConfig,
@@ -40,6 +48,18 @@ def build_parser() -> argparse.ArgumentParser:
parser.add_argument("--gate-chi", type=float, default=float("inf"))
parser.add_argument("--gate-d", type=float, default=float("inf"))
parser.add_argument("--max-cost", type=float, default=float("inf"))
+ parser.add_argument(
+ "--max-gap",
+ type=int,
+ default=0,
+ help="Maximum missing intermediate scans to bridge via gap closing (0 disables)",
+ )
+ parser.add_argument(
+ "--gap-max-cost",
+ type=float,
+ default=25.0,
+ help="Maximum penalized cost allowed when bridging missing scans",
+ )
parser.add_argument(
"--embedding-dir",
default=None,
@@ -80,6 +100,21 @@ def build_parser() -> argparse.ArgumentParser:
default=2,
help="Minimum contiguous scans above threshold to rank as a fracture precursor",
)
+ parser.add_argument(
+ "--detector-json",
+ default=None,
+ help="Optional DetectorGeometry JSON path to annotate (omega, 2theta, eta, d, |Q|) columns",
+ )
+ parser.add_argument(
+ "--export-imaged11",
+ default=None,
+ help="Optional path to write an ImageD11 .flt columnfile of tracked reflections",
+ )
+ parser.add_argument(
+ "--export-nexus",
+ default=None,
+ help="Optional path to write a NeXus NXprocess HDF5 summary file",
+ )
return parser
@@ -100,7 +135,7 @@ def _merge_embeddings(rows: list[dict[str, Any]], emb: dict[int, np.ndarray]) ->
row["embedding"] = emb[lid]
-def _detect_calibrated_axes(scan_dirs: list[Path]) -> bool:
+def _detect_calibration(scan_dirs: list[Path]) -> AxisCalibration | None:
for sd in scan_dirs:
summary_path = sd / "summary.json"
if not summary_path.exists():
@@ -111,8 +146,8 @@ def _detect_calibrated_axes(scan_dirs: list[Path]) -> bool:
continue
cal = meta.get("calibration")
if isinstance(cal, dict) and bool(cal.get("calibrated", False)):
- return True
- return False
+ return AxisCalibration.from_dict(cal)
+ return None
_TRACKING_QC_CODE = [
@@ -204,6 +239,7 @@ def main(argv: list[str] | None = None) -> int:
else:
cost_fn = geo
+ gap_cfg = GapClosingConfig(max_gap=args.max_gap, max_cost=args.gap_max_cost) if args.max_gap > 0 else None
sm_cfg = (
SplitMergeConfig(
max_distance=args.split_max_distance,
@@ -214,17 +250,28 @@ def main(argv: list[str] | None = None) -> int:
if args.detect_events
else None
)
- G = build_tracks(scan_tables, cost_fn=cost_fn, max_cost=args.max_cost, split_merge_config=sm_cfg)
+ G = build_tracks(
+ scan_tables,
+ cost_fn=cost_fn,
+ max_cost=args.max_cost,
+ gap_closing_config=gap_cfg,
+ split_merge_config=sm_cfg,
+ )
metrics = compute_tracking_metrics(G, n_scans=len(scan_tables))
+ active_cal = _detect_calibration(used_scan_dirs)
+ calibrated_axes = active_cal is not None
+ detector_geom = DetectorGeometry.from_json(args.detector_json) if args.detector_json else None
+
track_rows = tracks_to_table(G)
for tr in track_rows:
tr.pop("embedding", None)
+ if detector_geom is not None:
+ track_rows = annotate_crystallographic_columns(track_rows, detector_geom, calibration=active_cal)
write_csv(outdir / "tracks.csv", track_rows)
(outdir / "tracking_metrics.json").write_text(json.dumps(metrics, indent=2))
# Per-grain kinematics export.
- calibrated_axes = _detect_calibrated_axes(used_scan_dirs)
gk = compute_grain_kinematics(track_rows)
kin_summary = summarize_kinematics(gk, n_scans=len(scan_tables), calibrated_axes=calibrated_axes)
write_csv(outdir / "kinematics.csv", kinematics_to_table(gk, include_delta_d=True))
@@ -257,12 +304,19 @@ def main(argv: list[str] | None = None) -> int:
"schema_version": schema_version,
"cost_alpha": args.cost_alpha,
"cost_beta": args.cost_beta,
+ "max_gap": args.max_gap,
"embedding_dir": str(emb_root) if emb_root else None,
"detect_events": bool(args.detect_events),
+ "detector_geometry": detector_geom.to_dict() if detector_geom is not None else None,
}
(outdir / "tracking_summary.json").write_text(json.dumps(summary, indent=2))
write_qc_notebook(outdir / "qc" / "tracking_qc.ipynb", title="Tracking QC", code_source=_TRACKING_QC_CODE)
+ if args.export_imaged11:
+ export_imaged11_flt(track_rows, args.export_imaged11, geometry=detector_geom, calibration=active_cal)
+ if args.export_nexus:
+ export_nexus_process(outdir, args.export_nexus, geometry=detector_geom, calibration=active_cal)
+
print(json.dumps(summary, indent=2))
return 0
diff --git a/braggtrack/io/__init__.py b/braggtrack/io/__init__.py
index c2b0577..9a37a54 100644
--- a/braggtrack/io/__init__.py
+++ b/braggtrack/io/__init__.py
@@ -1,7 +1,10 @@
"""Data I/O helpers for BraggTrack."""
from .beamline import BeamlineAdapter
+from .crystallography import DetectorGeometry, annotate_crystallographic_columns
from .discovery import discover_operando_scans
+from .export import IMAGED11_COLUMNS, export_imaged11_flt, export_nexus_process, read_imaged11_flt
+from .lazy import LazyVolume, open_lazy_volume, otsu_threshold_chunked
from .models import AxisCalibration, AxisSpec, ExperimentSequence, ScanVolumeMeta
from .nexus import (
MissingH5DependencyError,
@@ -15,21 +18,30 @@
from .validation import ValidationIssue, validate_sequence
__all__ = [
+ "AxisCalibration",
+ "AxisSpec",
+ "BeamlineAdapter",
+ "DetectorGeometry",
+ "ExperimentSequence",
+ "IMAGED11_COLUMNS",
+ "LazyVolume",
+ "MissingH5DependencyError",
+ "ScanVolumeMeta",
+ "ValidationIssue",
+ "annotate_crystallographic_columns",
"default_dataset_root",
- "resolve_dataset_root",
- "sample_operando_root",
"discover_operando_scans",
"discover_primary_volume_path",
+ "export_imaged11_flt",
+ "export_nexus_process",
"extract_axis_calibration",
"extract_scan_metadata",
- "summarize_hdf5_tree",
"load_primary_volume",
- "MissingH5DependencyError",
- "AxisCalibration",
- "AxisSpec",
- "ScanVolumeMeta",
- "ExperimentSequence",
- "BeamlineAdapter",
- "ValidationIssue",
+ "open_lazy_volume",
+ "otsu_threshold_chunked",
+ "read_imaged11_flt",
+ "resolve_dataset_root",
+ "sample_operando_root",
+ "summarize_hdf5_tree",
"validate_sequence",
]
diff --git a/braggtrack/io/crystallography.py b/braggtrack/io/crystallography.py
new file mode 100644
index 0000000..d7169f8
--- /dev/null
+++ b/braggtrack/io/crystallography.py
@@ -0,0 +1,146 @@
+"""Transmission diffraction detector geometry and reciprocal-space (2theta, eta, |Q|) mapping."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .models import AxisCalibration
+
+
+@dataclass(frozen=True)
+class DetectorGeometry:
+ """Area-detector diffraction geometry for crystallographic angle & Q conversion.
+
+ Follows standard transmission 3DXRD conventions (e.g. ESRF / ImageD11):
+ incident beam along ``+X_lab``, detector plane at ``X_lab = distance_mm``,
+ horizontal detector coordinate ``x_px`` (BraggTrack ``chi`` axis),
+ vertical detector coordinate ``y_px`` (BraggTrack ``d`` axis), and
+ rotation stack ``z_idx`` (BraggTrack ``mu`` / ``omega`` axis).
+ """
+
+ distance_mm: float = 150.0
+ pixel_size_y_mm: float = 0.075
+ pixel_size_x_mm: float = 0.075
+ beam_center_y_px: float = 1024.0
+ beam_center_x_px: float = 1024.0
+ wavelength_angstrom: float = 0.2898
+ omega_origin_deg: float = 0.0
+ omega_step_deg: float = 0.05
+
+ def __post_init__(self) -> None:
+ if self.distance_mm <= 0.0:
+ raise ValueError("distance_mm must be positive.")
+ if self.pixel_size_y_mm <= 0.0 or self.pixel_size_x_mm <= 0.0:
+ raise ValueError("pixel_size_y_mm and pixel_size_x_mm must be positive.")
+ if self.wavelength_angstrom <= 0.0:
+ raise ValueError("wavelength_angstrom must be positive.")
+
+ def to_dict(self) -> dict[str, float]:
+ return {
+ "distance_mm": float(self.distance_mm),
+ "pixel_size_y_mm": float(self.pixel_size_y_mm),
+ "pixel_size_x_mm": float(self.pixel_size_x_mm),
+ "beam_center_y_px": float(self.beam_center_y_px),
+ "beam_center_x_px": float(self.beam_center_x_px),
+ "wavelength_angstrom": float(self.wavelength_angstrom),
+ "omega_origin_deg": float(self.omega_origin_deg),
+ "omega_step_deg": float(self.omega_step_deg),
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> DetectorGeometry:
+ return cls(
+ distance_mm=float(data.get("distance_mm", 150.0)),
+ pixel_size_y_mm=float(data.get("pixel_size_y_mm", 0.075)),
+ pixel_size_x_mm=float(data.get("pixel_size_x_mm", 0.075)),
+ beam_center_y_px=float(data.get("beam_center_y_px", 1024.0)),
+ beam_center_x_px=float(data.get("beam_center_x_px", 1024.0)),
+ wavelength_angstrom=float(data.get("wavelength_angstrom", 0.2898)),
+ omega_origin_deg=float(data.get("omega_origin_deg", 0.0)),
+ omega_step_deg=float(data.get("omega_step_deg", 0.05)),
+ )
+
+ @classmethod
+ def from_json(cls, path: str | Path) -> DetectorGeometry:
+ raw = json.loads(Path(path).read_text())
+ if not isinstance(raw, dict):
+ raise ValueError("DetectorGeometry JSON must contain an object.")
+ return cls.from_dict(raw)
+
+ def save_json(self, path: str | Path) -> None:
+ out = Path(path)
+ out.parent.mkdir(parents=True, exist_ok=True)
+ out.write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+
+ def spot_to_scattering(self, z_idx: float, y_px: float, x_px: float) -> dict[str, float]:
+ """Convert detector voxel centroid ``(z_idx, y_px, x_px)`` to ``(omega, 2theta, eta, d, Q)``."""
+ dx_mm = (float(x_px) - self.beam_center_x_px) * self.pixel_size_x_mm
+ dy_mm = (float(y_px) - self.beam_center_y_px) * self.pixel_size_y_mm
+ r_mm = math.hypot(dx_mm, dy_mm)
+ path_len = math.hypot(self.distance_mm, r_mm)
+
+ two_theta_rad = math.atan2(r_mm, self.distance_mm)
+ two_theta_deg = math.degrees(two_theta_rad)
+ eta_deg = math.degrees(math.atan2(dy_mm, dx_mm))
+ omega_deg = self.omega_origin_deg + float(z_idx) * self.omega_step_deg
+ omega_rad = math.radians(omega_deg)
+
+ sin_theta = math.sin(0.5 * two_theta_rad)
+ if sin_theta > 1e-12:
+ d_angstrom = self.wavelength_angstrom / (2.0 * sin_theta)
+ else:
+ d_angstrom = float("inf")
+
+ k_mag = (2.0 * math.pi) / self.wavelength_angstrom
+ qlab_x = k_mag * (self.distance_mm / path_len - 1.0)
+ qlab_y = k_mag * (dx_mm / path_len)
+ qlab_z = k_mag * (dy_mm / path_len)
+
+ cos_w = math.cos(omega_rad)
+ sin_w = math.sin(omega_rad)
+ qx = qlab_x * cos_w + qlab_y * sin_w
+ qy = -qlab_x * sin_w + qlab_y * cos_w
+ qz = qlab_z
+ q_mag = math.sqrt(qx * qx + qy * qy + qz * qz)
+
+ return {
+ "omega_deg": round(omega_deg, 6),
+ "two_theta_deg": round(two_theta_deg, 6),
+ "eta_deg": round(eta_deg, 6),
+ "d_spacing_angstrom": round(d_angstrom, 6) if math.isfinite(d_angstrom) else float("inf"),
+ "qx_inv_angstrom": round(qx, 6),
+ "qy_inv_angstrom": round(qy, 6),
+ "qz_inv_angstrom": round(qz, 6),
+ "q_mag_inv_angstrom": round(q_mag, 6),
+ }
+
+
+def _recover_voxel_centroid(row: dict[str, Any], calibration: AxisCalibration | None) -> tuple[float, float, float]:
+ mu = float(row["centroid_mu"])
+ chi = float(row["centroid_chi"])
+ d_val = float(row["centroid_d"])
+ if calibration is not None and calibration.calibrated:
+ z_idx = (mu - calibration.mu_origin) / calibration.mu_step
+ x_px = (chi - calibration.chi_origin) / calibration.chi_step
+ y_px = (d_val - calibration.d_origin) / calibration.d_step
+ return z_idx, y_px, x_px
+ return mu, d_val, chi
+
+
+def annotate_crystallographic_columns(
+ rows: list[dict[str, Any]],
+ geometry: DetectorGeometry,
+ *,
+ calibration: AxisCalibration | None = None,
+) -> list[dict[str, Any]]:
+ """Return shallow-copied rows augmented with ``(omega_deg, two_theta_deg, eta_deg, d_spacing_angstrom, q_*)``."""
+ enriched: list[dict[str, Any]] = []
+ for row in rows:
+ z_idx, y_px, x_px = _recover_voxel_centroid(row, calibration)
+ scat = geometry.spot_to_scattering(z_idx, y_px, x_px)
+ enriched.append({**row, **scat})
+ return enriched
diff --git a/braggtrack/io/export.py b/braggtrack/io/export.py
new file mode 100644
index 0000000..5b67a2d
--- /dev/null
+++ b/braggtrack/io/export.py
@@ -0,0 +1,256 @@
+"""Interoperability exporters for ImageD11 columnfiles (.flt) and NeXus NXprocess HDF5."""
+
+from __future__ import annotations
+
+import csv
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+import braggtrack
+
+from .crystallography import DetectorGeometry, _recover_voxel_centroid
+from .models import AxisCalibration
+from .nexus import _require_h5py
+
+IMAGED11_COLUMNS = (
+ "sc",
+ "fc",
+ "omega",
+ "Number_of_pixels",
+ "avg_intensity",
+ "sum_intensity",
+ "tth",
+ "eta",
+ "d_spacing",
+ "gx",
+ "gy",
+ "gz",
+ "scan_idx",
+ "spot_id",
+ "track_id",
+)
+
+
+def export_imaged11_flt(
+ rows: list[dict[str, Any]],
+ out_path: str | Path,
+ *,
+ geometry: DetectorGeometry | None = None,
+ calibration: AxisCalibration | None = None,
+) -> Path:
+ """Write segmented or tracked Bragg reflections as an ImageD11 ``.flt`` columnfile.
+
+ In ImageD11 convention, ``sc`` is the slow (vertical, ``y``) pixel coordinate,
+ ``fc`` is the fast (horizontal, ``x``) pixel coordinate, and ``(gx, gy, gz)``
+ are reciprocal-space scattering vectors in ``1/d`` (``Q / 2*pi``) units.
+ """
+ dest = Path(out_path)
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ geom = geometry or DetectorGeometry()
+ two_pi = 2.0 * math.pi
+
+ lines: list[str] = [
+ f"# ImageD11 columnfile exported by BraggTrack {braggtrack.__version__}",
+ f"# wavelength = {geom.wavelength_angstrom:.6f}",
+ f"# distance = {geom.distance_mm * 1000.0:.3f}",
+ f"# y_center = {geom.beam_center_y_px:.3f}",
+ f"# z_center = {geom.beam_center_x_px:.3f}",
+ f"# y_size = {geom.pixel_size_y_mm * 1000.0:.3f}",
+ f"# z_size = {geom.pixel_size_x_mm * 1000.0:.3f}",
+ "# " + " ".join(IMAGED11_COLUMNS),
+ ]
+
+ for idx, row in enumerate(rows):
+ z_idx, y_px, x_px = _recover_voxel_centroid(row, calibration)
+ scat = geom.spot_to_scattering(z_idx, y_px, x_px)
+ vox = max(1, int(float(row.get("voxel_count", 1))))
+ sum_int = float(row.get("integrated_intensity", 0.0))
+ avg_int = sum_int / float(vox)
+ scan_idx = int(float(row.get("scan_idx", 0)))
+ spot_id = int(float(row.get("label", row.get("spot_idx", idx + 1))))
+ track_id = int(float(row.get("track_id", -1)))
+ d_val = scat["d_spacing_angstrom"] if math.isfinite(scat["d_spacing_angstrom"]) else 0.0
+ gx = scat["qx_inv_angstrom"] / two_pi
+ gy = scat["qy_inv_angstrom"] / two_pi
+ gz = scat["qz_inv_angstrom"] / two_pi
+
+ lines.append(
+ f"{y_px:10.4f} {x_px:10.4f} {scat['omega_deg']:10.4f} "
+ f"{vox:8d} {avg_int:12.4f} {sum_int:14.4f} "
+ f"{scat['two_theta_deg']:10.5f} {scat['eta_deg']:10.4f} {d_val:10.5f} "
+ f"{gx:11.6f} {gy:11.6f} {gz:11.6f} "
+ f"{scan_idx:6d} {spot_id:6d} {track_id:6d}"
+ )
+
+ dest.write_text("\n".join(lines) + "\n")
+ return dest
+
+
+def read_imaged11_flt(path: str | Path) -> tuple[dict[str, str], list[dict[str, float]]]:
+ """Parse an ImageD11 ``.flt`` columnfile back into header parameters and numeric row dicts."""
+ params: dict[str, str] = {}
+ columns: list[str] = []
+ rows: list[dict[str, float]] = []
+
+ for raw_line in Path(path).read_text().splitlines():
+ line = raw_line.strip()
+ if not line:
+ continue
+ if line.startswith("#"):
+ body = line[1:].strip()
+ if "=" in body:
+ k, v = body.split("=", 1)
+ params[k.strip()] = v.strip()
+ elif body.startswith("sc ") or body.startswith("sc\t"):
+ columns = body.split()
+ continue
+ if not columns:
+ raise ValueError("Missing '# sc fc ...' column header in ImageD11 file.")
+ parts = line.split()
+ if len(parts) != len(columns):
+ raise ValueError(f"Expected {len(columns)} columns, got {len(parts)} in line: {line}")
+ rows.append({col: float(val) for col, val in zip(columns, parts)})
+
+ return params, rows
+
+
+def _read_csv_rows(path: Path) -> list[dict[str, str]]:
+ if not path.exists() or path.stat().st_size == 0:
+ return []
+ with path.open(newline="") as f:
+ return list(csv.DictReader(f))
+
+
+def _write_table_group(grp: Any, h5py: Any, rows: list[dict[str, Any]]) -> None:
+ if not rows:
+ grp.attrs["row_count"] = 0
+ return
+ grp.attrs["row_count"] = len(rows)
+ str_dt = h5py.string_dtype(encoding="utf-8")
+ keys = list(rows[0].keys())
+ for key in keys:
+ vals = [r.get(key, "") for r in rows]
+ # Attempt numeric conversion first (float64 or int64), else UTF-8 strings.
+ is_int = True
+ is_float = True
+ int_vals: list[int] = []
+ float_vals: list[float] = []
+ for v in vals:
+ s = str(v).strip()
+ if s == "" or s.lower() in ("true", "false") or ";" in s:
+ is_int = False
+ is_float = False
+ break
+ try:
+ iv = int(s)
+ int_vals.append(iv)
+ except ValueError:
+ is_int = False
+ try:
+ fv = float(s)
+ float_vals.append(fv)
+ except ValueError:
+ is_float = False
+ break
+ if is_int:
+ grp.create_dataset(key, data=np.asarray(int_vals, dtype=np.int64), compression="gzip")
+ elif is_float:
+ grp.create_dataset(key, data=np.asarray(float_vals, dtype=np.float64), compression="gzip")
+ else:
+ arr = np.asarray([str(v) for v in vals], dtype=object)
+ grp.create_dataset(key, data=arr, dtype=str_dt)
+
+
+def export_nexus_process(
+ artifact_dir: str | Path,
+ out_h5: str | Path,
+ *,
+ geometry: DetectorGeometry | None = None,
+ calibration: AxisCalibration | None = None,
+) -> Path:
+ """Package BraggTrack pipeline/tracking outputs into a NeXus ``NXentry`` / ``NXprocess`` HDF5 file."""
+ h5py = _require_h5py()
+ root = Path(artifact_dir)
+ dest = Path(out_h5)
+ dest.parent.mkdir(parents=True, exist_ok=True)
+
+ # Support either a pipeline root (containing tracking/ & events/) or a direct tracking output dir.
+ trk_dir = root / "tracking" if (root / "tracking").is_dir() else root
+ evt_dir = root / "events" if (root / "events").is_dir() else trk_dir
+
+ track_rows: list[dict[str, Any]] = [dict(r) for r in _read_csv_rows(trk_dir / "tracks.csv")]
+ if geometry is not None and track_rows:
+ from .crystallography import annotate_crystallographic_columns
+
+ track_rows = annotate_crystallographic_columns(track_rows, geometry, calibration=calibration)
+
+ kin_rows = _read_csv_rows(trk_dir / "kinematics.csv")
+ event_rows = _read_csv_rows(evt_dir / "events.csv")
+ prec_rows = _read_csv_rows(evt_dir / "precursors.csv")
+
+ provenance_json = "{}"
+ for cand in (root / "run_manifest.json", trk_dir / "tracking_summary.json"):
+ if cand.exists():
+ provenance_json = cand.read_text()
+ break
+
+ str_dt = h5py.string_dtype(encoding="utf-8")
+ with h5py.File(dest, "w") as h5:
+ h5.attrs["NX_class"] = "NXroot"
+ h5.attrs["default"] = "entry"
+
+ entry = h5.create_group("entry")
+ entry.attrs["NX_class"] = "NXentry"
+ entry.attrs["default"] = "braggtrack"
+ entry.create_dataset("title", data="BraggTrack 4D Diffraction Tracking & Fracture Analysis", dtype=str_dt)
+
+ proc = entry.create_group("braggtrack")
+ proc.attrs["NX_class"] = "NXprocess"
+ proc.create_dataset("program", data="braggtrack", dtype=str_dt)
+ proc.create_dataset("version", data=str(braggtrack.__version__), dtype=str_dt)
+ proc.create_dataset("date", data=datetime.now(timezone.utc).isoformat(), dtype=str_dt)
+ proc.create_dataset("provenance_json", data=provenance_json, dtype=str_dt)
+
+ if geometry is not None:
+ geom_grp = proc.create_group("detector_geometry")
+ geom_grp.attrs["NX_class"] = "NXparameters"
+ for k, v in geometry.to_dict().items():
+ geom_grp.create_dataset(k, data=float(v))
+
+ tracks_grp = proc.create_group("tracks")
+ tracks_grp.attrs["NX_class"] = "NXdata"
+ _write_table_group(tracks_grp, h5py, track_rows)
+
+ kin_grp = proc.create_group("kinematics")
+ kin_grp.attrs["NX_class"] = "NXdata"
+ _write_table_group(kin_grp, h5py, kin_rows)
+
+ evt_grp = proc.create_group("events")
+ evt_grp.attrs["NX_class"] = "NXcollection"
+ _write_table_group(evt_grp, h5py, event_rows)
+
+ prec_grp = proc.create_group("precursors")
+ prec_grp.attrs["NX_class"] = "NXcollection"
+ _write_table_group(prec_grp, h5py, prec_rows)
+
+ # Attach summary metrics if available
+ trk_summary_path = trk_dir / "tracking_summary.json"
+ if trk_summary_path.exists():
+ try:
+ ts = json.loads(trk_summary_path.read_text())
+ metrics_grp = proc.create_group("metrics")
+ metrics_grp.attrs["NX_class"] = "NXparameters"
+ for k, v in ts.items():
+ if isinstance(v, bool):
+ metrics_grp.create_dataset(k, data=bool(v))
+ elif isinstance(v, (int, float)):
+ metrics_grp.create_dataset(k, data=v)
+ except (OSError, json.JSONDecodeError):
+ pass
+
+ return dest
diff --git a/braggtrack/io/lazy.py b/braggtrack/io/lazy.py
new file mode 100644
index 0000000..968a26e
--- /dev/null
+++ b/braggtrack/io/lazy.py
@@ -0,0 +1,144 @@
+"""Chunked and ROI-lazy 3D volume access for multi-gigabyte HDF5 detector stacks."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from skimage.filters import threshold_otsu
+
+from .nexus import _require_h5py, _resolve_volume_dataset
+
+
+class LazyVolume:
+ """Lazy 3D volume wrapper supporting bounded ROI reads and z-slab streaming.
+
+ Works seamlessly over either an open ``h5py.Dataset`` or an in-memory
+ ``numpy.ndarray`` fallback so downstream stages (:func:`crop_spot_cube`,
+ chunked Otsu thresholding) never materialize full ``float64`` detector
+ cubes unless explicitly requested via ``vol[()]``.
+ """
+
+ def __init__(
+ self,
+ dataset: Any,
+ *,
+ handle: Any | None = None,
+ dataset_path: str | None = None,
+ ) -> None:
+ shape = tuple(int(x) for x in dataset.shape)
+ if len(shape) != 3:
+ if handle is not None:
+ handle.close()
+ raise ValueError(f"LazyVolume requires a 3D dataset, got shape={shape}")
+ self._dataset = dataset
+ self._handle = handle
+ self._shape: tuple[int, int, int] = (shape[0], shape[1], shape[2])
+ self._dtype = np.dtype(dataset.dtype)
+ self._dataset_path = dataset_path
+
+ @classmethod
+ def from_array(cls, array: np.ndarray, *, dataset_path: str | None = None) -> LazyVolume:
+ arr = np.asarray(array)
+ return cls(arr, handle=None, dataset_path=dataset_path)
+
+ @property
+ def shape(self) -> tuple[int, int, int]:
+ return self._shape
+
+ @property
+ def ndim(self) -> int:
+ return 3
+
+ @property
+ def dtype(self) -> np.dtype[Any]:
+ return self._dtype
+
+ @property
+ def dataset_path(self) -> str | None:
+ return self._dataset_path
+
+ def read_roi(self, z_slice: slice, y_slice: slice, x_slice: slice) -> np.ndarray:
+ """Read a bounded 3D sub-block into memory as ``float64``."""
+ return np.asarray(self._dataset[z_slice, y_slice, x_slice], dtype=np.float64)
+
+ def __getitem__(self, key: Any) -> np.ndarray:
+ return np.asarray(self._dataset[key], dtype=np.float64)
+
+ def iter_z_chunks(self, chunk_z: int = 32) -> Iterator[np.ndarray]:
+ """Yield contiguous ``(dz, ny, nx)`` ``float64`` slabs along axis 0."""
+ step = max(1, int(chunk_z))
+ nz = self._shape[0]
+ for z0 in range(0, nz, step):
+ z1 = min(nz, z0 + step)
+ yield np.asarray(self._dataset[z0:z1, :, :], dtype=np.float64)
+
+ def to_dense(self) -> np.ndarray:
+ """Materialize the full 3D volume as ``float64``."""
+ return np.asarray(self._dataset[()], dtype=np.float64)
+
+ def close(self) -> None:
+ if self._handle is not None:
+ self._handle.close()
+ self._handle = None
+
+ def __enter__(self) -> LazyVolume:
+ return self
+
+ def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+ self.close()
+
+
+def open_lazy_volume(
+ path: str | Path,
+ candidates: list[str] | None = None,
+ *,
+ auto_discover: bool = True,
+) -> LazyVolume:
+ """Open an HDF5 file and return a :class:`LazyVolume` bound to its primary 3D dataset."""
+ h5py = _require_h5py()
+ handle = h5py.File(path, "r")
+ try:
+ ds_path = _resolve_volume_dataset(handle, h5py, candidates=candidates, auto_discover=auto_discover)
+ ds = handle[ds_path]
+ except Exception:
+ handle.close()
+ raise
+ return LazyVolume(ds, handle=handle, dataset_path=ds_path)
+
+
+def otsu_threshold_chunked(
+ volume: LazyVolume | np.ndarray,
+ *,
+ nbins: int = 256,
+ chunk_z: int = 32,
+) -> float:
+ """Compute global Otsu threshold via streaming z-slabs in ``O(chunk)`` memory."""
+ lazy = volume if isinstance(volume, LazyVolume) else LazyVolume.from_array(np.asarray(volume))
+ nz, ny, nx = lazy.shape
+ if nz * ny * nx == 0:
+ raise ValueError("Otsu threshold requires at least one value.")
+
+ vmin = float("inf")
+ vmax = float("-inf")
+ for slab in lazy.iter_z_chunks(chunk_z=chunk_z):
+ s_min = float(np.min(slab))
+ s_max = float(np.max(slab))
+ if s_min < vmin:
+ vmin = s_min
+ if s_max > vmax:
+ vmax = s_max
+
+ if vmin == vmax:
+ return float(vmin)
+
+ edges = np.linspace(vmin, vmax, max(2, int(nbins)) + 1, dtype=np.float64)
+ counts = np.zeros(len(edges) - 1, dtype=np.int64)
+ for slab in lazy.iter_z_chunks(chunk_z=chunk_z):
+ c, _ = np.histogram(slab, bins=edges)
+ counts += c
+
+ bin_centers = 0.5 * (edges[:-1] + edges[1:])
+ return float(threshold_otsu(hist=(counts, bin_centers)))
diff --git a/braggtrack/segmentation/dino_segment.py b/braggtrack/segmentation/dino_segment.py
index d5b48ef..1250b23 100644
--- a/braggtrack/segmentation/dino_segment.py
+++ b/braggtrack/segmentation/dino_segment.py
@@ -61,10 +61,13 @@ def _patch_foreground_masks(
threshold: float,
patch_size: int,
axis: int = 0,
+ grid_hw: tuple[int, int] | None = None,
) -> list[np.ndarray]:
"""Boolean foreground mask at patch resolution for each slice.
A patch is foreground if any of its pixels exceed *threshold*.
+ Handles both fixed-stride grids (``mock``) and resized ViT patch grids
+ (e.g. ``16x16`` ``facebook/dinov2-small`` tokens on ``250x250`` slices).
"""
n_slices = volume.shape[axis]
masks: list[np.ndarray] = []
@@ -72,11 +75,22 @@ def _patch_foreground_masks(
slc = np.take(volume, i, axis=axis)
fg = (slc >= threshold).astype(np.float64)
h, w = slc.shape
- hp = max(1, h // patch_size)
- wp = max(1, w // patch_size)
- cropped = fg[: hp * patch_size, : wp * patch_size]
- blocks = cropped.reshape(hp, patch_size, wp, patch_size)
- masks.append(blocks.max(axis=(1, 3)) > 0)
+ default_hw = (max(1, h // patch_size), max(1, w // patch_size))
+ hp, wp = grid_hw if grid_hw is not None else default_hw
+ if (hp, wp) == default_hw and hp * patch_size <= h and wp * patch_size <= w:
+ cropped = fg[: hp * patch_size, : wp * patch_size]
+ blocks = cropped.reshape(hp, patch_size, wp, patch_size)
+ masks.append(blocks.max(axis=(1, 3)) > 0)
+ else:
+ r_edges = np.linspace(0, h, hp + 1, dtype=int)
+ c_edges = np.linspace(0, w, wp + 1, dtype=int)
+ pooled = np.zeros((hp, wp), dtype=bool)
+ for r_i in range(hp):
+ r0, r1 = r_edges[r_i], max(r_edges[r_i] + 1, r_edges[r_i + 1])
+ for c_i in range(wp):
+ c0, c1 = c_edges[c_i], max(c_edges[c_i] + 1, c_edges[c_i + 1])
+ pooled[r_i, c_i] = bool(np.any(fg[r0:r1, c0:c1] > 0))
+ masks.append(pooled)
return masks
@@ -159,6 +173,13 @@ def _upsample_labels(
patch_size: int,
) -> np.ndarray:
"""Nearest-neighbor upsample patch-resolution labels to pixel resolution."""
+ th, tw = target_shape
+ hp, wp = patch_labels.shape
+ default_hw = (max(1, th // patch_size), max(1, tw // patch_size))
+ if (hp, wp) != default_hw and th > 0 and tw > 0 and hp > 0 and wp > 0:
+ r_idx = (np.arange(th) * hp) // th
+ c_idx = (np.arange(tw) * wp) // tw
+ return patch_labels[np.ix_(r_idx, c_idx)].astype(np.int32)
expanded = np.repeat(np.repeat(patch_labels, patch_size, axis=0), patch_size, axis=1)
out = np.zeros(target_shape, dtype=np.int32)
h = min(expanded.shape[0], target_shape[0])
@@ -302,7 +323,13 @@ def segment_dino(
features, slice_hw = _extract_slice_features(volume, encoder, axis=axis)
# Foreground mask at patch resolution — exclude background from clustering.
- fg_masks = _patch_foreground_masks(volume, threshold, encoder.patch_size, axis=axis)
+ fg_masks = _patch_foreground_masks(
+ volume,
+ threshold,
+ encoder.patch_size,
+ axis=axis,
+ grid_hw=(features.shape[1], features.shape[2]),
+ )
# Global PCA across all foreground patches for a consistent feature space
# (per-slice PCA causes wildly different cluster counts).
diff --git a/braggtrack/semantic/dino.py b/braggtrack/semantic/dino.py
index 4430380..c636052 100644
--- a/braggtrack/semantic/dino.py
+++ b/braggtrack/semantic/dino.py
@@ -25,6 +25,9 @@ def _resolve_backend(requested: BackendName) -> Literal["mock", "torch"]:
return "mock"
if requested == "torch":
return "torch"
+ env_override = os.environ.get("BRAGGTRACK_DINO_BACKEND", "").strip().lower()
+ if env_override in ("mock", "torch"):
+ return "mock" if env_override == "mock" else "torch"
try:
import torch # noqa: F401
except ImportError:
diff --git a/braggtrack/semantic/mips.py b/braggtrack/semantic/mips.py
index e3240c7..11e58af 100644
--- a/braggtrack/semantic/mips.py
+++ b/braggtrack/semantic/mips.py
@@ -5,14 +5,16 @@
from __future__ import annotations
+from typing import Any
+
import numpy as np
def crop_spot_cube(
- volume: np.ndarray,
+ volume: np.ndarray | Any,
labels: np.ndarray,
label_id: int,
- bbox: dict[str, int],
+ bbox: dict[str, Any],
margin: int = 2,
) -> tuple[np.ndarray, np.ndarray]:
"""Crop a padded sub-volume and binary mask for one instance.
diff --git a/braggtrack/tracking/__init__.py b/braggtrack/tracking/__init__.py
index bc5d52d..68a1f62 100644
--- a/braggtrack/tracking/__init__.py
+++ b/braggtrack/tracking/__init__.py
@@ -3,6 +3,7 @@
from .assignment import associate_frames
from .cost import CostFunction, GeometrySemanticCost, PositionShapeCost
from .events import LineageEvent, SplitMergeConfig, events_to_table, resolve_splits_and_merges
+from .gap_closing import GapCloseRecord, GapClosingConfig, resolve_track_gaps
from .kinematics import (
GrainKinematics,
KinematicsSummary,
@@ -24,6 +25,8 @@
__all__ = [
"CostFunction",
+ "GapCloseRecord",
+ "GapClosingConfig",
"GeometrySemanticCost",
"GrainKinematics",
"KinematicsSummary",
@@ -45,6 +48,7 @@
"kinematics_to_table",
"precursors_to_table",
"resolve_splits_and_merges",
+ "resolve_track_gaps",
"summarize_kinematics",
"summary_to_dict",
"tracks_to_table",
diff --git a/braggtrack/tracking/gap_closing.py b/braggtrack/tracking/gap_closing.py
new file mode 100644
index 0000000..c40ce8f
--- /dev/null
+++ b/braggtrack/tracking/gap_closing.py
@@ -0,0 +1,275 @@
+"""Multi-scan gap closing for transient beam dropouts and rocking-clip recovery."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+import networkx as nx
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+from .cost import CostFunction, GeometrySemanticCost, PositionShapeCost
+from .lifecycle import TrackEvent
+
+
+@dataclass(frozen=True)
+class GapClosingConfig:
+ """Configuration for reconnecting tracks across missing intermediate scans.
+
+ Parameters
+ ----------
+ max_gap : int
+ Maximum number of missing intermediate scans (``1 <= gap_scans <= max_gap``).
+ ``0`` disables gap closing.
+ gap_penalty_per_scan : float
+ Multiplicative penalty per missing scan: ``cost * (1 + gap_penalty_per_scan * gap_scans)``.
+ max_cost : float
+ Upper bound on the penalized association cost for accepting a gap bridge.
+ min_cosine_similarity : float
+ Minimum embedding cosine similarity when both endpoints carry ``embedding``.
+ """
+
+ max_gap: int = 2
+ gap_penalty_per_scan: float = 0.15
+ max_cost: float = 25.0
+ min_cosine_similarity: float = 0.50
+
+
+@dataclass(frozen=True)
+class GapCloseRecord:
+ """Metadata record for an accepted multi-scan gap closure."""
+
+ track_id: int
+ from_scan: int
+ to_scan: int
+ gap_scans: int
+ from_node: str
+ to_node: str
+ cost: float
+
+
+def _cosine_sim(a_raw: Any, b_raw: Any) -> float | None:
+ if a_raw is None or b_raw is None:
+ return None
+ a = np.asarray(a_raw, dtype=np.float64).ravel()
+ b = np.asarray(b_raw, dtype=np.float64).ravel()
+ if a.size == 0 or b.size == 0 or a.shape != b.shape:
+ return None
+ na = float(np.linalg.norm(a))
+ nb = float(np.linalg.norm(b))
+ if na <= 0.0 or nb <= 0.0:
+ return None
+ return float(np.clip(np.dot(a, b) / (na * nb), -1.0, 1.0))
+
+
+def _eval_gap_cost(
+ cost_fn: CostFunction,
+ u_data: dict[str, Any],
+ v_data: dict[str, Any],
+ delta_scans: int,
+ min_cos_sim: float,
+) -> float:
+ """Evaluate gap-normalized cost across ``delta_scans = to_scan - from_scan >= 2``."""
+ sim = _cosine_sim(u_data.get("embedding"), v_data.get("embedding"))
+ if sim is not None and sim < min_cos_sim:
+ return math.inf
+
+ geo: PositionShapeCost | None = None
+ alpha = 1.0
+ beta = 0.0
+ if isinstance(cost_fn, PositionShapeCost):
+ geo = cost_fn
+ elif isinstance(cost_fn, GeometrySemanticCost):
+ geo = cost_fn.geometry
+ alpha = cost_fn.cost_alpha
+ beta = cost_fn.cost_beta
+
+ if geo is not None:
+ dmu = abs(float(u_data["centroid_mu"]) - float(v_data["centroid_mu"]))
+ dchi = abs(float(u_data["centroid_chi"]) - float(v_data["centroid_chi"]))
+ dd = abs(float(u_data["centroid_d"]) - float(v_data["centroid_d"]))
+ step_scale = float(max(1, delta_scans))
+ if (dmu / step_scale) > geo.gate_mu or (dchi / step_scale) > geo.gate_chi or (dd / step_scale) > geo.gate_d:
+ return math.inf
+
+ # Diffusive scaling (dx^2 / delta_t) keeps gap costs comparable to 1-step costs.
+ pos_dist2 = (dmu**2 + dchi**2 + dd**2) / step_scale
+ deig1 = float(u_data.get("eig_1", 0.0)) - float(v_data.get("eig_1", 0.0))
+ deig2 = float(u_data.get("eig_2", 0.0)) - float(v_data.get("eig_2", 0.0))
+ deig3 = float(u_data.get("eig_3", 0.0)) - float(v_data.get("eig_3", 0.0))
+ shape_dist2 = deig1**2 + deig2**2 + deig3**2
+ g_cost = geo.position_weight * pos_dist2 + geo.shape_weight * shape_dist2
+ if beta == 0.0:
+ return alpha * g_cost
+ if sim is None:
+ return math.inf
+ return alpha * g_cost + beta * (1.0 - sim)
+
+ return float(cost_fn(u_data, v_data))
+
+
+def _propagate_track_id_forward(G: nx.DiGraph, start_nid: str, old_tid: int, new_tid: int) -> None:
+ queue = [start_nid]
+ visited: set[str] = set()
+ while queue:
+ curr = queue.pop(0)
+ if curr in visited:
+ continue
+ visited.add(curr)
+ if G.nodes[curr].get("track_id") == old_tid:
+ G.nodes[curr]["track_id"] = new_tid
+ for _, succ in G.out_edges(curr):
+ queue.append(succ)
+
+
+def resolve_track_gaps(
+ G: nx.DiGraph,
+ *,
+ n_scans: int,
+ cost_fn: CostFunction | None = None,
+ config: GapClosingConfig | None = None,
+) -> list[GapCloseRecord]:
+ """Reconnect prematurely terminated tracks to matching births across ``1..max_gap`` missing scans."""
+ cfg = config or GapClosingConfig()
+ if cfg.max_gap <= 0 or G.number_of_nodes() == 0 or n_scans < 3:
+ G.graph.setdefault("gap_closures", [])
+ return []
+
+ active_cost: CostFunction = cost_fn if cost_fn is not None else PositionShapeCost()
+ next_tid = max((int(G.nodes[n]["track_id"]) for n in G.nodes), default=0) + 1
+
+ # Pass 0: Sever forced cross-detector 1-to-1 jump edges created when max_cost=inf
+ # paired a dropping-out track with a distant stray spot on an intermediate frame.
+ nodes_by_scan: dict[int, list[str]] = {}
+ for nid in G.nodes:
+ nodes_by_scan.setdefault(int(G.nodes[nid]["scan_idx"]), []).append(nid)
+
+ sever_threshold = max(cfg.max_cost * 4.0, 100.0)
+
+ def _edge_is_jump(a: str, b: str) -> bool:
+ c_ab = float(active_cost(G.nodes[a], G.nodes[b]))
+ return not math.isfinite(c_ab) or c_ab > sever_threshold
+
+ edges_to_sever: list[tuple[str, str]] = []
+ for u, v, edata in list(G.edges(data=True)):
+ if edata.get("edge_type", "continuation") != "continuation":
+ continue
+ if not _edge_is_jump(u, v):
+ continue
+ su = int(G.nodes[u]["scan_idx"])
+ sv = int(G.nodes[v]["scan_idx"])
+ has_gap_partner = False
+ # Forward check: u can bridge over the jump to w at su + gap + 1
+ for gap in range(1, cfg.max_gap + 1):
+ for w in nodes_by_scan.get(su + gap + 1, []):
+ if G.in_degree(w) == 0 or all(_edge_is_jump(p, w) for p, _ in G.in_edges(w)):
+ gc = _eval_gap_cost(active_cost, G.nodes[u], G.nodes[w], gap + 1, cfg.min_cosine_similarity)
+ if gc * (1.0 + cfg.gap_penalty_per_scan * gap) <= cfg.max_cost * 0.6:
+ has_gap_partner = True
+ break
+ if has_gap_partner:
+ break
+ # Backward check: v can receive a bridge from p at sv - gap - 1
+ if not has_gap_partner:
+ for gap in range(1, cfg.max_gap + 1):
+ for p in nodes_by_scan.get(sv - gap - 1, []):
+ if G.out_degree(p) == 0 or all(_edge_is_jump(p, q) for _, q in G.out_edges(p)):
+ gc = _eval_gap_cost(active_cost, G.nodes[p], G.nodes[v], gap + 1, cfg.min_cosine_similarity)
+ if gc * (1.0 + cfg.gap_penalty_per_scan * gap) <= cfg.max_cost * 0.6:
+ has_gap_partner = True
+ break
+ if has_gap_partner:
+ break
+ if has_gap_partner:
+ edges_to_sever.append((u, v))
+
+ for u, v in edges_to_sever:
+ old_tid = int(G.nodes[u]["track_id"])
+ G.remove_edge(u, v)
+ G.nodes[u]["event"] = TrackEvent.TERMINATED
+ G.nodes[v]["event"] = TrackEvent.BORN
+ _propagate_track_id_forward(G, v, old_tid, next_tid)
+ next_tid += 1
+
+ term_nodes = sorted(
+ [n for n in G.nodes if G.out_degree(n) == 0 and int(G.nodes[n]["scan_idx"]) < n_scans - 1],
+ key=lambda n: (int(G.nodes[n]["scan_idx"]), int(G.nodes[n]["spot_idx"])),
+ )
+ born_nodes = sorted(
+ [n for n in G.nodes if G.in_degree(n) == 0 and int(G.nodes[n]["scan_idx"]) > 0],
+ key=lambda n: (int(G.nodes[n]["scan_idx"]), int(G.nodes[n]["spot_idx"])),
+ )
+
+ n_term = len(term_nodes)
+ n_born = len(born_nodes)
+ if n_term == 0 or n_born == 0:
+ G.graph["gap_closures"] = []
+ return []
+
+ inadmissible = 1e12
+ unmatched_cost = cfg.max_cost + 1e-6
+ aug_matrix = np.full((n_term, n_born + n_term), inadmissible, dtype=np.float64)
+ for i in range(n_term):
+ aug_matrix[i, n_born + i] = unmatched_cost
+
+ for i, u in enumerate(term_nodes):
+ u_data = G.nodes[u]
+ su = int(u_data["scan_idx"])
+ for j, v in enumerate(born_nodes):
+ v_data = G.nodes[v]
+ sv = int(v_data["scan_idx"])
+ gap_scans = sv - su - 1
+ if gap_scans < 1 or gap_scans > cfg.max_gap:
+ continue
+ base = _eval_gap_cost(active_cost, u_data, v_data, gap_scans + 1, cfg.min_cosine_similarity)
+ if not math.isfinite(base):
+ continue
+ penalized = base * (1.0 + cfg.gap_penalty_per_scan * gap_scans)
+ if penalized <= cfg.max_cost:
+ aug_matrix[i, j] = penalized
+
+ row_ind, col_ind = linear_sum_assignment(aug_matrix)
+
+ accepted_pairs: list[tuple[int, int, str, str, float]] = []
+ for r, c in zip(row_ind, col_ind):
+ if c < n_born and aug_matrix[r, c] <= cfg.max_cost:
+ u = term_nodes[int(r)]
+ v = born_nodes[int(c)]
+ su = int(G.nodes[u]["scan_idx"])
+ sv = int(G.nodes[v]["scan_idx"])
+ accepted_pairs.append((su, sv, u, v, float(aug_matrix[r, c])))
+
+ # Process chronologically so multi-gap chains (e.g., 0 -> 2 -> 4) propagate a single track_id.
+ accepted_pairs.sort(key=lambda item: (item[0], item[1], item[2]))
+
+ records: list[GapCloseRecord] = []
+ for su, sv, u, v, cost_val in accepted_pairs:
+ tid = int(G.nodes[u]["track_id"])
+ old_v_tid = int(G.nodes[v]["track_id"])
+ gap_scans = sv - su - 1
+
+ G.add_edge(u, v, edge_type="gap_close", gap_scans=gap_scans, cost=round(cost_val, 4))
+ _propagate_track_id_forward(G, v, old_v_tid, tid)
+
+ G.nodes[u]["event"] = TrackEvent.BORN if G.in_degree(u) == 0 else TrackEvent.CONTINUED
+ if G.out_degree(v) > 0 or sv == n_scans - 1:
+ G.nodes[v]["event"] = TrackEvent.CONTINUED
+ else:
+ G.nodes[v]["event"] = TrackEvent.TERMINATED
+
+ records.append(
+ GapCloseRecord(
+ track_id=tid,
+ from_scan=su,
+ to_scan=sv,
+ gap_scans=gap_scans,
+ from_node=u,
+ to_node=v,
+ cost=round(cost_val, 4),
+ )
+ )
+
+ G.graph["gap_closures"] = records
+ return records
diff --git a/braggtrack/tracking/lifecycle.py b/braggtrack/tracking/lifecycle.py
index d72089c..54b8c8c 100644
--- a/braggtrack/tracking/lifecycle.py
+++ b/braggtrack/tracking/lifecycle.py
@@ -12,6 +12,7 @@
if TYPE_CHECKING:
from .events import SplitMergeConfig
+ from .gap_closing import GapClosingConfig
class TrackEvent(str, enum.Enum):
@@ -30,6 +31,7 @@ def build_tracks(
cost_fn: CostFunction | None = None,
max_cost: float = float("inf"),
*,
+ gap_closing_config: GapClosingConfig | None = None,
split_merge_config: SplitMergeConfig | None = None,
scan_timestamps: dict[int, str | None] | None = None,
) -> nx.DiGraph:
@@ -37,7 +39,8 @@ def build_tracks(
Each node represents a spot observation ``(scan_index, spot_index)``
and carries the full feature dict plus a ``track_id`` and ``event``
- attribute. Edges connect matched spots across consecutive frames, and
+ attribute. Edges connect matched spots across consecutive frames,
+ optional *gap_closing_config* reconnects missing intermediate scans, and
optional *split_merge_config* resolves ``1 -> 2+`` splits and ``2+ -> 1``
merges.
"""
@@ -106,6 +109,16 @@ def build_tracks(
# Still alive at end — leave as CONTINUED (not terminated)
pass
+ if gap_closing_config is not None and gap_closing_config.max_gap > 0:
+ from .gap_closing import resolve_track_gaps
+
+ resolve_track_gaps(
+ G,
+ n_scans=n_scans,
+ cost_fn=active_cost,
+ config=gap_closing_config,
+ )
+
if split_merge_config is not None:
from .events import resolve_splits_and_merges
diff --git a/braggtrack/tracking/metrics.py b/braggtrack/tracking/metrics.py
index 6901b51..3b6ae49 100644
--- a/braggtrack/tracking/metrics.py
+++ b/braggtrack/tracking/metrics.py
@@ -53,7 +53,17 @@ def compute_tracking_metrics(
terminated_count += 1
total_tracks = len(tracks)
- full_length_tracks = sum(1 for obs in tracks.values() if len(obs) >= n_scans)
+ full_length_tracks = sum(
+ 1
+ for obs in tracks.values()
+ if len(obs) >= n_scans
+ or (
+ n_scans > 0
+ and bool(G.graph.get("gap_closures"))
+ and min(int(r["scan_idx"]) for r in obs) == 0
+ and max(int(r["scan_idx"]) for r in obs) >= n_scans - 1
+ )
+ )
fragmentation_ratio = 1.0 - full_length_tracks / total_tracks if total_tracks > 0 else 0.0
# ID-switch rate (requires ground truth).
@@ -89,6 +99,7 @@ def compute_tracking_metrics(
lineage_events = G.graph.get("lineage_events", [])
split_count = sum(1 for ev in lineage_events if getattr(ev, "event_type", None) == "split")
merge_count = sum(1 for ev in lineage_events if getattr(ev, "event_type", None) == "merge")
+ gap_closed_count = len(G.graph.get("gap_closures", []))
return {
"total_tracks": total_tracks,
@@ -97,6 +108,7 @@ def compute_tracking_metrics(
"born_count": born_count,
"continued_count": continued_count,
"terminated_count": terminated_count,
+ "gap_closed_count": gap_closed_count,
"split_count": split_count,
"merge_count": merge_count,
"id_switch_count": id_switch_count,
diff --git a/braggtrack/viz/__init__.py b/braggtrack/viz/__init__.py
new file mode 100644
index 0000000..52705e6
--- /dev/null
+++ b/braggtrack/viz/__init__.py
@@ -0,0 +1,17 @@
+"""Publication plotting and interactive HTML 4D beamtime explorer for BraggTrack."""
+
+from .html_report import build_explorer_payload, generate_html_report
+from .kinematics import plot_kinematics_dashboard
+from .lineage import plot_lineage_dag
+from .mips import plot_scan_projection_overlay, plot_spot_mip_card
+from .precursors import plot_precursor_timeline
+
+__all__ = [
+ "build_explorer_payload",
+ "generate_html_report",
+ "plot_kinematics_dashboard",
+ "plot_lineage_dag",
+ "plot_precursor_timeline",
+ "plot_scan_projection_overlay",
+ "plot_spot_mip_card",
+]
diff --git a/braggtrack/viz/_style.py b/braggtrack/viz/_style.py
new file mode 100644
index 0000000..7306263
--- /dev/null
+++ b/braggtrack/viz/_style.py
@@ -0,0 +1,45 @@
+"""Shared styling and optional-dependency guards for braggtrack.viz."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+# Colorblind-safe Okabe-Ito inspired scientific palette
+OKABE_ITO = (
+ "#0072B2", # blue
+ "#D55E00", # vermilion / split highlight
+ "#009E73", # bluish green / merge highlight
+ "#CC79A7", # reddish purple
+ "#E69F00", # amber / gap-close highlight
+ "#56B4E9", # sky blue
+ "#F0E442", # yellow
+ "#333333", # charcoal
+)
+
+
+def _require_matplotlib() -> tuple[Any, Any]:
+ try:
+ import matplotlib
+ import matplotlib.pyplot as plt
+ except ImportError as exc:
+ raise ImportError(
+ "braggtrack.viz requires matplotlib. Install with `pip install braggtrack[notebook]`."
+ ) from exc
+ return matplotlib, plt
+
+
+def apply_axis_style(ax: Any) -> None:
+ """Apply crisp publication-ready spine and grid styling to a Matplotlib Axes."""
+ ax.spines["top"].set_visible(False)
+ ax.spines["right"].set_visible(False)
+ ax.grid(True, linestyle="--", linewidth=0.5, alpha=0.35)
+
+
+def maybe_save(fig: Any, save_path: str | Path | None, *, dpi: int = 200) -> Path | None:
+ if save_path is None:
+ return None
+ out = Path(save_path)
+ out.parent.mkdir(parents=True, exist_ok=True)
+ fig.savefig(out, dpi=dpi, bbox_inches="tight")
+ return out
diff --git a/braggtrack/viz/html_report.py b/braggtrack/viz/html_report.py
new file mode 100644
index 0000000..49518ef
--- /dev/null
+++ b/braggtrack/viz/html_report.py
@@ -0,0 +1,696 @@
+"""Self-contained offline interactive HTML 4D Lineage, Kinematics & Fracture Explorer."""
+
+from __future__ import annotations
+
+import base64
+import csv
+import html
+import json
+import struct
+import zlib
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from braggtrack.io import (
+ LazyVolume,
+ MissingH5DependencyError,
+ discover_operando_scans,
+ open_lazy_volume,
+ resolve_dataset_root,
+)
+from braggtrack.semantic.mips import crop_spot_cube, orthogonal_mips
+from braggtrack.tracking.kinematics import compute_grain_kinematics
+
+
+def _encode_rgb_png_base64(rgb: np.ndarray) -> str:
+ """Encode a ``(H, W, 3)`` ``uint8`` RGB array to a base64 PNG data URI using stdlib ``zlib``."""
+ h, w, _ = rgb.shape
+ raw_rows = b"".join(b"\x00" + rgb[y].tobytes() for y in range(h))
+
+ def _chunk(tag: bytes, payload: bytes) -> bytes:
+ crc = zlib.crc32(tag + payload) & 0xFFFFFFFF
+ return struct.pack(">I", len(payload)) + tag + payload + struct.pack(">I", crc)
+
+ ihdr = struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0)
+ png = (
+ b"\x89PNG\r\n\x1a\n"
+ + _chunk(b"IHDR", ihdr)
+ + _chunk(b"IDAT", zlib.compress(raw_rows, 6))
+ + _chunk(b"IEND", b"")
+ )
+ return "data:image/png;base64," + base64.b64encode(png).decode("ascii")
+
+
+def _mip_to_magma_like_rgb(mip: np.ndarray, size: int = 44) -> np.ndarray:
+ """Nearest-neighbor resize a 2D MIP to ``(size, size)`` and apply a high-contrast magma-like LUT."""
+ arr = np.asarray(mip, dtype=np.float64)
+ if arr.size == 0:
+ return np.zeros((size, size, 3), dtype=np.uint8)
+ yi = np.linspace(0, arr.shape[0] - 1, size).astype(np.intp)
+ xi = np.linspace(0, arr.shape[1] - 1, size).astype(np.intp)
+ resized = arr[np.ix_(yi, xi)]
+ lo = float(np.min(resized))
+ hi = float(np.percentile(resized, 99.5)) if resized.size > 1 else float(np.max(resized))
+ if hi <= lo:
+ hi = lo + 1.0
+ t = np.clip((resized - lo) / (hi - lo), 0.0, 1.0)
+ # Smooth 4-stop magma-like ramp: #0b0924 -> #6b1d5c -> #dc493a -> #f9e784
+ r = np.clip(11.0 + 235.0 * (t**0.75), 0.0, 255.0).astype(np.uint8)
+ g = np.clip(9.0 + 222.0 * (t**1.65), 0.0, 255.0).astype(np.uint8)
+ b = np.clip(36.0 + 140.0 * np.sin(np.pi * np.clip(t * 0.85, 0.0, 1.0)) + 80.0 * (t**3), 0.0, 255.0).astype(np.uint8)
+ return np.stack([r, g, b], axis=-1)
+
+
+def _stitch_three_mips_b64(mip_mu: np.ndarray, mip_chi: np.ndarray, mip_d: np.ndarray, tile: int = 40) -> str:
+ """Stitch ``(d, chi) | (mu, d) | (mu, chi)`` MIPs horizontally with 2-px dividers into one base64 PNG."""
+ t1 = _mip_to_magma_like_rgb(mip_mu, size=tile)
+ t2 = _mip_to_magma_like_rgb(mip_chi, size=tile)
+ t3 = _mip_to_magma_like_rgb(mip_d, size=tile)
+ sep = np.full((tile, 2, 3), 30, dtype=np.uint8)
+ strip = np.concatenate([t1, sep, t2, sep, t3], axis=1)
+ return _encode_rgb_png_base64(strip)
+
+
+def _read_csv(path: Path) -> list[dict[str, str]]:
+ if not path.exists() or path.stat().st_size == 0:
+ return []
+ with path.open(newline="") as f:
+ return list(csv.DictReader(f))
+
+
+def _read_json(path: Path) -> Any:
+ if not path.exists():
+ return None
+ try:
+ return json.loads(path.read_text())
+ except (OSError, json.JSONDecodeError):
+ return None
+
+
+def _collect_mip_thumbnails(
+ seg_dir: Path,
+ dataset_root: Path | None,
+ track_rows: list[dict[str, Any]],
+ priority_tids: list[int],
+ *,
+ max_tracks: int,
+) -> dict[str, str]:
+ """Extract compact 3-view MIP strips keyed by ``'{track_id}:{scan_idx}'`` via lazy HDF5 ROI reads."""
+ if not seg_dir.is_dir() or dataset_root is None or not dataset_root.is_dir():
+ return {}
+ try:
+ scans_fs = discover_operando_scans(dataset_root)
+ except Exception:
+ return {}
+ if not scans_fs:
+ return {}
+
+ scan_dirs = sorted(d for d in seg_dir.iterdir() if d.is_dir() and d.name.startswith("scan"))
+ scan_by_name = {s.scan_name: s for s in scans_fs}
+ selected = set(priority_tids[:max_tracks])
+ wanted_by_scan: dict[int, list[dict[str, Any]]] = {}
+ for r in track_rows:
+ tid = int(float(r["track_id"]))
+ if tid in selected and "bbox_min_z" in r and "label" in r:
+ s_idx = int(float(r["scan_idx"]))
+ wanted_by_scan.setdefault(s_idx, []).append(r)
+
+ thumbs: dict[str, str] = {}
+ with ExitStack() as stack:
+ for s_idx, obs_list in wanted_by_scan.items():
+ if s_idx >= len(scan_dirs):
+ continue
+ sd = scan_dirs[s_idx]
+ lab_path = sd / "labels.npz"
+ sf = scan_by_name.get(sd.name)
+ if not lab_path.exists() or sf is None:
+ continue
+ labels = np.load(lab_path)["labels"]
+ try:
+ lazy_vol: LazyVolume = stack.enter_context(open_lazy_volume(sf.path))
+ except (MissingH5DependencyError, KeyError, ValueError, OSError):
+ continue
+ if lazy_vol.shape != labels.shape:
+ continue
+ for obs in obs_list:
+ lid = int(float(obs["label"]))
+ tid = int(float(obs["track_id"]))
+ masked_cube, _ = crop_spot_cube(lazy_vol, labels, lid, obs, margin=2)
+ m_mu, m_chi, m_d = orthogonal_mips(masked_cube)
+ thumbs[f"{tid}:{s_idx}"] = _stitch_three_mips_b64(m_mu, m_chi, m_d, tile=38)
+ return thumbs
+
+
+def build_explorer_payload(
+ artifact_dir: str | Path,
+ *,
+ dataset_root: str | Path | None = None,
+ max_mip_tracks: int = 16,
+) -> dict[str, Any]:
+ """Assemble structured JSON payload for the interactive 4D explorer from pipeline/tracking outputs."""
+ root = Path(artifact_dir)
+ trk_dir = root / "tracking" if (root / "tracking").is_dir() else root
+ evt_dir = root / "events" if (root / "events").is_dir() else trk_dir
+ seg_dir = root / "segmentation" if (root / "segmentation").is_dir() else root.parent / "segmentation"
+
+ manifest = _read_json(root / "run_manifest.json") or {}
+ trk_summary = _read_json(trk_dir / "tracking_summary.json") or {}
+ evt_summary = _read_json(evt_dir / "events_summary.json") or {}
+
+ ds_root: Path | None = None
+ if dataset_root is not None:
+ ds_root = resolve_dataset_root(str(dataset_root))
+ elif manifest.get("dataset_root"):
+ cand = Path(str(manifest["dataset_root"]))
+ if cand.is_dir():
+ ds_root = cand
+
+ raw_tracks = _read_csv(evt_dir / "tracks.csv") or _read_csv(trk_dir / "tracks.csv")
+ raw_events = _read_csv(evt_dir / "events.csv") or _read_csv(trk_dir / "events.csv")
+ raw_precursors = _read_csv(evt_dir / "precursors.csv") or _read_csv(trk_dir / "precursors.csv")
+ raw_prec_obs = _read_csv(evt_dir / "precursor_observations.csv")
+
+ track_rows: list[dict[str, Any]] = []
+ for r in raw_tracks:
+ parsed: dict[str, Any] = {}
+ for k, v in r.items():
+ if k in ("event", "lineage_role", "parent_track_ids"):
+ parsed[k] = v
+ elif k in ("track_id", "scan_idx", "spot_idx", "label", "voxel_count"):
+ parsed[k] = int(float(v)) if v != "" else 0
+ else:
+ try:
+ parsed[k] = float(v)
+ except (TypeError, ValueError):
+ parsed[k] = v
+ track_rows.append(parsed)
+
+ gks = compute_grain_kinematics(track_rows) if track_rows else []
+ gk_by_tid = {g.track_id: g for g in gks}
+
+ prec_obs_by_key: dict[tuple[int, int], dict[str, float]] = {}
+ for r in raw_prec_obs:
+ key = (int(float(r["track_id"])), int(float(r["scan_idx"])))
+ prec_obs_by_key[key] = {
+ "score": float(r.get("precursor_score", 0.0)),
+ "anisotropy_term": float(r.get("anisotropy_term", 0.0)),
+ "spread_term": float(r.get("spread_term", 0.0)),
+ "roi_dispersion_term": float(r.get("roi_dispersion_term", 0.0)),
+ "subpeaks": int(float(r.get("roi_subpeak_count", 1))),
+ }
+
+ events_list: list[dict[str, Any]] = []
+ split_tids: set[int] = set()
+ merge_tids: set[int] = set()
+ for r in raw_events:
+ ptids = [int(x) for x in str(r.get("parent_track_ids", "")).split(";") if x.strip()]
+ ctids = [int(x) for x in str(r.get("child_track_ids", "")).split(";") if x.strip()]
+ etype = str(r.get("event_type", ""))
+ if etype == "split":
+ split_tids.update(ptids)
+ split_tids.update(ctids)
+ elif etype == "merge":
+ merge_tids.update(ptids)
+ merge_tids.update(ctids)
+ events_list.append(
+ {
+ "event_type": etype,
+ "parent_scan": int(float(r.get("scan_idx_from", r.get("parent_scan", 0)))),
+ "child_scan": int(float(r.get("scan_idx_to", r.get("child_scan", 1)))),
+ "parent_track_ids": ptids,
+ "child_track_ids": ctids,
+ "intensity_ratio": round(float(r.get("intensity_ratio", 1.0)), 3),
+ "centroid_distance": round(float(r.get("mean_distance", r.get("centroid_distance", 0.0))), 3),
+ "confidence": round(float(r.get("confidence", 0.0)), 3),
+ }
+ )
+
+ precursors_list: list[dict[str, Any]] = []
+ prec_tids: set[int] = set()
+ for r in raw_precursors:
+ tid = int(float(r["track_id"]))
+ prec_tids.add(tid)
+ precursors_list.append(
+ {
+ "rank": int(float(r.get("rank", 0))),
+ "track_id": tid,
+ "onset_scan": int(float(r.get("onset_scan", 0))),
+ "peak_scan": int(float(r.get("peak_scan", 0))),
+ "persistence_scans": int(float(r.get("persistence_scans", 0))),
+ "peak_score": round(float(r.get("peak_score", 0.0)), 4),
+ "max_anisotropy": round(float(r.get("max_anisotropy", 1.0)), 3),
+ "max_subpeak_count": int(float(r.get("max_subpeak_count", 1))),
+ "confidence": round(float(r.get("confidence", 0.0)), 4),
+ "subsequent_split": str(r.get("subsequent_split", "")).lower() == "true",
+ }
+ )
+
+ by_tid: dict[int, list[dict[str, Any]]] = {}
+ for r in track_rows:
+ by_tid.setdefault(int(r["track_id"]), []).append(r)
+
+ n_scans = int(trk_summary.get("n_scans") or evt_summary.get("n_scans") or 0)
+ if n_scans == 0 and track_rows:
+ n_scans = max(int(r["scan_idx"]) for r in track_rows) + 1
+
+ priority_tids = sorted(
+ by_tid.keys(),
+ key=lambda tid: (
+ 0 if (tid in split_tids or tid in merge_tids or tid in prec_tids) else 1,
+ -len(by_tid[tid]),
+ -max(float(x.get("integrated_intensity", 0.0)) for x in by_tid[tid]),
+ tid,
+ ),
+ )
+ thumbs = _collect_mip_thumbnails(seg_dir, ds_root, track_rows, priority_tids, max_tracks=max_mip_tracks)
+
+ tracks_payload: list[dict[str, Any]] = []
+ for tid in sorted(by_tid.keys(), key=lambda t: (float(by_tid[t][0]["centroid_d"]), t)):
+ obs_sorted = sorted(by_tid[tid], key=lambda x: int(x["scan_idx"]))
+ gk = gk_by_tid.get(tid)
+ scans = [int(x["scan_idx"]) for x in obs_sorted]
+ has_gap = any(scans[i + 1] - scans[i] > 1 for i in range(len(scans) - 1))
+ is_full = n_scans > 0 and min(scans) == 0 and max(scans) >= n_scans - 1
+
+ obs_items: list[dict[str, Any]] = []
+ for idx_o, o in enumerate(obs_sorted):
+ s_i = int(o["scan_idx"])
+ strain_pct = float(gk.strain[idx_o] * 100.0) if gk is not None and idx_o < len(gk.strain) else 0.0
+ miso = (
+ float(gk.misorientation_total[idx_o])
+ if gk is not None and idx_o < len(gk.misorientation_total)
+ else 0.0
+ )
+ aniso = float(gk.anisotropy[idx_o]) if gk is not None and idx_o < len(gk.anisotropy) else 1.0
+ po = prec_obs_by_key.get((tid, s_i), {})
+ obs_items.append(
+ {
+ "scan_idx": s_i,
+ "label": int(o.get("label", 0)),
+ "mu": round(float(o["centroid_mu"]), 4),
+ "chi": round(float(o["centroid_chi"]), 4),
+ "d": round(float(o["centroid_d"]), 4),
+ "intensity": round(float(o.get("integrated_intensity", 0.0)), 2),
+ "voxels": int(o.get("voxel_count", 0)),
+ "strain_pct": round(strain_pct, 4),
+ "misorientation": round(miso, 4),
+ "anisotropy": round(aniso, 3),
+ "precursor_score": round(float(po.get("score", 0.0)), 4),
+ "roi_dispersion_term": round(float(po.get("roi_dispersion_term", 0.0)), 4),
+ "subpeaks": int(po.get("subpeaks", 1)),
+ "mip_b64": thumbs.get(f"{tid}:{s_i}"),
+ }
+ )
+
+ tracks_payload.append(
+ {
+ "track_id": tid,
+ "is_full": is_full,
+ "has_gap": has_gap,
+ "is_split": tid in split_tids,
+ "is_merge": tid in merge_tids,
+ "is_precursor": tid in prec_tids,
+ "max_abs_strain_pct": round(max((abs(x["strain_pct"]) for x in obs_items), default=0.0), 4),
+ "max_precursor": round(max((x["precursor_score"] for x in obs_items), default=0.0), 4),
+ "observations": obs_items,
+ }
+ )
+
+ scan_names = (
+ trk_summary.get("scan_names") or evt_summary.get("scan_names") or [f"scan{i + 1:04d}" for i in range(n_scans)]
+ )
+ return {
+ "title": f"BraggTrack 4D Explorer — {Path(manifest.get('dataset_root') or root).name}",
+ "schema_version": "report.v1",
+ "n_scans": n_scans,
+ "scan_names": scan_names,
+ "calibrated_axes": bool(trk_summary.get("calibrated_axes", False)),
+ "backend": evt_summary.get("backend") or manifest.get("config", {}).get("backend") or "n/a",
+ "model": evt_summary.get("model") or manifest.get("config", {}).get("model") or "n/a",
+ "braggtrack_version": manifest.get("braggtrack_version", "0.3.0"),
+ "total_duration_sec": manifest.get("total_duration_sec"),
+ "kpis": {
+ "total_tracks": len(tracks_payload),
+ "full_length_tracks": sum(1 for t in tracks_payload if t["is_full"]),
+ "gap_closed_count": int(trk_summary.get("gap_closed_count", evt_summary.get("gap_closed_count", 0))),
+ "split_count": sum(1 for e in events_list if e["event_type"] == "split"),
+ "merge_count": sum(1 for e in events_list if e["event_type"] == "merge"),
+ "precursor_count": len(precursors_list),
+ },
+ "tracks": tracks_payload,
+ "events": events_list,
+ "precursors": precursors_list,
+ }
+
+
+_HTML_TEMPLATE = """
+
+
+
+
+__TITLE__
+
+
+
+
+
+
BraggTrack 4D Explorer
+
+
+
+
+
+
+
+
+ 4D Trajectory & Lineage DAG
+ Click any track node to inspect
+
+
+
+
+
+
+ Track Inspector
+
+
+
+
+
+
+
+
+
Split & Merge Lineage Events
+
+
+
+
Persistent Fracture Precursor Candidates
+
+
+
+
+
+
+
+"""
+
+
+def generate_html_report(
+ artifact_dir: str | Path,
+ out_html: str | Path | None = None,
+ *,
+ dataset_root: str | Path | None = None,
+ max_mip_tracks: int = 16,
+) -> Path:
+ """Render a self-contained interactive HTML 4D explorer from a BraggTrack output directory."""
+ root = Path(artifact_dir)
+ dest = Path(out_html) if out_html is not None else (root / "report.html")
+ dest.parent.mkdir(parents=True, exist_ok=True)
+
+ payload = build_explorer_payload(root, dataset_root=dataset_root, max_mip_tracks=max_mip_tracks)
+ safe_json = json.dumps(payload).replace("", "<\\/")
+ html_doc = _HTML_TEMPLATE.replace("__TITLE__", html.escape(str(payload["title"]))).replace(
+ "__PAYLOAD_JSON__", safe_json
+ )
+ dest.write_text(html_doc, encoding="utf-8")
+ return dest
diff --git a/braggtrack/viz/kinematics.py b/braggtrack/viz/kinematics.py
new file mode 100644
index 0000000..2496469
--- /dev/null
+++ b/braggtrack/viz/kinematics.py
@@ -0,0 +1,103 @@
+"""Multi-panel per-grain kinematics dashboard (strain, misorientation, and intensity/anisotropy)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from braggtrack.tracking.kinematics import GrainKinematics, compute_grain_kinematics
+
+from ._style import OKABE_ITO, _require_matplotlib, apply_axis_style, maybe_save
+
+
+def plot_kinematics_dashboard(
+ kinematics_or_tracks: list[GrainKinematics] | list[dict[str, Any]],
+ *,
+ events: list[Any] | None = None,
+ max_tracks: int = 12,
+ calibrated: bool = False,
+ title: str | None = None,
+ save_path: str | Path | None = None,
+) -> tuple[Any, Any]:
+ """Plot 3-panel kinematic evolution: lattice strain, angular misorientation, and intensity/anisotropy."""
+ _, plt = _require_matplotlib()
+
+ if kinematics_or_tracks and isinstance(kinematics_or_tracks[0], GrainKinematics):
+ gks: list[GrainKinematics] = list(kinematics_or_tracks) # type: ignore[arg-type]
+ else:
+ rows = [dict(r) for r in kinematics_or_tracks] # type: ignore[arg-type]
+ if rows and "strain" in rows[0] and "misorientation_total" in rows[0] and "relative_intensity" in rows[0]:
+ # Reconstruct GrainKinematics from kinematics.csv rows or compute from tracks.csv rows
+ gks = compute_grain_kinematics(rows)
+ else:
+ gks = compute_grain_kinematics(rows)
+
+ fig, axes = plt.subplots(1, 3, figsize=(13.5, 4.2))
+ if not gks:
+ for ax in axes:
+ apply_axis_style(ax)
+ fig.suptitle(title or "Per-Grain Kinematics Dashboard (empty)")
+ maybe_save(fig, save_path)
+ return fig, axes
+
+ ranked = sorted(gks, key=lambda g: (-len(g.scan_indices), -float(g.integrated_intensity[0]), g.track_id))[
+ :max_tracks
+ ]
+
+ for idx, gk in enumerate(ranked):
+ color = OKABE_ITO[idx % len(OKABE_ITO)]
+ lbl = f"T{gk.track_id}"
+ scans = gk.scan_indices
+ axes[0].plot(scans, 100.0 * gk.strain, "o-", color=color, linewidth=1.7, markersize=4.5, label=lbl)
+ axes[1].plot(scans, gk.misorientation_total, "o-", color=color, linewidth=1.7, markersize=4.5, label=lbl)
+ axes[2].plot(scans, gk.anisotropy, "s-", color=color, linewidth=1.6, markersize=4.0, label=lbl)
+
+ for ev in events or []:
+ etype = ev.get("event_type") if isinstance(ev, dict) else getattr(ev, "event_type", "")
+ raw_scan = (
+ ev.get("scan_idx_to", ev.get("child_scan", 0))
+ if isinstance(ev, dict)
+ else getattr(ev, "scan_idx_to", getattr(ev, "child_scan", 0))
+ )
+ cscan = int(float(raw_scan))
+ ev_col = OKABE_ITO[1] if etype == "split" else OKABE_ITO[2]
+ for ax in axes:
+ ax.axvline(cscan - 0.5, linestyle=":", linewidth=1.2, color=ev_col, alpha=0.8)
+
+ strain_label = (
+ r"Lattice strain $\varepsilon = \Delta d / d_0$ (%)"
+ if calibrated
+ else r"Relative $d$-shift $\Delta d / d_0$ (%)"
+ )
+ miso_label = (
+ r"Misorientation $\sqrt{\Delta\mu^2 + \Delta\chi^2}$ (deg)"
+ if calibrated
+ else r"Angular shift $\sqrt{\Delta\mu^2 + \Delta\chi^2}$ (px)"
+ )
+
+ axes[0].axhline(0.0, color="#94A3B8", linewidth=0.8)
+ axes[0].set_title("Strain / d-Spacing Evolution", fontsize=10, fontweight="bold")
+ axes[0].set_ylabel(strain_label, fontsize=8.8)
+
+ axes[1].set_title("Lattice Rotation / Misorientation", fontsize=10, fontweight="bold")
+ axes[1].set_ylabel(miso_label, fontsize=8.8)
+
+ axes[2].set_title(r"3D Shape Anisotropy ($\lambda_1 / \lambda_3$)", fontsize=10, fontweight="bold")
+ axes[2].set_ylabel(r"Eigenvalue ratio $\lambda_1 / \lambda_3$", fontsize=8.8)
+
+ for ax in axes:
+ ax.set_xlabel("Scan index", fontsize=9)
+ apply_axis_style(ax)
+
+ if len(ranked) <= 10:
+ axes[0].legend(fontsize=7.5, ncol=2, frameon=True)
+
+ fig.suptitle(
+ title or f"Operando Grain Kinematics ({'Calibrated Physical Units' if calibrated else 'Detector Units'})",
+ fontsize=11,
+ fontweight="bold",
+ y=1.02,
+ )
+ fig.tight_layout()
+ maybe_save(fig, save_path)
+ return fig, axes
diff --git a/braggtrack/viz/lineage.py b/braggtrack/viz/lineage.py
new file mode 100644
index 0000000..4dff72a
--- /dev/null
+++ b/braggtrack/viz/lineage.py
@@ -0,0 +1,216 @@
+"""Publication-grade 4D trajectory and split/merge lineage DAG visualization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import networkx as nx
+import numpy as np
+
+from braggtrack.tracking.lifecycle import tracks_to_table
+
+from ._style import OKABE_ITO, _require_matplotlib, apply_axis_style, maybe_save
+
+
+def _parse_int_list(val: Any) -> list[int]:
+ if val is None or val == "":
+ return []
+ if isinstance(val, (list, tuple)):
+ return [int(x) for x in val]
+ return [int(tok) for tok in str(val).split(";") if tok.strip()]
+
+
+def plot_lineage_dag(
+ tracks_or_graph: nx.DiGraph | list[dict[str, Any]],
+ *,
+ events: list[Any] | None = None,
+ max_tracks: int = 40,
+ title: str | None = None,
+ save_path: str | Path | None = None,
+) -> tuple[Any, Any]:
+ """Plot a scan-layered 4D trajectory & lineage DAG highlighting splits, merges, and gap closures."""
+ _, plt = _require_matplotlib()
+
+ if isinstance(tracks_or_graph, nx.DiGraph):
+ rows = tracks_to_table(tracks_or_graph)
+ if events is None:
+ events = list(tracks_or_graph.graph.get("lineage_events", []))
+ else:
+ rows = [dict(r) for r in tracks_or_graph]
+
+ fig, ax = plt.subplots(figsize=(9.5, 5.2))
+ if not rows:
+ ax.set_title(title or "4D Trajectory Lineage DAG (empty)")
+ apply_axis_style(ax)
+ maybe_save(fig, save_path)
+ return fig, ax
+
+ by_track: dict[int, list[dict[str, Any]]] = {}
+ for r in rows:
+ by_track.setdefault(int(float(r["track_id"])), []).append(r)
+ for tid in by_track:
+ by_track[tid].sort(key=lambda r: int(float(r["scan_idx"])))
+
+ # Prioritize tracks involved in split/merge events, then longest & brightest tracks.
+ event_records: list[dict[str, Any]] = []
+ involved_tids: set[int] = set()
+ for ev in events or []:
+ if isinstance(ev, dict):
+ etype = str(ev.get("event_type", ""))
+ pscan = int(float(ev.get("scan_idx_from", ev.get("parent_scan", 0))))
+ cscan = int(float(ev.get("scan_idx_to", ev.get("child_scan", pscan + 1))))
+ ptids = _parse_int_list(ev.get("parent_track_ids"))
+ ctids = _parse_int_list(ev.get("child_track_ids"))
+ else:
+ etype = str(getattr(ev, "event_type", ""))
+ pscan = int(getattr(ev, "scan_idx_from", getattr(ev, "parent_scan", 0)))
+ cscan = int(getattr(ev, "scan_idx_to", getattr(ev, "child_scan", pscan + 1)))
+ ptids = [int(x) for x in getattr(ev, "parent_track_ids", ())]
+ ctids = [int(x) for x in getattr(ev, "child_track_ids", ())]
+ event_records.append(
+ {
+ "event_type": etype,
+ "parent_scan": pscan,
+ "child_scan": cscan,
+ "parent_track_ids": ptids,
+ "child_track_ids": ctids,
+ }
+ )
+ involved_tids.update(ptids)
+ involved_tids.update(ctids)
+
+ ranked_tids = sorted(
+ by_track.keys(),
+ key=lambda tid: (
+ 0 if tid in involved_tids else 1,
+ -len(by_track[tid]),
+ -max(float(r.get("integrated_intensity", 0.0)) for r in by_track[tid]),
+ tid,
+ ),
+ )[:max_tracks]
+ selected_set = set(ranked_tids)
+
+ # Order vertical lanes by initial centroid_d so spatially nearby fragments sit adjacent.
+ ordered_tids = sorted(ranked_tids, key=lambda tid: (float(by_track[tid][0]["centroid_d"]), tid))
+ lane_y = {tid: float(idx) for idx, tid in enumerate(ordered_tids)}
+
+ node_xy: dict[tuple[int, int], tuple[float, float]] = {}
+ all_x: list[float] = []
+ all_y: list[float] = []
+ all_strain: list[float] = []
+
+ gap_labeled = False
+ cont_labeled = False
+ for tid in ordered_tids:
+ obs = by_track[tid]
+ y_val = lane_y[tid]
+ d0 = float(obs[0]["centroid_d"])
+ scans = [int(float(r["scan_idx"])) for r in obs]
+ for r in obs:
+ s_idx = int(float(r["scan_idx"]))
+ d_cur = float(r["centroid_d"])
+ strain_pct = 100.0 * (d_cur - d0) / d0 if abs(d0) > 1e-9 else 0.0
+ node_xy[(tid, s_idx)] = (float(s_idx), y_val)
+ all_x.append(float(s_idx))
+ all_y.append(y_val)
+ all_strain.append(strain_pct)
+
+ for i in range(len(scans) - 1):
+ s0, s1 = scans[i], scans[i + 1]
+ if s1 - s0 > 1:
+ ax.plot(
+ [s0, s1],
+ [y_val, y_val],
+ linestyle="--",
+ linewidth=1.8,
+ color=OKABE_ITO[4],
+ label="Gap-closed bridge" if not gap_labeled else None,
+ zorder=2,
+ )
+ gap_labeled = True
+ else:
+ ax.plot(
+ [s0, s1],
+ [y_val, y_val],
+ linestyle="-",
+ linewidth=1.8,
+ color="#64748B",
+ alpha=0.75,
+ label="Continuation" if not cont_labeled else None,
+ zorder=2,
+ )
+ cont_labeled = True
+
+ split_labeled = False
+ merge_labeled = False
+ for ev in event_records:
+ etype = ev["event_type"]
+ pscan = ev["parent_scan"]
+ cscan = ev["child_scan"]
+ for ptid in ev["parent_track_ids"]:
+ for ctid in ev["child_track_ids"]:
+ if ptid not in selected_set or ctid not in selected_set:
+ continue
+ p_xy = node_xy.get((ptid, pscan), (float(pscan), lane_y[ptid]))
+ c_xy = node_xy.get((ctid, cscan), (float(cscan), lane_y[ctid]))
+ color = OKABE_ITO[1] if etype == "split" else OKABE_ITO[2]
+ lbl = None
+ if etype == "split" and not split_labeled:
+ lbl = "1 -> 2+ Split"
+ split_labeled = True
+ elif etype == "merge" and not merge_labeled:
+ lbl = "2+ -> 1 Merge"
+ merge_labeled = True
+ ax.plot(
+ [p_xy[0], c_xy[0]],
+ [p_xy[1], c_xy[1]],
+ color=color,
+ linewidth=2.4,
+ alpha=0.92,
+ label=lbl,
+ zorder=3,
+ )
+ ax.scatter(
+ [c_xy[0] if etype == "split" else p_xy[0]],
+ [c_xy[1] if etype == "split" else p_xy[1]],
+ marker="D" if etype == "split" else "s",
+ s=58,
+ color=color,
+ edgecolor="#FFFFFF",
+ linewidth=0.8,
+ zorder=5,
+ )
+
+ vmax = max(0.05, float(np.max(np.abs(all_strain)))) if all_strain else 0.1
+ sc = ax.scatter(
+ all_x,
+ all_y,
+ c=all_strain,
+ cmap="coolwarm",
+ vmin=-vmax,
+ vmax=vmax,
+ s=42,
+ edgecolors="#1E293B",
+ linewidths=0.6,
+ zorder=4,
+ )
+ cbar = fig.colorbar(sc, ax=ax, pad=0.02)
+ cbar.set_label(r"Relative $d$-shift $\Delta d / d_0$ (%)", fontsize=9)
+
+ ax.set_yticks([lane_y[tid] for tid in ordered_tids])
+ ax.set_yticklabels([f"T{tid}" for tid in ordered_tids], fontsize=8)
+ max_scan = int(max(all_x)) if all_x else 0
+ ax.set_xticks(list(range(max_scan + 1)))
+ ax.set_xlabel("Scan index", fontsize=9.5)
+ ax.set_ylabel("Grain trajectory lane", fontsize=9.5)
+ ax.set_title(
+ title or f"4D Bragg Reflection Lineage DAG ({len(ordered_tids)} tracks)", fontsize=11, fontweight="bold"
+ )
+ apply_axis_style(ax)
+ handles, labels_legend = ax.get_legend_handles_labels()
+ if handles:
+ ax.legend(loc="upper left", fontsize=8, frameon=True)
+ fig.tight_layout()
+ maybe_save(fig, save_path)
+ return fig, ax
diff --git a/braggtrack/viz/mips.py b/braggtrack/viz/mips.py
new file mode 100644
index 0000000..8328f37
--- /dev/null
+++ b/braggtrack/viz/mips.py
@@ -0,0 +1,104 @@
+"""Orthogonal 3-view MIP spot cards and full-scan projection overlays."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from braggtrack.semantic.mips import crop_spot_cube, orthogonal_mips
+
+from ._style import _require_matplotlib, apply_axis_style, maybe_save
+
+
+def plot_spot_mip_card(
+ volume: np.ndarray | Any,
+ labels: np.ndarray,
+ label_id: int,
+ bbox: dict[str, Any],
+ *,
+ margin: int = 3,
+ title: str | None = None,
+ save_path: str | Path | None = None,
+) -> tuple[Any, Any]:
+ """Plot a 3-panel orthogonal MIP card ``(d, chi)``, ``(mu, d)``, ``(mu, chi)`` for one 3D reflection."""
+ _, plt = _require_matplotlib()
+ masked_cube, mask = crop_spot_cube(volume, labels, int(label_id), bbox, margin=margin)
+ mip_mu, mip_chi, mip_d = orthogonal_mips(masked_cube)
+ mask_mu, mask_chi, mask_d = orthogonal_mips(mask)
+
+ fig, axes = plt.subplots(1, 3, figsize=(10.5, 3.4))
+ panels = [
+ (mip_mu, mask_mu, r"$\mu$-collapsed $(d, \chi)$", r"$\chi$ (px)", r"$d$ (px)"),
+ (mip_chi, mask_chi, r"$\chi$-collapsed $(\mu, d)$", r"$d$ (px)", r"$\mu$ (frame)"),
+ (mip_d, mask_d, r"$d$-collapsed $(\mu, \chi)$", r"$\chi$ (px)", r"$\mu$ (frame)"),
+ ]
+
+ for ax, (mip, msk, subtitle, xlabel, ylabel) in zip(axes, panels):
+ im = ax.imshow(mip, cmap="magma", origin="lower", aspect="auto")
+ if msk.shape[0] >= 2 and msk.shape[1] >= 2 and np.any(msk > 0) and np.any(msk == 0):
+ ax.contour(msk, levels=[0.5], colors=["#56B4E9"], linewidths=1.1)
+ ax.set_title(subtitle, fontsize=9.5, fontweight="bold")
+ ax.set_xlabel(xlabel, fontsize=8.5)
+ ax.set_ylabel(ylabel, fontsize=8.5)
+ fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+
+ vox = int(np.sum(mask > 0))
+ tot_int = float(np.sum(masked_cube))
+ header = title or f"Spot #{label_id} | {vox} voxels | I = {tot_int:.1f}"
+ fig.suptitle(header, fontsize=10.5, fontweight="bold", y=1.02)
+ fig.tight_layout()
+ maybe_save(fig, save_path)
+ return fig, axes
+
+
+def plot_scan_projection_overlay(
+ volume: np.ndarray | Any,
+ labels: np.ndarray,
+ feature_rows: list[dict[str, Any]],
+ *,
+ max_labels: int = 25,
+ title: str | None = None,
+ save_path: str | Path | None = None,
+) -> tuple[Any, Any]:
+ """Plot a full-scan ``(d, chi)`` MIP with instance contours and ranked spot IDs."""
+ _, plt = _require_matplotlib()
+ vol_arr = volume[()] if not isinstance(volume, np.ndarray) else volume
+ mip_dc = np.max(np.asarray(vol_arr, dtype=np.float64), axis=0)
+ disp = np.log1p(np.maximum(0.0, mip_dc))
+ fg_proj = np.max(labels > 0, axis=0).astype(np.float64)
+
+ fig, ax = plt.subplots(figsize=(7.5, 6.0))
+ im = ax.imshow(disp, cmap="inferno", origin="lower", aspect="auto")
+ if fg_proj.shape[0] >= 2 and fg_proj.shape[1] >= 2 and np.any(fg_proj > 0) and np.any(fg_proj == 0):
+ ax.contour(fg_proj, levels=[0.5], colors=["#56B4E9"], linewidths=0.8, alpha=0.8)
+
+ ranked = sorted(feature_rows, key=lambda r: float(r.get("integrated_intensity", 0.0)), reverse=True)[:max_labels]
+ for row in ranked:
+ if "bbox_min_x" in row and "bbox_max_x" in row:
+ cx = 0.5 * (float(row["bbox_min_x"]) + float(row["bbox_max_x"]))
+ cy = 0.5 * (float(row["bbox_min_y"]) + float(row["bbox_max_y"]))
+ else:
+ cx = float(row["centroid_chi"])
+ cy = float(row["centroid_d"])
+ lid = int(float(row["label"]))
+ ax.plot(cx, cy, marker="+", color="#00E5FF", markersize=6, markeredgewidth=1.2)
+ ax.annotate(
+ f"#{lid}",
+ (cx, cy),
+ xytext=(4, 4),
+ textcoords="offset points",
+ fontsize=7.5,
+ color="#FFFFFF",
+ bbox={"boxstyle": "round,pad=0.15", "fc": "#111827", "ec": "none", "alpha": 0.65},
+ )
+
+ ax.set_title(title or f"Detector Projection (log1p MIP) — {len(feature_rows)} segmented reflections", fontsize=10.5)
+ ax.set_xlabel(r"Detector $\chi$ / fast pixel", fontsize=9)
+ ax.set_ylabel(r"Detector $d$ / slow pixel", fontsize=9)
+ apply_axis_style(ax)
+ fig.colorbar(im, ax=ax, label="log(1 + max intensity)")
+ fig.tight_layout()
+ maybe_save(fig, save_path)
+ return fig, ax
diff --git a/braggtrack/viz/precursors.py b/braggtrack/viz/precursors.py
new file mode 100644
index 0000000..771fcad
--- /dev/null
+++ b/braggtrack/viz/precursors.py
@@ -0,0 +1,149 @@
+"""Persistent 4D fracture precursor heatmap and component decomposition plots."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from braggtrack.tracking.precursors import ObservationPrecursorScore, PrecursorCandidate
+
+from ._style import OKABE_ITO, _require_matplotlib, apply_axis_style, maybe_save
+
+
+def _obs_to_dict(obs: ObservationPrecursorScore | dict[str, Any]) -> dict[str, Any]:
+ if isinstance(obs, dict):
+ return {
+ "track_id": int(float(obs["track_id"])),
+ "scan_idx": int(float(obs["scan_idx"])),
+ "anisotropy_term": float(obs.get("anisotropy_term", 0.0)),
+ "spread_term": float(obs.get("spread_term", 0.0)),
+ "roi_dispersion_term": float(obs.get("roi_dispersion_term", 0.0)),
+ "roi_subpeak_count": int(float(obs.get("roi_subpeak_count", 1))),
+ "precursor_score": float(obs.get("precursor_score", 0.0)),
+ }
+ return {
+ "track_id": obs.track_id,
+ "scan_idx": obs.scan_idx,
+ "anisotropy_term": obs.anisotropy_term,
+ "spread_term": obs.spread_term,
+ "roi_dispersion_term": obs.roi_dispersion_term,
+ "roi_subpeak_count": obs.roi_subpeak_count,
+ "precursor_score": obs.precursor_score,
+ }
+
+
+def plot_precursor_timeline(
+ obs_scores: list[ObservationPrecursorScore] | list[dict[str, Any]],
+ *,
+ candidates: list[PrecursorCandidate] | list[dict[str, Any]] | None = None,
+ max_tracks: int = 15,
+ score_threshold: float = 0.40,
+ title: str | None = None,
+ save_path: str | Path | None = None,
+) -> tuple[Any, Any]:
+ """Plot a track-by-scan fracture precursor heatmap and top-candidate component decomposition."""
+ _, plt = _require_matplotlib()
+ rows = [_obs_to_dict(x) for x in obs_scores]
+
+ fig, axes = plt.subplots(1, 2, figsize=(12.0, 4.4), gridspec_kw={"width_ratios": [1.15, 1.0]})
+ if not rows:
+ for ax in axes:
+ apply_axis_style(ax)
+ fig.suptitle(title or "Fracture Precursor Timeline (no observations)")
+ maybe_save(fig, save_path)
+ return fig, axes
+
+ by_track: dict[int, list[dict[str, Any]]] = {}
+ max_scan = 0
+ for r in rows:
+ by_track.setdefault(r["track_id"], []).append(r)
+ if r["scan_idx"] > max_scan:
+ max_scan = r["scan_idx"]
+
+ split_tids: set[int] = set()
+ top_tid: int | None = None
+ for idx_c, c in enumerate(candidates or []):
+ tid_c = int(float(c["track_id"])) if isinstance(c, dict) else int(c.track_id)
+ sub_split = (
+ str(c.get("subsequent_split", "")).lower() == "true" if isinstance(c, dict) else bool(c.subsequent_split)
+ )
+ if idx_c == 0:
+ top_tid = tid_c
+ if sub_split:
+ split_tids.add(tid_c)
+
+ ranked_tids = sorted(
+ by_track.keys(),
+ key=lambda tid: (-max(x["precursor_score"] for x in by_track[tid]), tid),
+ )[:max_tracks]
+ if top_tid is None and ranked_tids:
+ top_tid = ranked_tids[0]
+
+ mat = np.full((len(ranked_tids), max_scan + 1), np.nan, dtype=np.float64)
+ for r_i, tid in enumerate(ranked_tids):
+ for r in by_track[tid]:
+ mat[r_i, r["scan_idx"]] = r["precursor_score"]
+
+ im = axes[0].imshow(mat, aspect="auto", cmap="YlOrRd", vmin=0.0, vmax=1.0, interpolation="nearest")
+ axes[0].set_yticks(list(range(len(ranked_tids))))
+ axes[0].set_yticklabels(
+ [f"T{tid} *" if tid in split_tids else f"T{tid}" for tid in ranked_tids],
+ fontsize=8.5,
+ )
+ axes[0].set_xticks(list(range(max_scan + 1)))
+ axes[0].set_xlabel("Scan index", fontsize=9)
+ axes[0].set_ylabel("Track ID (* = subsequent split)", fontsize=9)
+ axes[0].set_title("Precursor Score Heatmap", fontsize=10, fontweight="bold")
+ fig.colorbar(im, ax=axes[0], fraction=0.046, pad=0.04, label="Precursor score")
+
+ # Right panel: component breakdown for top candidate
+ if top_tid is not None and top_tid in by_track:
+ top_obs = sorted(by_track[top_tid], key=lambda x: x["scan_idx"])
+ scans = [x["scan_idx"] for x in top_obs]
+ axes[1].plot(
+ scans,
+ [x["anisotropy_term"] for x in top_obs],
+ "o--",
+ color=OKABE_ITO[0],
+ linewidth=1.4,
+ label="Shape anisotropy",
+ )
+ axes[1].plot(
+ scans,
+ [x["spread_term"] for x in top_obs],
+ "s--",
+ color=OKABE_ITO[2],
+ linewidth=1.4,
+ label="Covariance broadening",
+ )
+ axes[1].plot(
+ scans,
+ [x["roi_dispersion_term"] for x in top_obs],
+ "^--",
+ color=OKABE_ITO[3],
+ linewidth=1.4,
+ label="3D sub-peaks + DINO dispersion",
+ )
+ axes[1].plot(
+ scans,
+ [x["precursor_score"] for x in top_obs],
+ "o-",
+ color=OKABE_ITO[1],
+ linewidth=2.2,
+ label=f"Composite score (T{top_tid})",
+ )
+ axes[1].axhline(score_threshold, linestyle=":", color="#475569", linewidth=1.2, label="Threshold")
+ axes[1].set_ylim(-0.04, 1.06)
+ axes[1].set_xticks(list(range(max_scan + 1)))
+ axes[1].set_xlabel("Scan index", fontsize=9)
+ axes[1].set_ylabel("Normalized term [0, 1]", fontsize=9)
+ axes[1].set_title(f"Top Precursor Decomposition — Track T{top_tid}", fontsize=10, fontweight="bold")
+ axes[1].legend(fontsize=7.8, loc="best", frameon=True)
+ apply_axis_style(axes[1])
+
+ fig.suptitle(title or "Persistent 4D Fracture Precursor Analysis", fontsize=11, fontweight="bold", y=1.02)
+ fig.tight_layout()
+ maybe_save(fig, save_path)
+ return fig, axes
diff --git a/docs/architecture.md b/docs/architecture.md
index 7f9e002..c8efe27 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -6,17 +6,18 @@ This document describes how the repository is structured, how data flows through
```text
BraggTrack/
-├── braggtrack/ # Installable Python package (v0.2.0)
-│ ├── io/ # Discovery, ESRF-ID03 / NeXus HDF5 auto-discovery, AxisCalibration, validation
-│ ├── segmentation/ # Classical 3D LoG+watershed, cross-scan threshold smoothing, experimental DINO segmenter, features
+├── braggtrack/ # Installable Python package (v0.3.0)
+│ ├── io/ # Discovery, LazyVolume streaming, AxisCalibration, DetectorGeometry, ImageD11 & NeXus export
+│ ├── segmentation/ # Classical 3D LoG+watershed, chunked Otsu + threshold smoothing, experimental DINO segmenter
│ ├── semantic/ # Orthogonal (mu, chi, d) MIPs + frozen ViT / patch encoders (DINOv2 default, DINOv3, mock)
-│ ├── tracking/ # Costs, Hungarian assignment, kinematics, split/merge lineage DAG, fracture precursors
-│ └── cli/ # Thin argparse entry points + reproducible run_pipeline orchestrator
+│ ├── tracking/ # Costs, Hungarian assignment, multi-scan gap closing, kinematics, split/merge DAG, precursors
+│ ├── viz/ # Publication plots (MIPs, Lineage DAG, Strain fans, Precursors) + interactive HTML 4D Explorer
+│ └── cli/ # Thin argparse entry points (9 CLIs) + reproducible run_pipeline orchestrator
├── data/
│ └── sample_operando/ # Bundled ESRF-ID03 Ni-rich cathode operando scans (scan0001..scan0003)
├── notebooks/ # End-to-end demo and DINO vs. classical segmentation notebooks
-├── docs/ # Architecture & coding practices
-├── scripts/ # Acceptance gates, semantic ablation with bootstrap CIs, ci_report.py
+├── docs/ # Architecture, quantitative benchmarks, figures, and coding practices
+├── scripts/ # 9 acceptance gates, 5-scenario benchmark suite, semantic ablation, ci_report.py
├── tests/ # Unit and acceptance test suite
└── artifacts/ # Generated outputs (gitignored)
```
@@ -25,11 +26,12 @@ BraggTrack/
| Layer | Responsibility | Key Types / Functions | Depends on |
|---|---|---|---|
-| **io** | Discover scans, auto-discover 3D HDF5 cubes, extract timestamps & `AxisCalibration`, validate sequences | `ScanVolumeMeta`, `AxisCalibration`, `load_primary_volume`, `BeamlineAdapter` | `numpy`, `h5py` |
+| **io** | Discover scans, stream `LazyVolume` HDF5 slices & chunked Otsu histograms, calibrate `(mu, chi, d)` & `(2theta, eta, d, \|Q\|)`, export `ImageD11` `.flt` & NeXus `.nxs` | `LazyVolume`, `otsu_threshold_chunked`, `AxisCalibration`, `DetectorGeometry`, `export_imaged11_flt`, `export_nexus_process` | `numpy`, `h5py` |
| **segmentation** | Multi-scan threshold smoothing, 3D LoG + `h`-maxima + watershed (or experimental DINO + HDBSCAN), physical/voxel feature table | `segment_classical`, `smooth_thresholds`, `segment_dino`, `extract_instance_table` | `numpy`, `scipy`, `scikit-image`, `scikit-learn` |
-| **semantic** | Cropped spot cubes, orthogonal MIPs, multi-view global embeddings & dense patch-token grids | `crop_spot_cube`, `orthogonal_mips`, `make_multiview_encoder`, `make_patch_encoder` | `numpy`, optional `torch` + `transformers` |
-| **tracking** | Vectorised geometry + semantic cost, Hungarian assignment, per-grain kinematics, `1 -> 2+` split & `2+ -> 1` merge lineage resolution, persistent fracture precursors | `PositionShapeCost`, `GeometrySemanticCost`, `build_tracks`, `compute_grain_kinematics`, `resolve_splits_and_merges`, `compute_fracture_precursors` | `numpy`, `scipy`, `networkx` |
-| **cli** | Parse args/JSON config, orchestrate stages, write CSV/JSON/NPZ artifacts and SHA-256 `run_manifest.json` | `segment_dataset`, `embed_dataset`, `track_dataset`, `detect_events`, `run_pipeline` | All of the above |
+| **semantic** | Lazy ROI spot cropping, orthogonal MIPs, multi-view global embeddings & dense patch-token grids | `crop_spot_cube`, `orthogonal_mips`, `make_multiview_encoder`, `make_patch_encoder` | `numpy`, optional `torch` + `transformers` |
+| **tracking** | Vectorised geometry + semantic cost, Hungarian assignment, multi-scan gap closing (`max_gap`), per-grain kinematics, `1 -> 2+` split & `2+ -> 1` merge lineage, fracture precursors | `PositionShapeCost`, `GeometrySemanticCost`, `resolve_track_gaps`, `build_tracks`, `compute_grain_kinematics`, `resolve_splits_and_merges`, `compute_fracture_precursors` | `numpy`, `scipy`, `networkx` |
+| **viz** | Publication figures and zero-CDN offline interactive HTML 4D Lineage & Strain Explorer | `plot_lineage_dag`, `plot_kinematics_dashboard`, `plot_precursor_timeline`, `plot_spot_mip_card`, `generate_html_report` | `numpy`, optional `matplotlib` (HTML explorer uses stdlib only) |
+| **cli** | Parse args/JSON config, orchestrate stages, write CSV/JSON/NPZ/FLT/NXS/HTML artifacts and SHA-256 `run_manifest.json` | `segment_dataset`, `embed_dataset`, `track_dataset`, `detect_events`, `report_dataset`, `run_pipeline` | All of the above |
**Rule of thumb:** keep **numeric kernels** and **typed data contracts** in subpackages; keep **CLI modules** as thin orchestration layers.
@@ -38,25 +40,29 @@ BraggTrack/
```mermaid
flowchart LR
subgraph inputs["Inputs"]
- H5["HDF5 / NeXus 3D scans"]
- CAL["AxisCalibration (auto or JSON)"]
+ H5["HDF5 / NeXus 3D scans (LazyVolume)"]
+ CAL["AxisCalibration & DetectorGeometry"]
end
subgraph seg["Segmentation"]
- SEG["segment_dataset (smoothed Otsu + 3D watershed)"]
+ SEG["segment_dataset (chunked Otsu + 3D watershed)"]
FEAT["features.csv + labels.npz"]
end
subgraph sem["Semantic"]
- EMB["embed_dataset (MIPs + DINOv2 / mock)"]
+ EMB["embed_dataset (ROI MIPs + DINOv2 / mock)"]
NPZ["embeddings.npz"]
end
- subgraph trk["Tracking & Kinematics"]
- TRK["track_dataset (Hungarian + kinematics)"]
- KIN["tracks.csv + kinematics.csv"]
+ subgraph trk["Tracking, Gap-Closing & Kinematics"]
+ TRK["track_dataset (Hungarian + max_gap + kinematics)"]
+ KIN["tracks.csv + kinematics.csv + .flt / .nxs"]
end
subgraph evt["Lineage & Precursors"]
EVT["detect_events (splits, merges, ROI dispersion)"]
OUT["events.csv + precursors.csv"]
end
+ subgraph rep["Visualization"]
+ REP["report_dataset (braggtrack.viz)"]
+ HTML["report.html + figures/*.png"]
+ end
MAN["run_manifest.json (SHA-256 + timings)"]
H5 --> SEG
@@ -65,19 +71,23 @@ flowchart LR
H5 --> EMB
FEAT --> EMB --> NPZ
FEAT --> TRK
+ CAL --> TRK
NPZ --> TRK
TRK --> KIN
H5 --> EVT
FEAT --> EVT
NPZ --> EVT
EVT --> OUT
+ KIN --> REP
+ OUT --> REP --> HTML
SEG --> MAN
TRK --> MAN
EVT --> MAN
+ REP --> MAN
```
- **Dataset root** is a directory containing `scan*` folders (defaults to bundled `data/sample_operando/` when present).
-- **Physical coordinates vs. voxel indices:** `extract_instance_table(..., calibration=cal)` converts `centroid_mu`, `centroid_chi`, `centroid_d`, `cov_*`, and `eig_1..3` into physical reciprocal-space units while preserving integer voxel `bbox_*` indices so downstream 3D ROI cropping (`crop_spot_cube`) remains exact.
+- **Physical coordinates vs. voxel indices:** `extract_instance_table(..., calibration=cal)` converts `centroid_mu`, `centroid_chi`, `centroid_d`, `cov_*`, and `eig_1..3` into physical reciprocal-space units while preserving integer voxel `bbox_*` indices so downstream 3D ROI cropping (`crop_spot_cube` over `LazyVolume`) remains exact.
- **Artifacts** under `artifacts/` are reproducible build outputs and are never committed to Git.
## Extension points
@@ -89,12 +99,12 @@ flowchart LR
## Performance notes
-- Frame-to-frame Hungarian association builds its `(N, M)` cost matrix via vectorised `scipy.spatial.distance.cdist` and a single dense matrix multiplication (`A @ B.T`) for semantic cosine similarity.
-- Cross-scan threshold stabilisation (`smooth_thresholds`) operates in $O(N \cdot W)$ on scalar per-scan Otsu thresholds without holding the entire 4D dataset in memory simultaneously during streaming workflows.
+- `LazyVolume` streams `z`-slabs (`otsu_threshold_chunked`) in Pass 1 of `segment_dataset` and reads only tight 3D spot ROIs (`read_roi`) in `embed_dataset` and `detect_events`, avoiding full-volume `float64` allocations on multi-gigabyte detector stacks.
+- Frame-to-frame Hungarian association and multi-scan gap closing (`resolve_track_gaps`) build cost matrices via vectorised `scipy.spatial.distance.cdist` and dense matrix multiplication (`A @ B.T`) for semantic cosine similarity.
## Configuration surfaces
- **Environment variables:**
- `BRAGGTRACK_DATA_ROOT`: Override default dataset root discovery.
- `BRAGGTRACK_DINO_BACKEND`: Force `auto`, `mock`, or `torch` backend selection.
-- **Pipeline JSON config:** Pass `--config pipeline.json` to `braggtrack-run` to declaratively configure backend, model ID (`DEFAULT_DINO_MODEL = "facebook/dinov2-small"` or DINOv3), calibration file, semantic weights (`cost_alpha`, `cost_beta`), and split/precursor thresholds.
+- **Pipeline JSON config:** Pass `--config pipeline.json` to `braggtrack-run` to declaratively configure backend, model ID (`DEFAULT_DINO_MODEL = "facebook/dinov2-small"` or DINOv3), calibration/detector JSON files, `max_gap`, semantic weights (`cost_alpha`, `cost_beta`), split/precursor thresholds, `--report`, and `ImageD11` / NeXus export paths.
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
new file mode 100644
index 0000000..d0b5d58
--- /dev/null
+++ b/docs/benchmarks.md
@@ -0,0 +1,115 @@
+# BraggTrack v0.3.0 Benchmarks & ESRF-ID03 Case Study
+
+This document reports reproducible multi-trial quantitative benchmarks for **BraggTrack v0.3.0**, comparing **Geometry-Only**, **Deterministic Mock-Hash** (`mock`), and **Pretrained Vision Transformer** (`torch` with ungated `facebook/dinov2-small`) tracking, gap-closing, and 4D chemomechanical fracture precursor scoring, followed by an end-to-end case study on bundled operando dark-field X-ray microscopy (DFXM) data from **ESRF ID03**.
+
+All synthetic benchmarks can be reproduced via:
+
+```bash
+python scripts/benchmark_suite.py \
+ --include-torch \
+ --model facebook/dinov2-small \
+ --trials 5 \
+ --bootstrap-samples 500 \
+ --output-json artifacts/benchmarks/benchmark_results.json \
+ --output-figure docs/figures/benchmark_comparison.png
+```
+
+
+
+---
+
+## 1. Benchmark Methodology
+
+To isolate when pretrained multi-view morphological features genuinely outperform classical 3D centroid + covariance tracking—and to verify that gains come from learned visual structure rather than arbitrary feature dimensionality—`scripts/benchmark_suite.py` evaluates three backends under identical segmentation and Hungarian/Jaqaman solver configurations:
+
+1. **`geo` (Geometry-Only, $\alpha=1.0, \beta=0.0$):** Uses calibrated 3D reciprocal-space centroid displacement and log-eigenvalue shape distance (`Eigen-Shape`), with zero semantic weight.
+2. **`mock` (Deterministic Hash Baseline, $\alpha=1.0, \beta=0.6$):** Appends `1152`-d `SHA-256` multi-view MIP vectors (`MockDinoEncoder`). Useful solely for deterministic offline CI plumbing; slight pixel changes completely decorrelate consecutive scan hashes.
+3. **`torch` (Pretrained `facebook/dinov2-small`, $\alpha=1.0, \beta=0.6$):** Extracts `1152`-d L2-normalized multi-view orthogonal MIP embeddings (`3` projections $\times$ `384`-d ViT-S/14 features) and `16x16` spatial patch tokens for sub-spot precursor dispersion.
+
+### Scenarios Evaluated (`N = 5` trials, `500` bootstrap resamples for 95% CIs)
+
+| Scenario | Physical Beamline Regime | Primary Failure Mode Tested |
+| :--- | :--- | :--- |
+| **`crossing_morphology`** | Two sub-grains on an antipodal circle ($R = 4.2\text{ px}$) rotating $90.25^\circ$ between scans with orthogonal $+45^\circ$ vs $-45^\circ$ streak tilt (`3D` eigenvalues identical by symmetry) | Equidistant / near-degenerate 3D geometry causing catastrophic Hungarian ID swaps without 2D MIP orientation semantics |
+| **`intensity_jitter`** | $\pm 45\%$ incident synchrotron beam-flux spikes + Poisson/Gaussian detector shot noise across 6 scans | Photometric invariance of L2-normalized ViT MIP embeddings vs pixel-hash fragility |
+| **`mosaic_broadening`** | Progressive rocking-curve ($\mu$) mosaic broadening ($1.0\times \to 1.9\times$) under electrochemical cycling | Smooth morphological continuity ($\cos > 0.98$) as Bragg reflections broaden |
+| **`beam_dropout_no_gap` vs `beam_dropout_gap2`** | Staggered 1-scan rocking-window dropouts across 4 grains over 6 scans (`max_gap=0` vs `max_gap=2`) | Track fragmentation and cross-grain jump hijacking vs Jaqaman diffusive gap-closing recovery |
+| **`chemomechanical_fracture`** | 8-scan 4D grain evolution with persistent pre-split broadening + sub-peak bimodality (`scans 1-3`), `1 -> 2` split (`scan 3 -> 4`), `2 -> 1` merge (`scan 5 -> 6`), and isotropic control | Exact split/merge lineage recall and pre-fracture precursor score contrast against stable control grains |
+
+---
+
+## 2. Quantitative Multi-Trial Results (`facebook/dinov2-small`)
+
+### 2.1 Tracking Identity, Gap-Closing & Embedding Stability
+
+| Scenario | Backend | Mean ID-Switch Rate (95% CI) | Fragmentation Ratio (95% CI) | Gap Closures | Cosine Stability $\cos(\mathbf{z}_t, \mathbf{z}_{t+1})$ | Elapsed (`5` trials, CPU) |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **`crossing_morphology`** | `geo` | `0.2500` (`[0.2500, 0.2500]`) | `0.0000` (`[0.0000, 0.0000]`) | `0.0` | — | `0.51 s` |
+| **`crossing_morphology`** | `mock` | `0.0000` (`[0.0000, 0.0000]`) | `0.0000` (`[0.0000, 0.0000]`) | `0.0` | `0.0160` | `0.50 s` |
+| **`crossing_morphology`** | **`torch` (`dinov2-small`)** | **`0.0000` (`[0.0000, 0.0000]`)** | **`0.0000` (`[0.0000, 0.0000]`)** | `0.0` | **`0.9035`** | `43.80 s` |
+| **`intensity_jitter`** | `geo` | `0.0000` (`[0.0000, 0.0000]`) | `0.0000` (`[0.0000, 0.0000]`) | `0.0` | — | `0.04 s` |
+| **`intensity_jitter`** | `mock` | `0.0000` (`[0.0000, 0.0000]`) | `0.0000` (`[0.0000, 0.0000]`) | `0.0` | `0.0089` | `0.05 s` |
+| **`intensity_jitter`** | **`torch` (`dinov2-small`)** | **`0.0000` (`[0.0000, 0.0000]`)** | **`0.0000` (`[0.0000, 0.0000]`)** | `0.0` | **`0.9908`** | `10.66 s` |
+| **`mosaic_broadening`** | `geo` | `0.0000` (`[0.0000, 0.0000]`) | `0.0000` (`[0.0000, 0.0000]`) | `0.0` | — | `0.05 s` |
+| **`mosaic_broadening`** | `mock` | `0.0000` (`[0.0000, 0.0000]`) | `0.0000` (`[0.0000, 0.0000]`) | `0.0` | `-0.0031` | `0.05 s` |
+| **`mosaic_broadening`** | **`torch` (`dinov2-small`)** | **`0.0000` (`[0.0000, 0.0000]`)** | **`0.0000` (`[0.0000, 0.0000]`)** | `0.0` | **`0.9899`** | `10.85 s` |
+| **`beam_dropout_no_gap` (`max_gap=0`)** | `geo` / `mock` / `torch` | `0.0833` (`[0.0833, 0.0833]`) | `0.5000` (`[0.5000, 0.5000]`) | `0.0` | `— / 0.0048 / 0.9879` | `0.07–17.83 s` |
+| **`beam_dropout_gap2` (`max_gap=2`)** | `geo` | `0.0000` (`[0.0000, 0.0000]`) | `0.0000` (`[0.0000, 0.0000]`) | **`2.0`** | — | `0.07 s` |
+| **`beam_dropout_gap2` (`max_gap=2`)** | `mock` | `0.0833` (`[0.0833, 0.0833]`) | `0.5000` (`[0.5000, 0.5000]`) | `0.0` | `0.0048` | `0.08 s` |
+| **`beam_dropout_gap2` (`max_gap=2`)** | **`torch` (`dinov2-small`)** | **`0.0000` (`[0.0000, 0.0000]`)** | **`0.0000` (`[0.0000, 0.0000]`)** | **`2.0`** | **`0.9879`** | `17.88 s` |
+
+### 2.2 4D Chemomechanical Fracture & Precursor Benchmark
+
+| Scenario | Backend | `1 -> 2` Split Recall | `2 -> 1` Merge Recall | Top-1 Precursor Precision | Precursor Contrast $\Delta S$ vs Control (95% CI) | Elapsed (`5` trials, CPU) |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **`chemomechanical_fracture`** | `geo` | `1.00` | `1.00` | `1.00` | `0.6449` (`[0.6448, 0.6450]`) | `0.13 s` |
+| **`chemomechanical_fracture`** | `mock` | `1.00` | `1.00` | `1.00` | `0.5539` (`[0.5538, 0.5540]`) | `0.29 s` |
+| **`chemomechanical_fracture`** | **`torch` (`dinov2-small`)** | **`1.00`** | **`1.00`** | **`1.00`** | **`0.5584` (`[0.5582, 0.5585]`)** | `74.82 s` |
+
+
+
+### Key Scientific Takeaways
+
+1. **Orientation-Sensitive Disambiguation (`crossing_morphology`):** When two grains have identical 3D eigenvalue magnitudes ($\lambda_1, \lambda_2, \lambda_3$) and rotate slightly past $90^\circ$ on a shared Debye-Scherrer / rocking locus, **Geometry-Only** suffers a deterministic `25.0%` ID-switch rate because 3D scalar eigenvalues discard 2D detector streak orientation (`+45 deg` vs `-45 deg`). **`facebook/dinov2-small`** preserves high multi-view morphological similarity (`0.9035`) along true trajectories and eliminates ID switches (`0.0%`).
+2. **Real Pretrained Embeddings vs Mock Hash (`beam_dropout_gap2` & `intensity_jitter`):** While `MockDinoEncoder` produces pseudo-random zero-mean cosine similarities (`-0.003` to `0.016`) whenever shot noise Perturbs a single voxel—causing semantic gap-closing (`min_cosine_similarity=0.35`) to reject valid re-links (`0.0` gap closures, `50%` fragmentation)—pretrained **`facebook/dinov2-small`** maintains `0.988–0.991` cosine stability across `45%` flux spikes, progressive mosaic broadening, and multi-scan dropouts, recovering `100%` of dropped tracks (`0.0%` fragmentation, `2.0` gap closures).
+3. **Early Precursor Contrast (`chemomechanical_fracture`):** Across `1 -> 2` grain splitting (`scan 3 -> 4`) and `2 -> 1` sub-grain coalescence (`scan 5 -> 6`), BraggTrack's multi-component precursor score flags the fracturing parent grain `3` scans before topological separation (`1.00` top-1 precision, `+0.56` to `+0.64` score contrast above isotropic control grains).
+
+---
+
+## 3. ESRF-ID03 Operando DFXM Case Study (`data/sample_operando/`)
+
+We executed the complete **BraggTrack v0.3.0** pipeline with real **`facebook/dinov2-small`** embeddings, multi-scan gap closing (`--max-gap 1`), interactive HTML reporting (`--report`), `ImageD11` `.flt` export, and NeXus `NXprocess` HDF5 archival on the bundled 3-scan **ESRF-ID03** near-field PCO dataset (`3` scans $\times$ `100 x 250 x 250` `uint16` cubes, ~`20 MB` compressed HDF5):
+
+```bash
+braggtrack-run data/sample_operando \
+ --outdir artifacts/esrf_id03_dinov2 \
+ --backend torch \
+ --model facebook/dinov2-small \
+ --max-gap 1 \
+ --report \
+ --export-nexus artifacts/esrf_id03_dinov2/esrf_id03.nxs \
+ --export-imaged11 artifacts/esrf_id03_dinov2/esrf_id03.flt
+```
+
+### 3.1 CPU Stage-Timing Profile
+
+| Pipeline Stage | Wall-Clock Time (CPU) | Share of Run | Primary Workload |
+| :--- | :---: | :---: | :--- |
+| **`validate`** | `0.043 s` | `0.1%` | NeXus `/entry_0000/ESRF-ID03/pco_nf/data` discovery & SHA-256 verification |
+| **`segment`** | `13.48 s` | `24.4%` | Chunked lazy Otsu pass (`LazyVolume`) + 3D LoG + `h`-maxima seeded watershed (`[18, 17, 15]` spots) |
+| **`embed`** | `18.35 s` | `33.3%` | Lazy ROI cropping + `facebook/dinov2-small` 3-view MIP inference (`50` spots $\times$ `1152`-d) |
+| **`track`** | `0.024 s` | `0.04%` | Geometry+semantic Hungarian matching + Jaqaman gap closing + 4D grain kinematics |
+| **`events`** | `20.23 s` | `36.7%` | `1 -> 2` / `2 -> 1` lineage resolution + 3D sub-peak & `dinov2-small` patch-token dispersion |
+| **`report` + exports** | `3.04 s` | `5.5%` | Self-contained `report.html`, publication PNGs, `esrf_id03.flt`, and `esrf_id03.nxs` |
+| **Total** | **`55.17 s`** | **`100.0%`** | Full 3-scan operando DFXM workflow on CPU (no GPU required) |
+
+### 3.2 Detected Lineage Events & Persistent Precursor Candidates
+
+- **Split Candidates (`events.csv`):**
+ - **Event 1 (`scan 0 -> 1`):** Parent **Track `6`** (`s0_i5`) $\to$ Daughters **Track `32`** (`s1_i11`) & **Track `34`** (`s1_i9`), intensity partition ratio `1.434`, mean daughter separation `18.64 px`, **DINOv2 multi-view cosine similarity `0.7561`**.
+ - **Event 2 (`scan 1 -> 2`):** Parent **Track `21`** (`s1_i1`) $\to$ Daughters **Track `36`** (`s2_i1`) & **Track `44`** (`s2_i13`), intensity partition ratio `1.258`, mean daughter separation `20.11 px`, **DINOv2 multi-view cosine similarity `0.6837`**.
+- **Top Persistent Precursor Tracks (`precursors.csv`, `min_persistence = 2` scans):**
+ 1. **Track `14`** (`rank 1`): Active across all `3` scans (`onset_scan=0`, `peak_scan=1`), `peak_score = 0.8789`, `mean_active_score = 0.7775`, `max_anisotropy = 5.45`, `max_spread_growth = +106%`, `confidence = 0.8555`.
+ 2. **Track `34`** (`rank 2`, split daughter of Track `6`): Active across `scans 1-2`, `peak_score = 0.9023`, extreme streak elongation (`max_anisotropy = 26.78`), `max_spread_growth = +129%`, `confidence = 0.8119`.
+ 3. **Track `27`** (`rank 3`): Active across `scans 1-2`, `peak_score = 0.6710`, `max_anisotropy = 16.00`, `confidence = 0.6534`.
+ 4. **Track `29`** (`rank 4`): Active across `scans 1-2`, `peak_score = 0.6668`, `max_anisotropy = 6.67`, `confidence = 0.6490`.
diff --git a/docs/figures/benchmark_comparison.png b/docs/figures/benchmark_comparison.png
new file mode 100644
index 0000000000000000000000000000000000000000..03a9b0cfa56a7192aa0f139a94f3ee70b0d987be
GIT binary patch
literal 182861
zcmeFZg+CR#Sqs|z(ZD}0?k&`=AVG+ur
zQ-#HnmX)Lx1ak17D_x-8+d-t-c!p?2X+ZY%ab}C*xe}#cz
zn*;;HCh?!Q;47h<_TUc;k}el?T{Il7ySQIT<)@!Nu0<+F>_yCub`Mdm%mn
z0X{*V!o-+dj`)l&QAMD?|$};@Gz@T{k
ztfoiIc%Qq^zP9y^X?Nzo!x^4#{`sl%h|<(yqkDIBxfb}Jq;#sEEfIa6erM-frwjLf
zKYKQ`KQw4A>u|;KpMK{3yLD;p6@N)rgKchfgT3hRypQyZ$ID0|3t8{$!wn5hUCygJ
zs!#t!-ok(X`e?d3EBW7l{P*v;U7Y?e-zIxkHRykS*GtY1b-VxPm%bg7l=$&~ekuMu
zr^5gI%Eyo|LqGq|FZt|=WyK2oFTeg!dlqu^fB7?h`&IG(^>6Bd%|U)+&EJ22GU71z
z<%1_1^B>aM4|;C@wc7Q`Q$nWl^Wflo9cO%sPPTEHenHxAzx}pv-@c*CHQrMd5reBY
zf<%Alf1ML9ma-W0w4ba^@vo<|H<90Ld*nGgJW|+WPZ11`kB|TB=1r{(T>-6>%V$Mw
z+BJI$?b@g8B)<$tJ7|A;{f`X$-u2`s
z`Mb2Y%~-g%^_Doh*0Q<3JH3ON%P!+(xxTuj+F{q85n1RkV6U_|J9}yBZyl^a*eNX~
zT78&CfpuGJiuzI4FYnK)M2i;8nhq%%N=Q^PvWh>M>?<34_wcA*cx+TuRKn^zX1l+R
zTF{l`|NQgMQ~LQS*aOW9FITLeiHz6WN=Ko_U0DruH3|5j~=aHPtI;*A=@_a
z@4NBx{uK=kqvdDo^8PdZ>_Z-zQ1UP1ngDeRFqj_lv7Hu|3K7aaNz-+&!g{6kylmKb})N
zM~g6#G>Uuh;7MnvE}N{6?xhI6HmRxdgzJq_BYDlT8X+fCZ0{dcG44=^8mtW-YZM!3
z?J)7r#4b~G`3#GnoV(3vwYEGTCGPm_lxE74hes7gQ_gr7dHj+REG=_%Cc9;)vigYQe`z=dW6AnNj%ZmtTG<^_YI98YBJ`
zJ1@brGDlSt@%eVc;h(6Z`LD1CXI{N=X(RuYeHay$W<^a(H7K%ImDs?QV03BktfOgF@SB-Sxlz7Ckb>CgF6xsMqN}esV;|QwCX_ZSK+j
zin7XYpYO94C@y^}+tU3zKFpKfuN@;*_i%g{&O_zu%%yk^qaVI~-;m{niFE9JNkM<5
z?~2PMa$9A(d+B0tpyg%><0C-Vawk}lH*-gCW`2z7lzw24cgMQxb3?0
z6}8ed>s*y@WSP}HQc_Y9Ok7#nnDzHIcp&HP*6%$f!)sJ3oL&7sNhP}V*@f+ydU^5%
zHXTi4H(E;eM3mKbtgo%`QaQZG1u9l&D5td2LRVK;k177}!w<{&X}$Hq;~!3Ra*K#)
z1@TENAMp8*(a!zcn3-wQr-(0e(OsX7tWv8
z9gdgrE{r(JBaTD*@ddx&hVN{nSom01a{AmX)b0hfA#ZqZSU-Tn&qZWmm3wcZGLRQ;b9cC4zsf
zS#G0Mfy4JXcEBL3%zet(uCKH$T-@iWtlMO7>XCD|blq<7XlFdG31Ul+m2w|#NxXFL
z?%faf_Hzs0_;`krOI`;Xa7tEIw!`s=4a!YY)n7B8OAq_IS-6dNKK+oOkh~#x`t<3F
zycjl7+s-G?pC227|-w?vP4ThW!emu7IKt-ic}8t$nUC!LB<>@D%zOEIGorwbvRYNCnw
ztol<`8-B}cUWSG-L2ObM@3n$F45y_0+@sXP*Iq%Qlhxg=Aoyw>VIZr6uozl-(E9A_XAcxQ2?7a7-8Zk
z@F*mtFYP8;2h+{1yF}Bp(y#C1)^50S=gw)bxi43hqeUApDk=&9>1<(SwOrou_TGL9
zHJ92DB|>qE-*M>l%Mr{W_5PfCr^G4U0l%%ffX{?nE%QSHD3i!HO`162bvLgaE?
zR8es~IW^vuCqL4XsN%`3l{T~>@koPHElyY|oX3i37R&2oRGHmct0LBC#-!lkQ9O-<
zAYtUNJU4Qys;Y`s%CzVmHQ=|>ICCgg(lyO|scFW4vClnxNybstqNDx!^XG^1t~UyL
z&5xREW*K&!L}%Q+d-v5|zmYE?UY@V!h
zdGB?OyPokqIv9{>cK}G;p!sySaG2-5?M*hdJ?5gy_9}T-UyzD`19cv=5g12YBlX
zS=9`=o$6zqkBf-3k?l5L=h8?rE8{KemUC#2=bUPE-fN+$sTuBiFX&
z*Z#hBi}};1Pc>w1mE&dmTsRKx-D_IDG#o9Do*Hl^QHd#0DeU{VVjpV6-6svh9f#gl
zXu8?y8q4fWjFj`Qq%EK)#!Zw03kls~WV7~JqD6#LWIP?l8@=BK_!K@P3BCDKe_2EkjL9AAh8>4OMHA2nOrb~h!6M|)xOg4HPs$7@<>gzHIWEKf%
zOV_bj=?V!62}FM}*V86vT_ahQ$-U1t!b%SSYxenggHubLKzf7`@S>1)Ysyvq0|yQa
zU#_WIpXV=HxQ}Bp{bsM)A)N2V1);>GBxan#INX9^rzMN#IM*ei>k9yD`oozz*>R4e
zty~8e-)zi{P-``{ainq$=>;9eLYaFH9kM)s;X)$a^V2^Ec?MS(dK`EutOD2mHeUyD
zEL)3osvrFpZss%n_FxHL&%sgC`O!Aj;5u_kxOrJ+o@lPm(#%NgD{6*eNsHhV&ajs>Z-kQB?(pOK--sbST!QGT!1yEGBFCw-lr_8uwzH4W-
z^Mq~`N~$SvxO~pFx4D6G;^LhiBZ(2x?Ppg$C~&xT8k02|8ZygvaZ(=4ICmAmBs@0J
zh?ZGw_#HYvNEqzwtHRZ=MH^p~?zi15Sn4(rH4TKp0{q8kmkkhBvphc*8&1D#b3wJl
zJFC}!V=a6s*0o-6$4ZZ!Lu-68&J+uMgqoZu-JGtKKAhhRJjw!+AdK=A&TDWzlv}6C
zs(*$?VZp9AGv6+nN;I^po|%aR_BEXustY$SZIQiR8?so_U#=s(W1y6u@UM@OHC|is
zU!P7i2VSa8d&Y>i1SxkXlpp^tQDIXfoKEYK@c8-!Z#WHL!#r|oePyb{BHlOLJPwp0
z1sh6WlYxLouC1D+*IbI%!gwmGZB)2<|G~-0=+;(E-*2C8m#$2fg+)b;3Y+})+h6F`
znaS~f-I-RB&Q2K@TmJrKFKg0C6)J%D8n$`cu3heB4O=;U-iIz=4P%pX
zYmIiOOf4=hwlyumb`h}bx3ps4qMI#%#cJ6G$b=~)`fBin@mOG1+
zorcSnG#47W4|u;iJ;!V)-LdQG;r`i9+@9^$)TBUye$b*D6J6b=`ZGaZP(!Tj?YQL(
zxqE#@XRfbU=&X4zi_Z`FsY*5P;*cE|Zhmz9(%ieF!Issxc8>Oy5pXdm?10Z@Uoo$Z
zuKd=iL@ax0GXHAU*Ed2Bj~zdLTrVlxutZRSwzhYv#rHe=UVQ(Zg?~K@_@-ZI8_5oA
zMWHPY_*WUwDmKA0AMA1ZDuFM2#g%*A+
zO|Z;3r8!zmZNO(XkV?abx8t+fb!ofFE`K>HvofBSGzY$51>AWGur#QCf|?vmD+Lh9
zZ>aKJahvEVY7ULd2~k&4x<{y3y+*l*V=_OR4O)6+rRVH*ic8tsH*YNK9vx4bd-39Q
zfy02Tj`@m`FONxOui#pc)Z`7TH9_B%@tN3a^
z-itAuov^Kzo>x9bAajm#6)ua2*PJCtbK?Ss>(G2fPMHtw-<5sk-|MxN3blz0kJnS%O0FC?M*+`}e6&&)pXGU3O{9H0aP=|8vvU{NG>wsNsd3
zGWJ_Cr#uD>&fdu)`UT%D>GI_PjS`oE%kN;_krf-xXOsrkh%&Aux3QWh={El5L9%UE
zZs}l<)Er>DHAp@|(FD`lbYzWyp6gfnRm6FG{$*(;nqyY>+s93mi6)$@Jd5T+!}cT<
zmc~dSg=DpOZNSWhse$ZWvfs`C&^3OrSY4fM7I7N7NSWXK{v3Dx*vPNJmAJAD;
zJjt8bymc$xS_<_fH8nLnw)FWJ|35};`BoZ~IT`PT;`~Y@ekTHW-ZnR@@t1%7i;+V%
z16bb%DCrb%7}o$`8LQ+&V8}B-Az&U(%hwihK}I}V*0I>1wSC;|YMZ>~+btrbsX>Y@
zKx85)C>s4AKmJ~U-Iw%REzUA5d4_H_VzRLu!8Pz)F(lt{P~Khko(7iSN%bA0OHwVZ$Y^eGX5
z!rkICB0!ZPMkg%T}8@g2>wi1Vy*+At};@hY?k%MdQGlU=&=qN-{kkKB`%nazFX+jMS0V6)N#4GX~0=$R>TpXfF(StHo_h>5jzntGzrevL|coOjca
z0n&UaHk~h?QV&5v`MpF{SNAb*yg=jor{@Cy_=Dl-;lqb1q6vUBHAMq{HWX3cr?S_s
zU5oK+$1yH7Y^vq(x78!8gmos9;GF^VBOZ!txPNBu#|GzbdqqF+wUXb8)%O(EQ%TIsf
zd;6&_x8fBl0YJQy=iE^p=xp7g*F}EpFL9>lU#;Gv(GTV`hHj&Ux@*4l&$j(7XfY{h
zYZ0IIAOw+CLOuCgUzvNyUz@kH%I|3m+_IB71=4ELT!Tgh$gws)rx1-I{f{-uAkFQs
zzy6A;`Doh}#;p^R6|$FTUH(n^)@@2SXdOoGedga!2%mBJ7Z*K1Rztp8z5e{&|KysA
zFhAfd@lv%oe(czJQn$D&07Jr;Os`!t+;uuWH^F$~y1Nu)2?-R#y3lNhT;U1w^5@Tg
z0b&tJ#NJ%Id-rZv%~V62jQ1SsFNBA~htCLIZ@6q}X&FSxKX>us9jbX&;nuj1>5eq*
zv&Hlr4Q1s3ns6HwgbrLPbYxdb1#cs`WjG!LI
zUAx2r-?QxA{S>fAf4GP_Fq`Nt`B0;1qmpK|B63A`kBj2&J|Ck7l&$P|0lcu2L)I{m
zMXVh+sZYP7XR$_t#=Up}yUXCj=P&I`e)GV^xBkVa>f2*&Iwr0*GVUf$go}ECK(*yr
zs6n*4boJ`hQ&*nfsm^zVP9vIm5R6;NS#)zoo@xY$*%h2}qkGg4bMJFFxmtPGRU&3h
z%01MYtRBHav3V$hK|Ulm__S`#qCsrICw`*g&4-GXw!;@^@i%t-4j?
zWqpMm`lTsBDJ9b{H|=`da=ke&6AWQ)!$4)ayVTW&>SER;`P!U^TgZaHY&=6v$FB3m
zS@5%#2S?7?j_e!UKL1b)qGoD-tYiDtJT!a0Ob2?Xk6Rp7Z=^FPffhq7K?gG`gUk#bgcIb^#U|bzk=@(|(?mWIfqiGK!xX#4a=Xf``Am
zs<%D9C`bd%q0p{Jzn@dj^(7BPZu{a-TQo}Z+?w=Q`%8z*dTyByH(ES<`SOe}U`v#&
zZ)uOf1~eX`Q#QrRP0dL5M`cMC{fE<@ne1Go>XChvXiwMSU&HAe*$55}?#MB%6}IaZ
zR(X8-mGHHms*N>=`7a;NK`3@gU4@EL5;}z*$1G@eM?1@K#Oo`QVTD&)=9XUBJoj-AZeuB!CTOv;-kPeB^|wQ=S>2x7jM}{V`R~DLoi)Sz1l{i`
zX{20!$|I%a9hF@ZX0UlWj#Dh=ZA_c5EvnBDoo*o+Y{YiAIU;L6i>U2o9A|2g^Kb)`
zU03df?DCm=&=o&DSVR|Pmh~wR-COO{=6>r38iGVxNW
zc+hrdSC*@mE)A+zImKPZZ0msH${Spp|Td-
z`1G61*O!~ZYZq~>=g>%pt)l@E*VoroP3FpkqVBcL#XlP3&(4(8Q<@BP8G_Eh-6Wst
zB06vGN1O1P|4FJxz#^V#MpwI60{okT9Ngty>Q6dbgf&KsaYI%36vsKij}Dc;j=IM>
zW7d|_Z3MNd%-qX3_}lpRids&e{(JmdQ=`R9qRj;e4a=S!U@S^ur$)jJ>_6b2X{Kp%
zX{^Hn8Ut_|*=YU`R3j{;Yt&dhcYR0G=Ns*H0zwWZvqpB+ysZB_dRsFT-mv
z;;Rme&?f2~5V5V&R8LX1cBXzJXy0@948Y(kH@ECG>@IAZGrQ6rn_$Ss^a|DVCie;r
z{hwLJE1ydSjVaz|<}TRGb1?6@wHbIGW%+g%3GHms9`6(9jm$-!T|!HN9%1cSP780d
zygobJsDZY4y(z{@-wl-{{rufMNpmPG6vpGAx~d94_Ez~5hi-j(P@AQif?l~i<-cK5!jo>rEz_to
zn0tf7hfpXd7A2lU+j&Kp$@O@bp9J_0UQsBDsVJCx|qTvcz!oY$l5y^dC-MY~sJxCfL{YGrxqn$nw>Pzh2-mxls;fg->l~
zd#VN}Wsb12I;=Ly&j4FM)j%0$%
z=(!bpfBbVR50z6T%1lWLBy-s%mx&nuVgo*TT)tT9aB6{mVEZgiszJQpa;iDKyaCR>
zZKQFonIgr-{qt8d-{LeBbfR2w$-r@2>~#))_Uu_q7VI=zl^F34PF!a{~z{@@dneT8~0_@Q&vNz&app`j#8u*pcr(L2iSNeETc89vdM#Jhw
zw?MR>kKb6W&COVq-DW8-ARy3P?3h5y4d|Fy?OgYq?U$~iWG`On_c)goA)?}Ph1<#Qvi>`~^7SmPvm}&IV^7-tKn}Tn!QeiP
zkGF2!ifSRniZkBl3a4t!Whg_$tyW<7JP+1VPN6LTi~y&LCT5#d8E@LM<2?{+*rP|!
z2q|Wh(uSpxq!v2Cow0ELSj9{|Hz_vIDO`cUp(m+X_m`K@TCX)pW6dE2_)PypcAQjq
zteO%ODR3(hXf>oRWLGRi8ED*EURtsmZA~SbkX09cSX+X^t_Z2d($9ZxWj|fvA?d$f
zZeE$u3UMd*TtANf9PsCtFCP+=R8`y2*IJX+I4BX;C^8<)Uy_+5qI28QjMd
z!)%4bm4)rqBcJx#wP!o3FN66*UQLHBC&~696SX3IWb)0Yy5$?S@Slyoq-=k8Q1V!tLA*?$(L^VBmYtH6)6gAQF3%uwSZ}Pa
zp@VBczXI1x2N4;=71D$Nr`hILeim_lY>Nm-+ILFxWJmlo0PqW*Dz$i7iBtS1
zPSi{^d%!PEz&{IL>MpdidGq#dN%6tl4uCnH!CgQ9d>T=UhjtS9=>kfjCm$wA!aB}*
z`1rA<-Xwa9eMu9PM`ceAuP;vxC%par{fWU-5>y>B|0xT+l(ro6!0f!dJTq)R*V0&g
z@30pOI=s_KY6v~Q%&rj^qp!XSKBR4MLH<}L&humF|L7P+Vg1YFOkE#>h%<#nYto7h
zI3)0EkM6`}Abe_}_uQ9;%y($A;5A!UEVq?^moMR_(e(?OEA)}&
z+2IOL)j^j@SyLW>B|_KcNjuBoY!^bs{FiKwqz2Al>eFwYuGgvg*8zgZgC%eulm
zl#0sK_g%O+ZTdaC@p9{-TMs8rS~FFAeZ5^(;W`Cr8?XA2(85UAAQ!M|&L!hp**(q>
zK6=S>tS#L_qV$4s=)`tdz9TNj;v0V4w24>YIi()jQZy~J(e0FRc`?ac0hC3DXF`1_
z>i0^wqu!Nb`EXigak38xInkDKHz1%Dg5GmbpwfahW)W*kus|?hCmWeEoUajbUjQj>
zxteuGO`*^%!)V#JXV0TSVsJh~oW}@aw__9?0*&U=-~P$vVn8k52n6&02FQ8#I$?Eh>Wd3E?lxxRB2CiKy@&|^>zbP11*FZ(Qh1a;e(}@{Ckf%buklzE!yolMm2RyUzghz>|f^yV*
zs!TWMntsl;e~kUtTq&hF20#J@Aa{u9eaN?kWB=VnLpEw`qL-vp+`1dHW-rS_!f6BW
zNn&v*|B$%4wzAj(Ra2|LS}UUH(=W(_eSku1gfKhe`cJ0$I?>ir0|ZsqbQH{nd2MT2!jyl#G%
z<;Ei{tV!73Y_nYUuNUqWm#-liF$xQp3UF#<%qd6C3CX{JMC^mWp;d3jAL4S^NsEp02GAYi3mWFJfQ4j}z|1*Neb{o4vo$v%YT
z;Lhp6KDEzgVQ0^ps$5Y$Dj#qosut~gvR>uCz*)!UVOLTE88VP_NrhQ*FCah@<*lv4
z+a0|?4Xlv8=Q`Geq?w3S871ZrN1O&2y6D@gIEdfX9ju&;g8A0Xn@MwJmiBmYLM<)>
zMV;%!33(z8;U#g>4ikd7ZO0BU^JL{Qi?*ef5c8G4AmQR=R0wX8T^Se31QG!6(3<}I
zRtq99)>tQ4dgjirzy2x=EW;WmcfH|IAgja`l(QC?ECuG21F;g$@?a%b?(R9R3DiR{
zIWm^&=pb52%8{)8agbyo09-`2@;yKeYj|UT=4vJBO6%QeA;Nf9BX13AmE!QxDUXUWGW
zNlvJQid%QFw*q~+uCICmbm}1za|&T568ytIAOikqS6=c&LdEsai1~-=s7502CeXKy
zt5#?3YiAp0lHLmcgQTn;J$j@(2A};LWNkN37Sizo#rjha8MK7)E9p7&eB1t0&k_3}
z30A6UuuM{}Ib{@O%eh2ZEuI>ORp$hWG2-z1_7uuLfCeL%tZYAL;ot~4u4<+hQran(
zk5s^AM!gEHTpDIsgPo1;6iuK3)YEhXHnwfwt^s1y3cCkph5?a6wWP+kw{+KnUZ){>
zN(vMH{c}W8fS^Hw9+u7@Pu0$IpKgtc2Uhb@Jpz=#b>7Lsf4@f%h>
z^^7_lV}`@?I(yf8Z(SX-uIk=@JDV7iaJ@~vJ}sf%cFDd@Om32Kr?@Uk=O@_ZN=69P
z(laND>$BEqBh8bPiN}2zlia!KoE92#bk{WxAwKsYe)pc$7~`WvoD}M}-sQ~ApS54x
zFt$>Le=&8xNov)&hoGwaOzCXzm%DU5wSh}CH(xcmz2@OP^sVlNu=*p$D|CpE@zHyo
z$$=NY`NQXRb8~Y-?CtWUzgqhu=1300zI5aSZh4~>d-dtLRt>dC$sE4xOS*e+#~byTYNM)gjTIGulgZkNP!_@T3<(={w@
zIHNsVR_%BODsjEtEELkh4In*Gh_i1wajZE-L
zc^mt%wy`01#j!+Pc``s%t2*w)L9rXDSh?I9n>
z-LYsF*;;N=&JY(##|K&de4pRtzMO
zZ+bVt?(_9*AA%^1R&{lCrAQ09u6~;?|AovweE(I
zu8?HBLY3^&&|ab`0tYCm-AAg?uBa~wfEHqx_^yQSiFEQxdRM;#83x%2cmeNmufwP6
zw|taB_UaipFwt`uN20|X+7VZZQcx$r_WLiL(~rI<|FcQ-E)0|cw4^I>6|dhx{1w10
zx>Xm$Iuo4fOcJ*i5fRBg_h0|o{;SZA>UU#@$xH2Hg)%~g7BdHuVFSWIGA#(l??;2g
zO-~_Z45#_ftD4t`)+O92=SE-jUz?9mg`y4Jss3~T&+OKpejMDUw!D>s@p
zG5q0Q3T$f$^v-An3HmZpQL`t1Wnfs>TMZcR|F-EX7y2?8(4pm`i4k5**09H-|B3Dy$%G-9kN
zRZxeE<$AG%hrK#Lh_6^A9hvu4Q4;d=V16_^#~uIDhzwq(q4c{
zGUfzT0pn!Pz-TCdS@(Av(|J^(>wuOKxC$OdfH%TM&9b+bN|E8SglNEM1^n7#;7~!E
zw&OP}e*ZKi6g2^_A=rN>C!-h(nd-P=RMGd^?
z627X#C*RSf8TM%sw-;8k3*kAKuE5(RsSxm-2OUolz)&P7hQ!(+Ya%?Bj^VU>ckYm%
zn`^WIlLT5y#5sMCL=XmEwSNM9KEnPWBR^jrEHp_?ed)4@Z&ddrAP16V4BxIDJD^U!
z-FM(X5|Zd?@b@LU84XPf5+Y5D}Q*8g*E4!g7ez=3cD_1F93Y^(F693XX&RS4tK
zkca2`r3K7gna!!CHC;!I
zNIuAyr-4`UEBtJdheZAS)WAS^E+ID1464I(1*63spAimqJ0F@JaR}JE;<69HF=k|!
z{&Iz6*<2^OwbW$hLov2D{^=d7%*?x^%QF=Iic%GaQz^9^3?Jh^!S=TAn+oI6yMkn0
zD{|>%&dl?)pu*&vk*TR{ocI)+B4+qG%)*u*KYjWAHb!Q?Ko>>w_UE53J2^SA%bRgn
z)Mn#cK)z0b%8c=yYj1wWWPk~y)mBE<-&=P_A3Jfv8j~Bu;&&PE6rj$)^G(I;l3=2(
zH(&USzqi}`s1}*~!?1-rS5NiI+A=5$I#PC(k@!Qv{zH=WG^vgYRpz&Ks
zl&QkGZ-f0WGxz?SHO2sR1`S{=^!qLvQFk2`JY`gxPa+Qmc0JmJK+|MCVAkvz5$BHB
z0ZDry*e<~m&uv3Y*sPk+g#J%>3EI}~)at+NCeHx8&Np(d-1
zk@P8yPhl|dWH#30Rwz-Z7BL7%r9#&65Kv->bD8KCSz8{b)aczAwbW4$BP
z53`wH;4!OL`K`5Vc<6#xEE*NxIEzSBCSj~Nw!^OC;Yd4>tgbJjHP*%&?K7~GqH*ATRTGZ*Qe?=s$aG2OOL(sT3`tcBKZ8BFR
z*HeJ8#o%Wk3sz+86(Q&p$Vgmc)p!45VMMw0lOx9noifN&i>
zvt{engLk%WY5IZTrQDxa50U9kWFNepvGBYg=D_
zKw={!u_S*P@vD;yCS*x^)N1Q@p#?J$+kW}w1Jta19H_T7HC__+tEu3E*i?Jt+n*fw
zpVB<-`ziMNK&5Ze2Np~TwPqPfQC6{%A(}Tv`LYTBCJG3$mZUI4>cc?3{XICeD{4!2^~oD3LW$6ZhnMb${guCg9InCb4dOsUWgF4B
zos7g3v_Il)bzG~bEHuRWHVgI3DV&w0|M286xgb!HW87}+U}V%r`_qJ2M+Wb1GqSbd
zmX)(6&f$U@Btb1zdHC?*HhdTMiA)k;Ood-zYjGA7GGeA2L;C%~?Ohy&(i>#xF;>P~
z8xUvO?apSU?sXDphmYv`_2b!CX-~|^APk;`N;8Ucx!@G~&W5SE2O)VIfRyl?a>Uib
zP<`%MY+XEw)50J4_@Eu(Oh64aD3eNR(Sqhmajs52s9QY#u0+a3B;(7~+7lhRg7QH86E
zL(H!jZt@y4imC(|U9`cZAsmF*@FE;fvbLBYCMAD;KHHy5ShzK_Sa31~?Gu7eZRWhQ
z4JJvwATLulI53LIXH;s5+y&zjTGp^rq(o{oY|{~dgro_j4*!D3)8bY=g_-r?ykkz%
zZg1!TR}V?v`1l7*cNbdye$v@doG>pIrrgsoG93}^d^p)InX~6tsqSkGe@rc*#cE+m
z<~B$?5tG4Gh(ByIdPZXvT+T6A`Y70eq>p24Lvkn(vJ4E-40Hf9gGqGqIh=%3qN3Ue
z%AC^4ih-Gs47d?tdLLms_-ro24Uu!+p-9$qBUN(Y-af~*bEE!?3;;+v@Pn}=`w`rP
zJ#8>7_rE~oi8&5-#N=$ybBK_;XU`roQe2uJmrf)10mqDd8J1KkE>9`|Pm(x^lwgMx
zODm@Y1$R`>bbUtuar6jkJc)OQHmw8W8M$vwJamA}Dme8_`mkHfn@8Z^j6eW-AM4(4
zb;&a>Z7a7MJKZhDJ*&P~oqs}HWe~W6maBDS5Eu@8b_&Zza&li{!onsRT_
zu{z}02DkHx=NDv!2@#mJ7%5UFB0j8PjH_lr%T58-+4l3#@7gRH?4qX{b&q!}C}{Uq
zT-Tqz?)?*k8w;9qp?#mV62D&V^M0=}UU+K0BXX9P^87dad@=d9j9K{dJ%cbC=Fr$p2ciU4LP@rMpWRl_>vHnS1bAmKKwitz^v$l)Owf0fY+qZr*~?%8DK#N5-Z?UH@)NWQx?
zlX-75YFs-E#Y`N!bo9U^w+p4~<;C!GFhZ1q{5F`&L#*~tJN-sP+j=L`U>I+E!e9CA
zweW1G|N1NkF@jKg94{7)iL0T!kjnApi{;z5Z*h|~v8UQtj=VLVuDAcf<%N{1fy+)R
zQjgqU6f0Zc|0Mbl^zbzA#mS^{w1^M5D6B2SN?LDf%o6Q2iVP0<_RWLrAMrt1XUK>Q
zp0B|-Z}MWSSH&4XlTFUg5SjYRP+$>Edw%E6&k;REG2;W6vU^;~KY~y!bt)tyZVJVn
z=5mX{!PpxF)oS@wW!tPr6r2t#pejbIEJL*;bqo*q%aLQhb?i3MgNs!)=XS}MDGeYC
z(=oV$1cr*^ML_~g2NBKa%Bpf5(>6uqi_r>PE@=jU(3Xs18&`A}L#}2E=LPN3oFwaijJKHkfL91&9xlQ>04b2uWDYeHCVB1-MPh{o{IF@uAp)}$>ffdD88*73#Uy~9
zexHX}LOF@`^Q%4`06@w@#zf{76ILYHzCwn50oZztwz5i4pmrwVx@rIHon&
zHai%#`Zc<+>r98fvgLvFGO&^tbpl;uzs+NDjE&naUALZ^i;S^Dz`@y7g63F2)
z!QJ!aQ^f~{y~F}uoo{FX$`(F$?AWnG#3^zF;AcjyO_~S&y58%%*jIxbU2cFY;H*5#
zqRQf^l|TMo9_1iG>`yU-(|BU<^8OzwsT`0
z&EJ4tV%q;n?(uPWJKD7Vjz_GcLD;j6{f9qdF)$N=D;m}P0-p0=cGY^l+uB}E)#p_v
zU!P-J9$zbmhn#B!mB+URr~UJT>+@`$+WxR2RZZMszSkTLmcAxz+xb3sLTx48sH|`r
z@fc=6fjYrT@^*2ap6%YV=kp6cGBuB^0dCPDvLj&|Aow1M(l`R>0EY;T7^yrlkxj<;
zu@=|7MC(rCaR~XwKpBK%QWqQW?n)J|o!(J>=l*>m^h5Ksctm`e;(ZtNf<`%|$Sihh
zIp(t?XE5IwIl1{b6Y@lE`h{%s*XROv^Ff?kTy^5es(mPNwzxfqImtu#q{=2@5)xe=
z69pa0i$Ub+3hQ7=EUtu8`D)PW-N<3%|nb(pVeX7=2?pG-@Iy5nq(P@Ji^
z%Iez&&2SOIdse}$@^}WaL>n=d45Ot6aWZ=ll2^GIWd5BjP7aPqviZ>U4SnB5Df9Y$
z$vx!RLtIsDzUPe%y%AB8&{&7V`^subyS5I5D|Wbc1Ea0)IEg^;{vDjuH^qp)n$uqc
zC3?$L*0Osy?7IzlAP3K%V2v2b2x%bIY-#gnOxv_{RABs#JZqrLCu9#3lNFf>Njii`
z-;g$)D?R#@RQ)?Ug$jUq$%+S;1W~NaGEA!ao#a@>Z@f&ol6a5my0*3!hz*NU4Lab@
zBqd>t`2tdRC}WJw!taVPIZU$vUaty(@Fis=h9mq~)J`8rc@=bAc?nnTOTMAhXiZ2g
z>qM_R`bxOir>6B5NeA!rkOU*UG~OPI(YNLq1L+i`a{CUZY%;
zd8%XutuSN|qkB>2F=QkJ&p)72>g+gcL7bULY{;_@g@_rIyCAdD(A;&k9Y8uoD?R*N
zHwMneU&N)yvdS3kitKWY>2d9+y@83Z(sL5e5pqPq?0k&P$ndEy*x+j)+QTuopa?{h8Ci%4te&F
z%Uij=Y(ps=18S=qd(TQ9XtB=}D6FrtSu~*6^}z_Tdj@0V{Sj5xoE0cbkhuD^Wi{#P
zzbUbk<9yAS1w*lMUy`i^Jspwz*4&VmPzU}RfO4R*Y?ECv{O}Msf+cxM5@kN#Ycy4Q
zY^WH|YoR=jaShK+Hy)Qx%BJ|z-Om_`pV=cESsldD$=N=VVoyhbi5f)>Y}sd`By-KY#YKxvv1aSe3*})wYu><>M^B%Af5ZfX
zIXp!W+(Z(b)j~^c*
zaE1)GMsb4Qx%WEW#;C}b2kg)%aV@!loQR%@A-I+ZHW@EXk{Q5g2V2q#{*-TJ{Txsr
z9mVZYmRj__{rk-&RElEFhic&Xx>9(H$apasDMmQ0;Cdr7s6#ScQCS%lyi6kCnp8&g
zi49n
zNA>@D`t)UtRb8>POd&Y8v$J!~oXoW2X-g0~24AR>;iw&le((0f5G{Gs7*tIXSlU?h
z--xhSF+*cW%6FUS)*CKJx3|ahNgz~=0v{8kdQK0o?3A+Ig4*pZSSd`v&Q3Xgqj>g2
zsI4RK+>v%vf%lUf38KviB1TujhSq;fKs@k
z0RXD@3b#EH0xJ-csqMBxZoj+4IhjZ>8G1rk0TOvdI$5PT&!&TKCzIfLsE&_t83>>B
zQzL^kx2^1m*olpPTo@v{e-y$-Yk`dpks_{oBIVQyY2i3TTRiW8(VP!%1d0-QlozJ3
zKJmx}Cy#Ms;~dJTZ%q~t2F>LYiHr0O@Ty5CiMXuW4daqc6OvO-qfm-TDDfNLAnFrQ
zH6g(z0$fuiAxJo-(22c|PFfQ5c7Il(h4#33__=fEsLgG_H{#MaFJ8eiB7c`Nx6y&%
zMlHQij0dzv%59wBbUZ~N6*K|-rTR$otD9Rz96z5&pjcD}!RD*W(8XA10E0+UOTf+)
zVHd^?evHB4X=Usb55jZ_12imgA~F{^Mm}l{b+(nlUzHJUU#j?h`d`Q^ZRhOy42eFD
zM=~7^<@Ui0FIBat{=rJS;N#NI3O6CBr~$0(Tri6y;;Y5S2L*Oo%n@UrQl}v;@BGtRdF70s{gFi1uR`eCWKQ_*7
zLSMrRU4B0t6q42=@oD@qZ%sMw>Wi;+U&*t|N@)cEnupN!rA^NJ1Z8$VNbIwm+OxJe2^!NFgDY*4Zm0B1YCA%Xg>x(upD||acv+TR4PB>
zR9HD8M~wCqITTLs!bCp`?G-WrT4<|B9_96vS7gUIL=P|HQ>$p)@D?o0=epTvuE1h{
zFx@>BAl`Yo;%+Q`5&^=@gT@}OG|5v6$+HCh`TOrL7)_M)`St=^aE&RLZKVj|uu;s3
zRttXub1TC2}Q|7BDIjU5>FQ_8B(Xa0p}
z5E^hB#$~(?5m#{sVlJl0-vh$dAQq$SiPd%(?=2Ck7>B_%i1;1Gk$V#=ae5gkWZ;CN
z3$@0oAx45aBh;fVZ!do|)QrHoPQ)y|D#^H=pUUC7Ih)PtR=2BPzYf6GC)4i+1&OM#
z#VstVG1mzkO;=ybWq#CWJ@f~3FczY{G&|$*Nrc}e`QW2DpBxKOlg;U^0>4&lc19d6
zIbmC;%%efnwgAwWcc?9El-a@>%pdOeJBa3w)}G)4WWA@lj<
zX=C}Tl`E4%VHyyusQI>7TO1`pqU&gsw#jI8#{;8&c&@lN0ovq<#^a>5dP%XP5=w$-
znifdUC(;e@tPI+mxK;B#Ci8WgE2hc0)a13R-c0qD+7csrY#GG3fU>DdDM}$3845qTwbzBJ
z!ni~je!?N?t~k%-Ua=k3q|+AGn#)hd^<>pIUL>xHiV(X4;XPbx(5aPs?9gAo-J`
zCN1@#A*5zBB-pb{xit{d5rBo!_p8L345C7v4kM$Y8pdi
z81$$i%AQ)lsEwj26oS|7&{HiQR1TptX9xbNg=_L58$#n^)
zI)UTI-#X=&Bi<@LM5%ME#G^c^C%urMtwGbGQqVs|$P-sIA|cJXe3N~vw*z}9f?(^z
z@1Ld^exULaOz(-y;juY-fkV1@{wQU+$^KZau!L2$k-2LOvb5EYA@&L&2Tzc`AQ|X8
zib>N@e$%o?4^fpMvhxg3(4ybqabq#(`eDhK5=_JObfUKkPSa^x4zolqNHL=)kXRtF
zf%o&E9eD8R5PWH6Pr^twx*`=`K_z4a0u5MmpBq?Fs0R*Dqm(Jw}e_uuH
zA2J+sE)H-sx;{$K{9bAXysXYjwO+Owqeto(a3eU|IF+UPMO8>b?6h928jQqzYN=z5
z2I!cr)P(*0aZ80C7%Gn>$Ff3Zw1;Xl5L
zMjw+Zk<4FIx)pQ&r3M;V&>?kIxkIKET(fSp-+hit#wd3K4vYwXXMTyZ7P^GK-w)z=
z0E$LGFzw@+66)?#VA#T$Rycx=!1&)ES`uAo0s+ckl%k~v`Ut6mwFSK29*;?5y7kbP
zQ^BG2-0+%1t)o5Nlg^jU@h6#F3DrjKgX&^##rCFUU9i&3?RIjvQ1#c<5{E+@0jfa&
z&NUE~SZ4@#caeps_Ab8<>Q+>JG#>AFjy*j>7}yb
zng)T7GIk>-OMa!;LK&xNsRSJQ%jcTDKRF?_w}H(iV~c#rSXP;G4>_D8-dc65LA8@J
zx3CZOvrt$b*I!aq6;0F0o_vsv8%N04Ia!PUgSPj8iu&%_MMq6yViaSdQ4wrllp-ok
zI>rK`fP!=Z3nEoSs&q>tHi}dM0hQjBDj=Yuq97m)MY;-z!w5)|4(HjVzUO}De&1bZ
zUDtZwG|J3>er4~cZEh6`I^qE+E8F(cefj9ib!NjJc%oU8&`r@#$1R?;*
zg5{YmZ6^Z4j2gElOG_dFwT#1w5~;>QM2bWr0O0Z+_|W$?QcZ(bN7c5Gm7;M?gS`!6
z*W%$8G%I)|-%j{Ec?&jLtJ(r!^~{53_nuOsY7EaBv(qvD6CZ
z0(57l8tFo3-@xHq!{z;5iiA?BsA3YlkNyhOeq
zi)W+$18HjrmWikd)@V>Pv_Q21s4QiPR}&R1+AfRuOi~Y^pf<~GuE^{EO1k};msc&E
z56WyAm?*!@kC^9>6Ru^`__LBzoA+GCKr60{EIXDuF%)QND%sYz(nFtYK$HnIKYpo4
zwuq?42`b?pt;WVwW*fV61fxJG0Z!Xzj>jas68MGE5ZUgA+}q9Ncb(v$&|
z0;yF?`e;BZQZAVgR>k82myT`_vu}a;EE+IZNHy52v|vN$m+Q*S8^s*aUpx`*G(|%~
zmc&D?KqV64RN*Ljf(}tIF7D+E=5Syv)(AT0U@)(1S>xL#kZz`{dO9d%d-pn#1KeGb
zvVG0iJ~HLV(^=Q!E#3PX*$D~wNm9y=#88qH2mFi%4)-ivG~se?Qf|3u$lZ*R2ll<1379t!%{KU-n79_Fu5f4M-f?@ESQ}JNYs?!;mnk(FaUVHBeT;*?$Y7%ET*iU>p^a6C
z`hNfP89@r&srkLtWEMr{4GV8lbB-v541jYI#QDA%k4DD;a1YXbF&>Iv?{eymA%4R&J==rV@g%TJ_7F3
zq|)b#^2N$2)#SvmcRU0Q-HlmE?vwqBo21mz@
zXt;CDArV3n8ZwYk5v8E7QS!qlM+}^&@Xf?VSrGiL%~b81fhiFedw~|%?m?9*_^?bf
zrYHjG4tQ>2jXzs!8y9(sp?kansGXV6Ud}%~EU?G9H69>`L`9EGUvobw
zMXAXmxCh4(i?i&Yok4DW#C7-u(5H4~(
z^SolJm!)HyC;#ce$q$-ftRs#Or#|`#o4N+JGPJ(?AvT~)#7tP&h~vYIF^Jw=oHt_!!BxRl`(Q|1=jkbq9MAr)KI%Dy*m&_Kzdrm%miFBDtT)Xp
z-!3*@QVcoZK|ZBVzKcE4musOJlwT?4(ANg2_aM=%+^y#UqKFmvw`03-4d65~zz1o+
zckp)$AG;~ftDsVD72A&E?qNzxRv=`0od=4~T2M5>?Y|9GvfeM8oJaUqdi_|uT2xJu
zhlghoRbm6WF;4r?|Eidw9)B?qY%RG2?nj_}ab+omjPmZUO;IEAfu^%y&CsNVVPK@W
zL)Uzm*-_O
zz=eN>RP7MjZx!zMKtaLRq+u!OrCOM@oV|b&IncNy&7krSQb+E=u3AE$jS&zuV5QU=5_g>ET-d|~N
z=9YB(@CMGZ;u++qgiO!N!o6UD5Ya?1HM=4}^HEVWjuwu)x?n2FUAs}lOEG`aca)Dz~KmzFn@RZ8Vm{{k3$=`nb
z&yrW0O5UrrE_a}M8h2GxWQ{L0#^=IBGm1RGBc!(^84r*^qf!g81p)c3XWJK*RU8F;
zKq(mG!zpNc8-k37d!IMBh-kMqz0oydCaV>0T0dWCIgGwd}&P3=YXte}!>o14(n+nT;H(7(t_F6&Gm0}TZiV$242rO+^
z<4BuF8i_Ul^@*}u;XCARoOk5Gm+0>nEU1P-tJ^mlaD7ipzBY)XTHLT)K~$m5#H;4F
zz75;81~F^}+Rj$)x;AuUK~{+el(CK90y$0FWIvLQ3Uv<6oAB=$hvI|KzD_%%mBzI%
zRr98=g};JPQ=oXO;FcdCSJ@V0{4n?P$Vfev4wS$FO`mGfw-B?u8F>5)%7wm%gWknI
zv^WIZSe{%s2Rdo-vxkBDngUZL
zqEJxLEGQaKsRb@)R?&&T_0p$05N^Rf5EnpzW^lU#akH48Z9
z6$-oH7Yzd(iSf8E1BlF${bJSdTg!YuS7rQcL1-i_6N|
z#+}0*dA7hmN}wl1q*X5H`wO^W6L5IxA>_`v5ypdI_!z?qudRadH(~Jc?>a@q;%=zh6kgOx>ac9Z`-hJ!^eg%Dw5nI(pK
z2wTLjuVV>nnvnpRH07dq{c88R_m;}o`12xHMvX_&+irB){?*NG98qqEzx)1s5rZwL
zCY7UFl~N0G?q|rrKJfeRze_f^?Nf&=Io*rLOCV~`Nqdz{=}TbssHHuYn=#)1TzaJd
zDtl0RamrEQQ&1F9APDsJmT9;fSPy9ig-6W&Vc2)2LxfzrBF4%
z)m^?;UAbXeS|9k@DT#e7`S`O#6OP~qAi`4}pD{8r5<}I_)Tl?B=ZvHt{i`p->LaeB
z$4w0nlO;Au-U0umDn2R()ZjbKZk&HElaPJ7+z>$1t^6
zjwL+-OBzz0Jb{<5o`{9UUEd2rk5$^RQLf=UA%2AyeSk
z{u{3S#)nQB;73@#+ohzW4#e&GBJSv}MwzFSJp{Eh%ZzFRyo8qCX2i$Gf|BuEm&1&$
zeKGkx6T9NTbj)(
zU2Em-zxoZxjZ~%!n#p<^bRcyaosPL)eIidQ02d4AZ6vtyTrTAFIM^ub?@ftQ25QOe
z%#lK1`t>xW32F#+RQ%ccj*uHUcLr)}z|lm}I>#Dt^DBpQ61Cdy@)C%_9t8z+*m7v0
z)*z)aZe*cWM)8S=1===!5j+4mMZHdf3>-%M|IN}dERpoheV9K|11g!j8Wo<2b1!TF
z_T$YEhr={*jPu)f;3LksNYymo6S+hPubof2^RRhYmvT~<+UW*R_{QVZgPOb}0$wh5
z@QFa$!}nDKP!y)kj!yaP3}y1E1_iAASz0j@I=~j2p;xyGnYu`v?Og1YG12?1;!SdE
ziSe}B9XmI>N6>PFR;P4y+8SX;3_+ViMyyyVXGHqjVOG>l_t(ZIVI*xP9|VUPeqh1j
zzEPPopX~cu4X`WhO-~~<+XDAi*}5Z;uxyrA8h?_t5jsm_n%LrotDa?s3PKxS!99R}
zvN*k1CjGfx?KvOHoq|}S&sU35*xnU{PZ_)4{|xR*TA3N}0TCM8Rh-aJc5{^+Mhg_j
zBM#xIArOjs5FZKXaLBAg4(=iNSRg-iCO#9}^;Y{S6AE=~IA)5oa-WjYnY~bBUrq2v
zG6@C`c@E7WiLY{?el1oQg%_-L{uKiuWH-|`_3Hc0u_|^c$`*MHUdS;oi
z=*38LR%(-f>DWh#4PGI;9@+%>&(pbHrlL6`Q%a}X{^u4aXdi&@^Xw#|9Pwhe9L`Fk
z#|^sgT!!U3OjEF;!OZJ;`yI7k96lDo544^YzlwelfUb652VlNs6NX7(K&IeG1EjO8k^wefM~Gg<~cbPwbkMrzIs}-z*wKaj(LykfKwN
z69RRJndo!ej--1q+)~*v^0uKMjU-sp=teEe9DfhrrXza*E}bgTEY>Ya+glEznM^c)
z)kX67E^kVeL40qssBEHLfvwK-iX9HM*IG*K+=H^^-N#uQRl=n-aYUt~Y>uM&Sm3x~
zCy7EP9Jnl-Lbnbzl8TqB5A|cZ3grhbKVoBmC3j}2EOUW_OT(SPr{>h;mt;p
z;-R=~_`gD=V$h&W2+2=4y_XHkmzy3nVmjHu0$J9l^U0D4KaOST2zut5t?y!$fHl{8
zZS#lLTf?j!DmG+)-Y|M~b?#_kaf~LmuWF
z#HJ(_T%CJoX2AA~B0G=y`gw#k+Co!k4uiHup!X9^zYs^6g(N}2xgQ*njr<>SrJ?FB
zLQK{j(k=l5*qR~@vcNM~$OpkOlmUYNl)_dpY$2K6=8qfpkw=aM$SeiQ%i@^HiMsx9
z0IeZ?yY*LgnSMZF+udgr(^83E}Mm8u!0
z@)L3j(z3w5Qipm{469hCX(QPV>2t;bAQ|n$DYg&bvwzXdjJwgXKiba%B=m+#+Qt?a
z?|=n|lB7`kYa{Jf9ZfJ!%T&T2aRO9B!El?<&!-)|{aw8#Sy4Tihuy6}<)k{ng<(*N
zEVMXKEoUV-yY#&d`4Q1pb|nA6AC?tWkC0$^e<&>pKab#C0%oC+jcYsdskPuR4e|RE
zEN_9!2r>2xS}?tYj2TGap~zIk@~ou#9#tKtAlxk8a*27OPyyA<1c4pJi&xR81f29N
zm@&2S^@NS18KGH
z%bz{e`P%k2O;|)&S^5(`ka*aQoB`GeE7VVLug;^-2|L^VgUKBN*3|bzCeotJX0S
zB@r@|0tuHHnxljV8iOh>0lyGIicZdk#al^LB#W>j64{_tranA(D0~{FVhlwQ-zk1a
z$RBQdSqOFrF2pE=G$>tp50vJEU>zc8&F%xJ)hzNq(_%wqrv>{KGtHh}4hWA-I1ONq
zJ%aADBHdN{&B|hQVJYO1JC<379wr`jBqzkyBzeKdV~(@c&}k!S*W&o$Gu+o
zoN+XySmuy|7|g{!G?3b;NJ!1-2FN(pm0Whk((Ch$*l>qXS?!q#h_f4`6UlUqK-s$h
zo5*S0P@%pqx9yV4P6}(nC^hoDa=FMKUwYe)vVUD9*cpfHJIcdnt1dY*JsxmvHl)@A$SZS82iN#Xpy>)0_s!A?Y-7Q}RNai{
z!l|T@
zmyjj!z)humbOb+EFUZ0^@<(VvHlFzzNo}LpIT?Z;SaAwai!>RZZpz+Va2@qT4l3xP
z!X<0goW5!T-zO;@$~sSo!#fb%yTm3hLbDJTG$$^BGT{o`mZSwz9r@KE(iYbp2V42(
z)^$xLQP(}_nWINJde|)&~jy`7L-E2OMY$dDAEA$tk|2-^&uSsMpIbV
zS=%mEY~@!rp&_pj0v8WUT1$^wNjgda3qt?ta!-&GChr6hQ258POp@0H?b14IhPoUY
zSF_N(N8Z8%)c{W7P_>Yc(q;@(ZbXrwUv}g;DR!9eI(atAW7_hN%805w7Er=%g_GVbP;SAVlawO|EX6;LIShMH-N5oqR8B&k^TGGzA5{h2
zZ6Cqe5<3l7K_Wi1h9D%bp9;?I
zG6O_Kb77e`u|m?w-Hlc-U7w@{Wo9Mm11Pr$$`+ChgB@iLNvkn>_fwtt!_A2Hqe|^C
z`)tPQPcjuf5`E3Jxb`Rt510O{FJs9>OJQq7{mJnW7VgisqSNx(|6xFpH|$28?exITM4+
zEO56`RRpv_SLie#2QmmatvQvoD8CG-%`Mda(GXDnN^Y$WOnq&rcgXe`^Dq_I0sbSd
zu08O3XXIhczn0778eq8Z}G6T>^NqDv6i)(1d40PG#
zEE)-*L_*xDA~DcIHi)+5hM&?S%H4g+c@~7z(a{MqUW%|kMComdap`_zE57Sj;1G7O
zYnbGwZqauUCIKjFjbpjj6B2E`S&4Jjka?83JiWs3)rp^>!6li=u{U-~SavxOzeG&W
zU_FLqlXIF&!BPvDtxAN9E|^e~+h<__4aj~yGFXC3z@ZvLnHne-2-WEfp2Dpn{_NwY
zIc57$!xJA&WhkBk1@xf>iG!(}Vhf>EqFxcM3ign3F%*r-U`2KS{CkZ9@(#`^3UQ?I
z+=yM(q>l#ZFgOBje7u{>?nf=uW#+#R;gy=0WIGbg(His1l(7N|X?qC`9dW
z-6o)3@=IO3D_j>9=H{}pD=6zi-k(B^o6UB*+sn(sZLa}rSrn=^;%n*bTp`!geT-^9
z%ry%ocP9=4Q@9$hdVANQ+d}Z{U4kbO%R)*Ol-OotjL;8=#6E~0G(;UQzBp(i8c1F2
zx`Gs`@?3I=$4XTuM!kdN#MntD4Z~@Ngde5m0T|CVlRs%WA)MD4bU5JV&70FR$x>Sz
zbNe969)hxIR{ucxlW3|0{tVMZDF&Q%18I|C0@FBpdpLzKko=Nt?tfW)FfvxAsbV80
zj$jVW-f{alyd1=?s|1DL0$;2@b(|S40onZ06)Q-M!3Vw@1hpC-TMdv5N>oqbvm}}s
z%>73k?$z+!;Fxn@p~0f*3zX=IBa8YHD!ITSD9cMh9bb)Ok&NX;+0n-iV%i>^oB`b9
zSRGneS2QdOr^M!_HJ6*AoTZd{TwB|Lx+%h>(pomfc?;r(ddn1Poba
zHiu1~AyjvzG!mJ*8tBI2QLxkNhEAal0=5VY-@!y<%ISb%$q{6;2J}ExfV{Y4-(-aT
zD4N1-#4+$!EFXfk1HqB+3l<8O<5tlM|J8OPH^az&^5pPC4|K1Twuvvv5-hu#)BU)&
zT_&f?K$U2U@0SbJpv))D4_cW0xB(AgFVM(#q-oOWjDzXW`2GOpWcz2#
z_T9fu0@(KE)9|9OI)BS(S1%pQ4d*r)zBy*>EghKxMnejUid}jR+|IZf_RMPTrjb%|
zBG(W_Cx!w=WBr+!qi7T;oQ{tM=R~l0W|LxoD{Mk8
z5#1B0c!vNW2q3-!Y&)DM8hB;Y&OjHLgqyO#Fc`OADhw*!*w}WX9AZ(|Bm1GrQODMz
zzy?ah08DlWbqrlB!$?O08WhxaS~`Em0-|43Xh~3Do8tLPAzz*v9jv=V`0e08aAX&F
zwRBRzDG7SW-hcB{tOb4=rBp4_l1bY&;L_6DlFxn>BEn(TFtwwt
zcLi?(UMt~(bV^}~9Io?`o~T@gUABD@=M7zyuq5aKRzcS}>b0^jEw>EF5$T4w<**1P
zk-jbhess0^-tUAgZ%lvehM~i)9v|G$Uw`vWBIFaqI8fz6nM=5s0F3$VH}3i%LADLT
zh6<*~*?M_)3BX*F|MZ7rE#vKI;q)LTKd#40tG8gpkW@r~fa`%k;DCrnNg
zw`XzZ&{gxn15UhQfXPzPIp`V5^p_+!=@WTug@WPyIgA%=c)we4$!f3M!iO6}%szW|
z;DsZlwot*fcNNMBZG`|znLjuA5hMr^?Qq&wGbyMF6LqRh!y<$hpF5qPmz4-RL$_}b
z+Eu%)9E=9|DIybgwJ$&7dIu^d37_?)Gbl9~zA>oAnOhn}i20=iQsZ6`c?2sT@SKgZ
zr_{NFxApTKHkbYSi@LhHC>l&pjw{u}HxiPicpD8ckj9s;>(4W2L|afsIxQ`ipVyK)
zhoMX0JFHx{2`a;(NFOdOR4}+y5{GUxx`cC&yADc_^azjXF`26?=$Fx-w~;JdZshmJ
z2N_2z8`mh-3x*%O25?GaPEgahaj*&bAn}`a={&~mwPd)#2N#2eh$bE2p1fZ?u!Kh;
z9^yKur7iOFC=;}SrZ`|Zpi$4W9K7V|X#s2jU`7AV6My`2{QuXL(D7tpH(3tSUZKb(
zQa#lUFc_Qmy2Ben=x|UONr%W`QnqAjaI1kBW9@zzgAU>JPA{j~jRZtun`@z}eE7r4
zzkc|R$GB;hK)%b<U`U6hM6JGx1F9QK0NmR1|Mj2BU%mDJV}8rO{;lhe
z|9{4{Mn6J6tfW5zYcT{wNgbfr(iJaKDT?^qz_Z8`WH3JM+Nk(Q0W>`PdVbgz15!&FtDlc?Eake@$2hpP
zYI@$+-*?FzyhrJSu8Zn_VeD{!G`zs+imLZHFDlru1jZ(8&F9S6-Rgq~c8r7Z^-n$W
zvtLi&$aqw5eQGYFW4?ZxZ}8kfDeQ=+&^`j(bmIPovE{An`~@5pj*Lw=O=r$u_}zB(
zCLM_`h~_U@{KQx*|JM2Uhr8?b9x1?TPPc=fzyIL>hnGhqT9HeDX$>FjH!)=N`3ruoaJqf;-L3hIQO;BqJic@6Wdr{gpWQhxfY?+kLX-E9m{R{W8Ddek8x9OZuR-b>X}n
zk9SYZe&y`9Fg}avhcOsqbLs^;Hel4GWdNXMoH~4eeobOgf8eYlf?MSme4Z&Rr2pVHTBM!0f46T&tORq{V%cb#ywq9YM?Ydf6)yxw@SYT%
z`#X{2NW*5)Mx~;7;72D-$x(ogC_C~xdT
zSSOeS@QxJW77EV<_}w(fDUyKRw@$|Y{hD_a5*tDk5D3j6UX0Yw!^nu->krfZO$5!Il>s8;*^^R8A*8ZdQCQ>Y!t`hd;b@ES@Aw2*pQoH>HE2 }EpxH%Gio~6v
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