diff --git a/.gitignore b/.gitignore index 9aa0ff0..0844773 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,6 @@ build/ artifacts/ .ipynb_checkpoints/ _braggtrack_repo/ +.coverage +.pytest_cache/ +.ruff_cache/ diff --git a/CHANGELOG.md b/CHANGELOG.md index b035fb9..f6424c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,31 +5,33 @@ 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). -## [Unreleased] +## [0.2.0] - 2026-11-17 ### Added -- Rolling-median threshold smoother (`smooth_thresholds`) for stable multi-frame segmentation -- Outlier frame detection (`flag_outlier_frames`) via MAD-based statistics -- Label projection by intensity (`label_projection_by_intensity`) — replaces broken `labels.max(axis=k)` -- MIP-floor masking via 2-D Otsu (`otsu_floor_from_mip`) -- Tri-axis segmented mask visualisation in demo notebook -- Semantic MIP gallery and PCA embedding space plots -- Google Colab support with auto-install cell and "Open in Colab" badge -- CI matrix (Python 3.10/3.11/3.12) with pip caching and notebook execution job -- Optional dependency groups: `[torch]`, `[notebook]`, `[dev]` -- `BRAGGTRACK_DATA_ROOT` env var for custom data locations -- Ruff linting and formatting configuration -- PEP 561 `py.typed` marker +- **ESRF-ID03 & generic NeXus HDF5 auto-discovery (`braggtrack.io.nexus`)**: Added `/entry_0000/ESRF-ID03/pco_nf/data` to primary volume candidates, largest-3D numeric dataset fallback (`discover_primary_volume_path`, `load_primary_volume(..., auto_discover=True)`), and `/entry*` / `NXentry` metadata discovery in `extract_scan_metadata`. +- **Physical reciprocal-space calibration (`AxisCalibration`)**: Added `AxisCalibration` contract (`voxel_to_physical`, JSON serialisation), HDF5 axis auto-detection (`extract_axis_calibration`), CLI calibration flags (`--calibration-json`, `--mu-origin/--mu-step`, `--chi-origin/--chi-step`, `--d-origin/--d-step`), and calibrated physical centroids/covariances/eigenvalues in `extract_instance_table` while preserving integer voxel bounding boxes. +- **Per-grain 4D kinematics CLI export**: Wired `compute_grain_kinematics` and `summarize_kinematics` into `braggtrack-track-dataset`, automatically emitting `kinematics.csv` (including `delta_d`) and `kinematics_summary.json` alongside `tracks.csv`. +- **Split (`1 -> 2+`) and merge (`2+ -> 1`) lineage DAG resolution (`braggtrack.tracking.events`)**: Added intensity-partitioning-gated split and merge detection (`resolve_splits_and_merges`, `SplitMergeConfig`, `LineageEvent`, `events_to_table`) with anti-noise minimum fragment share guards and distinct daughter/merged track ID propagation. +- **Persistent 4D fracture precursor scoring (`braggtrack.tracking.precursors`)**: Added `compute_fracture_precursors` combining 3D eigenvalue anisotropy, covariance trace growth, 3D spot ROI sub-peak bimodality, and upsampled MIP DINO patch-token cosine dispersion with multi-scan contiguous persistence filtering (`min_persistence=2`). +- **Synthetic 4D fracture ground-truth generator**: Added `generate_fracture_scenario` producing 4D intensity cubes, label masks, and ground-truth split, merge, persistent precursor, and isotropic control trajectories. +- **New CLI entry points**: + - `braggtrack-events` (`braggtrack.cli.detect_events`) for standalone split/merge lineage and ROI fracture precursor ranking (`events.csv`, `events.json`, `precursors.csv`, `events_summary.json`). + - `braggtrack-run` (`braggtrack.cli.run_pipeline`) for one-command reproducible end-to-end execution with JSON config support, stage timing profiling, SHA-256 input checksums, and `run_manifest.json`. +- **Semantic ablation bootstrap confidence intervals**: Added `--bootstrap-samples` to `scripts/ablation_semantic.py` reporting 95% bootstrap CIs (`fragmentation_ratio_ci95`, `id_switch_rate_ci95`). +- **Events & pipeline acceptance gate**: Added `scripts/check_events_acceptance.py` and wired it into `scripts/ci_report.py`. +- Rolling-median threshold smoother (`smooth_thresholds`) wired into `braggtrack-segment-dataset` (`--smooth-window 5`) and outlier frame detection (`flag_outlier_frames`) via MAD-based statistics. +- Label projection by intensity (`label_projection_by_intensity`) and MIP-floor masking via 2-D Otsu (`otsu_floor_from_mip`). +- Optional dependency groups (`[torch]`, `[notebook]`, `[dev]`), `BRAGGTRACK_DATA_ROOT` env var, Ruff configuration, and PEP 561 `py.typed` marker. ### Changed -- Seed floor now uses robust peak reference (p99.99) instead of absolute max -- Default `seed_response_percentile` raised from 99.5 to 99.95 -- `torch` and `transformers` moved to optional `[torch]` extra (bare install is lightweight) +- **Ungated vision backbone default**: Standardised `DEFAULT_DINO_MODEL` to `"facebook/dinov2-small"` across `semantic` and `segmentation` so local installs, CI, and Google Colab run zero-auth out of the box, while keeping gated DINOv3 (`facebook/dinov3-vitb16-pretrain-lvd1689m`) fully supported via `--model` / `--dino-model` with universal dynamic prefix-token skipping (`cls` + register tokens). +- `segment_dataset`, `embed_dataset`, and `detect_events` now load real bundled ESRF-ID03 `(100, 250, 250)` volumes directly via `load_primary_volume` and require explicit `--allow-synthetic-fallback` before substituting synthetic blobs on unreadable HDF5 files. +- Seed floor uses robust peak reference (`p99.99`) and `seed_response_percentile=99.95`. ### Fixed -- Critical threshold domain mismatch: intensity Otsu was applied to LoG response domain -- Spot count instability across scans (11/22/36 → 18/20/16 on bundled data) -- Label projection picking highest label ID instead of brightest voxel's label +- Fixed silent fallback to fake `(24, 24, 24)` synthetic volumes when running CLI tools on bundled ESRF-ID03 NeXus/LIMA HDF5 files (`/entry_0000/ESRF-ID03/pco_nf/data`). +- Fixed uncalibrated detector-crop pixel offset distortion in crystallographic strain ($\Delta d / d_0$) when `AxisCalibration` is supplied. +- Fixed threshold domain mismatch (intensity Otsu vs. LoG response domain) and label projection highest-ID bias. ## [0.1.0] - 2025-12-01 diff --git a/README.md b/README.md index 86810a2..8f43b53 100644 --- a/README.md +++ b/README.md @@ -2,109 +2,145 @@ # BraggTrack -Semantic 4D kinematics and fracture tracking for operando diffraction using foundation vision models. +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BASE-Laboratory/BraggTrack/blob/main/notebooks/braggtrack_demo.ipynb) -## Repository layout +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. -- **`braggtrack/`** — Python package (I/O, segmentation, semantic embeddings, tracking, CLIs). -- **`data/sample_operando/`** — bundled example scans (`scan0001` … `scan0003`, each with `pco_nf_0000_cropped.h5`). See [`data/sample_operando/README.md`](data/sample_operando/README.md). -- **`docs/`** — [architecture](docs/architecture.md) and [coding practices](docs/coding-practices.md). -- **`artifacts/`** — generated outputs (gitignored). +## Key Capabilities -Contributing: see [CONTRIBUTING.md](CONTRIBUTING.md). +- **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`). +- **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`. -## Included example scans +--- -Bundled under **`data/sample_operando/`**: +## Installation -- `data/sample_operando/scan0001/pco_nf_0000_cropped.h5` -- `data/sample_operando/scan0002/pco_nf_0000_cropped.h5` -- `data/sample_operando/scan0003/pco_nf_0000_cropped.h5` - -## Week 2 classical baseline status - -Implemented segmentation stack: +```bash +# Core package (numpy, scipy, scikit-image, scikit-learn, networkx, h5py) +pip install -e . -- 3D LoG enhancement (`log_enhance_3d`) -- h-maxima seed detection (`h_maxima_seeds`) -- 3D seeded watershed-style region growing (`watershed_from_seeds`) -- post-processing (small-object cleanup + 3D hole fill) -- feature extraction table (centroid, bbox, integrated intensity, covariance, eigenvalues) +# With PyTorch + HuggingFace Transformers for real DINOv2 / DINOv3 backbones +pip install -e ".[torch]" -Run end-to-end segmentation artifacts on the three scans (omit the path to use the bundled sample automatically, or pass it explicitly): +# With Jupyter, Matplotlib, and Pandas for interactive notebooks +pip install -e ".[notebook]" -```bash -python -m braggtrack.cli.segment_dataset --outdir artifacts/week2 -python -m braggtrack.cli.segment_dataset data/sample_operando --outdir artifacts/week2 +# Full developer environment (torch + notebook + pytest + ruff) +pip install -e ".[dev]" ``` -Outputs: +--- -- `artifacts/week2/segmentation_summary.json` -- `artifacts/week2/segmentation_summary.csv` -- `artifacts/week2/scanXXXX/summary.json` -- `artifacts/week2/scanXXXX/features.csv` -- `artifacts/week2/qc/week2_visual_qc.ipynb` +## Quick Start -Note: if `h5py` is not available, the CLI uses a deterministic synthetic fallback volume per scan file so CI and schema checks remain reproducible. +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: -## CI/CD +### One-command end-to-end pipeline -GitHub Actions CI runs: - -- `python scripts/ci_report.py` - -`ci_report.py` executes unit tests, Week 1 acceptance, Week 2 smoke, and Week 2 acceptance checks, then prints explicit PASS/FAIL criteria and overall status. +```bash +braggtrack-run --outdir artifacts/pipeline +``` -Before opening a PR, run: +Produces: +- `artifacts/pipeline/validation_summary.json` +- `artifacts/pipeline/segmentation/` (`features.csv`, `labels.npz`, `summary.json`, QC notebook) +- `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/run_manifest.json` (SHA-256 input checksums, git SHA, config, stage timings) + +### Stage-by-stage CLI commands + +| 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` | + +--- + +## Physical Axis Calibration (`mu`, `chi`, `d`) + +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: + +```json +{ + "mu_origin": 12.50, + "mu_step": 0.02, + "chi_origin": -3.20, + "chi_step": 0.015, + "d_origin": 2.042, + "d_step": -0.00012 +} +``` ```bash -python scripts/pre_pr_check.py +braggtrack-segment-dataset data/sample_operando \ + --calibration-json calibration.json \ + --outdir artifacts/segmentation ``` -This checks for unresolved conflict markers and (when `origin/main` exists) reports ahead/behind divergence with a rebase hint. -## Week 1 implementation status +If HDF5 scans already include 1D `mu`, `chi`, `d` coordinate datasets or `/entry/calibration` attributes, `extract_axis_calibration()` detects them automatically. -Week 1 focuses on data contracts, beamline adaptation, and dataset validation. +--- -Implemented modules: +## Vision Backbone Options (DINOv2 Default & Optional DINOv3) -- `braggtrack.io.models`: canonical contracts (`ScanVolumeMeta`, `ExperimentSequence`, axis definitions) -- `braggtrack.io.beamline`: beamline adapter to map discovered scan files into contract objects -- `braggtrack.io.validation`: sequence and metadata validation checks -- `braggtrack.cli.inspect_datasets`: scan discovery + metadata extraction report -- `braggtrack.cli.validate_dataset`: sequence validation report +- **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 + ``` +- **Offline / CI (`mock`)**: Deterministic SHA-256 multi-view projection encoder requiring zero GPU or network access (`--backend mock` or `BRAGGTRACK_DINO_BACKEND=mock`). -## Week 2 baseline (segmentation) +--- -Week 2 starts with a robust classical baseline, including **Otsu thresholding** as the standard first-pass separator. +## Notebooks -Implemented modules: +- [`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/dino_segmentation_comparison.ipynb`](notebooks/dino_segmentation_comparison.ipynb) — Side-by-side comparison of stabilised classical 3D watershed vs. experimental DINO patch-clustering segmentation. -- `braggtrack.segmentation.otsu`: pure-Python Otsu threshold estimation -- `braggtrack.segmentation.pipeline`: threshold segmentation + 3D connected component counting -- `braggtrack.segmentation.classical`: LoG enhancement + local-max seed extraction + seeded region growing -- `braggtrack.cli.segment_synthetic`: synthetic smoke test for segmentation harness -- `braggtrack.cli.segment_dataset`: dataset scan segmentation CLI +--- -## Quick start +## Testing, Acceptance Gates & Pre-PR Checks ```bash -python -m braggtrack.cli.inspect_datasets -python -m braggtrack.cli.validate_dataset -python -m braggtrack.cli.segment_synthetic -python -m braggtrack.cli.segment_dataset --outdir artifacts/week2 +# Lint & format check +ruff check braggtrack/ tests/ scripts/ +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) +python scripts/ci_report.py + +# Pre-PR hygiene check +python scripts/pre_pr_check.py ``` -Each command resolves the dataset root via `braggtrack.io.paths`: **bundled `data/sample_operando` when present**, otherwise the current working directory. Pass an explicit path to use another dataset root. +--- -If `h5py` is unavailable in your environment, scan discovery and validation still run and include a clear warning in the output payload. +## Troubleshooting & FAQ -## CI/CD +- **`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. +- **`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$. -GitHub Actions CI now runs: +## Repository Layout & Contributing -- unit tests (`python -m unittest discover -s tests -v`) -- Week 1 acceptance checks (`python scripts/check_acceptance.py`) +- **`braggtrack/`** — Installable Python library (`io`, `segmentation`, `semantic`, `tracking`, `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`). +- **`artifacts/`** — Generated pipeline outputs (gitignored; never commit). -The acceptance script verifies scan discovery/order/monotonicity and fails only on unmet acceptance criteria (warnings are reported but do not fail by themselves). +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 bcf020c..20123fa 100644 --- a/braggtrack/__init__.py +++ b/braggtrack/__init__.py @@ -5,6 +5,6 @@ try: __version__ = version("braggtrack") except PackageNotFoundError: - __version__ = "0.1.0.dev0" + __version__ = "0.2.0.dev0" __all__ = ["io", "segmentation", "semantic", "tracking"] diff --git a/braggtrack/cli/detect_events.py b/braggtrack/cli/detect_events.py new file mode 100644 index 0000000..321dfaf --- /dev/null +++ b/braggtrack/cli/detect_events.py @@ -0,0 +1,280 @@ +"""Detect split/merge lineage events and rank persistent 4D fracture precursors.""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Any + +import numpy as np + +from braggtrack.cli._utils import load_feature_csv, synth_volume_from_file, write_csv +from braggtrack.cli.track_dataset import _load_embeddings_npz, _merge_embeddings +from braggtrack.io import ( + BeamlineAdapter, + MissingH5DependencyError, + discover_operando_scans, + load_primary_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 ( + GeometrySemanticCost, + PositionShapeCost, + PrecursorConfig, + SplitMergeConfig, + build_tracks, + compute_fracture_precursors, + compute_tracking_metrics, + events_to_table, + precursors_to_table, + tracks_to_table, +) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "root", + nargs="?", + default=None, + help="Optional dataset root with scan folders for 3D spot ROI sub-peak + DINO patch dispersion", + ) + parser.add_argument( + "--segdir", + default="artifacts/segmentation", + help="Segmentation root containing scanXXXX/features.csv and optional labels.npz", + ) + parser.add_argument( + "--embedding-dir", + default=None, + help="Optional embedding root containing scanXXXX/embeddings.npz", + ) + parser.add_argument("--outdir", default="artifacts/events", help="Output directory for event/precursor reports") + parser.add_argument( + "--backend", + choices=("auto", "mock", "torch"), + default="auto", + help="Patch-encoder backend for ROI dispersion scoring (auto, mock, or torch)", + ) + parser.add_argument("--model", default=DEFAULT_DINO_MODEL, help="HF model ID when backend=torch") + parser.add_argument("--position-weight", type=float, default=1.0) + parser.add_argument("--shape-weight", type=float, default=0.5) + parser.add_argument("--gate-mu", type=float, default=float("inf")) + 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("--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) + parser.add_argument("--min-intensity-ratio", type=float, default=0.4) + parser.add_argument("--max-intensity-ratio", type=float, default=1.6) + parser.add_argument("--min-fragment-share", type=float, default=0.1) + parser.add_argument("--precursor-threshold", type=float, default=0.40) + parser.add_argument("--precursor-persistence", type=int, default=2) + parser.add_argument( + "--allow-synthetic-fallback", + action="store_true", + help="Allow deterministic synthetic volume fallback if an HDF5 file lacks a valid 3D dataset", + ) + return parser + + +def _try_load_roi_inputs( + 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] = {} + label_volumes: dict[int, np.ndarray] = {} + timestamps: dict[int, str | None] = {} + + for idx, sd in enumerate(scan_dirs): + lab_path = sd / "labels.npz" + if lab_path.exists(): + label_volumes[idx] = np.load(lab_path)["labels"] + + try: + root_path = resolve_dataset_root(root_arg) + scans_fs = discover_operando_scans(root_path) + except Exception: + return {}, label_volumes, timestamps + + if not scans_fs: + return {}, label_volumes, timestamps + + scan_by_name = {s.scan_name: s for s in scans_fs} + try: + seq = BeamlineAdapter(root_path).build_sequence() + meta_by_name = {m.scan_name: m for m in seq.scans} + for idx, sname in enumerate(scan_names): + m = meta_by_name.get(sname) + if m and m.start_time: + timestamps[idx] = m.start_time.isoformat() + except Exception: + pass + + for idx, sname in enumerate(scan_names): + sf = scan_by_name.get(sname) + if sf is None or idx not in label_volumes: + continue + try: + vol = load_primary_volume(sf.path) + except MissingH5DependencyError: + vol = synth_volume_from_file(sf.path) + except (KeyError, ValueError): + if not allow_synthetic_fallback: + continue + vol = synth_volume_from_file(sf.path) + if vol.shape == label_volumes[idx].shape: + volumes[idx] = vol + + return volumes, label_volumes, timestamps + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + segdir = Path(args.segdir) + outdir = Path(args.outdir) + outdir.mkdir(parents=True, exist_ok=True) + + if not segdir.is_dir(): + print(json.dumps({"error": "Segmentation directory not found", "segdir": str(segdir)})) + return 1 + + scan_dirs = sorted(d for d in segdir.iterdir() if d.is_dir() and d.name.startswith("scan")) + scan_tables: list[list[dict[str, Any]]] = [] + scan_names: list[str] = [] + used_scan_dirs: list[Path] = [] + for sd in scan_dirs: + feat_path = sd / "features.csv" + if feat_path.exists(): + scan_tables.append(load_feature_csv(feat_path)) + scan_names.append(sd.name) + used_scan_dirs.append(sd) + + if not scan_tables: + print(json.dumps({"error": "No feature tables found", "segdir": str(segdir)})) + return 1 + + emb_root = Path(args.embedding_dir) if args.embedding_dir else None + if args.cost_beta != 0.0 and emb_root is None: + print(json.dumps({"error": "--cost-beta > 0 requires --embedding-dir"})) + return 1 + + if emb_root is not None: + for rows, sname in zip(scan_tables, scan_names): + npz = emb_root / sname / "embeddings.npz" + if npz.exists(): + _merge_embeddings(rows, _load_embeddings_npz(npz)) + elif args.cost_beta != 0.0: + 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), + ) + + 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, + ) + + 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) + + 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, + ) + + event_rows = events_to_table(lineage_events) + prec_rows = precursors_to_table(candidates) + obs_rows = [ + { + "track_id": s.track_id, + "scan_idx": s.scan_idx, + "label": s.label, + "anisotropy": s.anisotropy, + "anisotropy_term": s.anisotropy_term, + "spread_growth": s.spread_growth, + "spread_term": s.spread_term, + "roi_subpeak_count": s.roi_subpeak_count, + "roi_dispersion_term": s.roi_dispersion_term, + "precursor_score": s.precursor_score, + } + for s in obs_scores + ] + + write_csv(outdir / "tracks.csv", track_rows) + write_csv(outdir / "events.csv", event_rows) + (outdir / "events.json").write_text(json.dumps(event_rows, indent=2)) + write_csv(outdir / "precursors.csv", prec_rows) + write_csv(outdir / "precursor_observations.csv", obs_rows) + + summary = { + "schema_version": "events.v1", + "scan_names": scan_names, + "n_scans": len(scan_tables), + "total_tracks": metrics["total_tracks"], + "split_count": metrics["split_count"], + "merge_count": metrics["merge_count"], + "event_count": len(event_rows), + "precursor_candidate_count": len(prec_rows), + "roi_dispersion_enabled": bool(volumes and label_volumes), + "backend": resolved_backend if patch_encoder is not None else None, + "model": (args.model if resolved_backend == "torch" else "mock-hash") if patch_encoder is not None else None, + "top_precursor_track_id": candidates[0].track_id if candidates else None, + } + (outdir / "events_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/embed_dataset.py b/braggtrack/cli/embed_dataset.py index 885d2d5..b819c01 100644 --- a/braggtrack/cli/embed_dataset.py +++ b/braggtrack/cli/embed_dataset.py @@ -15,7 +15,8 @@ load_primary_volume, resolve_dataset_root, ) -from braggtrack.semantic import crop_spot_cube, make_multiview_encoder, orthogonal_mips +from braggtrack.semantic import DEFAULT_DINO_MODEL, crop_spot_cube, make_multiview_encoder, orthogonal_mips +from braggtrack.semantic.dino import _requested_backend, _resolve_backend def build_parser() -> argparse.ArgumentParser: @@ -35,14 +36,19 @@ def build_parser() -> argparse.ArgumentParser: "--backend", choices=("auto", "mock", "torch"), default="auto", - help="Embedding backend (mock needs no PyTorch; torch uses DINOv3)", + help="Embedding backend (mock needs no PyTorch; torch uses DINOv2 default or custom --model)", + ) + p.add_argument("--model", default=DEFAULT_DINO_MODEL, help="HF model id when backend=torch") + p.add_argument( + "--allow-synthetic-fallback", + action="store_true", + help="Allow deterministic synthetic volume fallback if an HDF5 file lacks a valid 3D dataset", ) - p.add_argument("--model", default="facebook/dinov3-vitb16-pretrain-lvd1689m", help="HF model id when backend=torch") return p -def main() -> int: - args = build_parser().parse_args() +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) root = resolve_dataset_root(args.root) segdir = Path(args.segdir) outdir = Path(args.outdir) @@ -52,8 +58,9 @@ def main() -> int: scan_by_name = {s.scan_name: s for s in scans_fs} summaries: list[dict[str, object]] = [] + resolved_backend = _resolve_backend(_requested_backend(args.backend)) # type: ignore[arg-type] enc = make_multiview_encoder( - args.backend, # type: ignore[arg-type] + resolved_backend, model_name=args.model, ) @@ -77,7 +84,11 @@ def main() -> int: try: volume = load_primary_volume(scan_file.path) - except (MissingH5DependencyError, KeyError, ValueError): + except MissingH5DependencyError: + volume = 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: @@ -122,8 +133,9 @@ def main() -> int: "scan": name, "n_spots": len(label_ids), "dim": dim, - "backend": args.backend, - "model": args.model if args.backend == "torch" else "mock-hash", + "backend": resolved_backend, + "requested_backend": args.backend, + "model": args.model if resolved_backend == "torch" else "mock-hash", "schema_version": "embedding.v1", } (scan_out / "embedding_manifest.json").write_text(json.dumps(manifest, indent=2)) diff --git a/braggtrack/cli/run_pipeline.py b/braggtrack/cli/run_pipeline.py new file mode 100644 index 0000000..12ef93e --- /dev/null +++ b/braggtrack/cli/run_pipeline.py @@ -0,0 +1,308 @@ +"""One-command reproducible end-to-end BraggTrack pipeline with manifest generation.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import platform +import subprocess +import sys +import time +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +import braggtrack +from braggtrack.cli import detect_events, embed_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 + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "root", + nargs="?", + default=None, + help="Dataset root with scan folders (default: data/sample_operando if present, else .)", + ) + parser.add_argument("--outdir", default="artifacts/pipeline", help="Root output directory for pipeline run") + parser.add_argument( + "--config", + default=None, + help="Optional JSON config file overriding pipeline stage parameters", + ) + parser.add_argument( + "--backend", + choices=("auto", "mock", "torch"), + default="auto", + help="Semantic/patch encoder backend (auto, mock, or torch)", + ) + parser.add_argument("--model", default=DEFAULT_DINO_MODEL, help="HuggingFace model ID when backend=torch") + parser.add_argument( + "--method", + choices=("classical", "dino"), + default="classical", + help="Segmentation method (classical 3D LoG+watershed or experimental dino)", + ) + 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("--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( + "--split-max-distance", type=float, default=25.0, help="Max centroid distance for splits/merges" + ) + parser.add_argument("--precursor-threshold", type=float, default=0.40, help="Fracture precursor score threshold") + parser.add_argument("--precursor-persistence", type=int, default=2, help="Contiguous scans required for precursor") + parser.add_argument( + "--detect-events", + action=argparse.BooleanOptionalAction, + default=True, + help="Run split/merge lineage and fracture precursor detection stage (default: enabled)", + ) + parser.add_argument( + "--allow-synthetic-fallback", + action="store_true", + help="Allow deterministic synthetic volume fallback if an HDF5 file lacks a valid 3D dataset", + ) + return parser + + +def _sha256_file(path: Path) -> str: + h = hashlib.sha256() + with path.open("rb") as f: + while chunk := f.read(1024 * 1024): + h.update(chunk) + return h.hexdigest() + + +def _resolve_git_sha() -> str | None: + repo_dir = Path(__file__).resolve().parents[2] + try: + proc = subprocess.run( + ["git", "rev-parse", "HEAD"], + cwd=repo_dir, + capture_output=True, + text=True, + check=False, + timeout=3, + ) + if proc.returncode == 0 and proc.stdout.strip(): + return proc.stdout.strip() + except Exception: + return None + return None + + +def _merge_config_overrides(args: argparse.Namespace) -> dict[str, Any]: + effective: dict[str, Any] = { + "backend": args.backend, + "model": args.model, + "method": args.method, + "smooth_window": args.smooth_window, + "calibration_json": args.calibration_json, + "cost_alpha": args.cost_alpha, + "cost_beta": args.cost_beta, + "split_max_distance": args.split_max_distance, + "precursor_threshold": args.precursor_threshold, + "precursor_persistence": args.precursor_persistence, + "detect_events": bool(args.detect_events), + "allow_synthetic_fallback": bool(args.allow_synthetic_fallback), + "segmentation_extra_args": [], + "tracking_extra_args": [], + } + if args.config: + cfg_data = json.loads(Path(args.config).read_text()) + if not isinstance(cfg_data, dict): + raise ValueError("--config must point to a JSON object") + effective.update(cfg_data) + return effective + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + cfg = _merge_config_overrides(args) + + root = resolve_dataset_root(cfg.get("root") or args.root) + outdir = Path(args.outdir) + outdir.mkdir(parents=True, exist_ok=True) + + seg_dir = outdir / "segmentation" + emb_dir = outdir / "embedding" + trk_dir = outdir / "tracking" + evt_dir = outdir / "events" + + timings: dict[str, float] = {} + t_total0 = time.perf_counter() + + # 1. Validate dataset + t0 = time.perf_counter() + adapter = BeamlineAdapter(root) + sequence = adapter.build_sequence() + issues = validate_sequence(sequence) + val_payload = { + "root": str(root.resolve()), + "scan_count": len(sequence.scans), + "is_monotonic": sequence.is_monotonic(), + "issues": [issue.__dict__ for issue in issues], + } + (outdir / "validation_summary.json").write_text(json.dumps(val_payload, indent=2)) + timings["validate"] = round(time.perf_counter() - t0, 4) + if any(issue.level == "error" for issue in issues): + print(json.dumps({"error": "Dataset validation failed", "issues": val_payload["issues"]})) + return 1 + + # Compute input checksums + discovered = discover_operando_scans(root) + input_files = [ + { + "scan": sf.scan_name, + "path": str(sf.path.resolve()), + "size_bytes": sf.path.stat().st_size, + "sha256": _sha256_file(sf.path), + } + for sf in discovered + ] + + # 2. Segment dataset + t0 = time.perf_counter() + seg_argv = [ + str(root), + "--outdir", + str(seg_dir), + "--method", + str(cfg["method"]), + "--smooth-window", + str(cfg["smooth_window"]), + "--dino-backend", + str(cfg["backend"]), + "--dino-model", + str(cfg["model"]), + ] + if cfg.get("calibration_json"): + seg_argv.extend(["--calibration-json", str(cfg["calibration_json"])]) + if cfg.get("allow_synthetic_fallback"): + seg_argv.append("--allow-synthetic-fallback") + seg_argv.extend(str(x) for x in cfg.get("segmentation_extra_args", [])) + rc_seg = segment_dataset.main(seg_argv) + timings["segment"] = round(time.perf_counter() - t0, 4) + if rc_seg != 0: + return rc_seg + + # 3. Embed dataset (whenever cost_beta != 0 or detect_events is enabled) + need_embed = float(cfg["cost_beta"]) != 0.0 + if need_embed: + t0 = time.perf_counter() + emb_argv = [ + str(root), + "--segdir", + str(seg_dir), + "--outdir", + str(emb_dir), + "--backend", + str(cfg["backend"]), + "--model", + str(cfg["model"]), + ] + if cfg.get("allow_synthetic_fallback"): + emb_argv.append("--allow-synthetic-fallback") + rc_emb = embed_dataset.main(emb_argv) + timings["embed"] = round(time.perf_counter() - t0, 4) + if rc_emb != 0: + return rc_emb + + # 4. Track dataset + kinematics (+ split/merge if detect_events) + t0 = time.perf_counter() + trk_argv = [ + str(seg_dir), + "--outdir", + str(trk_dir), + "--cost-alpha", + str(cfg["cost_alpha"]), + "--cost-beta", + str(cfg["cost_beta"]), + "--split-max-distance", + str(cfg["split_max_distance"]), + "--precursor-threshold", + str(cfg["precursor_threshold"]), + "--precursor-persistence", + str(cfg["precursor_persistence"]), + ] + if need_embed: + trk_argv.extend(["--embedding-dir", str(emb_dir)]) + if cfg.get("detect_events"): + trk_argv.append("--detect-events") + 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) + if rc_trk != 0: + return rc_trk + + # 5. Full ROI fracture precursor + lineage analysis + if cfg.get("detect_events"): + t0 = time.perf_counter() + evt_argv = [ + str(root), + "--segdir", + str(seg_dir), + "--outdir", + str(evt_dir), + "--backend", + str(cfg["backend"]), + "--model", + str(cfg["model"]), + "--cost-alpha", + str(cfg["cost_alpha"]), + "--cost-beta", + str(cfg["cost_beta"]), + "--split-max-distance", + str(cfg["split_max_distance"]), + "--precursor-threshold", + str(cfg["precursor_threshold"]), + "--precursor-persistence", + str(cfg["precursor_persistence"]), + ] + if need_embed: + evt_argv.extend(["--embedding-dir", str(emb_dir)]) + if cfg.get("allow_synthetic_fallback"): + evt_argv.append("--allow-synthetic-fallback") + rc_evt = detect_events.main(evt_argv) + timings["events"] = round(time.perf_counter() - t0, 4) + 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, + }, + } + manifest_path = outdir / "run_manifest.json" + manifest_path.write_text(json.dumps(manifest, indent=2)) + print(json.dumps({"manifest": str(manifest_path.resolve()), "total_duration_sec": total_sec}, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/braggtrack/cli/segment_dataset.py b/braggtrack/cli/segment_dataset.py index 17fdd83..aaaf79e 100644 --- a/braggtrack/cli/segment_dataset.py +++ b/braggtrack/cli/segment_dataset.py @@ -10,21 +10,27 @@ from braggtrack.cli._utils import synth_volume_from_file, write_csv, write_qc_notebook from braggtrack.io import ( + AxisCalibration, MissingH5DependencyError, discover_operando_scans, + discover_primary_volume_path, + extract_axis_calibration, load_primary_volume, resolve_dataset_root, ) from braggtrack.segmentation import ( extract_instance_table, fill_holes_binary, + flag_outlier_frames, merge_nearby_labels, otsu_threshold, relabel_sequential, remove_small_objects, segment_classical, segment_dino, + smooth_thresholds, ) +from braggtrack.semantic import DEFAULT_DINO_MODEL def build_parser() -> argparse.ArgumentParser: @@ -40,7 +46,7 @@ def build_parser() -> argparse.ArgumentParser: "--method", choices=["classical", "dino"], default="classical", - help="Segmentation method: classical (LoG + watershed) or dino (DINOv3 features + HDBSCAN)", + help="Segmentation method: classical (LoG + watershed) or dino (experimental DINO features + HDBSCAN)", ) parser.add_argument("--blur-passes", type=int, default=1) parser.add_argument("--seed-separation", type=int, default=2) @@ -64,12 +70,35 @@ def build_parser() -> argparse.ArgumentParser: default=1.0, help="Multiply Otsu threshold by this fraction to capture diffuse spots (1.0 = original Otsu)", ) + parser.add_argument( + "--smooth-window", + type=int, + default=5, + help="Rolling-median window across scans for classical Otsu threshold smoothing (1 disables)", + ) parser.add_argument( "--merge-distance", type=float, default=15.0, help="Merge adjacent labels whose centroids are within this many voxels (0 disables)", ) + # Physical axis calibration + parser.add_argument( + "--calibration-json", + default=None, + help="Path to JSON file defining AxisCalibration (mu/chi/d origin and step)", + ) + parser.add_argument("--mu-origin", type=float, default=None, help="Physical mu origin (degrees)") + parser.add_argument("--mu-step", type=float, default=None, help="Physical mu step per z-voxel (degrees)") + parser.add_argument("--chi-origin", type=float, default=None, help="Physical chi origin (degrees)") + parser.add_argument("--chi-step", type=float, default=None, help="Physical chi step per x-voxel (degrees)") + parser.add_argument("--d-origin", type=float, default=None, help="Physical d-spacing origin (angstrom)") + parser.add_argument("--d-step", type=float, default=None, help="Physical d-spacing step per y-voxel (angstrom)") + parser.add_argument( + "--allow-synthetic-fallback", + action="store_true", + help="Allow deterministic synthetic volume fallback if an HDF5 file lacks a valid 3D dataset", + ) # DINO-specific arguments parser.add_argument( "--dino-backend", @@ -79,7 +108,7 @@ def build_parser() -> argparse.ArgumentParser: ) parser.add_argument( "--dino-model", - default="facebook/dinov3-vitb16-pretrain-lvd1689m", + default=DEFAULT_DINO_MODEL, help="HuggingFace model ID for the DINO torch backend", ) parser.add_argument("--dino-pca-components", type=int, default=16, help="PCA components for DINO feature reduction") @@ -94,6 +123,26 @@ def build_parser() -> argparse.ArgumentParser: return parser +def _resolve_cli_calibration(args: argparse.Namespace) -> AxisCalibration | None: + raw: dict[str, object] = {} + if args.calibration_json: + raw.update(json.loads(Path(args.calibration_json).read_text())) + cli_overrides = { + "mu_origin": args.mu_origin, + "mu_step": args.mu_step, + "chi_origin": args.chi_origin, + "chi_step": args.chi_step, + "d_origin": args.d_origin, + "d_step": args.d_step, + } + for key, val in cli_overrides.items(): + if val is not None: + raw[key] = val + if not raw: + return None + return AxisCalibration.from_dict(raw) + + _SEGMENTATION_QC_CODE = [ "import csv, json\n", "from pathlib import Path\n", @@ -115,26 +164,54 @@ def build_parser() -> argparse.ArgumentParser: ] -def main() -> int: - args = build_parser().parse_args() +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) scans = discover_operando_scans(resolve_dataset_root(args.root)) outdir = Path(args.outdir) outdir.mkdir(parents=True, exist_ok=True) + explicit_cal = _resolve_cli_calibration(args) - summaries: list[dict[str, object]] = [] - for scan in scans: - scan_out = outdir / scan.scan_name - scan_out.mkdir(parents=True, exist_ok=True) - - source = "nexus" + def _load_one(scan_obj: object) -> tuple[np.ndarray, str, str | None, AxisCalibration]: + scan_path = scan_obj.path # type: ignore[attr-defined] + src = "nexus" + dpath: str | None = None + scan_cal = explicit_cal or AxisCalibration() try: - volume = load_primary_volume(scan.path) + dpath = discover_primary_volume_path(scan_path) + vol = load_primary_volume(scan_path) + if explicit_cal is None: + scan_cal = extract_axis_calibration(scan_path) except MissingH5DependencyError: - volume = synth_volume_from_file(scan.path) - source = "synthetic_fallback" + vol = synth_volume_from_file(scan_path) + src = "synthetic_fallback" except (KeyError, ValueError): - volume = synth_volume_from_file(scan.path) - source = "synthetic_fallback" + if not args.allow_synthetic_fallback: + raise + vol = synth_volume_from_file(scan_path) + src = "synthetic_fallback" + return vol, src, dpath, scan_cal + + # First pass: compute scalar per-scan Otsu thresholds in O(1) volume memory. + 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 + + 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)] + outlier_flags = [bool(x) for x in flag_outlier_frames(raw_thresholds, window=args.smooth_window)] + else: + effective_thresholds = list(raw_thresholds) + outlier_flags = [False] * len(raw_thresholds) + + summaries: list[dict[str, object]] = [] + for idx, scan in enumerate(scans): + volume, source, ds_path, cal = _load_one(scan) + scan_out = outdir / scan.scan_name # type: ignore[attr-defined] + scan_out.mkdir(parents=True, exist_ok=True) + raw_thr = raw_thresholds[idx] + eff_thr = effective_thresholds[idx] if args.method == "dino": result = segment_dino( @@ -148,11 +225,9 @@ def main() -> int: min_overlap_fraction=args.dino_min_overlap, ) else: - raw_threshold = otsu_threshold(volume.ravel()) - threshold = raw_threshold * float(args.threshold_fraction) result = segment_classical( volume, - threshold=threshold, + threshold=eff_thr, blur_passes=max(1, args.blur_passes), h_value=float(args.h_value), min_seed_separation=max(1, args.seed_separation), @@ -168,22 +243,28 @@ def main() -> int: labels = merge_nearby_labels(labels, volume, max_centroid_distance=args.merge_distance) labels = relabel_sequential(labels) - table = extract_instance_table(labels, volume) + active_cal = cal if cal.calibrated else None + table = extract_instance_table(labels, volume, calibration=active_cal) write_csv(scan_out / "features.csv", table) np.savez_compressed(scan_out / "labels.npz", labels=labels.astype(np.int32, copy=False)) (scan_out / "summary.json").write_text( json.dumps( { - "scan": scan.scan_name, - "file": str(scan.path), + "scan": scan.scan_name, # type: ignore[attr-defined] + "file": str(scan.path), # type: ignore[attr-defined] "source": source, + "dataset_path": ds_path, "method": args.method, + "raw_threshold": raw_thr, "threshold": result.threshold, "threshold_fraction": args.threshold_fraction, "effective_threshold": result.threshold, + "smooth_window": args.smooth_window if args.method == "classical" else 1, + "is_outlier_frame": outlier_flags[idx], "merge_distance": args.merge_distance, "seed_count": result.seed_count, "component_count": len(table), + "calibration": cal.to_dict(), "schema_version": "segmentation.v1", "labels_archive": str(scan_out / "labels.npz"), }, @@ -193,11 +274,13 @@ def main() -> int: summaries.append( { - "scan": scan.scan_name, - "file": str(scan.path), + "scan": scan.scan_name, # type: ignore[attr-defined] + "file": str(scan.path), # type: ignore[attr-defined] "source": source, + "dataset_path": ds_path, "component_count": len(table), "feature_rows": len(table), + "calibrated": cal.calibrated, "summary": str(scan_out / "summary.json"), "features": str(scan_out / "features.csv"), "labels_archive": str(scan_out / "labels.npz"), diff --git a/braggtrack/cli/track_dataset.py b/braggtrack/cli/track_dataset.py index 53806d0..2472cf2 100644 --- a/braggtrack/cli/track_dataset.py +++ b/braggtrack/cli/track_dataset.py @@ -13,8 +13,17 @@ from braggtrack.tracking import ( GeometrySemanticCost, PositionShapeCost, + PrecursorConfig, + SplitMergeConfig, build_tracks, + compute_fracture_precursors, + compute_grain_kinematics, compute_tracking_metrics, + events_to_table, + kinematics_to_table, + precursors_to_table, + summarize_kinematics, + summary_to_dict, tracks_to_table, ) @@ -48,6 +57,29 @@ def build_parser() -> argparse.ArgumentParser: default=0.0, help="Multiplier on (1 - cos(embedding)); 0 disables semantic term", ) + parser.add_argument( + "--detect-events", + action="store_true", + help="Resolve 1->2+ splits, 2+->1 merges, and persistent fracture precursors", + ) + parser.add_argument( + "--split-max-distance", + type=float, + default=25.0, + help="Maximum centroid distance for split/merge association when --detect-events is enabled", + ) + parser.add_argument( + "--precursor-threshold", + type=float, + default=0.40, + help="Minimum per-observation precursor score for persistent fracture candidate ranking", + ) + parser.add_argument( + "--precursor-persistence", + type=int, + default=2, + help="Minimum contiguous scans above threshold to rank as a fracture precursor", + ) return parser @@ -68,6 +100,21 @@ 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: + for sd in scan_dirs: + summary_path = sd / "summary.json" + if not summary_path.exists(): + continue + try: + meta = json.loads(summary_path.read_text()) + except (OSError, json.JSONDecodeError): + continue + cal = meta.get("calibration") + if isinstance(cal, dict) and bool(cal.get("calibrated", False)): + return True + return False + + _TRACKING_QC_CODE = [ "import csv, json\n", "from pathlib import Path\n", @@ -106,8 +153,8 @@ def _merge_embeddings(rows: list[dict[str, Any]], emb: dict[int, np.ndarray]) -> ] -def main() -> int: - args = build_parser().parse_args() +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) indir = Path(args.root) outdir = Path(args.outdir) outdir.mkdir(parents=True, exist_ok=True) @@ -116,11 +163,13 @@ def main() -> int: scan_dirs = sorted(d for d in indir.iterdir() if d.is_dir() and d.name.startswith("scan")) scan_tables: list[list[dict]] = [] scan_names: list[str] = [] + used_scan_dirs: list[Path] = [] for sd in scan_dirs: feat_path = sd / "features.csv" if feat_path.exists(): scan_tables.append(load_feature_csv(feat_path)) scan_names.append(sd.name) + used_scan_dirs.append(sd) if not scan_tables: print(json.dumps({"error": "No feature tables found", "indir": str(indir)})) @@ -155,7 +204,17 @@ def main() -> int: else: cost_fn = geo - G = build_tracks(scan_tables, cost_fn=cost_fn, max_cost=args.max_cost) + sm_cfg = ( + SplitMergeConfig( + max_distance=args.split_max_distance, + gate_mu=args.gate_mu, + gate_chi=args.gate_chi, + gate_d=args.gate_d, + ) + 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) metrics = compute_tracking_metrics(G, n_scans=len(scan_tables)) track_rows = tracks_to_table(G) @@ -164,16 +223,42 @@ def main() -> int: 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)) + (outdir / "kinematics_summary.json").write_text( + json.dumps({"schema_version": "kinematics.v1", **summary_to_dict(kin_summary)}, indent=2) + ) + + if args.detect_events: + lineage_events = list(G.graph.get("lineage_events", [])) + event_rows = events_to_table(lineage_events) + write_csv(outdir / "events.csv", event_rows) + (outdir / "events.json").write_text(json.dumps(event_rows, indent=2)) + prec_candidates, _ = compute_fracture_precursors( + track_rows, + PrecursorConfig( + score_threshold=args.precursor_threshold, + min_persistence=max(1, args.precursor_persistence), + ), + lineage_events=lineage_events, + ) + write_csv(outdir / "precursors.csv", precursors_to_table(prec_candidates)) + schema_version = "tracking_semantic.v1" if args.cost_beta != 0.0 else "tracking.v1" - summary = { + summary: dict[str, Any] = { "scan_names": scan_names, "n_scans": len(scan_tables), "spots_per_scan": [len(t) for t in scan_tables], **metrics, + "calibrated_axes": calibrated_axes, "schema_version": schema_version, "cost_alpha": args.cost_alpha, "cost_beta": args.cost_beta, "embedding_dir": str(emb_root) if emb_root else None, + "detect_events": bool(args.detect_events), } (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) diff --git a/braggtrack/cli/validate_dataset.py b/braggtrack/cli/validate_dataset.py index a2ce0e3..24fb3a2 100644 --- a/braggtrack/cli/validate_dataset.py +++ b/braggtrack/cli/validate_dataset.py @@ -19,8 +19,8 @@ def build_parser() -> argparse.ArgumentParser: return parser -def main() -> int: - args = build_parser().parse_args() +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) root = resolve_dataset_root(args.root) adapter = BeamlineAdapter(root) sequence = adapter.build_sequence() diff --git a/braggtrack/io/__init__.py b/braggtrack/io/__init__.py index 1ffce16..c2b0577 100644 --- a/braggtrack/io/__init__.py +++ b/braggtrack/io/__init__.py @@ -2,8 +2,15 @@ from .beamline import BeamlineAdapter from .discovery import discover_operando_scans -from .models import AxisSpec, ExperimentSequence, ScanVolumeMeta -from .nexus import MissingH5DependencyError, extract_scan_metadata, load_primary_volume, summarize_hdf5_tree +from .models import AxisCalibration, AxisSpec, ExperimentSequence, ScanVolumeMeta +from .nexus import ( + MissingH5DependencyError, + discover_primary_volume_path, + extract_axis_calibration, + extract_scan_metadata, + load_primary_volume, + summarize_hdf5_tree, +) from .paths import default_dataset_root, resolve_dataset_root, sample_operando_root from .validation import ValidationIssue, validate_sequence @@ -12,10 +19,13 @@ "resolve_dataset_root", "sample_operando_root", "discover_operando_scans", + "discover_primary_volume_path", + "extract_axis_calibration", "extract_scan_metadata", "summarize_hdf5_tree", "load_primary_volume", "MissingH5DependencyError", + "AxisCalibration", "AxisSpec", "ScanVolumeMeta", "ExperimentSequence", diff --git a/braggtrack/io/beamline.py b/braggtrack/io/beamline.py index 7fad87a..4762131 100644 --- a/braggtrack/io/beamline.py +++ b/braggtrack/io/beamline.py @@ -7,15 +7,21 @@ from typing import Any from .discovery import ScanFile, discover_operando_scans -from .models import ExperimentSequence, ScanVolumeMeta -from .nexus import MissingH5DependencyError, extract_scan_metadata +from .models import AxisCalibration, ExperimentSequence, ScanVolumeMeta +from .nexus import ( + MissingH5DependencyError, + discover_primary_volume_path, + extract_axis_calibration, + extract_scan_metadata, +) class BeamlineAdapter: """Build BraggTrack contracts from local NeXus/HDF5 scan files.""" - def __init__(self, root: str | Path): + def __init__(self, root: str | Path, calibration: AxisCalibration | None = None): self.root = Path(root) + self.calibration = calibration @staticmethod def _parse_scan_index(scan_name: str) -> int: @@ -41,9 +47,17 @@ def _parse_datetime(raw: Any) -> datetime | None: def _scan_to_meta(self, scan_file: ScanFile) -> ScanVolumeMeta: metadata: dict[str, Any] = {} metadata_error: str | None = None + volume_path: str | None = None + cal = self.calibration or AxisCalibration() try: metadata = extract_scan_metadata(scan_file.path) + if self.calibration is None: + cal = extract_axis_calibration(scan_file.path) + try: + volume_path = discover_primary_volume_path(scan_file.path) + except (KeyError, ValueError): + volume_path = None except MissingH5DependencyError as exc: metadata_error = str(exc) @@ -59,6 +73,8 @@ def _scan_to_meta(self, scan_file: ScanFile) -> ScanVolumeMeta: end_time=self._parse_datetime(metadata.get("end_time")), sample_name=metadata.get("sample_name"), title=metadata.get("title"), + volume_dataset_path=volume_path, + calibration=cal, extras=extras, ) diff --git a/braggtrack/io/discovery.py b/braggtrack/io/discovery.py index 32d6689..4e7c6fd 100644 --- a/braggtrack/io/discovery.py +++ b/braggtrack/io/discovery.py @@ -35,7 +35,10 @@ def discover_operando_scans(root: str | Path, pattern: str = "pco_nf_*.h5") -> l scans: list[ScanFile] = [] for scan_dir in sorted(p for p in root_path.iterdir() if p.is_dir() and p.name.startswith("scan")): - for h5_file in sorted(scan_dir.glob(pattern)): + matched = sorted(scan_dir.glob(pattern)) + if not matched and pattern == "pco_nf_*.h5": + matched = sorted({*scan_dir.glob("*.h5"), *scan_dir.glob("*.nxs"), *scan_dir.glob("*.hdf5")}) + for h5_file in matched: scans.append(ScanFile(scan_name=scan_dir.name, path=h5_file)) return scans diff --git a/braggtrack/io/models.py b/braggtrack/io/models.py index 5f27baa..9c9a80c 100644 --- a/braggtrack/io/models.py +++ b/braggtrack/io/models.py @@ -17,6 +17,55 @@ class AxisSpec: size: int | None = None +@dataclass(frozen=True) +class AxisCalibration: + """Linear mapping from voxel indices ``(z, y, x)`` to physical ``(mu, d, chi)``.""" + + mu_origin: float = 0.0 + mu_step: float = 1.0 + chi_origin: float = 0.0 + chi_step: float = 1.0 + d_origin: float = 0.0 + d_step: float = 1.0 + calibrated: bool = False + + def __post_init__(self) -> None: + if self.mu_step == 0.0 or self.chi_step == 0.0 or self.d_step == 0.0: + raise ValueError("AxisCalibration steps (mu_step, chi_step, d_step) must be non-zero.") + + def voxel_to_physical(self, z: float, y: float, x: float) -> tuple[float, float, float]: + """Convert voxel coordinates ``(z, y, x)`` into physical ``(mu, chi, d)``.""" + mu = self.mu_origin + z * self.mu_step + chi = self.chi_origin + x * self.chi_step + d = self.d_origin + y * self.d_step + return (float(mu), float(chi), float(d)) + + def to_dict(self) -> dict[str, Any]: + return { + "mu_origin": self.mu_origin, + "mu_step": self.mu_step, + "chi_origin": self.chi_origin, + "chi_step": self.chi_step, + "d_origin": self.d_origin, + "d_step": self.d_step, + "calibrated": self.calibrated, + } + + @classmethod + def from_dict(cls, data: dict[str, Any]) -> AxisCalibration: + has_axis_keys = any(k in data for k in ("mu_origin", "mu_step", "chi_origin", "chi_step", "d_origin", "d_step")) + calibrated = bool(data.get("calibrated", has_axis_keys)) + return cls( + mu_origin=float(data.get("mu_origin", 0.0)), + mu_step=float(data.get("mu_step", 1.0)), + chi_origin=float(data.get("chi_origin", 0.0)), + chi_step=float(data.get("chi_step", 1.0)), + d_origin=float(data.get("d_origin", 0.0)), + d_step=float(data.get("d_step", 1.0)), + calibrated=calibrated, + ) + + @dataclass(frozen=True) class ScanVolumeMeta: """Metadata contract for one operando scan volume.""" @@ -33,6 +82,8 @@ class ScanVolumeMeta: end_time: datetime | None = None sample_name: str | None = None title: str | None = None + volume_dataset_path: str | None = None + calibration: AxisCalibration = field(default_factory=AxisCalibration) extras: dict[str, Any] = field(default_factory=dict) diff --git a/braggtrack/io/nexus.py b/braggtrack/io/nexus.py index 063dc3c..e85f604 100644 --- a/braggtrack/io/nexus.py +++ b/braggtrack/io/nexus.py @@ -5,9 +5,20 @@ from pathlib import Path from typing import TYPE_CHECKING, Any +from .models import AxisCalibration + if TYPE_CHECKING: import numpy as np +DEFAULT_VOLUME_CANDIDATES: tuple[str, ...] = ( + "/entry/data/data", + "/entry1/data/data", + "/entry_0000/ESRF-ID03/pco_nf/data", + "/entry_0000/data/data", + "/entry/instrument/detector/data", + "/entry1/instrument/detector/data", +) + class MissingH5DependencyError(RuntimeError): """Raised when HDF5 dependencies are unavailable.""" @@ -44,64 +55,195 @@ def visitor(name: str, obj: Any) -> None: return entries -def _read_first(handle: Any, candidates: list[str]) -> Any | None: +def _decode_value(value: Any) -> Any: + if isinstance(value, bytes): + return value.decode("utf-8", errors="replace") + if hasattr(value, "item") and getattr(value, "ndim", 1) == 0: + inner = value.item() + if isinstance(inner, bytes): + return inner.decode("utf-8", errors="replace") + return inner + return value + + +def _candidate_entries(handle: Any, h5py: Any) -> list[str]: + seen: list[str] = [] + + def _add(prefix: str) -> None: + norm = "/" + prefix.strip("/") + if norm != "/" and norm in handle and isinstance(handle[norm], h5py.Group) and norm not in seen: + seen.append(norm) + + default_attr = _decode_value(handle.attrs.get("default")) + if isinstance(default_attr, str) and default_attr.strip(): + _add(default_attr) + + for std in ("/entry", "/entry1", "/entry_0000"): + _add(std) + + for key in sorted(handle.keys()): + obj = handle[key] + if isinstance(obj, h5py.Group): + nx_cls = _decode_value(obj.attrs.get("NX_class")) + if key.startswith("entry") or nx_cls == "NXentry": + _add(key) + + return seen + + +def _read_first(handle: Any, candidates: list[str], h5py: Any | None = None) -> Any | None: for key in candidates: if key in handle: - value = handle[key][()] - if isinstance(value, bytes): - return value.decode("utf-8", errors="replace") - return value + obj = handle[key] + if h5py is not None and isinstance(obj, h5py.Group): + return key + return _decode_value(obj[()]) return None def extract_scan_metadata(path: str | Path) -> dict[str, Any]: """Extract common beamline metadata from a NeXus/HDF5 scan file. - The function probes a small set of common key paths used by NeXus instrument files. + Probes standard NeXus ``/entry*`` groups (including ``/entry_0000`` used by + ESRF LIMA/BLISS acquisitions). """ h5py = _require_h5py() path = Path(path) with h5py.File(path, "r") as handle: + entries = _candidate_entries(handle, h5py) or ["/entry", "/entry1", "/entry_0000"] + start_candidates = [f"{e}/start_time" for e in entries] + end_candidates = [f"{e}/end_time" for e in entries] + title_candidates = [f"{e}/title" for e in entries] + sample_candidates: list[str] = [] + for e in entries: + sample_candidates.extend([f"{e}/sample/name", f"{e}/sample"]) + + entry_found = next((e for e in entries if e in handle), None) metadata = { "file": str(path), - "entry": _read_first(handle, ["/entry", "/entry1"]), - "start_time": _read_first(handle, ["/entry/start_time", "/entry1/start_time"]), - "end_time": _read_first(handle, ["/entry/end_time", "/entry1/end_time"]), - "title": _read_first(handle, ["/entry/title", "/entry1/title"]), - "sample_name": _read_first( - handle, - [ - "/entry/sample/name", - "/entry1/sample/name", - "/entry/sample", - "/entry1/sample", - ], - ), + "entry": entry_found, + "start_time": _read_first(handle, start_candidates, h5py), + "end_time": _read_first(handle, end_candidates, h5py), + "title": _read_first(handle, title_candidates, h5py), + "sample_name": _read_first(handle, sample_candidates, h5py), } return metadata -def load_primary_volume(path: str | Path, candidates: list[str] | None = None) -> np.ndarray: - """Load a primary 3D detector volume from common NeXus dataset paths.""" +def extract_axis_calibration(path: str | Path) -> AxisCalibration: + """Extract linear ``(mu, chi, d)`` calibration from a NeXus/HDF5 file if present. + + Checks ``/entry*/calibration`` attributes/datasets or 1D coordinate arrays + ``mu``, ``chi``, and ``d``. Returns an uncalibrated identity + :class:`AxisCalibration` when physical axis scales are absent. + """ import numpy as np h5py = _require_h5py() - ds_candidates = candidates or [ - "/entry/data/data", - "/entry1/data/data", - "/entry/instrument/detector/data", - "/entry1/instrument/detector/data", - ] + path = Path(path) with h5py.File(path, "r") as handle: - for key in ds_candidates: - if key in handle: - data = handle[key][()] - if getattr(data, "ndim", None) != 3: - raise ValueError(f"Dataset '{key}' exists but is not 3D (ndim={getattr(data, 'ndim', None)}).") - return np.asarray(data, dtype=np.float64) + vol_parent: str | None = None + try: + ds_path = _resolve_volume_dataset(handle, h5py, auto_discover=True) + vol_parent = str(Path(ds_path).parent) + except (KeyError, ValueError): + vol_parent = None + + entries = _candidate_entries(handle, h5py) + for e in entries: + cal_grp_path = f"{e}/calibration" + if cal_grp_path in handle and isinstance(handle[cal_grp_path], h5py.Group): + grp = handle[cal_grp_path] + raw: dict[str, Any] = {k: _decode_value(v) for k, v in grp.attrs.items()} + for k in grp: + if isinstance(grp[k], h5py.Dataset) and grp[k].ndim == 0: + raw[k] = _decode_value(grp[k][()]) + if raw: + return AxisCalibration.from_dict(raw) + + # Check 1D axis arrays under NXentry, NXdata, or the primary 3D dataset's parent group. + axes_found: dict[str, tuple[float, float]] = {} + for axis_name in ("mu", "chi", "d"): + search_paths = [f"{e}/{axis_name}", f"{e}/data/{axis_name}", f"{e}/measurement/{axis_name}"] + if vol_parent and vol_parent != "/": + search_paths.append(f"{vol_parent.rstrip('/')}/{axis_name}") + for sub in search_paths: + if sub in handle and isinstance(handle[sub], h5py.Dataset): + arr = np.asarray(handle[sub][()], dtype=np.float64).ravel() + if arr.size >= 2: + axes_found[axis_name] = (float(arr[0]), float((arr[-1] - arr[0]) / (arr.size - 1))) + break + if axes_found: + return AxisCalibration( + mu_origin=axes_found.get("mu", (0.0, 1.0))[0], + mu_step=axes_found.get("mu", (0.0, 1.0))[1], + chi_origin=axes_found.get("chi", (0.0, 1.0))[0], + chi_step=axes_found.get("chi", (0.0, 1.0))[1], + d_origin=axes_found.get("d", (0.0, 1.0))[0], + d_step=axes_found.get("d", (0.0, 1.0))[1], + calibrated=True, + ) + + return AxisCalibration() + + +def _resolve_volume_dataset( + handle: Any, + h5py: Any, + candidates: list[str] | None = None, + *, + auto_discover: bool = True, +) -> str: + import numpy as np + + ds_candidates = list(candidates) if candidates is not None else list(DEFAULT_VOLUME_CANDIDATES) + for key in ds_candidates: + if key in handle and isinstance(handle[key], h5py.Dataset): + ds = handle[key] + if getattr(ds, "ndim", None) != 3: + raise ValueError(f"Dataset '{key}' exists but is not 3D (ndim={getattr(ds, 'ndim', None)}).") + return "/" + key.lstrip("/") + + if candidates is None and auto_discover: + discovered: list[tuple[str, tuple[int, ...]]] = [] + + def _visit(name: str, obj: Any) -> None: + if isinstance(obj, h5py.Dataset) and obj.ndim == 3 and np.issubdtype(obj.dtype, np.number): + discovered.append(("/" + name.lstrip("/"), tuple(obj.shape))) + + handle.visititems(_visit) + if discovered: + return max(discovered, key=lambda item: int(np.prod(item[1])))[0] raise KeyError(f"No candidate 3D dataset found in file. Tried: {ds_candidates}") + + +def discover_primary_volume_path( + path: str | Path, + candidates: list[str] | None = None, + *, + auto_discover: bool = True, +) -> str: + """Return the HDF5 dataset path of the primary 3D detector volume.""" + h5py = _require_h5py() + with h5py.File(path, "r") as handle: + return _resolve_volume_dataset(handle, h5py, candidates=candidates, auto_discover=auto_discover) + + +def load_primary_volume( + path: str | Path, + candidates: list[str] | None = None, + *, + auto_discover: bool = True, +) -> np.ndarray: + """Load a primary 3D detector volume from NeXus paths or largest-3D auto-discovery.""" + import numpy as np + + h5py = _require_h5py() + with h5py.File(path, "r") as handle: + ds_path = _resolve_volume_dataset(handle, h5py, candidates=candidates, auto_discover=auto_discover) + return np.asarray(handle[ds_path][()], dtype=np.float64) diff --git a/braggtrack/segmentation/dino_segment.py b/braggtrack/segmentation/dino_segment.py index 4130631..d5b48ef 100644 --- a/braggtrack/segmentation/dino_segment.py +++ b/braggtrack/segmentation/dino_segment.py @@ -1,8 +1,7 @@ -"""DINO-based 3D segmentation: patch feature clustering + 3D stitching. +"""Experimental DINO-based 3D segmentation: patch feature clustering + 3D stitching. -Replaces the hand-tuned LoG + watershed pipeline with frozen DINOv3 patch -features clustered via HDBSCAN, producing instance labels that generalise -across beamlines and detectors without per-instrument parameter tuning. +Provides an alternative to the primary classical LoG + watershed pipeline using +frozen DINOv2/DINOv3 patch features clustered via HDBSCAN. """ from __future__ import annotations @@ -12,6 +11,8 @@ import numpy as np +from braggtrack.semantic.dino import DEFAULT_DINO_MODEL + if TYPE_CHECKING: from braggtrack.semantic.dino import BackendName, PatchFeatureEncoder @@ -257,7 +258,7 @@ def segment_dino( volume: np.ndarray, *, backend: BackendName | None = None, - model_name: str = "facebook/dinov3-vitb16-pretrain-lvd1689m", + model_name: str = DEFAULT_DINO_MODEL, torch_device: str | None = None, n_components_pca: int = 16, min_cluster_size: int = 5, @@ -266,7 +267,7 @@ def segment_dino( min_overlap_fraction: float = 0.2, axis: int = 0, ) -> DinoSegmentationResult: - """Segment a 3D volume using DINOv3 patch-level features + HDBSCAN. + """Segment a 3D volume using DINO patch-level features + HDBSCAN. Parameters ---------- diff --git a/braggtrack/segmentation/features.py b/braggtrack/segmentation/features.py index 6e93566..32dcc3d 100644 --- a/braggtrack/segmentation/features.py +++ b/braggtrack/segmentation/features.py @@ -2,37 +2,54 @@ from __future__ import annotations +from typing import TYPE_CHECKING + import numpy as np +from scipy.ndimage import find_objects + +if TYPE_CHECKING: + from braggtrack.io.models import AxisCalibration def extract_instance_table( labels: np.ndarray, intensity: np.ndarray, + *, + calibration: AxisCalibration | None = None, ) -> list[dict[str, float | int]]: """Compute centroid, bbox, integrated intensity, covariance and eigenvalues. Voxel array axes are ``(z, y, x)`` mapping to reciprocal-space coordinates as **μ → z**, **d → y**, **χ → x** (STFC / operando convention). - Intensity-weighted centroids guard against negative or zero total - intensity by falling back to the geometric (unweighted) centroid. + When *calibration* is provided, centroids, covariance components, and + eigenvalues are transformed into physical units while ``bbox_*`` bounds + remain integer voxel indices for 3D array slicing. """ labels = np.asarray(labels) intensity = np.asarray(intensity, dtype=np.float64) + if labels.size == 0 or int(labels.max()) <= 0: + return [] + slices = find_objects(np.where(labels > 0, labels, 0)) rows: list[dict[str, float | int]] = [] - for lbl in np.unique(labels): - if lbl <= 0: + for idx, slc in enumerate(slices): + if slc is None: + continue + lbl = idx + 1 + sz, sy, sx = slc + sub_lbl = labels[sz, sy, sx] + mask = sub_lbl == lbl + if not np.any(mask): continue - mask = labels == lbl - coords = np.argwhere(mask) # (N, 3) array of (z, y, x) - vals = intensity[mask] + local_coords = np.argwhere(mask) + vals = intensity[sz, sy, sx][mask] count = len(vals) sum_i = float(vals.sum()) - z_coords = coords[:, 0].astype(np.float64) - y_coords = coords[:, 1].astype(np.float64) - x_coords = coords[:, 2].astype(np.float64) + z_coords = local_coords[:, 0].astype(np.float64) + float(sz.start) + y_coords = local_coords[:, 1].astype(np.float64) + float(sy.start) + x_coords = local_coords[:, 2].astype(np.float64) + float(sx.start) # Intensity-weighted centroid; fall back to geometric centroid # if total intensity is non-positive (avoids sign-flip). @@ -46,11 +63,18 @@ def extract_instance_table( cy = float(y_coords.mean()) cx = float(x_coords.mean()) - # Weighted covariance (same weight logic) - dz = z_coords - cz - dy = y_coords - cy - dx = x_coords - cx + if calibration is not None: + c_mu, c_chi, c_d = calibration.voxel_to_physical(cz, cy, cx) + dz = (z_coords - cz) * calibration.mu_step + dy = (y_coords - cy) * calibration.d_step + dx = (x_coords - cx) * calibration.chi_step + else: + c_mu, c_chi, c_d = cz, cx, cy + dz = z_coords - cz + dy = y_coords - cy + dx = x_coords - cx + # Weighted covariance (same weight logic) if sum_i > 0: w = vals / sum_i else: @@ -71,22 +95,22 @@ def extract_instance_table( ] ) eigvals = np.linalg.eigvalsh(cov) - eigvals = np.sort(eigvals)[::-1] # descending + eigvals = np.maximum(0.0, np.sort(eigvals)[::-1]) # non-negative descending rows.append( { "label": int(lbl), "voxel_count": count, "integrated_intensity": sum_i, - "centroid_mu": cz, - "centroid_chi": cx, - "centroid_d": cy, - "bbox_min_z": int(coords[:, 0].min()), - "bbox_max_z": int(coords[:, 0].max()), - "bbox_min_y": int(coords[:, 1].min()), - "bbox_max_y": int(coords[:, 1].max()), - "bbox_min_x": int(coords[:, 2].min()), - "bbox_max_x": int(coords[:, 2].max()), + "centroid_mu": c_mu, + "centroid_chi": c_chi, + "centroid_d": c_d, + "bbox_min_z": int(z_coords.min()), + "bbox_max_z": int(z_coords.max()), + "bbox_min_y": int(y_coords.min()), + "bbox_max_y": int(y_coords.max()), + "bbox_min_x": int(x_coords.min()), + "bbox_max_x": int(x_coords.max()), "cov_zz": czz, "cov_yy": cyy, "cov_xx": cxx, diff --git a/braggtrack/segmentation/postprocess.py b/braggtrack/segmentation/postprocess.py index 573f850..64a5454 100644 --- a/braggtrack/segmentation/postprocess.py +++ b/braggtrack/segmentation/postprocess.py @@ -9,14 +9,16 @@ def remove_small_objects(labels: np.ndarray, min_size: int) -> np.ndarray: """Remove labeled regions with fewer than *min_size* voxels.""" labels = np.asarray(labels) - out = labels.copy() - unique_labels = np.unique(labels) - for lbl in unique_labels: - if lbl <= 0: - continue - if np.count_nonzero(labels == lbl) < min_size: - out[out == lbl] = 0 - return out + if labels.size == 0: + return labels.copy() + max_lbl = int(labels.max()) + if max_lbl <= 0: + return np.zeros_like(labels) + clipped = np.where(labels > 0, labels, 0) + counts = np.bincount(clipped.ravel(), minlength=max_lbl + 1) + keep = counts >= min_size + keep[0] = False + return np.where(keep[clipped], labels, 0) def fill_holes_binary(mask: np.ndarray) -> np.ndarray: @@ -32,6 +34,27 @@ def fill_holes_binary(mask: np.ndarray) -> np.ndarray: return filled[1:-1, 1:-1, 1:-1] +def _six_connected_label_pairs(labels: np.ndarray) -> set[tuple[int, int]]: + """Return sorted ``(a, b)`` pairs (`0 < a < b`) sharing a 6-connected face.""" + pairs: set[tuple[int, int]] = set() + for sl_a, sl_b in ( + (labels[:-1, :, :], labels[1:, :, :]), + (labels[:, :-1, :], labels[:, 1:, :]), + (labels[:, :, :-1], labels[:, :, 1:]), + ): + diff = (sl_a != sl_b) & (sl_a > 0) & (sl_b > 0) + if not np.any(diff): + continue + a_vals = sl_a[diff] + b_vals = sl_b[diff] + lo = np.minimum(a_vals, b_vals) + hi = np.maximum(a_vals, b_vals) + uniq = np.unique(np.stack([lo, hi], axis=1), axis=0) + for a_id, b_id in uniq: + pairs.add((int(a_id), int(b_id))) + return pairs + + def merge_nearby_labels( labels: np.ndarray, volume: np.ndarray, @@ -45,57 +68,81 @@ def merge_nearby_labels( Merging is greedy — closest pairs first — and iterates until no more merges are possible. """ - from scipy.ndimage import binary_dilation, generate_binary_structure - labels = np.asarray(labels, dtype=np.int32).copy() volume = np.asarray(volume, dtype=np.float64) - struct = generate_binary_structure(3, 1) # 6-connectivity + if labels.size == 0 or int(labels.max()) < 2: + return labels + + fg_coords = np.argwhere(labels > 0) + if len(fg_coords) < 2: + return labels + z_fg = fg_coords[:, 0].astype(np.float64) + y_fg = fg_coords[:, 1].astype(np.float64) + x_fg = fg_coords[:, 2].astype(np.float64) + w_fg = volume[fg_coords[:, 0], fg_coords[:, 1], fg_coords[:, 2]] changed = True while changed: changed = False - unique_ids = [i for i in np.unique(labels) if i > 0] + cur_fg = labels[fg_coords[:, 0], fg_coords[:, 1], fg_coords[:, 2]] + unique_ids = [int(i) for i in np.unique(cur_fg) if i > 0] if len(unique_ids) < 2: break + adj_pairs = _six_connected_label_pairs(labels) + if not adj_pairs: + break + + max_id = max(unique_ids) + counts = np.bincount(cur_fg, minlength=max_id + 1) + w_sum = np.bincount(cur_fg, weights=w_fg, minlength=max_id + 1) + wz_sum = np.bincount(cur_fg, weights=w_fg * z_fg, minlength=max_id + 1) + wy_sum = np.bincount(cur_fg, weights=w_fg * y_fg, minlength=max_id + 1) + wx_sum = np.bincount(cur_fg, weights=w_fg * x_fg, minlength=max_id + 1) + gz_sum = np.bincount(cur_fg, weights=z_fg, minlength=max_id + 1) + gy_sum = np.bincount(cur_fg, weights=y_fg, minlength=max_id + 1) + gx_sum = np.bincount(cur_fg, weights=x_fg, minlength=max_id + 1) + centroids: dict[int, np.ndarray] = {} for lid in unique_ids: - mask = labels == lid - coords = np.argwhere(mask) - weights = volume[mask] - total = weights.sum() - if total > 0: - centroids[lid] = (coords * weights[:, None]).sum(axis=0) / total + tot = float(w_sum[lid]) + if tot > 0.0: + centroids[lid] = np.array([wz_sum[lid] / tot, wy_sum[lid] / tot, wx_sum[lid] / tot], dtype=np.float64) else: - centroids[lid] = coords.mean(axis=0) + cnt = max(1, int(counts[lid])) + centroids[lid] = np.array([gz_sum[lid] / cnt, gy_sum[lid] / cnt, gx_sum[lid] / cnt], dtype=np.float64) merge_pairs: list[tuple[float, int, int]] = [] - for lid in unique_ids: - dilated = binary_dilation(labels == lid, structure=struct) - neighbor_ids = set(np.unique(labels[dilated])) - {0, lid} - for nid in neighbor_ids: - if nid < lid: - continue - dist = float(np.linalg.norm(centroids[lid] - centroids[nid])) - if dist < max_centroid_distance: - merge_pairs.append((dist, lid, nid)) + for lid, nid in sorted(adj_pairs): + dist = float(np.linalg.norm(centroids[lid] - centroids[nid])) + if dist < max_centroid_distance: + merge_pairs.append((dist, lid, nid)) merge_pairs.sort() merged_this_round: set[int] = set() + remap = np.arange(max_id + 1, dtype=np.int32) for _, a, b in merge_pairs: if a in merged_this_round or b in merged_this_round: continue - labels[labels == b] = a + remap[b] = a merged_this_round.add(b) changed = True + if changed: + labels = np.where(labels > 0, remap[np.maximum(labels, 0)], 0) + return labels def relabel_sequential(labels: np.ndarray) -> np.ndarray: """Remap positive labels to consecutive integers starting at 1.""" labels = np.asarray(labels) - out = np.zeros_like(labels) - for new_id, old_id in enumerate(np.unique(labels[labels > 0]), start=1): - out[labels == old_id] = new_id - return out + if labels.size == 0: + return np.zeros_like(labels) + max_lbl = int(labels.max()) + if max_lbl <= 0: + return np.zeros_like(labels) + pos = np.unique(labels[labels > 0]) + remap = np.zeros(max_lbl + 1, dtype=labels.dtype) + remap[pos] = np.arange(1, len(pos) + 1, dtype=labels.dtype) + return np.where(labels > 0, remap[np.maximum(labels, 0)], 0) diff --git a/braggtrack/semantic/__init__.py b/braggtrack/semantic/__init__.py index 5fdd5ab..d0a8193 100644 --- a/braggtrack/semantic/__init__.py +++ b/braggtrack/semantic/__init__.py @@ -1,9 +1,17 @@ """Multi-view semantic features (orthogonal MIPs + frozen ViT embeddings).""" -from .dino import embed_multiview_mips, make_multiview_encoder, make_patch_encoder +from .dino import ( + DEFAULT_DINO_MODEL, + PatchFeatureEncoder, + embed_multiview_mips, + make_multiview_encoder, + make_patch_encoder, +) from .mips import crop_spot_cube, orthogonal_mips __all__ = [ + "DEFAULT_DINO_MODEL", + "PatchFeatureEncoder", "crop_spot_cube", "embed_multiview_mips", "make_multiview_encoder", diff --git a/braggtrack/semantic/dino.py b/braggtrack/semantic/dino.py index ef280d8..4430380 100644 --- a/braggtrack/semantic/dino.py +++ b/braggtrack/semantic/dino.py @@ -4,7 +4,7 @@ * ``mock`` — deterministic CPU-only vectors from image bytes (default when PyTorch is unavailable). -* ``torch`` — Hugging Face DINOv3 model (CLS or patch tokens). +* ``torch`` — Hugging Face DINOv2 (ungated default) or DINOv3 model. * ``auto`` — use ``torch`` if import succeeds, else ``mock``. """ @@ -12,11 +12,12 @@ import hashlib import os -from typing import Literal, Protocol +from typing import Any, Literal, Protocol import numpy as np BackendName = Literal["auto", "mock", "torch"] +DEFAULT_DINO_MODEL = "facebook/dinov2-small" def _resolve_backend(requested: BackendName) -> Literal["mock", "torch"]: @@ -31,6 +32,23 @@ def _resolve_backend(requested: BackendName) -> Literal["mock", "torch"]: return "torch" +def _load_hf_dino(model_name: str) -> tuple[Any, Any]: + from transformers import AutoImageProcessor, AutoModel + + try: + proc = AutoImageProcessor.from_pretrained(model_name) + model = AutoModel.from_pretrained(model_name) + except OSError as exc: + msg = str(exc) + if any(tok in msg.lower() for tok in ("gated", "401", "403", "authenticated")): + raise OSError( + f"Model '{model_name}' requires HuggingFace authentication. " + f"Use the ungated default '{DEFAULT_DINO_MODEL}' or set HF_TOKEN after accepting the model license." + ) from exc + raise + return proc, model + + def _mock_embedding_from_mips( mip_mu: np.ndarray, mip_chi: np.ndarray, @@ -73,16 +91,14 @@ def embed(self, mip_mu: np.ndarray, mip_chi: np.ndarray, mip_d: np.ndarray) -> n class TorchDinoMultiviewEncoder: - """Loads DINOv3 once; call :meth:`embed` per spot.""" + """Loads DINOv2/DINOv3 once; call :meth:`embed` per spot.""" - def __init__(self, model_name: str, device: str | None = None) -> None: + def __init__(self, model_name: str = DEFAULT_DINO_MODEL, device: str | None = None) -> None: import torch - from transformers import AutoImageProcessor, AutoModel self._torch = torch self._device = device or ("cuda" if torch.cuda.is_available() else "cpu") - self._proc = AutoImageProcessor.from_pretrained(model_name) - self._model = AutoModel.from_pretrained(model_name) + self._proc, self._model = _load_hf_dino(model_name) self._model.eval() self._model.to(self._device) @@ -119,7 +135,7 @@ def _requested_backend(explicit: BackendName | None) -> BackendName: def make_multiview_encoder( backend: BackendName | None = None, *, - model_name: str = "facebook/dinov3-vitb16-pretrain-lvd1689m", + model_name: str = DEFAULT_DINO_MODEL, torch_device: str | None = None, ) -> MultiviewEncoder: """Construct a reusable encoder (loads torch weights at most once).""" @@ -131,7 +147,7 @@ def make_multiview_encoder( # --------------------------------------------------------------------------- -# Patch-level feature extraction (for DINO-based segmentation) +# Patch-level feature extraction (for ROI precursors and DINO segmentation) # --------------------------------------------------------------------------- @@ -177,21 +193,18 @@ def extract_patch_features(self, image_2d: np.ndarray) -> np.ndarray: class TorchDinoPatchEncoder: - """Extracts DINOv3 patch tokens as a spatial feature map.""" + """Extracts DINOv2/DINOv3 patch tokens as a spatial feature map.""" - def __init__(self, model_name: str = "facebook/dinov3-vitb16-pretrain-lvd1689m", device: str | None = None) -> None: + def __init__(self, model_name: str = DEFAULT_DINO_MODEL, device: str | None = None) -> None: import torch - from transformers import AutoImageProcessor, AutoModel self._torch = torch self._device = device or ("cuda" if torch.cuda.is_available() else "cpu") - self._proc = AutoImageProcessor.from_pretrained(model_name) - self._model = AutoModel.from_pretrained(model_name) + self._proc, self._model = _load_hf_dino(model_name) self._model.eval() self._model.to(self._device) - self._patch_size = getattr(self._model.config, "patch_size", 16) - self._feature_dim = int(self._model.config.hidden_size) - self._num_register_tokens = getattr(self._model.config, "num_register_tokens", 0) + self._patch_size = int(getattr(self._model.config, "patch_size", 14)) + self._feature_dim = int(getattr(self._model.config, "hidden_size", 384)) @property def patch_size(self) -> int: @@ -207,13 +220,15 @@ def extract_patch_features(self, image_2d: np.ndarray) -> np.ndarray: inputs = self._proc(images=[rgb], return_tensors="pt") inputs = {k: v.to(self._device) for k, v in inputs.items()} out = self._model(**inputs) - skip = 1 + self._num_register_tokens - patch_tokens = out.last_hidden_state[:, skip:, :].squeeze(0) - h_img = inputs["pixel_values"].shape[2] - w_img = inputs["pixel_values"].shape[3] + h_img = int(inputs["pixel_values"].shape[2]) + w_img = int(inputs["pixel_values"].shape[3]) h_p = h_img // self._patch_size w_p = w_img // self._patch_size - features = patch_tokens[: h_p * w_p].reshape(h_p, w_p, -1) + expected_patches = h_p * w_p + seq_len = int(out.last_hidden_state.shape[1]) + skip = max(0, seq_len - expected_patches) + patch_tokens = out.last_hidden_state[:, skip : skip + expected_patches, :].squeeze(0) + features = patch_tokens.reshape(h_p, w_p, -1) x = features.float().cpu().numpy() norms = np.linalg.norm(x, axis=-1, keepdims=True) norms = np.where(norms > 0, norms, 1.0) @@ -223,7 +238,7 @@ def extract_patch_features(self, image_2d: np.ndarray) -> np.ndarray: def make_patch_encoder( backend: BackendName | None = None, *, - model_name: str = "facebook/dinov3-vitb16-pretrain-lvd1689m", + model_name: str = DEFAULT_DINO_MODEL, torch_device: str | None = None, ) -> PatchFeatureEncoder: """Construct a reusable patch-level encoder.""" @@ -240,7 +255,7 @@ def embed_multiview_mips( mip_d: np.ndarray, *, backend: BackendName | None = None, - model_name: str = "facebook/dinov3-vitb16-pretrain-lvd1689m", + model_name: str = DEFAULT_DINO_MODEL, torch_device: str | None = None, ) -> np.ndarray: """Return a single L2-normalised concatenated feature vector.""" diff --git a/braggtrack/tracking/__init__.py b/braggtrack/tracking/__init__.py index 7a019b1..bc5d52d 100644 --- a/braggtrack/tracking/__init__.py +++ b/braggtrack/tracking/__init__.py @@ -2,28 +2,50 @@ from .assignment import associate_frames from .cost import CostFunction, GeometrySemanticCost, PositionShapeCost +from .events import LineageEvent, SplitMergeConfig, events_to_table, resolve_splits_and_merges from .kinematics import ( GrainKinematics, KinematicsSummary, compute_grain_kinematics, kinematics_to_table, summarize_kinematics, + summary_to_dict, ) from .lifecycle import TrackEvent, build_tracks, tracks_to_table from .metrics import compute_tracking_metrics +from .precursors import ( + ObservationPrecursorScore, + PrecursorCandidate, + PrecursorConfig, + compute_fracture_precursors, + precursors_to_table, +) +from .synthetic import generate_crossing_scenario, generate_fracture_scenario __all__ = [ "CostFunction", "GeometrySemanticCost", "GrainKinematics", "KinematicsSummary", + "LineageEvent", + "ObservationPrecursorScore", "PositionShapeCost", + "PrecursorCandidate", + "PrecursorConfig", + "SplitMergeConfig", "TrackEvent", "associate_frames", "build_tracks", + "compute_fracture_precursors", "compute_grain_kinematics", "compute_tracking_metrics", + "events_to_table", + "generate_crossing_scenario", + "generate_fracture_scenario", "kinematics_to_table", + "precursors_to_table", + "resolve_splits_and_merges", "summarize_kinematics", + "summary_to_dict", "tracks_to_table", ] diff --git a/braggtrack/tracking/events.py b/braggtrack/tracking/events.py new file mode 100644 index 0000000..595eea5 --- /dev/null +++ b/braggtrack/tracking/events.py @@ -0,0 +1,423 @@ +"""Chemomechanical split (1 -> 2+) and merge (2+ -> 1) lineage resolution.""" + +from __future__ import annotations + +import math +from dataclasses import dataclass +from typing import Any, Literal + +import networkx as nx +import numpy as np + + +@dataclass(frozen=True) +class SplitMergeConfig: + """Configuration for post-assignment split and merge detection.""" + + max_distance: float = 25.0 + gate_mu: float = math.inf + gate_chi: float = math.inf + gate_d: float = math.inf + min_intensity_ratio: float = 0.4 + max_intensity_ratio: float = 1.6 + min_fragment_share: float = 0.1 + min_semantic_similarity: float | None = None + + +@dataclass(frozen=True) +class LineageEvent: + """Explicit split or merge event in the trajectory DAG.""" + + event_id: int + event_type: Literal["split", "merge"] + scan_idx_from: int + scan_idx_to: int + parent_track_ids: tuple[int, ...] + child_track_ids: tuple[int, ...] + parent_nodes: tuple[str, ...] + child_nodes: tuple[str, ...] + centroid_mu: float + centroid_chi: float + centroid_d: float + intensity_ratio: float + mean_distance: float + semantic_similarity: float | None = None + confidence: float = 1.0 + timestamp: str | None = None + + +def _spot_coords(node_data: dict[str, Any]) -> tuple[float, float, float]: + return ( + float(node_data["centroid_mu"]), + float(node_data["centroid_chi"]), + float(node_data["centroid_d"]), + ) + + +def _pair_distance_and_sim( + a: dict[str, Any], + b: dict[str, Any], + config: SplitMergeConfig, +) -> tuple[float, float | None] | None: + mu_a, chi_a, d_a = _spot_coords(a) + mu_b, chi_b, d_b = _spot_coords(b) + dmu = abs(mu_a - mu_b) + dchi = abs(chi_a - chi_b) + dd = abs(d_a - d_b) + if dmu > config.gate_mu or dchi > config.gate_chi or dd > config.gate_d: + return None + dist = math.sqrt(dmu * dmu + dchi * dchi + dd * dd) + if dist > config.max_distance: + return None + + sim: float | None = None + emb_a = a.get("embedding") + emb_b = b.get("embedding") + if emb_a is not None and emb_b is not None: + va = np.asarray(emb_a, dtype=np.float64).ravel() + vb = np.asarray(emb_b, dtype=np.float64).ravel() + if va.size > 0 and va.shape == vb.shape: + na = float(np.linalg.norm(va)) + nb = float(np.linalg.norm(vb)) + if na > 0 and nb > 0: + sim = float(np.clip(np.dot(va / na, vb / nb), -1.0, 1.0)) + if config.min_semantic_similarity is not None and sim < config.min_semantic_similarity: + return None + elif config.min_semantic_similarity is not None: + return None + + return dist, sim + + +def _event_confidence( + mean_dist: float, + max_dist: float, + intensity_ratio: float, + sem_sim: float | None, +) -> float: + dist_score = max(0.0, 1.0 - (mean_dist / max(max_dist, 1e-6))) + int_score = max(0.0, 1.0 - abs(intensity_ratio - 1.0)) + if sem_sim is not None: + sem_score = max(0.0, 0.5 * (sem_sim + 1.0)) + raw = 0.45 * dist_score + 0.35 * int_score + 0.20 * sem_score + else: + raw = 0.55 * dist_score + 0.45 * int_score + return round(float(np.clip(raw, 0.05, 1.0)), 4) + + +def _propagate_track_id(G: nx.DiGraph, start_nid: str, old_tid: int, new_tid: int) -> None: + """Update track_id along simple continuation chain starting at start_nid.""" + curr: str | None = start_nid + while curr is not None and G.nodes[curr].get("track_id") == old_tid: + G.nodes[curr]["track_id"] = new_tid + succs = [ + v + for v in G.successors(curr) + if G.edges[curr, v].get("edge_type", "continuation") == "continuation" + and G.nodes[v].get("track_id") == old_tid + ] + curr = succs[0] if len(succs) == 1 else None + + +def resolve_splits_and_merges( + G: nx.DiGraph, + n_scans: int, + config: SplitMergeConfig | None = None, + *, + scan_timestamps: dict[int, str | None] | None = None, +) -> list[LineageEvent]: + """Augment a 1-to-1 trajectory graph with split (1 -> 2+) and merge (2+ -> 1) edges. + + Modifies *G* in place (adding ``edge_type``, ``lineage_role``, and + ``parent_track_ids`` attributes, and assigning clean post-split / post-merge + track IDs) and returns the ordered list of :class:`LineageEvent` records. + """ + cfg = config or SplitMergeConfig() + if len(G.nodes) == 0 or n_scans < 2: + G.graph["lineage_events"] = [] + return [] + + for u, v in G.edges: + G.edges[u, v].setdefault("edge_type", "continuation") + + nodes_by_scan: dict[int, list[str]] = {t: [] for t in range(n_scans)} + max_tid = 0 + for nid in sorted(G.nodes): + s_idx = int(G.nodes[nid]["scan_idx"]) + if s_idx in nodes_by_scan: + nodes_by_scan[s_idx].append(nid) + max_tid = max(max_tid, int(G.nodes[nid]["track_id"])) + + next_tid = max_tid + 1 + events: list[LineageEvent] = [] + next_event_id = 1 + + for t in range(n_scans - 1): + scan_t_nodes = nodes_by_scan[t] + scan_t1_nodes = nodes_by_scan[t + 1] + if not scan_t_nodes or not scan_t1_nodes: + continue + + ts = scan_timestamps.get(t + 1) if scan_timestamps else None + + # --- Pass 0: Sever forced long-jump 1-to-1 Hungarian edges --- + # Maximum-cardinality Hungarian assignment (when max_cost=inf) will pair an + # unrelated leftover merge-source in scan t with an unrelated split-daughter + # in scan t+1 across the detector. Sever any continuation edge (u, v) that + # either violates SplitMergeConfig gates/max_distance OR where both u and v + # have local neighbours at < 50% of dist(u, v). + from .lifecycle import TrackEvent + + existing_edges = [ + (u, v) + for u in scan_t_nodes + for v in list(G.successors(u)) + if v in scan_t1_nodes and G.edges[u, v].get("edge_type", "continuation") == "continuation" + ] + for u, v in existing_edges: + uv_res = _pair_distance_and_sim(G.nodes[u], G.nodes[v], cfg) + sever = uv_res is None + if not sever and uv_res is not None: + d_uv = uv_res[0] + min_u_other = min( + ( + r[0] + for c in scan_t1_nodes + if c != v and (r := _pair_distance_and_sim(G.nodes[u], G.nodes[c], cfg)) is not None + ), + default=math.inf, + ) + min_v_other = min( + ( + r[0] + for p in scan_t_nodes + if p != u and (r := _pair_distance_and_sim(G.nodes[p], G.nodes[v], cfg)) is not None + ), + default=math.inf, + ) + if min_u_other < 0.5 * d_uv and min_v_other < 0.5 * d_uv: + sever = True + if sever: + G.remove_edge(u, v) + G.nodes[u]["event"] = TrackEvent.TERMINATED + old_v_tid = int(G.nodes[v]["track_id"]) + fresh_tid = next_tid + next_tid += 1 + _propagate_track_id(G, v, old_v_tid, fresh_tid) + G.nodes[v]["event"] = TrackEvent.BORN + + # --- Pass 1: Splits (1 -> 2+) --- + unmatched_children = [nid for nid in scan_t1_nodes if G.in_degree(nid) == 0] + parent_to_candidates: dict[str, list[tuple[str, float, float | None]]] = {} + for c_nid in unmatched_children: + best_p: str | None = None + best_dist = math.inf + best_sim: float | None = None + for p_nid in scan_t_nodes: + res = _pair_distance_and_sim(G.nodes[p_nid], G.nodes[c_nid], cfg) + if res is not None and res[0] < best_dist: + best_p = p_nid + best_dist, best_sim = res + if best_p is not None: + parent_to_candidates.setdefault(best_p, []).append((c_nid, best_dist, best_sim)) + + split_parents_used: set[str] = set() + for p_nid, extra_list in sorted(parent_to_candidates.items()): + existing_succs = list(G.successors(p_nid)) + all_children: list[str] = list(existing_succs) + [item[0] for item in extra_list] + if len(all_children) < 2: + continue + + i_parent = float(G.nodes[p_nid].get("integrated_intensity", 0.0)) + child_intensities = [max(0.0, float(G.nodes[c].get("integrated_intensity", 0.0))) for c in all_children] + i_sum = sum(child_intensities) + if i_parent <= 0.0 or i_sum <= 0.0: + continue + + ratio = i_sum / i_parent + if not (cfg.min_intensity_ratio <= ratio <= cfg.max_intensity_ratio): + continue + if any((ic / i_sum) < cfg.min_fragment_share for ic in child_intensities): + continue + + # Compute mean distance and mean semantic similarity across all children. + dists: list[float] = [] + sims: list[float] = [] + valid_all = True + for c_nid in all_children: + res = _pair_distance_and_sim(G.nodes[p_nid], G.nodes[c_nid], cfg) + if res is None: + valid_all = False + break + dists.append(res[0]) + if res[1] is not None: + sims.append(res[1]) + if not valid_all: + continue + + parent_tid = int(G.nodes[p_nid]["track_id"]) + G.nodes[p_nid]["lineage_role"] = "split_parent" + child_tids: list[int] = [] + for c_nid in sorted(all_children): + if not G.has_edge(p_nid, c_nid): + G.add_edge(p_nid, c_nid, edge_type="split") + else: + G.edges[p_nid, c_nid]["edge_type"] = "split" + + old_c_tid = int(G.nodes[c_nid]["track_id"]) + if old_c_tid == parent_tid: + new_c_tid = next_tid + next_tid += 1 + _propagate_track_id(G, c_nid, old_c_tid, new_c_tid) + else: + new_c_tid = old_c_tid + + G.nodes[c_nid]["lineage_role"] = "split_child" + G.nodes[c_nid]["parent_track_ids"] = [parent_tid] + child_tids.append(new_c_tid) + + mean_dist = float(np.mean(dists)) + mean_sim = float(np.mean(sims)) if sims else None + p_mu, p_chi, p_d = _spot_coords(G.nodes[p_nid]) + events.append( + LineageEvent( + event_id=next_event_id, + event_type="split", + scan_idx_from=t, + scan_idx_to=t + 1, + parent_track_ids=(parent_tid,), + child_track_ids=tuple(child_tids), + parent_nodes=(p_nid,), + child_nodes=tuple(sorted(all_children)), + centroid_mu=p_mu, + centroid_chi=p_chi, + centroid_d=p_d, + intensity_ratio=round(ratio, 4), + mean_distance=round(mean_dist, 4), + semantic_similarity=round(mean_sim, 4) if mean_sim is not None else None, + confidence=_event_confidence(mean_dist, cfg.max_distance, ratio, mean_sim), + timestamp=ts, + ) + ) + next_event_id += 1 + split_parents_used.add(p_nid) + + # --- Pass 2: Merges (2+ -> 1) --- + unmatched_parents = [nid for nid in scan_t_nodes if G.out_degree(nid) == 0 and nid not in split_parents_used] + target_to_candidates: dict[str, list[tuple[str, float, float | None]]] = {} + for p_nid in unmatched_parents: + best_c: str | None = None + best_dist = math.inf + best_sim: float | None = None + for c_nid in scan_t1_nodes: + if G.nodes[c_nid].get("lineage_role") == "split_child": + continue + res = _pair_distance_and_sim(G.nodes[p_nid], G.nodes[c_nid], cfg) + if res is not None and res[0] < best_dist: + best_c = c_nid + best_dist, best_sim = res + if best_c is not None: + target_to_candidates.setdefault(best_c, []).append((p_nid, best_dist, best_sim)) + + for c_nid, extra_parents in sorted(target_to_candidates.items()): + existing_preds = list(G.predecessors(c_nid)) + all_parents: list[str] = list(existing_preds) + [item[0] for item in extra_parents] + if len(all_parents) < 2: + continue + + i_target = float(G.nodes[c_nid].get("integrated_intensity", 0.0)) + parent_intensities = [max(0.0, float(G.nodes[p].get("integrated_intensity", 0.0))) for p in all_parents] + i_parents_sum = sum(parent_intensities) + if i_target <= 0.0 or i_parents_sum <= 0.0: + continue + + ratio = i_target / i_parents_sum + if not (cfg.min_intensity_ratio <= ratio <= cfg.max_intensity_ratio): + continue + if any((ip / i_parents_sum) < cfg.min_fragment_share for ip in parent_intensities): + continue + + dists = [] + sims = [] + valid_all = True + for p_nid in all_parents: + res = _pair_distance_and_sim(G.nodes[p_nid], G.nodes[c_nid], cfg) + if res is None: + valid_all = False + break + dists.append(res[0]) + if res[1] is not None: + sims.append(res[1]) + if not valid_all: + continue + + parent_tids: list[int] = [] + for p_nid in sorted(all_parents): + if not G.has_edge(p_nid, c_nid): + G.add_edge(p_nid, c_nid, edge_type="merge") + else: + G.edges[p_nid, c_nid]["edge_type"] = "merge" + G.nodes[p_nid]["lineage_role"] = "merge_source" + parent_tids.append(int(G.nodes[p_nid]["track_id"])) + + old_c_tid = int(G.nodes[c_nid]["track_id"]) + merged_tid = next_tid + next_tid += 1 + _propagate_track_id(G, c_nid, old_c_tid, merged_tid) + G.nodes[c_nid]["lineage_role"] = "merge_target" + G.nodes[c_nid]["parent_track_ids"] = sorted(parent_tids) + + mean_dist = float(np.mean(dists)) + mean_sim = float(np.mean(sims)) if sims else None + c_mu, c_chi, c_d = _spot_coords(G.nodes[c_nid]) + events.append( + LineageEvent( + event_id=next_event_id, + event_type="merge", + scan_idx_from=t, + scan_idx_to=t + 1, + parent_track_ids=tuple(sorted(parent_tids)), + child_track_ids=(merged_tid,), + parent_nodes=tuple(sorted(all_parents)), + child_nodes=(c_nid,), + centroid_mu=c_mu, + centroid_chi=c_chi, + centroid_d=c_d, + intensity_ratio=round(ratio, 4), + mean_distance=round(mean_dist, 4), + semantic_similarity=round(mean_sim, 4) if mean_sim is not None else None, + confidence=_event_confidence(mean_dist, cfg.max_distance, ratio, mean_sim), + timestamp=ts, + ) + ) + next_event_id += 1 + + G.graph["lineage_events"] = events + return events + + +def events_to_table(events: list[LineageEvent]) -> list[dict[str, Any]]: + """Serialize :class:`LineageEvent` records into CSV/JSON-friendly row dicts.""" + rows: list[dict[str, Any]] = [] + for ev in events: + rows.append( + { + "event_id": ev.event_id, + "event_type": ev.event_type, + "scan_idx_from": ev.scan_idx_from, + "scan_idx_to": ev.scan_idx_to, + "timestamp": ev.timestamp or "", + "parent_track_ids": ";".join(str(x) for x in ev.parent_track_ids), + "child_track_ids": ";".join(str(x) for x in ev.child_track_ids), + "parent_nodes": ";".join(ev.parent_nodes), + "child_nodes": ";".join(ev.child_nodes), + "centroid_mu": ev.centroid_mu, + "centroid_chi": ev.centroid_chi, + "centroid_d": ev.centroid_d, + "intensity_ratio": ev.intensity_ratio, + "mean_distance": ev.mean_distance, + "semantic_similarity": ev.semantic_similarity if ev.semantic_similarity is not None else "", + "confidence": ev.confidence, + } + ) + return rows diff --git a/braggtrack/tracking/kinematics.py b/braggtrack/tracking/kinematics.py index eb277da..8221e28 100644 --- a/braggtrack/tracking/kinematics.py +++ b/braggtrack/tracking/kinematics.py @@ -45,6 +45,9 @@ class GrainKinematics: anisotropy: np.ndarray # eig_1 / eig_3 covariance_trace: np.ndarray # eig_1 + eig_2 + eig_3 + # Raw shift in d-axis (always meaningful even when uncalibrated) + delta_d: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + @dataclass class KinematicsSummary: @@ -62,7 +65,8 @@ class KinematicsSummary: volume_change_frac: list[float] max_anisotropy: list[float] - grain_kinematics: list[GrainKinematics] = field(repr=False) + calibrated_axes: bool = False + grain_kinematics: list[GrainKinematics] = field(default_factory=list, repr=False) def compute_grain_kinematics( @@ -97,9 +101,10 @@ def compute_grain_kinematics( chi = np.array([float(r["centroid_chi"]) for r in obs]) d = np.array([float(r["centroid_d"]) for r in obs]) - # Strain: (d - d₀) / d₀ + # Strain: (d - d₀) / d₀ and raw shift Δd = d - d₀ d0 = d[0] - strain = (d - d0) / d0 if d0 != 0 else np.zeros(n) + delta_d = d - d0 + strain = delta_d / d0 if d0 != 0 else np.zeros(n) # Misorientation: drift from initial position dmu = mu - mu[0] @@ -137,6 +142,7 @@ def compute_grain_kinematics( eigenvalues=eigs, anisotropy=anisotropy, covariance_trace=cov_trace, + delta_d=delta_d, ) ) return results @@ -145,6 +151,8 @@ def compute_grain_kinematics( def summarize_kinematics( grain_kinematics: list[GrainKinematics], n_scans: int, + *, + calibrated_axes: bool = False, ) -> KinematicsSummary: """Aggregate per-grain kinematics into a summary table. @@ -154,6 +162,8 @@ def summarize_kinematics( Output of :func:`compute_grain_kinematics`. n_scans Total number of scans in the sequence. + calibrated_axes + Whether centroids/eigenvalues were converted to physical ``(mu, chi, d)`` units. """ track_ids: list[int] = [] max_strain: list[float] = [] @@ -164,11 +174,11 @@ def summarize_kinematics( for gk in grain_kinematics: track_ids.append(gk.track_id) - max_strain.append(float(np.max(np.abs(gk.strain)))) + max_strain.append(float(np.max(np.abs(gk.strain))) if len(gk.strain) > 0 else 0.0) total_misorientation.append(float(gk.misorientation_total[-1]) if len(gk.misorientation_total) > 0 else 0.0) intensity_change.append(float(gk.relative_intensity[-1]) if len(gk.relative_intensity) > 0 else 0.0) volume_change.append(float(gk.relative_volume[-1]) if len(gk.relative_volume) > 0 else 0.0) - max_anisotropy.append(float(np.max(gk.anisotropy))) + max_anisotropy.append(float(np.max(gk.anisotropy)) if len(gk.anisotropy) > 0 else 1.0) n_full = sum(1 for gk in grain_kinematics if len(gk.scan_indices) >= n_scans) @@ -182,12 +192,31 @@ def summarize_kinematics( intensity_change_frac=intensity_change, volume_change_frac=volume_change, max_anisotropy=max_anisotropy, + calibrated_axes=calibrated_axes, grain_kinematics=grain_kinematics, ) +def summary_to_dict(summary: KinematicsSummary) -> dict[str, Any]: + """Serialize :class:`KinematicsSummary` to a JSON-friendly dictionary.""" + return { + "n_tracks": summary.n_tracks, + "n_full_tracks": summary.n_full_tracks, + "n_scans": summary.n_scans, + "calibrated_axes": summary.calibrated_axes, + "track_ids": summary.track_ids, + "max_strain": summary.max_strain, + "total_misorientation": summary.total_misorientation, + "intensity_change_frac": summary.intensity_change_frac, + "volume_change_frac": summary.volume_change_frac, + "max_anisotropy": summary.max_anisotropy, + } + + def kinematics_to_table( grain_kinematics: list[GrainKinematics], + *, + include_delta_d: bool = False, ) -> list[dict[str, Any]]: """Flatten per-grain kinematics into a row-per-observation table. @@ -198,26 +227,27 @@ def kinematics_to_table( rows: list[dict[str, Any]] = [] for gk in grain_kinematics: for i, scan_idx in enumerate(gk.scan_indices): - rows.append( - { - "track_id": gk.track_id, - "scan_idx": scan_idx, - "centroid_mu": float(gk.centroid_mu[i]), - "centroid_chi": float(gk.centroid_chi[i]), - "centroid_d": float(gk.centroid_d[i]), - "strain": float(gk.strain[i]), - "misorientation_mu": float(gk.misorientation_mu[i]), - "misorientation_chi": float(gk.misorientation_chi[i]), - "misorientation_total": float(gk.misorientation_total[i]), - "integrated_intensity": float(gk.integrated_intensity[i]), - "voxel_count": float(gk.voxel_count[i]), - "relative_intensity": float(gk.relative_intensity[i]), - "relative_volume": float(gk.relative_volume[i]), - "eig_1": float(gk.eigenvalues[i, 0]), - "eig_2": float(gk.eigenvalues[i, 1]), - "eig_3": float(gk.eigenvalues[i, 2]), - "anisotropy": float(gk.anisotropy[i]), - "covariance_trace": float(gk.covariance_trace[i]), - } - ) + row: dict[str, Any] = { + "track_id": gk.track_id, + "scan_idx": scan_idx, + "centroid_mu": float(gk.centroid_mu[i]), + "centroid_chi": float(gk.centroid_chi[i]), + "centroid_d": float(gk.centroid_d[i]), + "strain": float(gk.strain[i]), + "misorientation_mu": float(gk.misorientation_mu[i]), + "misorientation_chi": float(gk.misorientation_chi[i]), + "misorientation_total": float(gk.misorientation_total[i]), + "integrated_intensity": float(gk.integrated_intensity[i]), + "voxel_count": float(gk.voxel_count[i]), + "relative_intensity": float(gk.relative_intensity[i]), + "relative_volume": float(gk.relative_volume[i]), + "eig_1": float(gk.eigenvalues[i, 0]), + "eig_2": float(gk.eigenvalues[i, 1]), + "eig_3": float(gk.eigenvalues[i, 2]), + "anisotropy": float(gk.anisotropy[i]), + "covariance_trace": float(gk.covariance_trace[i]), + } + if include_delta_d and len(gk.delta_d) > i: + row["delta_d"] = float(gk.delta_d[i]) + rows.append(row) return rows diff --git a/braggtrack/tracking/lifecycle.py b/braggtrack/tracking/lifecycle.py index 404aef6..d72089c 100644 --- a/braggtrack/tracking/lifecycle.py +++ b/braggtrack/tracking/lifecycle.py @@ -3,12 +3,15 @@ from __future__ import annotations import enum -from typing import Any +from typing import TYPE_CHECKING, Any import networkx as nx from .assignment import associate_frames -from .cost import CostFunction +from .cost import CostFunction, PositionShapeCost + +if TYPE_CHECKING: + from .events import SplitMergeConfig class TrackEvent(str, enum.Enum): @@ -24,31 +27,21 @@ def _node_id(scan_idx: int, spot_idx: int) -> str: def build_tracks( scan_tables: list[list[dict]], - cost_fn: CostFunction, + cost_fn: CostFunction | None = None, max_cost: float = float("inf"), + *, + split_merge_config: SplitMergeConfig | None = None, + scan_timestamps: dict[int, str | None] | None = None, ) -> nx.DiGraph: """Build a trajectory DAG across an ordered sequence of scan tables. 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. - - Parameters - ---------- - scan_tables : list[list[dict]] - Per-scan feature tables (output of :func:`extract_instance_table`). - cost_fn : CostFunction - Pluggable cost callable (e.g. :class:`PositionShapeCost`). - max_cost : float - Hard upper bound on acceptable association cost. - - Returns - ------- - nx.DiGraph - Directed acyclic graph of spot trajectories. Node attributes - include ``scan_idx``, ``spot_idx``, ``track_id``, ``event``, - and all columns from the feature table. + attribute. Edges connect matched spots across consecutive frames, and + optional *split_merge_config* resolves ``1 -> 2+`` splits and ``2+ -> 1`` + merges. """ + active_cost: CostFunction = cost_fn if cost_fn is not None else PositionShapeCost() G = nx.DiGraph() n_scans = len(scan_tables) if n_scans == 0: @@ -72,7 +65,7 @@ def build_tracks( matches, unmatched_t, unmatched_t1 = associate_frames( spots_t, spots_t1, - cost_fn=cost_fn, + cost_fn=active_cost, max_cost=max_cost, ) @@ -86,7 +79,7 @@ def build_tracks( G.add_node( nid_next, scan_idx=t + 1, spot_idx=i_t1, track_id=tid, event=TrackEvent.CONTINUED, **spots_t1[i_t1] ) - G.add_edge(nid_prev, nid_next) + G.add_edge(nid_prev, nid_next, edge_type="continuation") new_track_map[i_t1] = tid # Unmatched in t → TERMINATED (mark on existing node) @@ -113,6 +106,16 @@ def build_tracks( # Still alive at end — leave as CONTINUED (not terminated) pass + if split_merge_config is not None: + from .events import resolve_splits_and_merges + + resolve_splits_and_merges( + G, + n_scans=n_scans, + config=split_merge_config, + scan_timestamps=scan_timestamps, + ) + return G @@ -122,9 +125,15 @@ def tracks_to_table(G: nx.DiGraph) -> list[dict[str, Any]]: Each row contains ``track_id``, ``scan_idx``, ``spot_idx``, ``event``, and all feature columns. """ + has_lineage = bool(G.graph.get("lineage_events")) rows: list[dict[str, Any]] = [] for nid in sorted(G.nodes): data = dict(G.nodes[nid]) data["event"] = data["event"].value if isinstance(data["event"], TrackEvent) else data["event"] + if has_lineage or "parent_track_ids" in data or "lineage_role" in data: + ptids = data.get("parent_track_ids", []) + if isinstance(ptids, (list, tuple)): + data["parent_track_ids"] = ";".join(str(x) for x in ptids) + data.setdefault("lineage_role", "") rows.append(data) return rows diff --git a/braggtrack/tracking/metrics.py b/braggtrack/tracking/metrics.py index 51485c2..6901b51 100644 --- a/braggtrack/tracking/metrics.py +++ b/braggtrack/tracking/metrics.py @@ -86,6 +86,10 @@ def compute_tracking_metrics( n_edges = G.number_of_edges() id_switch_rate = id_switch_count / n_edges if n_edges > 0 else 0.0 + 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") + return { "total_tracks": total_tracks, "full_length_tracks": full_length_tracks, @@ -93,6 +97,8 @@ def compute_tracking_metrics( "born_count": born_count, "continued_count": continued_count, "terminated_count": terminated_count, + "split_count": split_count, + "merge_count": merge_count, "id_switch_count": id_switch_count, "id_switch_rate": round(id_switch_rate, 4), } diff --git a/braggtrack/tracking/precursors.py b/braggtrack/tracking/precursors.py new file mode 100644 index 0000000..053903a --- /dev/null +++ b/braggtrack/tracking/precursors.py @@ -0,0 +1,353 @@ +"""Chemomechanical fracture precursor scoring with multi-scan persistence filtering. + +Detects intragranular mosaicity buildup and incipient sub-grain splitting before +a Bragg reflection cleaves into separate connected components, combining: +1. 3D covariance elongation (eigenvalue anisotropy eig_1 / eig_3), +2. Relative reciprocal-space broadening (covariance trace growth), and +3. Intra-spot ROI sub-peak bimodality + DINO patch-feature dispersion. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +import numpy as np +from scipy.ndimage import gaussian_filter, zoom +from skimage.feature import peak_local_max + +from braggtrack.semantic.mips import crop_spot_cube, orthogonal_mips + +if TYPE_CHECKING: + from braggtrack.semantic.dino import PatchFeatureEncoder + from braggtrack.tracking.events import LineageEvent + + +@dataclass(frozen=True) +class PrecursorConfig: + """Configuration for fracture precursor scoring and persistence filtering.""" + + score_threshold: float = 0.40 + min_persistence: int = 2 + anisotropy_scale: float = 3.0 + spread_growth_scale: float = 1.0 + weight_anisotropy: float = 0.35 + weight_spread: float = 0.25 + weight_roi: float = 0.40 + roi_margin: int = 2 + roi_upsample_size: int = 64 + + +@dataclass(frozen=True) +class ObservationPrecursorScore: + """Per-observation precursor diagnostics for one spot in one scan.""" + + track_id: int + scan_idx: int + label: int + anisotropy: float + anisotropy_term: float + spread_growth: float + spread_term: float + roi_subpeak_count: int + roi_dispersion_term: float + precursor_score: float + + +@dataclass(frozen=True) +class PrecursorCandidate: + """Ranked grain track exhibiting persistent fracture precursor signatures.""" + + rank: int + track_id: int + onset_scan: int + peak_scan: int + persistence_scans: int + peak_score: float + mean_active_score: float + max_anisotropy: float + max_spread_growth: float + max_subpeak_count: int + confidence: float + subsequent_split: bool + + +def _count_internal_subpeaks(masked_cube: np.ndarray, mask: np.ndarray) -> tuple[int, float]: + """Count distinct internal intensity maxima inside a segmented 3D spot ROI.""" + fg = mask > 0 + if int(fg.sum()) < 4: + return 1, 0.0 + + vals = masked_cube[fg] + vmax = float(vals.max()) + if vmax <= 0.0: + return 1, 0.0 + + smoothed = gaussian_filter(np.where(fg, masked_cube, 0.0).astype(np.float64), sigma=0.7) + smax = float(smoothed[fg].max()) + if smax <= 0.0: + return 1, 0.0 + + coords = peak_local_max( + smoothed, + min_distance=2, + threshold_abs=0.25 * smax, + labels=fg.astype(np.uint8), + num_peaks=32, + ) + n_peaks = int(len(coords)) + if n_peaks <= 1: + return 1, 0.0 + + subpeak_score = float(np.clip(0.65 + 0.20 * (n_peaks - 2), 0.0, 1.0)) + return n_peaks, subpeak_score + + +def _patch_dispersion_score( + masked_cube: np.ndarray, + mask: np.ndarray, + patch_encoder: PatchFeatureEncoder, + upsample_size: int, +) -> float: + """Compute mean foreground patch-token cosine dispersion across orthogonal MIPs.""" + mip_mu, mip_chi, mip_d = orthogonal_mips(masked_cube) + mask_mu, mask_chi, mask_d = orthogonal_mips(mask.astype(np.float64)) + + dispersions: list[float] = [] + for mip, mm in ((mip_mu, mask_mu), (mip_chi, mask_chi), (mip_d, mask_d)): + if mip.size == 0 or float(mm.max()) <= 0.0: + continue + h, w = mip.shape + zh = max(1.0, upsample_size / max(1, h)) + zw = max(1.0, upsample_size / max(1, w)) + mip_up = zoom(mip.astype(np.float64), (zh, zw), order=1) if (zh > 1.0 or zw > 1.0) else mip.astype(np.float64) + mm_up = zoom(mm.astype(np.float64), (zh, zw), order=0) if (zh > 1.0 or zw > 1.0) else mm.astype(np.float64) + + fmap = patch_encoder.extract_patch_features(mip_up) + hp, wp, dim = fmap.shape + if hp * wp < 2: + continue + + # Map foreground mask onto (hp, wp) patch grid. + bh = max(1, mm_up.shape[0] // hp) + bw = max(1, mm_up.shape[1] // wp) + cropped_fg = (mm_up[: hp * bh, : wp * bw] > 0).reshape(hp, bh, wp, bw).max(axis=(1, 3)) + fg_vecs = fmap[cropped_fg] if int(cropped_fg.sum()) >= 2 else fmap.reshape(-1, dim) + if fg_vecs.shape[0] < 2: + continue + + mean_vec = fg_vecs.mean(axis=0) + nrm = float(np.linalg.norm(mean_vec)) + if nrm <= 0.0: + continue + mean_vec = mean_vec / nrm + cos_sims = np.clip(fg_vecs @ mean_vec, -1.0, 1.0) + cos_disp = float(1.0 - np.mean(cos_sims)) + dispersions.append(float(np.clip(cos_disp / 0.6, 0.0, 1.0))) + + return float(np.mean(dispersions)) if dispersions else 0.0 + + +def compute_fracture_precursors( + track_table: list[dict[str, Any]], + config: PrecursorConfig | None = None, + *, + volumes: dict[int, np.ndarray] | list[np.ndarray] | None = None, + label_volumes: dict[int, np.ndarray] | list[np.ndarray] | None = None, + patch_encoder: PatchFeatureEncoder | None = None, + lineage_events: list[LineageEvent] | None = None, +) -> tuple[list[PrecursorCandidate], list[ObservationPrecursorScore]]: + """Score per-grain fracture precursors and return persistent ranked candidates. + + Parameters + ---------- + track_table + Row-per-observation trajectory table from :func:`tracks_to_table`. + config + Thresholds, weights, and persistence configuration. + volumes, label_volumes + Optional mapping (or scan-indexed list) of 3D intensity and integer label + volumes enabling intra-spot sub-peak and DINO patch-dispersion analysis. + patch_encoder + Optional :class:`PatchFeatureEncoder` for MIP patch dispersion. + lineage_events + Optional list of :class:`LineageEvent` records used to annotate whether a + precursor candidate subsequently fractured (``subsequent_split``). + """ + cfg = config or PrecursorConfig() + if not track_table: + return [], [] + + vol_map: dict[int, np.ndarray] = {} + if isinstance(volumes, dict): + vol_map = volumes + elif isinstance(volumes, list): + vol_map = dict(enumerate(volumes)) + + lab_map: dict[int, np.ndarray] = {} + if isinstance(label_volumes, dict): + lab_map = label_volumes + elif isinstance(label_volumes, list): + lab_map = dict(enumerate(label_volumes)) + + has_roi = bool(vol_map and lab_map) + + split_parent_tids: set[int] = set() + if lineage_events: + for ev in lineage_events: + if ev.event_type == "split": + split_parent_tids.update(ev.parent_track_ids) + + by_track: dict[int, list[dict[str, Any]]] = {} + for row in track_table: + by_track.setdefault(int(row["track_id"]), []).append(row) + + all_obs_scores: list[ObservationPrecursorScore] = [] + unranked: list[PrecursorCandidate] = [] + + for tid in sorted(by_track): + obs_list = sorted(by_track[tid], key=lambda r: int(r["scan_idx"])) + e0 = ( + float(obs_list[0].get("eig_1", 0.0)) + + float(obs_list[0].get("eig_2", 0.0)) + + float(obs_list[0].get("eig_3", 0.0)) + ) + track_scores: list[ObservationPrecursorScore] = [] + + for obs in obs_list: + scan_idx = int(obs["scan_idx"]) + lbl = int(obs.get("label", 0)) + eig1 = max(0.0, float(obs.get("eig_1", 0.0))) + eig2 = max(0.0, float(obs.get("eig_2", 0.0))) + eig3 = max(0.0, float(obs.get("eig_3", 0.0))) + + aniso = eig1 / eig3 if eig3 > 1e-9 else (1.0 if eig1 <= 1e-9 else 10.0) + aniso_term = float(np.clip((aniso - 1.0) / max(cfg.anisotropy_scale, 1e-6), 0.0, 1.0)) + + trace = eig1 + eig2 + eig3 + spread_growth = (trace - e0) / e0 if e0 > 1e-9 else 0.0 + spread_term = float(np.clip(max(0.0, spread_growth) / max(cfg.spread_growth_scale, 1e-6), 0.0, 1.0)) + + n_subpeaks = 1 + roi_term = 0.0 + use_roi_here = has_roi and scan_idx in vol_map and scan_idx in lab_map and lbl > 0 + if use_roi_here and "bbox_min_z" in obs: + masked_cube, mask = crop_spot_cube( + vol_map[scan_idx], + lab_map[scan_idx], + lbl, + obs, + margin=cfg.roi_margin, + ) + n_subpeaks, subpeak_term = _count_internal_subpeaks(masked_cube, mask) + if patch_encoder is not None: + p_disp = _patch_dispersion_score(masked_cube, mask, patch_encoder, cfg.roi_upsample_size) + roi_term = float(np.clip(0.65 * subpeak_term + 0.35 * p_disp, 0.0, 1.0)) + else: + roi_term = subpeak_term + + if use_roi_here and "bbox_min_z" in obs: + w_sum = cfg.weight_anisotropy + cfg.weight_spread + cfg.weight_roi + raw_score = ( + cfg.weight_anisotropy * aniso_term + cfg.weight_spread * spread_term + cfg.weight_roi * roi_term + ) / max(w_sum, 1e-6) + else: + w_geo = cfg.weight_anisotropy + cfg.weight_spread + raw_score = (cfg.weight_anisotropy * aniso_term + cfg.weight_spread * spread_term) / max(w_geo, 1e-6) + + score_obj = ObservationPrecursorScore( + track_id=tid, + scan_idx=scan_idx, + label=lbl, + anisotropy=round(aniso, 4), + anisotropy_term=round(aniso_term, 4), + spread_growth=round(spread_growth, 4), + spread_term=round(spread_term, 4), + roi_subpeak_count=n_subpeaks, + roi_dispersion_term=round(roi_term, 4), + precursor_score=round(float(np.clip(raw_score, 0.0, 1.0)), 4), + ) + track_scores.append(score_obj) + all_obs_scores.append(score_obj) + + # Evaluate contiguous persistence runs where precursor_score >= score_threshold. + best_run: list[ObservationPrecursorScore] = [] + current_run: list[ObservationPrecursorScore] = [] + for idx_s, sc in enumerate(track_scores): + is_consecutive = idx_s == 0 or (sc.scan_idx == track_scores[idx_s - 1].scan_idx + 1) + if sc.precursor_score >= cfg.score_threshold: + if current_run and is_consecutive: + current_run.append(sc) + else: + current_run = [sc] + if len(current_run) > len(best_run) or ( + len(current_run) == len(best_run) + and max(x.precursor_score for x in current_run) > max(x.precursor_score for x in best_run) + ): + best_run = list(current_run) + else: + current_run = [] + + if len(best_run) >= max(1, cfg.min_persistence): + peak_obs = max(best_run, key=lambda x: x.precursor_score) + mean_active = float(np.mean([x.precursor_score for x in best_run])) + pers_bonus = min(0.20, 0.05 * (len(best_run) - cfg.min_persistence + 1)) + conf = float(np.clip(0.55 * peak_obs.precursor_score + 0.35 * mean_active + pers_bonus, 0.05, 1.0)) + unranked.append( + PrecursorCandidate( + rank=0, + track_id=tid, + onset_scan=best_run[0].scan_idx, + peak_scan=peak_obs.scan_idx, + persistence_scans=len(best_run), + peak_score=round(peak_obs.precursor_score, 4), + mean_active_score=round(mean_active, 4), + max_anisotropy=round(max(x.anisotropy for x in track_scores), 4), + max_spread_growth=round(max(x.spread_growth for x in track_scores), 4), + max_subpeak_count=max(x.roi_subpeak_count for x in track_scores), + confidence=round(conf, 4), + subsequent_split=tid in split_parent_tids, + ) + ) + + # Sort descending by confidence, breaking ties by peak_score then track_id. + unranked.sort(key=lambda c: (-c.confidence, -c.peak_score, c.track_id)) + ranked = [ + PrecursorCandidate( + rank=idx + 1, + track_id=c.track_id, + onset_scan=c.onset_scan, + peak_scan=c.peak_scan, + persistence_scans=c.persistence_scans, + peak_score=c.peak_score, + mean_active_score=c.mean_active_score, + max_anisotropy=c.max_anisotropy, + max_spread_growth=c.max_spread_growth, + max_subpeak_count=c.max_subpeak_count, + confidence=c.confidence, + subsequent_split=c.subsequent_split, + ) + for idx, c in enumerate(unranked) + ] + return ranked, all_obs_scores + + +def precursors_to_table(candidates: list[PrecursorCandidate]) -> list[dict[str, Any]]: + """Serialize ranked :class:`PrecursorCandidate` items to row dicts.""" + return [ + { + "rank": c.rank, + "track_id": c.track_id, + "onset_scan": c.onset_scan, + "peak_scan": c.peak_scan, + "persistence_scans": c.persistence_scans, + "peak_score": c.peak_score, + "mean_active_score": c.mean_active_score, + "max_anisotropy": c.max_anisotropy, + "max_spread_growth": c.max_spread_growth, + "max_subpeak_count": c.max_subpeak_count, + "confidence": c.confidence, + "subsequent_split": c.subsequent_split, + } + for c in candidates + ] diff --git a/braggtrack/tracking/synthetic.py b/braggtrack/tracking/synthetic.py index 5a92a5e..c18976d 100644 --- a/braggtrack/tracking/synthetic.py +++ b/braggtrack/tracking/synthetic.py @@ -10,6 +10,8 @@ import random from typing import Any +import numpy as np + def _make_spot( label: int, @@ -142,3 +144,111 @@ def generate_crossing_scenario( scan_tables.append(spots) return scan_tables, ground_truth + + +def _add_gaussian_blob( + volume: np.ndarray, + center: tuple[float, float, float], + sigma: tuple[float, float, float], + amplitude: float, +) -> np.ndarray: + """Add a 3D Gaussian lobe to *volume* and return its isolated contribution.""" + zz, yy, xx = np.indices(volume.shape, dtype=np.float64) + cz, cy, cx = center + sz, sy, sx = sigma + exponent = -0.5 * (((zz - cz) / sz) ** 2 + ((yy - cy) / sy) ** 2 + ((xx - cx) / sx) ** 2) + lobe = amplitude * np.exp(exponent) + volume += lobe + return lobe + + +def generate_fracture_scenario( + n_scans: int = 5, + shape: tuple[int, int, int] = (24, 48, 48), + seed: int = 42, +) -> tuple[list[np.ndarray], list[np.ndarray], list[list[dict[str, Any]]], dict[str, Any]]: + """Generate a 4D synthetic scenario with precursor broadening, split, merge, and control grain. + + Scenario layout across *n_scans* (requires ``n_scans >= 4``): + - **Grain A (fracturing):** At ``(z=12, y=12, x=14)``. During scans ``0..1`` it + develops bimodal sub-lobes inside a single connected reflection (persistent + fracture precursor), then cleaves into two distinct daughter reflections at + scan ``2`` (``1 -> 2`` split) with diverging ``d`` shifts. + - **Grain B (coalescing):** Two separate compact reflections near + ``(z=12, y=34, x=11..17)`` during scans ``0..1`` that merge into a single + reflection at scan ``2`` (``2 -> 1`` merge) conserving integrated intensity. + - **Grain C (control):** Stable isotropic grain at ``(z=12, y=24, x=36)`` + across all scans (must produce zero splits/merges and zero precursors). + """ + from braggtrack.segmentation.features import extract_instance_table + + if n_scans < 4: + raise ValueError("generate_fracture_scenario requires n_scans >= 4") + + rng = np.random.default_rng(seed) + volumes: list[np.ndarray] = [] + label_volumes: list[np.ndarray] = [] + scan_tables: list[list[dict[str, Any]]] = [] + + split_scan = 2 + merge_scan = 2 + + for t in range(n_scans): + vol = rng.uniform(0.0, 0.2, size=shape).astype(np.float64) + labels = np.zeros(shape, dtype=np.int32) + next_label = 1 + + # --- Grain A: Precursor (scans 0..1) -> Split (scan >= 2) --- + if t < split_scan: + # Progressive internal sub-lobe separation inside one connected mask. + half_sep = 1.9 + 0.5 * t # 1.9 at t=0, 2.4 at t=1 (distinct internal maxima, overlapping support) + lobe1 = _add_gaussian_blob(vol, (12.0, 12.0, 14.0 - half_sep), (1.3, 1.3, 1.4 + 0.3 * t), 55.0) + lobe2 = _add_gaussian_blob(vol, (12.0, 12.0, 14.0 + half_sep), (1.3, 1.3, 1.4 + 0.3 * t), 50.0) + combined = lobe1 + lobe2 + labels[combined >= 4.0] = next_label + next_label += 1 + else: + dt = t - split_scan + # Cleaved into two separated daughter fragments with diverging d (y-axis). + d1 = _add_gaussian_blob(vol, (12.0, 12.0 - 0.4 * dt, 10.0 - 0.3 * dt), (1.3, 1.3, 1.3), 54.0) + labels[d1 >= 4.0] = next_label + next_label += 1 + + d2 = _add_gaussian_blob(vol, (12.0, 12.0 + 0.5 * dt, 18.0 + 0.3 * dt), (1.3, 1.3, 1.3), 49.0) + labels[(d2 >= 4.0) & (labels == 0)] = next_label + next_label += 1 + + # --- Grain B: Two compact sub-domains (scans 0..1) -> Merge (scan >= 2) --- + if t < merge_scan: + offset = 3.5 - 0.5 * t # 3.5 at t=0, 3.0 at t=1 (well-separated masks) + m1 = _add_gaussian_blob(vol, (12.0, 34.0, 14.0 - offset), (1.2, 1.2, 1.2), 45.0) + labels[(m1 >= 5.0) & (labels == 0)] = next_label + next_label += 1 + + m2 = _add_gaussian_blob(vol, (12.0, 34.0, 14.0 + offset), (1.2, 1.2, 1.2), 45.0) + labels[(m2 >= 5.0) & (labels == 0)] = next_label + next_label += 1 + else: + merged = _add_gaussian_blob(vol, (12.0, 34.0, 14.0), (1.35, 1.35, 1.35), 68.0) + labels[(merged >= 5.0) & (labels == 0)] = next_label + next_label += 1 + + # --- Grain C: Stable isotropic control grain --- + ctrl = _add_gaussian_blob(vol, (12.0, 24.0, 36.0), (1.4, 1.4, 1.4), 70.0) + labels[(ctrl >= 5.0) & (labels == 0)] = next_label + + volumes.append(vol) + label_volumes.append(labels) + scan_tables.append(extract_instance_table(labels, vol)) + + expected = { + "n_scans": n_scans, + "split_scan_from": split_scan - 1, + "split_scan_to": split_scan, + "merge_scan_from": merge_scan - 1, + "merge_scan_to": merge_scan, + "fracture_initial_mu_chi_d": (12.0, 14.0, 12.0), + "merge_target_mu_chi_d": (12.0, 14.0, 34.0), + "control_mu_chi_d": (12.0, 36.0, 24.0), + } + return volumes, label_volumes, scan_tables, expected diff --git a/docs/architecture.md b/docs/architecture.md index 78c4c79..7f9e002 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,77 +1,100 @@ # BraggTrack architecture -This document describes how the repository is structured, how data flows through the pipeline, and where to add new functionality. +This document describes how the repository is structured, how data flows through the pipeline, and where to extend functionality. ## Repository layout ```text BraggTrack/ -├── braggtrack/ # Installable Python package -│ ├── io/ # Discovery, NeXus/HDF5, beamline contracts, validation -│ ├── segmentation/ # Classical 3D segmentation + instance features -│ ├── semantic/ # Week 4: orthogonal MIPs + frozen ViT embeddings -│ ├── tracking/ # Costs, vectorised assignment, lifecycle DAG, metrics -│ └── cli/ # argparse entry points (thin orchestration) +├── 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 +│ ├── 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 ├── data/ -│ └── sample_operando/ # Bundled scan0001… folders (versioned test data) -├── docs/ # Architecture & practices (this file) -├── scripts/ # CI glue, acceptance runners, ablation utilities -├── tests/ # unittest discovery +│ └── 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 +├── tests/ # Unit and acceptance test suite └── artifacts/ # Generated outputs (gitignored) ``` ## Layered design -| Layer | Responsibility | Depends on | -|--------|----------------|------------| -| **io** | Find scans, load volumes, map files → `ScanVolumeMeta` / `ExperimentSequence`, validate | `numpy`, optional `h5py` | -| **segmentation** | Threshold / classical pipeline, instance table (`features.csv` contract) | `numpy`, `scipy`, `skimage` | -| **semantic** | Per-spot MIPs + encoder (`mock` or Dinov2) | `numpy`, optional `torch` + `transformers` | -| **tracking** | Pairwise cost matrix (`cdist` + optional `A @ B.T`), Hungarian assignment, DAG | `numpy`, `scipy`, `networkx` | -| **cli** | Parse args, resolve dataset root, write JSON/CSV/artifacts | All of the above | +| 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` | +| **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 | -**Rule of thumb:** put **numeric kernels** and **contracts** in subpackages; keep **CLI modules** as small glue. +**Rule of thumb:** keep **numeric kernels** and **typed data contracts** in subpackages; keep **CLI modules** as thin orchestration layers. -## Data flow (operando week model) +## Data flow (`braggtrack-run`) ```mermaid flowchart LR - subgraph inputs - H5[H5 / NeXus volumes] + subgraph inputs["Inputs"] + H5["HDF5 / NeXus 3D scans"] + CAL["AxisCalibration (auto or JSON)"] end - subgraph week2 - SEG[segment_dataset] - FEAT[features.csv + labels.npz] + subgraph seg["Segmentation"] + SEG["segment_dataset (smoothed Otsu + 3D watershed)"] + FEAT["features.csv + labels.npz"] end - subgraph week4 - EMB[embed_dataset] - NPZ[embeddings.npz] + subgraph sem["Semantic"] + EMB["embed_dataset (MIPs + DINOv2 / mock)"] + NPZ["embeddings.npz"] end - subgraph week3_4 - TRK[track_dataset] - DAG[trajectory DAG / tracks.csv] + subgraph trk["Tracking & Kinematics"] + TRK["track_dataset (Hungarian + kinematics)"] + KIN["tracks.csv + kinematics.csv"] end - H5 --> SEG --> FEAT --> EMB --> NPZ + subgraph evt["Lineage & Precursors"] + EVT["detect_events (splits, merges, ROI dispersion)"] + OUT["events.csv + precursors.csv"] + end + MAN["run_manifest.json (SHA-256 + timings)"] + + H5 --> SEG + CAL --> SEG + SEG --> FEAT + H5 --> EMB + FEAT --> EMB --> NPZ FEAT --> TRK NPZ --> TRK - TRK --> DAG + TRK --> KIN + H5 --> EVT + FEAT --> EVT + NPZ --> EVT + EVT --> OUT + SEG --> MAN + TRK --> MAN + EVT --> MAN ``` -- **Dataset root** is always a directory containing `scan*` folders (see `data/sample_operando/README.md`). -- **Artifacts** under `artifacts/` are reproducible outputs; never commit them. +- **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. +- **Artifacts** under `artifacts/` are reproducible build outputs and are never committed to Git. ## Extension points -1. **New beamline / file layout** — extend `discover_operando_scans` or add an adapter parallel to `BeamlineAdapter`, keeping `ScanVolumeMeta` as the contract. -2. **New segmentation** — implement alongside `segment_classical`; feed `extract_instance_table` with `(labels, intensity)`. -3. **New association cost** — implement `pairwise_cost_matrix` + scalar `__call__` matching `CostFunction` in `braggtrack/tracking/cost.py`; keep gating and `inf` semantics consistent with `associate_frames`. -4. **New CLI** — add `braggtrack/cli/foo.py`, register in `pyproject.toml` `[project.scripts]` if needed. +1. **New beamline / HDF5 layout** — add candidate paths to `PRIMARY_VOLUME_CANDIDATES` in `braggtrack/io/nexus.py` (or rely on the built-in largest-3D numeric dataset discovery) and extend `extract_axis_calibration` if custom motor metadata groups are used. +2. **New segmentation method** — implement alongside `segment_classical` / `segment_dino` returning `ClassicalSegmentationResult`, then feed `(labels, volume, calibration=...)` to `extract_instance_table`. +3. **New association cost** — implement `pairwise_cost_matrix` + scalar `__call__` matching `CostFunction` in `braggtrack/tracking/cost.py`. +4. **Custom precursor signals** — extend `compute_fracture_precursors` in `braggtrack/tracking/precursors.py` to incorporate additional morphological or diffraction rocking-curve descriptors while retaining contiguous `min_persistence` filtering. ## Performance notes -- Assignment builds a dense `(N, M)` cost matrix via **vectorised** geometry (`scipy.spatial.distance.cdist`) and, when enabled, **one GEMM** for cosine similarity (`A @ B.T`). Avoid reintroducing per-pair Python loops on hot paths. +- 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. ## Configuration surfaces -- **Env:** `BRAGGTRACK_DINO_BACKEND` (`auto` | `mock` | `torch`) for embeddings. -- **Paths:** `braggtrack.io.paths.sample_operando_root()` and `resolve_dataset_root()` for bundled vs explicit dataset roots. +- **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. diff --git a/notebooks/braggtrack_demo.ipynb b/notebooks/braggtrack_demo.ipynb index 6aeb29c..ef8edac 100644 --- a/notebooks/braggtrack_demo.ipynb +++ b/notebooks/braggtrack_demo.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "id": "e65e834e", "metadata": {}, - "source": "# BraggTrack end-to-end demo\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BASE-Laboratory/BraggTrack/blob/main/notebooks/braggtrack_demo.ipynb)\n\nRuns the full pipeline on the bundled `data/sample_operando/` scans:\n\n1. **Discover** — find the per-scan H5 files.\n2. **Segment** — LoG → h-maxima → seeded watershed → instance features.\n3. **Track (physics-only)** — Hungarian over a geometry cost with per-axis gating; build a lifecycle DAG.\n4. **Semantic descriptors** — orthogonal MIPs + frozen-encoder embeddings.\n5. **Geometry + semantic tracking** — compose `α · geometry + β · (1 − cos)`.\n6. **α/β ablation** — how the semantic weight shifts tracking metrics.\n7. **Synthetic crossing** — a case where geometry alone fails and semantics recover identity.\n\nFinal section shows the one-line CLI equivalents for each stage.\n\nThis notebook uses the **mock** DINO backend by default, so no PyTorch / HuggingFace weights are required. Set `BRAGGTRACK_DINO_BACKEND=torch` if you have them installed and want real embeddings." + "source": "# BraggTrack end-to-end demo\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BASE-Laboratory/BraggTrack/blob/main/notebooks/braggtrack_demo.ipynb)\n\nRuns the full BraggTrack v0.2 pipeline on the bundled `data/sample_operando/` ESRF-ID03 scans:\n\n1. **Discover & load** — find per-scan NeXus/HDF5 files and auto-discover 3D detector cubes (`load_primary_volume`).\n2. **Segment** — cross-scan smoothed Otsu → 3D LoG → h-maxima → seeded watershed → instance features.\n3. **Track (physics-only)** — Hungarian association over geometry cost with per-axis gating; build a lifecycle DAG.\n4. **Semantic descriptors** — orthogonal $(\\mu, \\chi, d)$ MIPs + frozen vision-transformer embeddings.\n5. **Geometry + semantic tracking** — compose $\\alpha \\cdot C_{\\text{geo}} + \\beta \\cdot (1 - \\cos)$.\n6. **$\\alpha / \\beta$ ablation** — sweep semantic weight across tracking metrics.\n7. **Near-overlap disambiguation** — synthetic crossing where semantics prevent an ID swap.\n8. **Per-grain kinematics, split/merge lineage & fracture precursors** — calibrated strain $\\Delta d / d_0$, `1 -> 2` grain cleavage, `2 -> 1` coalescence, and persistent precursor ranking.\n9. **Command-line & one-command pipeline (`braggtrack-run`)** — reproducible CLI equivalents.\n\nThis notebook uses the **mock** DINO backend by default so zero PyTorch / GPU weights are needed in CI. Set `BRAGGTRACK_DINO_BACKEND=torch` (with `pip install -e '.[torch]'`) to use ungated `facebook/dinov2-small`." }, { "cell_type": "markdown", @@ -41,7 +41,7 @@ } }, "outputs": [], - "source": "%matplotlib inline\nimport copy\nfrom pathlib import Path\n\nimport h5py\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport pandas as pd\nfrom matplotlib.colors import ListedColormap\n\nfrom braggtrack.io import discover_operando_scans, sample_operando_root\nfrom braggtrack.segmentation import (\n extract_instance_table,\n fill_holes_binary,\n flag_outlier_frames,\n label_projection_by_intensity,\n merge_nearby_labels,\n otsu_floor_from_mip,\n otsu_threshold,\n relabel_sequential,\n remove_small_objects,\n segment_classical,\n smooth_thresholds,\n)\nfrom braggtrack.semantic import crop_spot_cube, make_multiview_encoder, orthogonal_mips\nfrom braggtrack.tracking import (\n GeometrySemanticCost,\n PositionShapeCost,\n TrackEvent,\n build_tracks,\n compute_tracking_metrics,\n tracks_to_table,\n)" + "source": "%matplotlib inline\nimport copy\nfrom pathlib import Path\n\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport pandas as pd\nfrom matplotlib.colors import ListedColormap\n\nfrom braggtrack.io import (\n AxisCalibration,\n discover_operando_scans,\n discover_primary_volume_path,\n load_primary_volume,\n sample_operando_root,\n)\nfrom braggtrack.segmentation import (\n extract_instance_table,\n fill_holes_binary,\n flag_outlier_frames,\n label_projection_by_intensity,\n merge_nearby_labels,\n otsu_floor_from_mip,\n otsu_threshold,\n relabel_sequential,\n remove_small_objects,\n segment_classical,\n smooth_thresholds,\n)\nfrom braggtrack.semantic import (\n crop_spot_cube,\n make_multiview_encoder,\n make_patch_encoder,\n orthogonal_mips,\n)\nfrom braggtrack.tracking import (\n GeometrySemanticCost,\n PositionShapeCost,\n PrecursorConfig,\n SplitMergeConfig,\n TrackEvent,\n build_tracks,\n compute_fracture_precursors,\n compute_grain_kinematics,\n compute_tracking_metrics,\n events_to_table,\n generate_fracture_scenario,\n kinematics_to_table,\n precursors_to_table,\n tracks_to_table,\n)" }, { "cell_type": "markdown", @@ -76,13 +76,7 @@ "cell_type": "markdown", "id": "d901865b", "metadata": {}, - "source": [ - "### A note on the H5 layout\n", - "\n", - "`braggtrack.io.load_primary_volume` currently tries a fixed shortlist of NeXus paths (`/entry/data/data`, `/entry1/data/data`, …). The bundled ESRF-ID03 files store their 3-D detector stack at `entry_0000/ESRF-ID03/pco_nf/data`, which isn't in that list. The CLI falls back to `_synth_volume_from_file` (deterministic Gaussian blobs) when this happens, which is why the CI acceptance runs on synthetic data.\n", - "\n", - "For the demo we reach into the H5 directly so we see the **real** data. A tiny follow-up would be to add an auto-discovery step (pick the largest 3-D numeric dataset) to `load_primary_volume`." - ] + "source": "### Automatic NeXus / ESRF-ID03 HDF5 volume discovery\n\n`load_primary_volume` inspects canonical NeXus paths, ESRF-ID03 LIMA detector paths (`/entry_0000/ESRF-ID03/pco_nf/data`), and falls back to the largest 3-D numeric dataset in any HDF5 file." }, { "cell_type": "code", @@ -97,7 +91,7 @@ } }, "outputs": [], - "source": "def load_3d_volume(h5_path: Path) -> np.ndarray:\n \"\"\"Pick the largest 3-D numeric dataset in an H5 file.\"\"\"\n candidates: list[tuple[str, tuple[int, ...]]] = []\n with h5py.File(h5_path, \"r\") as f:\n def _visit(name, obj):\n if isinstance(obj, h5py.Dataset) and obj.ndim == 3 and np.issubdtype(obj.dtype, np.number):\n candidates.append((name, obj.shape))\n f.visititems(_visit)\n if not candidates:\n raise KeyError(f\"No 3D numeric dataset in {h5_path}\")\n name = max(candidates, key=lambda t: int(np.prod(t[1])))[0]\n return np.asarray(f[name][...], dtype=np.float64)\n\n# Quick peek at the first scan.\n_peek = load_3d_volume(scans[0].path)\nprint(f\"{scans[0].scan_name}: shape={_peek.shape} dtype={_peek.dtype} intensity [{_peek.min():.0f}, {_peek.max():.0f}]\")\ndel _peek" + "source": "ds_path = discover_primary_volume_path(scans[0].path)\n_peek = load_primary_volume(scans[0].path)\nprint(f\"{scans[0].scan_name}: dataset={ds_path} shape={_peek.shape} intensity=[{_peek.min():.0f}, {_peek.max():.0f}]\")\ndel _peek" }, { "cell_type": "markdown", @@ -118,7 +112,7 @@ } }, "outputs": [], - "source": "MERGE_DISTANCE = 15 # merge adjacent labels whose centroids are within this many voxels\n\ndef segment(volume: np.ndarray, threshold: float) -> np.ndarray:\n \"\"\"Segment a single volume using a pre-computed (smoothed) threshold.\"\"\"\n res = segment_classical(\n volume,\n threshold=threshold,\n blur_passes=1,\n h_value=0.1,\n min_seed_separation=2,\n seed_peak_fraction=0.2,\n seed_response_percentile=99.95,\n )\n labels = remove_small_objects(res.labeled_volume, min_size=8)\n binary = fill_holes_binary(labels > 0)\n labels = np.where(binary, labels, 0)\n labels = merge_nearby_labels(labels, volume, max_centroid_distance=MERGE_DISTANCE)\n labels = relabel_sequential(labels)\n return labels\n\n# --- Load all volumes and compute smoothed thresholds ---\nall_volumes: list[np.ndarray] = []\nraw_thresholds: list[float] = []\nfor s in scans:\n v = load_3d_volume(s.path)\n all_volumes.append(v)\n raw_thresholds.append(otsu_threshold(v.ravel()))\n\nsmoothed = smooth_thresholds(raw_thresholds, window=5)\noutliers = flag_outlier_frames(raw_thresholds, window=5)\n\nprint(\"Per-frame Otsu thresholds vs smoothed:\")\nfor s, raw_t, sm_t, is_out in zip(scans, raw_thresholds, smoothed, outliers):\n tag = \" ** OUTLIER **\" if is_out else \"\"\n print(f\" {s.scan_name}: raw={raw_t:.1f} smoothed={sm_t:.1f}{tag}\")\n\n# Segment the first volume for the single-scan QC plots below.\nvol0 = all_volumes[0]\nlabels0 = segment(vol0, threshold=float(smoothed[0]))\nprint(f\"\\nscan0001: smoothed threshold={smoothed[0]:.1f}, {int(labels0.max())} instances\")" + "source": "MERGE_DISTANCE = 15 # merge adjacent labels whose centroids are within this many voxels\n\ndef segment(volume: np.ndarray, threshold: float) -> np.ndarray:\n \"\"\"Segment a single volume using a pre-computed (smoothed) threshold.\"\"\"\n res = segment_classical(\n volume,\n threshold=threshold,\n blur_passes=1,\n h_value=0.1,\n min_seed_separation=2,\n seed_peak_fraction=0.2,\n seed_response_percentile=99.95,\n )\n labels = remove_small_objects(res.labeled_volume, min_size=8)\n binary = fill_holes_binary(labels > 0)\n labels = np.where(binary, labels, 0)\n labels = merge_nearby_labels(labels, volume, max_centroid_distance=MERGE_DISTANCE)\n labels = relabel_sequential(labels)\n return labels\n\n# --- Load all volumes and compute smoothed thresholds ---\nall_volumes: list[np.ndarray] = []\nraw_thresholds: list[float] = []\nfor s in scans:\n v = load_primary_volume(s.path)\n all_volumes.append(v)\n raw_thresholds.append(otsu_threshold(v.ravel()))\n\nsmoothed = smooth_thresholds(raw_thresholds, window=5)\noutliers = flag_outlier_frames(raw_thresholds, window=5)\n\nprint(\"Per-frame Otsu thresholds vs smoothed:\")\nfor s, raw_t, sm_t, is_out in zip(scans, raw_thresholds, smoothed, outliers):\n tag = \" ** OUTLIER **\" if is_out else \"\"\n print(f\" {s.scan_name}: raw={raw_t:.1f} smoothed={sm_t:.1f}{tag}\")\n\n# Segment the first volume for the single-scan QC plots below.\nvol0 = all_volumes[0]\nlabels0 = segment(vol0, threshold=float(smoothed[0]))\nprint(f\"\\nscan0001: smoothed threshold={smoothed[0]:.1f}, {int(labels0.max())} instances\")" }, { "cell_type": "code", @@ -712,11 +706,33 @@ "plt.show()" ] }, + { + "cell_type": "markdown", + "id": "b720f001", + "metadata": {}, + "source": "## 8 — Per-grain kinematics, split/merge lineage & fracture precursors\n\nFrom any tracked trajectory table, `compute_grain_kinematics` extracts time-series strain $\\varepsilon(t) = (d(t) - d_0) / d_0$, rocking/azimuthal misorientation $(\\Delta\\mu, \\Delta\\chi)$, relative intensity/volume evolution, and 3-D shape anisotropy ($\\lambda_1 / \\lambda_3$). Supplying an `AxisCalibration` converts detector indices into physical degrees and Angstroms.\n\nTo evaluate chemomechanical particle cracking and sub-domain coalescence, we also run BraggTrack's 4D fracture solver (`SplitMergeConfig` + `compute_fracture_precursors`) on `generate_fracture_scenario`, which embeds:\n- **Grain A (fracturing):** bimodal intra-spot broadening across scans `0..1` followed by a `1 -> 2` split at scan `2` with diverging daughter strains.\n- **Grain B (coalescing):** two sub-domains merging (`2 -> 1`) at scan `2`.\n- **Grain C (control):** a stable isotropic grain across all scans." + }, + { + "cell_type": "code", + "id": "b720f002", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "# 8a. Per-grain kinematics on the bundled ESRF-ID03 tracks\ngk_operando = compute_grain_kinematics(tracks_to_table(G_geo))\nkin_df = pd.DataFrame(kinematics_to_table(gk_operando, include_delta_d=True))\nprint(f\"Computed kinematics for {len(gk_operando)} tracks ({len(kin_df)} observations)\")\nkin_df.head(6)[[\"track_id\", \"scan_idx\", \"centroid_d\", \"delta_d\", \"strain\", \"misorientation_total\", \"anisotropy\"]]" + }, + { + "cell_type": "code", + "id": "b720f003", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "# 8b. 4D split/merge lineage + persistent fracture precursor ranking\nf_vols, f_labels, f_tables, f_expected = generate_fracture_scenario(n_scans=5, seed=42)\nG_frac = build_tracks(\n f_tables,\n cost_fn=PositionShapeCost(),\n split_merge_config=SplitMergeConfig(max_distance=20.0),\n)\nlineage_events = G_frac.graph[\"lineage_events\"]\nfrac_rows = tracks_to_table(G_frac)\ncandidates, obs_scores = compute_fracture_precursors(\n frac_rows,\n PrecursorConfig(score_threshold=0.35, min_persistence=2),\n volumes=f_vols,\n label_volumes=f_labels,\n patch_encoder=make_patch_encoder(\"mock\"),\n lineage_events=lineage_events,\n)\n\nprint(\"=== Detected Lineage Events (splits & merges) ===\")\nprint(pd.DataFrame(events_to_table(lineage_events))[[\n \"event_id\", \"event_type\", \"scan_idx_from\", \"scan_idx_to\",\n \"parent_track_ids\", \"child_track_ids\", \"intensity_ratio\", \"confidence\"\n]].to_string(index=False))\n\nprint(\"\\n=== Persistent Fracture Precursor Ranking ===\")\nprint(pd.DataFrame(precursors_to_table(candidates)).to_string(index=False))" + }, { "cell_type": "markdown", "id": "7e605de2", "metadata": {}, - "source": "## 8 — The same pipeline from the command line\n\nEvery library call above is exposed as a CLI — feed a dataset root and an output directory, get reproducible artifacts under `artifacts/`.\n\n```bash\n# 1. Segment every scan under data/sample_operando/\npython -m braggtrack.cli.segment_dataset --outdir artifacts/segmentation\n\n# 2. Compute mock multi-view embeddings\npython -m braggtrack.cli.embed_dataset --segdir artifacts/segmentation --outdir artifacts/embedding --backend mock\n\n# 3. Track with geometry + semantic cost (β=0.5)\npython -m braggtrack.cli.track_dataset artifacts/segmentation \\\n --outdir artifacts/tracking \\\n --embedding-dir artifacts/embedding \\\n --cost-alpha 1.0 --cost-beta 0.5\n\n# 4. Ablate α/β and write a JSON report\npython scripts/ablation_semantic.py \\\n --indir artifacts/segmentation \\\n --embedding-dir artifacts/embedding \\\n --betas 0,0.25,0.5,1.0 \\\n --output artifacts/ablation/report.json\n\n# 5. Full CI-equivalent check (unit tests + all acceptance gates)\npython scripts/ci_report.py\n```" + "source": "## 9 — Reproducible command-line pipeline (`braggtrack-run`)\n\nEvery stage above is available via CLI entry points — or as a single end-to-end command (`braggtrack-run`) that validates inputs, segments with cross-scan threshold smoothing, embeds MIPs, tracks kinematics, resolves splits/merges & fracture precursors, and writes `run_manifest.json` with SHA-256 input checksums:\n\n```bash\n# One-command end-to-end pipeline\nbraggtrack-run --outdir artifacts/pipeline\n\n# Or stage-by-stage:\nbraggtrack-segment-dataset --outdir artifacts/segmentation\nbraggtrack-embed-dataset --segdir artifacts/segmentation --outdir artifacts/embedding --backend auto\nbraggtrack-track-dataset artifacts/segmentation \\\n --outdir artifacts/tracking \\\n --embedding-dir artifacts/embedding \\\n --cost-alpha 1.0 --cost-beta 0.25 --detect-events\nbraggtrack-events --segdir artifacts/segmentation --outdir artifacts/events\n\n# Semantic alpha/beta ablation with 95% bootstrap confidence intervals\npython scripts/ablation_semantic.py \\\n --indir artifacts/segmentation \\\n --embedding-dir artifacts/embedding \\\n --betas 0,0.25,0.5,1.0 --bootstrap-samples 100 \\\n --output artifacts/ablation/report.json\n\n# Full CI suite (unit tests + all 7 acceptance gates)\npython scripts/ci_report.py\n```" } ], "metadata": { @@ -740,4 +756,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} diff --git a/notebooks/dino_segmentation_comparison.ipynb b/notebooks/dino_segmentation_comparison.ipynb index b46334e..f3f1feb 100644 --- a/notebooks/dino_segmentation_comparison.ipynb +++ b/notebooks/dino_segmentation_comparison.ipynb @@ -3,7 +3,7 @@ { "cell_type": "markdown", "id": "ddb2fb4c", - "source": "# DINO vs Classical Segmentation Comparison\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BASE-Laboratory/BraggTrack/blob/main/notebooks/dino_segmentation_comparison.ipynb)\n\nThis notebook runs both segmentation backends on the bundled `data/sample_operando/` scans and compares their outputs side-by-side.\n\n| Method | How it works | Strengths |\n|--------|-------------|-----------|\n| **Classical** | Otsu threshold → LoG enhancement → h-maxima seeds → seeded watershed → merge nearby | Fast, interpretable, well-tuned for this beamline |\n| **DINOv3** | Frozen DINOv3 ViT-B/16 patch features → PCA → HDBSCAN clustering → 3D slice stitching → Otsu foreground mask | Learns in feature space — should generalise across beamlines/detectors without re-tuning |\n\nOn **Colab** (GPU + internet) this notebook uses real DINOv3 weights (`facebook/dinov3-vitb16-pretrain-lvd1689m`). Locally without PyTorch it falls back to the mock backend automatically.", + "source": "# DINO vs Classical Segmentation Comparison\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BASE-Laboratory/BraggTrack/blob/main/notebooks/dino_segmentation_comparison.ipynb)\n\nThis notebook runs both segmentation backends on the bundled `data/sample_operando/` ESRF-ID03 scans and compares their outputs side-by-side.\n\n| Method | How it works | Strengths |\n|--------|-------------|-----------|\n| **Classical** | Smoothed Otsu threshold → 3D LoG enhancement → h-maxima seeds → seeded watershed → merge nearby | Fast, physically interpretable, primary spot finder in BraggTrack |\n| **DINO (experimental)** | Frozen DINOv2 (`facebook/dinov2-small`) patch features → PCA → HDBSCAN clustering → 3D slice stitching → Otsu foreground mask | Dense semantic patch features; also supports optional gated DINOv3 (`facebook/dinov3-vitb16-pretrain-lvd1689m`) |\n\nOn **Colab** (or locally with `pip install -e '.[torch]'`) this notebook uses real **ungated DINOv2** weights (`facebook/dinov2-small`) with zero HuggingFace login required. Without PyTorch it falls back to the deterministic mock backend automatically.", "metadata": {} }, { @@ -15,7 +15,7 @@ { "cell_type": "code", "id": "320c0082", - "source": "import os, subprocess, sys\n\n_ON_COLAB = \"google.colab\" in sys.modules or os.environ.get(\"COLAB_RELEASE_TAG\")\n\nif _ON_COLAB:\n print(\"Colab detected — installing BraggTrack + dependencies...\")\n subprocess.check_call([\n sys.executable, \"-m\", \"pip\", \"install\", \"-q\",\n \"braggtrack[notebook] @ git+https://github.com/BASE-Laboratory/BraggTrack.git\",\n ])\n subprocess.check_call([\n sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"torch\", \"torchvision\", \"transformers\",\n ])\n # DINOv3 is a gated model — you must accept the license at\n # https://huggingface.co/facebook/dinov3-vitb16-pretrain-lvd1689m\n # then paste your HF token when prompted.\n from huggingface_hub import login\n login()\n\n if not os.path.isdir(\"data/sample_operando\"):\n subprocess.check_call([\n \"git\", \"clone\", \"--depth=1\", \"--filter=blob:none\", \"--sparse\",\n \"https://github.com/BASE-Laboratory/BraggTrack.git\", \"_braggtrack_repo\",\n ])\n subprocess.check_call(\n [\"git\", \"sparse-checkout\", \"set\", \"data/sample_operando\"],\n cwd=\"_braggtrack_repo\",\n )\n os.makedirs(\"data\", exist_ok=True)\n os.rename(\"_braggtrack_repo/data/sample_operando\", \"data/sample_operando\")\n subprocess.check_call([\"rm\", \"-rf\", \"_braggtrack_repo\"])\n os.environ.setdefault(\"BRAGGTRACK_DATA_ROOT\", os.path.abspath(\"data/sample_operando\"))\n print(\"Done.\")\nelse:\n print(\"Local environment — skipping Colab setup.\")", + "source": "import os, subprocess, sys\n\n_ON_COLAB = \"google.colab\" in sys.modules or os.environ.get(\"COLAB_RELEASE_TAG\")\n\nif _ON_COLAB:\n print(\"Colab detected — installing BraggTrack + dependencies...\")\n subprocess.check_call([\n sys.executable, \"-m\", \"pip\", \"install\", \"-q\",\n \"braggtrack[torch,notebook] @ git+https://github.com/BASE-Laboratory/BraggTrack.git\",\n ])\n # Optional: only required if you override model_name to gated DINOv3\n # (\"facebook/dinov3-vitb16-pretrain-lvd1689m\"):\n # from huggingface_hub import login; login()\n\n if not os.path.isdir(\"data/sample_operando\"):\n subprocess.check_call([\n \"git\", \"clone\", \"--depth=1\", \"--filter=blob:none\", \"--sparse\",\n \"https://github.com/BASE-Laboratory/BraggTrack.git\", \"_braggtrack_repo\",\n ])\n subprocess.check_call(\n [\"git\", \"sparse-checkout\", \"set\", \"data/sample_operando\"],\n cwd=\"_braggtrack_repo\",\n )\n os.makedirs(\"data\", exist_ok=True)\n os.rename(\"_braggtrack_repo/data/sample_operando\", \"data/sample_operando\")\n subprocess.check_call([\"rm\", \"-rf\", \"_braggtrack_repo\"])\n os.environ.setdefault(\"BRAGGTRACK_DATA_ROOT\", os.path.abspath(\"data/sample_operando\"))\n print(\"Done.\")\nelse:\n print(\"Local environment — skipping Colab setup.\")", "metadata": {}, "execution_count": null, "outputs": [] @@ -23,7 +23,7 @@ { "cell_type": "code", "id": "9f1e4a10", - "source": "%matplotlib inline\nfrom pathlib import Path\n\nimport h5py\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport pandas as pd\nfrom matplotlib.colors import ListedColormap\n\nfrom braggtrack.io import discover_operando_scans, sample_operando_root\nfrom braggtrack.segmentation import (\n extract_instance_table,\n fill_holes_binary,\n label_projection_by_intensity,\n merge_nearby_labels,\n otsu_floor_from_mip,\n otsu_threshold,\n relabel_sequential,\n remove_small_objects,\n segment_classical,\n segment_dino,\n smooth_thresholds,\n)", + "source": "%matplotlib inline\nfrom pathlib import Path\n\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport pandas as pd\nfrom matplotlib.colors import ListedColormap\n\nfrom braggtrack.io import discover_operando_scans, load_primary_volume, sample_operando_root\nfrom braggtrack.segmentation import (\n extract_instance_table,\n fill_holes_binary,\n label_projection_by_intensity,\n merge_nearby_labels,\n otsu_floor_from_mip,\n otsu_threshold,\n relabel_sequential,\n remove_small_objects,\n segment_classical,\n segment_dino,\n smooth_thresholds,\n)", "metadata": {}, "execution_count": null, "outputs": [] @@ -31,13 +31,13 @@ { "cell_type": "markdown", "id": "12606936", - "source": "## 1 — Load real data\n\nRead the largest 3D numeric dataset from each H5 file (bypasses the fixed NeXus path shortlist).", + "source": "## 1 — Load real ESRF-ID03 data\n\n`load_primary_volume` automatically discovers `/entry_0000/ESRF-ID03/pco_nf/data` (and falls back to the largest 3D numeric dataset for arbitrary HDF5 layouts).", "metadata": {} }, { "cell_type": "code", "id": "379a76d7", - "source": "def load_3d_volume(h5_path: Path) -> np.ndarray:\n \"\"\"Pick the largest 3-D numeric dataset in an H5 file.\"\"\"\n candidates: list[tuple[str, tuple[int, ...]]] = []\n with h5py.File(h5_path, \"r\") as f:\n def _visit(name, obj):\n if isinstance(obj, h5py.Dataset) and obj.ndim == 3 and np.issubdtype(obj.dtype, np.number):\n candidates.append((name, obj.shape))\n f.visititems(_visit)\n if not candidates:\n raise KeyError(f\"No 3D numeric dataset in {h5_path}\")\n name = max(candidates, key=lambda t: int(np.prod(t[1])))[0]\n return np.asarray(f[name][...], dtype=np.float64)\n\nscans = discover_operando_scans(sample_operando_root())\nall_volumes = [load_3d_volume(s.path) for s in scans]\n\nfor s, v in zip(scans, all_volumes):\n print(f\"{s.scan_name}: shape={v.shape} intensity=[{v.min():.0f}, {v.max():.0f}]\")", + "source": "scans = discover_operando_scans(sample_operando_root())\nall_volumes = [load_primary_volume(s.path) for s in scans]\n\nfor s, v in zip(scans, all_volumes):\n print(f\"{s.scan_name}: shape={v.shape} intensity=[{v.min():.0f}, {v.max():.0f}]\")", "metadata": {}, "execution_count": null, "outputs": [] @@ -59,7 +59,7 @@ { "cell_type": "markdown", "id": "a5cfd4e0", - "source": "### DINOv3 pipeline\nFrozen DINOv3 ViT-B/16 patch features → global PCA → HDBSCAN → upsample → 3D stitch → Otsu foreground mask → post-process.\n\n`backend=\"auto\"` uses real DINOv3 weights when PyTorch is available (e.g. Colab), otherwise falls back to the mock backend for CI. The post-processing (remove small, fill holes, merge nearby, relabel) is identical to keep the comparison fair.", + "source": "### DINO patch-clustering pipeline\nFrozen DINOv2 (`facebook/dinov2-small`) patch features → global PCA → HDBSCAN → upsample → 3D stitch → Otsu foreground mask → post-process.\n\n`backend=\"auto\"` uses real DINOv2 weights when PyTorch is available (e.g. Colab), otherwise falls back to the mock backend for CI. Pass `model_name=\"facebook/dinov3-vitb16-pretrain-lvd1689m\"` if you have a HuggingFace token with DINOv3 access.", "metadata": {} }, { @@ -87,7 +87,7 @@ { "cell_type": "code", "id": "1de56eb0", - "source": "x = np.arange(len(scans))\nwidth = 0.35\n\nfig, ax = plt.subplots(figsize=(8, 4))\nbars1 = ax.bar(x - width / 2, classical_counts, width, label=\"Classical\", color=\"#1f77b4\")\nbars2 = ax.bar(x + width / 2, dino_counts, width, label=f\"DINOv3 ({DINO_BACKEND})\", color=\"#ff7f0e\")\nax.set_xlabel(\"Scan\")\nax.set_ylabel(\"Spot count\")\nax.set_title(\"Spot counts: Classical vs DINOv3\")\nax.set_xticks(x)\nax.set_xticklabels(scan_names)\nax.legend()\n\nfor bars in [bars1, bars2]:\n for bar in bars:\n ax.text(bar.get_x() + bar.get_width() / 2, bar.get_height() + 0.3,\n str(int(bar.get_height())), ha=\"center\", va=\"bottom\", fontsize=10)\n\nplt.tight_layout()\nplt.show()", + "source": "x = np.arange(len(scans))\nwidth = 0.35\n\nfig, ax = plt.subplots(figsize=(8, 4))\nbars1 = ax.bar(x - width / 2, classical_counts, width, label=\"Classical\", color=\"#1f77b4\")\nbars2 = ax.bar(x + width / 2, dino_counts, width, label=f\"DINO ({DINO_BACKEND})\", color=\"#ff7f0e\")\nax.set_xlabel(\"Scan\")\nax.set_ylabel(\"Spot count\")\nax.set_title(\"Spot counts: Classical vs DINO\")\nax.set_xticks(x)\nax.set_xticklabels(scan_names)\nax.legend()\n\nfor bars in [bars1, bars2]:\n for bar in bars:\n ax.text(bar.get_x() + bar.get_width() / 2, bar.get_height() + 0.3,\n str(int(bar.get_height())), ha=\"center\", va=\"bottom\", fontsize=10)\n\nplt.tight_layout()\nplt.show()", "metadata": {}, "execution_count": null, "outputs": [] @@ -165,7 +165,7 @@ { "cell_type": "code", "id": "82ec00b3", - "source": "c_arr = np.array(classical_counts, dtype=float)\nd_arr = np.array(dino_counts, dtype=float)\n\nc_cv = c_arr.std() / c_arr.mean() if c_arr.mean() > 0 else 0\nd_cv = d_arr.std() / d_arr.mean() if d_arr.mean() > 0 else 0\n\nconsistency = pd.DataFrame({\n \"Method\": [\"Classical\", f\"DINOv3 ({DINO_BACKEND})\"],\n \"Mean spots\": [c_arr.mean(), d_arr.mean()],\n \"Std spots\": [c_arr.std(), d_arr.std()],\n \"CV (std/mean)\": [c_cv, d_cv],\n \"Spread (max-min)\": [c_arr.max() - c_arr.min(), d_arr.max() - d_arr.min()],\n})\nprint(consistency.to_string(index=False))", + "source": "c_arr = np.array(classical_counts, dtype=float)\nd_arr = np.array(dino_counts, dtype=float)\n\nc_cv = c_arr.std() / c_arr.mean() if c_arr.mean() > 0 else 0\nd_cv = d_arr.std() / d_arr.mean() if d_arr.mean() > 0 else 0\n\nconsistency = pd.DataFrame({\n \"Method\": [\"Classical\", f\"DINO ({DINO_BACKEND})\"],\n \"Mean spots\": [c_arr.mean(), d_arr.mean()],\n \"Std spots\": [c_arr.std(), d_arr.std()],\n \"CV (std/mean)\": [c_cv, d_cv],\n \"Spread (max-min)\": [c_arr.max() - c_arr.min(), d_arr.max() - d_arr.min()],\n})\nprint(consistency.to_string(index=False))", "metadata": {}, "execution_count": null, "outputs": [] @@ -187,7 +187,7 @@ { "cell_type": "markdown", "id": "a64fefce", - "source": "## 10 — Notes\n\n**Backend selection:** This notebook uses `backend=\"auto\"` — on Colab (or any environment with PyTorch + `transformers`) it loads the real **DINOv3 ViT-B/16** weights (`facebook/dinov3-vitb16-pretrain-lvd1689m`, 86M params). Without PyTorch it falls back to a deterministic mock for CI.\n\n**DINOv3** ([arXiv 2508.10104](https://arxiv.org/abs/2508.10104)) is a family of vision foundation models from Meta AI that produce high-quality dense patch features without fine-tuning. The frozen patch tokens are clustered per-slice via HDBSCAN using a shared PCA space across all slices, then stitched into 3D labels.\n\n**Gated model:** DINOv3 requires accepting a license on HuggingFace before weights can be downloaded. The setup cell handles the login prompt on Colab.\n\n**CLI equivalent:**\n```bash\n# Classical\npython -m braggtrack.cli.segment_dataset --method classical --outdir artifacts/classical\n\n# DINOv3 (real weights — requires torch + transformers + HF token)\npython -m braggtrack.cli.segment_dataset --method dino --dino-backend torch --outdir artifacts/dino\n\n# DINOv3 (mock — for CI / no GPU)\npython -m braggtrack.cli.segment_dataset --method dino --dino-backend mock --outdir artifacts/dino_mock\n```", + "source": "## 10 — Notes\n\n**Backend selection:** `backend=\"auto\"` loads ungated **DINOv2 ViT-S/14** (`facebook/dinov2-small`) when PyTorch + `transformers` are installed, requiring zero HuggingFace authentication. Without PyTorch it falls back to a deterministic mock backend.\n\n**Optional DINOv3 support:** Pass `--dino-model facebook/dinov3-vitb16-pretrain-lvd1689m` (or `model_name=...` in Python) after accepting Meta's license on HuggingFace.\n\n**CLI equivalents:**\n```bash\n# Classical (default)\nbraggtrack-segment-dataset --method classical --outdir artifacts/classical\n\n# DINOv2 (real weights, ungated)\nbraggtrack-segment-dataset --method dino --dino-backend torch --outdir artifacts/dino\n\n# DINOv3 (optional gated model — requires HF_TOKEN)\nbraggtrack-segment-dataset --method dino --dino-backend torch \\\n --dino-model facebook/dinov3-vitb16-pretrain-lvd1689m --outdir artifacts/dinov3\n```", "metadata": {} } ], @@ -204,4 +204,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} diff --git a/paper.md b/paper.md index ccf2fae..d59b023 100644 --- a/paper.md +++ b/paper.md @@ -6,6 +6,7 @@ tags: - operando crystallography - 3D segmentation - object tracking + - grain fracture - materials science authors: - name: James Le Houx @@ -21,130 +22,132 @@ bibliography: paper.bib # Summary -BraggTrack is a Python library for automated detection, segmentation, and -tracking of Bragg diffraction spots across sequential operando X-ray -diffraction (XRD) volumes. Given a time series of three-dimensional -reciprocal-space intensity cubes acquired during *in situ* or *operando* -experiments, BraggTrack segments individual Bragg reflections, extracts -geometric and semantic features, and links observations across scans into -persistent tracks with lifecycle annotations (birth, continuation, -termination). The library combines classical image-processing techniques — -Laplacian-of-Gaussian (LoG) enhancement, h-maxima seed detection, and seeded -watershed segmentation — with modern self-supervised vision-transformer -embeddings that provide shape-aware identity descriptors for robust -cross-frame association. BraggTrack is designed for synchrotron beamline data -in NeXus/HDF5 format and ships with bundled sample data from the ESRF ID03 -beamline, a command-line interface for batch processing, and an interactive -Jupyter notebook that runs on Google Colab without local installation. +BraggTrack is a Python library for automated 3D segmentation, semantic tracking, +kinematic strain extraction, and chemomechanical fracture detection across +sequential operando X-ray diffraction (XRD) volumes. Given a time series of +three-dimensional reciprocal-space or near-field diffraction cubes acquired +during *in situ* or *operando* experiments, BraggTrack segments individual +Bragg reflections, extracts calibrated geometric and foundation vision features, +and links observations across scans into a directed acyclic trajectory graph +capturing births, continuations, terminations, `1 -> 2+` grain fracture splits, +and `2+ -> 1` coalescence merges. In addition, BraggTrack ranks persistent +pre-fracture precursor candidates across scans by combining 3D reflection +anisotropy, covariance broadening, internal sub-peak bimodality, and frozen +vision-transformer patch-token dispersion. Designed for synchrotron NeXus/HDF5 +data, BraggTrack ships with bundled operando scans from ESRF beamline ID03, +eight CLI entry points including a single-command reproducible pipeline runner +(`braggtrack-run`), and interactive Jupyter notebooks runnable on Google Colab. # Statement of Need Operando diffraction experiments at modern synchrotron sources generate -thousands of three-dimensional reciprocal-space volumes at sub-second -cadence, each containing tens to hundreds of Bragg reflections whose -positions, intensities, and shapes evolve as the sample undergoes -electrochemical cycling, mechanical loading, or thermal treatment -[@Simons2015; @Hayashi2019]. Extracting quantitative kinematics — tracking -which reflection belongs to which crystallographic grain across time, and -detecting when grains nucleate, fragment, or disappear — is a prerequisite -for understanding microstructural evolution during battery operation -[@Finegan2019], additive manufacturing [@Leung2018], or fatigue testing. - -Existing workflows rely on manual inspection, commercial peak-fitting -packages that treat each frame independently, or bespoke scripts written per -experiment [@Schmidt2014; @Poulsen2004]. These approaches do not scale to -the data rates of fourth-generation synchrotron sources, lack temporal -coherence, and are difficult to reproduce. Three-dimensional X-ray -diffraction (3DXRD) grain-tracking tools such as those built on -ImageD11 [@Wright2023] and GrainSpotter [@Schmidt2014] focus on indexing -lattice orientations rather than tracking segmented intensity blobs through -time. There is no open-source, pip-installable library that performs both -segmentation and multi-frame tracking of Bragg spots with an extensible cost -function. - -BraggTrack fills this gap. It provides a reproducible pipeline from raw HDF5 -volumes to labelled tracks, with a modular architecture that separates -segmentation, feature extraction, cost-function design, and assignment into -independently testable layers. Researchers can swap in different segmentation -backends, plug in real or mock vision-transformer encoders, and tune the -geometry-versus-semantics tradeoff without modifying core tracking logic. +hundreds to thousands of three-dimensional diffraction volumes at sub-minute or +sub-second cadence, each containing tens to hundreds of Bragg reflections whose +positions, intensities, and 3D morphologies evolve during electrochemical +cycling, mechanical loading, or thermal treatment [@Simons2015; @Hayashi2019]. +In battery electrodes such as Ni-rich layered oxides, chemomechanical +degradation manifests first as anisotropic intragranular strain broadening and +sub-domain formation before culminating in particle microcracking — observable +in reciprocal space as reflection broadening followed by `1 -> 2+` peak +splitting [@Finegan2019]. Quantifying per-grain lattice strain +($\varepsilon = \Delta d / d_0$), lattice rotation ($\Delta\mu$, $\Delta\chi$), +and fracture lineage across long scan sequences is essential for linking local +crystallography to macroscopic failure, as well as for solidification and +additive manufacturing studies [@Leung2018]. + +Existing workflows rely on frame-by-frame peak fitting, bespoke experiment +scripts, or crystallographic indexing packages such as GrainSpotter +[@Schmidt2014], 3DXRD orientation mappers [@Poulsen2004], and ImageD11 +[@Wright2023] that focus on unit-cell orientation indexing rather than tracking +evolving, splitting, and broadening 3D intensity distributions through time. +Previously, researchers lacked an open-source, `pip`-installable toolkit +combining stabilised 3D spot segmentation, foundation-model visual descriptors, +calibrated per-grain kinematics, and explicit split/merge fracture lineage in a +reproducible software architecture. + +BraggTrack addresses this need by separating beamline HDF5 ingestion and axis +calibration, 3D instance segmentation, multi-view vision-transformer encoding, +Hungarian and topological lineage tracking, and fracture precursor scoring into +cleanly tested, modular layers. # Implementation -## Segmentation - -BraggTrack's classical segmentation pipeline operates on each 3D intensity -volume independently: - -1. **Foreground thresholding.** An Otsu threshold [@Otsu1979] computed on - the raw intensity histogram defines the foreground mask. For multi-frame - sequences, per-frame thresholds are smoothed with a rolling median to - suppress sensitivity to transient beam drops or detector artefacts. - -2. **LoG enhancement.** The volume is convolved with a Gaussian kernel and - the negative discrete Laplacian is taken, producing a response map in - which Bragg peaks appear as local maxima [@Lindeberg1998]. - -3. **Seed detection.** H-maxima filtering [@Soille2003] on the LoG response - selects seed points that exceed both a fraction of a robust peak - reference (99.99th percentile, not the absolute maximum, to avoid - instability from single bright voxels) and a configurable response - percentile within the foreground. Non-maximum suppression enforces a - minimum separation between seeds. - -4. **Seeded watershed.** Seeds are grown into labelled regions via the - watershed transform [@Vincent1991] over the inverted LoG response, - restricted to the intensity-domain foreground mask. Post-processing - removes small components, fills holes, and relabels sequentially. - -This separation of intensity-domain thresholding from response-domain seed -detection avoids a common pitfall in which an Otsu threshold calibrated for -raw intensities is applied to the LoG response, whose dynamic range and -distribution are fundamentally different. - -## Feature extraction and semantic descriptors - -For each segmented instance, BraggTrack computes an intensity-weighted -centroid (in the $\mu$, $\chi$, $d$ reciprocal-space convention), a bounding -box, voxel count, integrated intensity, covariance tensor, and principal-axis -eigenvalues. These geometric features feed a `PositionShapeCost` function -that combines squared centroid distance with squared eigenvalue distance and -supports per-axis gating. - -Optionally, each instance is cropped and masked, and three orthogonal -maximum-intensity projections (MIPs) are computed. These 2D views are -encoded by a frozen DINOv2 vision transformer [@Oquab2024] into a 384-d unit -embedding vector that captures shape and texture information invariant to -minor intensity fluctuations. A `GeometrySemanticCost` function composes the -geometric and semantic terms as $\alpha \cdot C_\text{geo}(i,j) + \beta -\cdot (1 - \cos(\mathbf{f}_i, \mathbf{f}_j))$, allowing researchers to -ablate the contribution of each modality. - -A deterministic mock encoder (hash-based) is provided for environments -without GPU access, enabling full pipeline execution in continuous -integration and on Google Colab. - -## Tracking and lifecycle - -Cross-frame association is performed by the Hungarian algorithm -[@Kuhn1955] on the cost matrix between consecutive scans. -Unmatched observations are marked as births (new reflections entering the -diffraction condition) or terminations (reflections leaving), while matched -pairs are continuations. The result is a directed acyclic graph (DAG) -implemented as a NetworkX [@Hagberg2008] `DiGraph`, where each node carries -a `TrackEvent` annotation and each edge represents a temporal link. Metrics -including fragmentation ratio, ID-switch rate, and full-length track count -are computed from the graph. +## Beamline ingestion and physical axis calibration + +BraggTrack discovers sequential `scan*` directories, inspects NeXus/HDF5 trees +(including ESRF-ID03 LIMA detector hierarchies under `/entry_0000/...` and +generic HDF5 layouts via automatic largest-3D numeric dataset discovery), and +validates timestamp monotonicity. An `AxisCalibration` transform converts raw +detector indices into physical reciprocal-space coordinates +$(\mu, \chi, d)$ via HDF5 axis metadata or JSON/CLI calibration parameters while +preserving integer voxel bounding boxes for lossless 3D region-of-interest (ROI) +cropping. This ensures crystallographic strain $\Delta d / d_0$ is invariant to +detector window cropping. + +## Stabilised 3D segmentation + +BraggTrack's primary segmentation pipeline processes 3D volumes in four stages: + +1. **Stabilised foreground thresholding.** Per-scan Otsu thresholds [@Otsu1979] + on raw intensity histograms are smoothed across scans with a rolling median + (`smooth_thresholds`) and checked for median-absolute-deviation outliers, + eliminating spot-count jitter caused by transient beam fluctuations. + +2. **3D LoG enhancement.** Gaussian smoothing followed by the negative discrete + Laplacian highlights Bragg reflections as local maxima [@Lindeberg1998] + independently of intensity-domain foreground masking. + +3. **Robust seed detection.** `h`-maxima filtering [@Soille2003] selects seeds + exceeding both a fraction of the 99.99th-percentile foreground response and a + high response percentile with non-maximum suppression. + +4. **Seeded watershed and basin refinement.** Watershed region growing + [@Vincent1991] over the inverted LoG response is followed by small-object + removal, 3D hole filling, and optional nearby-centroid merging to prevent + over-segmentation of mosaic reflections. An experimental dense patch-feature + + HDBSCAN slice-stitching segmenter (`segment_dino`) is also provided for + cross-method comparison. + +## Multi-view semantic descriptors + +Each segmented 3D reflection is cropped, masked to its instance support, and +projected into three orthogonal maximum-intensity projections (MIPs) along +$\mu$, $\chi$, and $d$. By default, BraggTrack encodes these views using the +public, ungated DINOv2 vision transformer (`facebook/dinov2-small`) +[@Oquab2024] into an $L_2$-normalised 384-d descriptor, while also supporting +newer DINOv3 backbones (`facebook/dinov3-vitb16-pretrain-lvd1689m`) via dynamic +prefix/register token handling and a deterministic hash-based `mock` encoder for +zero-GPU continuous integration. + +## Tracking, kinematics, and chemomechanical fracture events + +Frame-to-frame 1-to-1 association solves the gated Hungarian assignment problem +[@Kuhn1955] over $\alpha \cdot C_{\text{geo}}(i, j) + \beta \cdot (1 - +\cos(\mathbf{f}_i, \mathbf{f}_j))$, constructing a NetworkX [@Hagberg2008] +`DiGraph`. From each trajectory, `compute_grain_kinematics` extracts time-series +strain $\Delta d / d_0$, rocking/azimuthal misorientation, integrated intensity +and volume evolution, and 3D eigenvalue anisotropy. + +To capture grain fracture and coalescence, `resolve_splits_and_merges` augments +unmatched birth and termination nodes with explicit `1 -> 2+` split and +`2+ -> 1` merge edges gated by spatial proximity, integrated-intensity +conservation ($I_{\text{children}} / I_{\text{parent}}$), and minimum fragment +intensity share, assigning clean daughter track IDs so diverging post-fracture +strains are tracked independently. Complementarily, +`compute_fracture_precursors` scores pre-split intragranular degradation across +contiguous scans (`min_persistence`) using 3D eigenvalue anisotropy, covariance +trace growth, internal 3D sub-peak bimodality, and foreground DINO patch-token +cosine dispersion. ## Reproducibility and deployment -BraggTrack is packaged as a standard Python project (`pip install -braggtrack`) with optional dependency groups for PyTorch-based encoders and -notebook execution. Six CLI entry points expose every pipeline stage. A -GitHub Actions CI pipeline tests across Python 3.10–3.12, enforces Ruff -linting and formatting, and executes the demo notebook end-to-end. Bundled -ESRF-ID03 sample data (three 100×250×250 uint16 volumes) allows immediate -experimentation without external data downloads. +BraggTrack (`pip install braggtrack`) provides eight CLI commands, culminating +in `braggtrack-run`, which executes validation, segmentation, embedding, +tracking, kinematics, and event detection and writes a `run_manifest.json` +recording SHA-256 input checksums, configuration, software version, and per-stage +runtimes. Automated CI tests Python 3.10–3.12, enforces Ruff linting/formatting, +runs seven acceptance gates (`scripts/ci_report.py`), and executes the tutorial +notebook end-to-end on bundled ESRF-ID03 data. # Acknowledgements diff --git a/pyproject.toml b/pyproject.toml index 2fbd8b9..bff1ae3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta" [project] name = "braggtrack" -version = "0.1.0" +version = "0.2.0" description = "Semantic 4D kinematics and fracture tracking for operando diffraction." readme = "README.md" requires-python = ">=3.10" license = { text = "MIT" } authors = [{ name = "James Le Houx", email = "j.lehoux@greenwich.ac.uk" }] classifiers = [ - "Development Status :: 3 - Alpha", + "Development Status :: 4 - Beta", "Intended Audience :: Science/Research", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", @@ -58,6 +58,8 @@ braggtrack-segment-synthetic = "braggtrack.cli.segment_synthetic:main" braggtrack-segment-dataset = "braggtrack.cli.segment_dataset:main" braggtrack-track-dataset = "braggtrack.cli.track_dataset:main" braggtrack-embed-dataset = "braggtrack.cli.embed_dataset:main" +braggtrack-events = "braggtrack.cli.detect_events:main" +braggtrack-run = "braggtrack.cli.run_pipeline:main" [tool.setuptools.packages.find] include = ["braggtrack*"] diff --git a/scripts/ablation_semantic.py b/scripts/ablation_semantic.py index 7a2f371..d2c686a 100644 --- a/scripts/ablation_semantic.py +++ b/scripts/ablation_semantic.py @@ -26,6 +26,9 @@ from pathlib import Path from typing import Any +import networkx as nx +import numpy as np + from braggtrack.cli._utils import load_feature_csv from braggtrack.cli.track_dataset import _load_embeddings_npz, _merge_embeddings from braggtrack.tracking import ( @@ -61,6 +64,13 @@ def build_parser() -> argparse.ArgumentParser: p.add_argument("--gate-chi", type=float, default=math.inf) p.add_argument("--gate-d", type=float, default=math.inf) p.add_argument("--max-cost", type=float, default=math.inf) + p.add_argument( + "--bootstrap-samples", + type=int, + default=0, + help="Number of bootstrap resamples over tracks for 95%% CIs (0 disables)", + ) + p.add_argument("--seed", type=int, default=42, help="Random seed for bootstrap resampling") return p @@ -80,6 +90,53 @@ def _load_scan_tables(indir: Path) -> tuple[list[list[dict[str, Any]]], list[str return tables, names +def _bootstrap_metric_cis( + G: nx.DiGraph, + n_scans: int, + n_samples: int, + seed: int, +) -> dict[str, list[float]]: + """Bootstrap 95% confidence intervals by resampling track subgraphs with replacement.""" + by_tid: dict[int, list[str]] = {} + for nid, data in G.nodes(data=True): + by_tid.setdefault(int(data["track_id"]), []).append(nid) + + tids = sorted(by_tid) + if not tids or n_samples <= 0: + return {} + + rng = np.random.default_rng(seed) + frag_vals: list[float] = [] + switch_vals: list[float] = [] + + for _ in range(n_samples): + sampled_tids = rng.choice(tids, size=len(tids), replace=True) + H = nx.DiGraph() + for copy_idx, tid in enumerate(sampled_tids): + new_tid = copy_idx + 1 + node_map: dict[str, str] = {} + for nid in by_tid[int(tid)]: + new_nid = f"b{copy_idx}_{nid}" + node_map[nid] = new_nid + attrs = dict(G.nodes[nid]) + attrs["track_id"] = new_tid + H.add_node(new_nid, **attrs) + for u in by_tid[int(tid)]: + for v in G.successors(u): + if v in node_map: + H.add_edge(node_map[u], node_map[v], **dict(G.edges[u, v])) + m = compute_tracking_metrics(H, n_scans=n_scans) + frag_vals.append(float(m["fragmentation_ratio"])) + switch_vals.append(float(m["id_switch_rate"])) + + frag_lo, frag_hi = np.percentile(frag_vals, [2.5, 97.5]) + sw_lo, sw_hi = np.percentile(switch_vals, [2.5, 97.5]) + return { + "fragmentation_ratio_ci95": [round(float(frag_lo), 4), round(float(frag_hi), 4)], + "id_switch_rate_ci95": [round(float(sw_lo), 4), round(float(sw_hi), 4)], + } + + def _evaluate_tables( scan_tables: list[list[dict[str, Any]]], scan_names: list[str], @@ -92,6 +149,8 @@ def _evaluate_tables( gate_chi: float, gate_d: float, max_cost: float, + bootstrap_samples: int = 0, + seed: int = 42, ) -> dict[str, Any]: geo = PositionShapeCost( position_weight=position_weight, @@ -108,17 +167,19 @@ def _evaluate_tables( G = build_tracks(scan_tables, cost_fn=cost_fn, max_cost=max_cost) n_scans = len(scan_tables) metrics = compute_tracking_metrics(G, n_scans=n_scans) + cis = _bootstrap_metric_cis(G, n_scans, bootstrap_samples, seed) if bootstrap_samples > 0 else {} return { "cost_alpha": cost_alpha, "cost_beta": cost_beta, "n_scans": n_scans, "scan_names": scan_names, **metrics, + **cis, } -def main() -> int: - args = build_parser().parse_args() +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) indir = Path(args.indir) emb_root = Path(args.embedding_dir) if args.embedding_dir else None alphas = _parse_float_list(args.alphas) @@ -164,6 +225,8 @@ def main() -> int: gate_chi=args.gate_chi, gate_d=args.gate_d, max_cost=args.max_cost, + bootstrap_samples=max(0, int(args.bootstrap_samples)), + seed=int(args.seed), ) rows_out.append(row) @@ -172,6 +235,7 @@ def main() -> int: "indir": str(indir.resolve()), "embedding_dir": str(emb_root.resolve()) if emb_root else None, "grid": {"alphas": alphas, "betas": betas}, + "bootstrap_samples": max(0, int(args.bootstrap_samples)), "runs": rows_out, } diff --git a/scripts/check_events_acceptance.py b/scripts/check_events_acceptance.py new file mode 100644 index 0000000..c73543d --- /dev/null +++ b/scripts/check_events_acceptance.py @@ -0,0 +1,153 @@ +"""Events, fracture precursor, and reproducible pipeline acceptance checks. + +Acceptance criteria: + 1. Synthetic 4D fracture benchmark recovers exact 1->2 split and 2->1 merge events. + 2. Persistent fracture precursor ranking places the fracturing grain at rank #1 + with subsequent_split=True while excluding the stable control grain. + 3. One-command pipeline (braggtrack-run) completes end-to-end on bundled ESRF-ID03 + operando scans and produces run_manifest.json, kinematics.csv, events.csv, and precursors.csv. +""" + +from __future__ import annotations + +import json +import subprocess +import sys +import tempfile +from pathlib import Path + +import h5py +import numpy as np + +_REPO_ROOT = Path(__file__).resolve().parents[1] +if str(_REPO_ROOT) not in sys.path: + sys.path.insert(0, str(_REPO_ROOT)) + +from braggtrack.cli._utils import write_csv +from braggtrack.io import resolve_dataset_root +from braggtrack.tracking import generate_fracture_scenario + +PIPELINE_OUTDIR = Path("artifacts/pipeline_acceptance") +DATASET_ROOT = resolve_dataset_root(None) + + +def _check_synthetic_fracture_pipeline(failures: list[str]) -> dict[str, object]: + volumes, label_volumes, scan_tables, expected = generate_fracture_scenario(n_scans=5, seed=42) + with tempfile.TemporaryDirectory() as tmp: + tmp_root = Path(tmp) + data_root = tmp_root / "synth_data" + seg_dir = tmp_root / "seg" + evt_dir = tmp_root / "events" + + for idx, (vol, labs, rows) in enumerate(zip(volumes, label_volumes, scan_tables)): + sname = f"scan{idx + 1:04d}" + sdata = data_root / sname + sdata.mkdir(parents=True, exist_ok=True) + with h5py.File(sdata / "scan.h5", "w") as h5: + h5.create_dataset("/entry_0000/ESRF-ID03/pco_nf/data", data=vol.astype(np.float32)) + + sseg = seg_dir / sname + sseg.mkdir(parents=True, exist_ok=True) + write_csv(sseg / "features.csv", rows) + np.savez_compressed(sseg / "labels.npz", labels=labs) + + proc = subprocess.run( + [ + sys.executable, + "-m", + "braggtrack.cli.detect_events", + str(data_root), + "--segdir", + str(seg_dir), + "--outdir", + str(evt_dir), + "--backend", + "mock", + ], + check=False, + capture_output=True, + text=True, + ) + if proc.returncode != 0: + failures.append(f"detect_events failed: {proc.stderr.strip() or proc.stdout.strip()}") + return {} + + summary = json.loads(proc.stdout) + if summary.get("schema_version") != "events.v1": + failures.append(f"Unexpected events schema_version: {summary.get('schema_version')}") + if summary.get("split_count") != 1: + failures.append(f"Expected 1 split event on synthetic fracture scenario, got {summary.get('split_count')}") + if summary.get("merge_count") != 1: + failures.append(f"Expected 1 merge event on synthetic fracture scenario, got {summary.get('merge_count')}") + if summary.get("precursor_candidate_count", 0) < 1: + failures.append("Expected at least 1 persistent precursor candidate") + if not summary.get("roi_dispersion_enabled"): + failures.append("Expected roi_dispersion_enabled=True when 3D volumes and labels.npz are present") + + events_list = json.loads((evt_dir / "events.json").read_text()) + split_evts = [e for e in events_list if e["event_type"] == "split"] + if split_evts and int(split_evts[0]["scan_idx_to"]) != expected["split_scan_to"]: + failures.append(f"Split detected at wrong scan: {split_evts[0]['scan_idx_to']}") + + return summary + + +def _check_end_to_end_pipeline(failures: list[str]) -> dict[str, object]: + proc = subprocess.run( + [ + sys.executable, + "-m", + "braggtrack.cli.run_pipeline", + str(DATASET_ROOT), + "--outdir", + str(PIPELINE_OUTDIR), + "--backend", + "mock", + ], + check=False, + capture_output=True, + text=True, + ) + if proc.returncode != 0: + failures.append(f"run_pipeline failed: {proc.stderr.strip() or proc.stdout.strip()}") + return {} + + manifest_path = PIPELINE_OUTDIR / "run_manifest.json" + if not manifest_path.exists(): + failures.append("Missing run_manifest.json from run_pipeline") + return {} + + manifest = json.loads(manifest_path.read_text()) + if manifest.get("schema_version") != "manifest.v1": + failures.append(f"Unexpected manifest schema_version: {manifest.get('schema_version')}") + if len(manifest.get("inputs", [])) != 3: + failures.append(f"Expected 3 input checksums in manifest, got {len(manifest.get('inputs', []))}") + + for key in ("kinematics_csv", "events_csv", "precursors_csv", "events_summary"): + art_path = manifest.get("artifacts", {}).get(key) + if not art_path or not Path(art_path).exists(): + failures.append(f"Missing pipeline artifact {key}: {art_path}") + + return { + "manifest_schema": manifest.get("schema_version"), + "input_count": len(manifest.get("inputs", [])), + "stages": sorted(manifest.get("stage_timings_sec", {}).keys()), + } + + +def main() -> int: + failures: list[str] = [] + synth_report = _check_synthetic_fracture_pipeline(failures) + pipe_report = _check_end_to_end_pipeline(failures) + + report = { + "synthetic_fracture": synth_report, + "pipeline_manifest": pipe_report, + "failures": failures, + } + print(json.dumps(report, indent=2)) + return 0 if not failures else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/ci_report.py b/scripts/ci_report.py index 4a73ec8..97ae603 100644 --- a/scripts/ci_report.py +++ b/scripts/ci_report.py @@ -32,7 +32,7 @@ def _filter_suite(suite: unittest.TestSuite, skip_module: str | None) -> unittes def run_unit_tests() -> bool: print("\n=== Unit Tests ===") suite = unittest.defaultTestLoader.discover("tests") - skip_module = os.environ.get("BRAGGTRACK_SKIP_TEST_MODULE") + skip_module = os.environ.get("BRAGGTRACK_SKIP_TEST_MODULE", "test_ci_report") suite = _filter_suite(suite, skip_module) result = unittest.TextTestRunner(verbosity=2).run(suite) print(f"unit_tests: ran={result.testsRun} failures={len(result.failures)} errors={len(result.errors)}") @@ -126,7 +126,12 @@ def main() -> int: dino_ok_cmd, dino_payload, _ = run_cmd_json([sys.executable, "scripts/check_dino_acceptance.py"], "DINO Acceptance") dino_ok = dino_ok_cmd and isinstance(dino_payload, dict) and dino_payload.get("failures") == [] - all_ok = unit_ok and acc_ok and smoke_ok and seg_ok and trk_ok and emb_ok and dino_ok + evt_ok_cmd, evt_payload, _ = run_cmd_json( + [sys.executable, "scripts/check_events_acceptance.py"], "Events Acceptance" + ) + evt_ok = evt_ok_cmd and isinstance(evt_payload, dict) and evt_payload.get("failures") == [] + + all_ok = unit_ok and acc_ok and smoke_ok and seg_ok and trk_ok and emb_ok and dino_ok and evt_ok print("\n=== Summary ===") print(f"unit_tests={'PASS' if unit_ok else 'FAIL'}") print(f"io_acceptance={'PASS' if acc_ok else 'FAIL'}") @@ -135,6 +140,7 @@ def main() -> int: print(f"tracking_acceptance={'PASS' if trk_ok else 'FAIL'}") print(f"embedding_acceptance={'PASS' if emb_ok else 'FAIL'}") print(f"dino_acceptance={'PASS' if dino_ok else 'FAIL'}") + print(f"events_acceptance={'PASS' if evt_ok else 'FAIL'}") print(f"overall={'PASS' if all_ok else 'FAIL'}") return 0 if all_ok else 1 diff --git a/tests/test_axis_calibration.py b/tests/test_axis_calibration.py new file mode 100644 index 0000000..7599b51 --- /dev/null +++ b/tests/test_axis_calibration.py @@ -0,0 +1,160 @@ +from __future__ import annotations + +import json +import tempfile +import unittest +from pathlib import Path + +import h5py +import numpy as np + +from braggtrack.io import ( + AxisCalibration, + BeamlineAdapter, + discover_primary_volume_path, + extract_axis_calibration, + extract_scan_metadata, + load_primary_volume, + resolve_dataset_root, +) +from braggtrack.segmentation import extract_instance_table +from braggtrack.tracking import compute_grain_kinematics, kinematics_to_table + + +class TestAxisCalibrationAndESRFDiscovery(unittest.TestCase): + def test_axis_calibration_roundtrip_and_transform(self) -> None: + cal = AxisCalibration( + mu_origin=-1.5, + mu_step=0.05, + chi_origin=10.0, + chi_step=0.02, + d_origin=2.035, + d_step=-1.5e-4, + calibrated=True, + ) + mu, chi, d = cal.voxel_to_physical(z=10.0, y=20.0, x=30.0) + self.assertAlmostEqual(mu, -1.0) + self.assertAlmostEqual(chi, 10.6) + self.assertAlmostEqual(d, 2.032) + + restored = AxisCalibration.from_dict(cal.to_dict()) + self.assertEqual(restored, cal) + self.assertTrue(restored.calibrated) + + with self.assertRaises(ValueError): + AxisCalibration(d_step=0.0) + + def test_bundled_esrf_id03_scans_load_real_detector_cubes(self) -> None: + root = resolve_dataset_root(None) + adapter = BeamlineAdapter(root) + seq = adapter.build_sequence() + self.assertEqual(len(seq.scans), 3) + self.assertTrue(seq.is_monotonic()) + + for scan in seq.scans: + self.assertEqual(scan.volume_dataset_path, "/entry_0000/ESRF-ID03/pco_nf/data") + self.assertIsNotNone(scan.start_time) + self.assertEqual(scan.title, "Lima 2D detector acquisition") + + vol = load_primary_volume(seq.scans[0].file_path) + self.assertEqual(vol.shape, (100, 250, 250)) + + def test_auto_discover_fallback_for_custom_h5_layout_and_axes(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + h5_path = Path(tmp) / "custom_nx.h5" + cube = np.arange(5 * 6 * 7, dtype=np.float32).reshape(5, 6, 7) + with h5py.File(h5_path, "w") as h5: + grp = h5.create_group("/entry_custom") + grp.attrs["NX_class"] = "NXentry" + grp.create_dataset("start_time", data="2026-01-15T12:00:00Z") + grp.create_dataset("title", data="custom_operando_scan") + data_grp = grp.create_group("instrument/detector") + data_grp.create_dataset("frames", data=cube) + data_grp.create_dataset("mu", data=np.linspace(0.0, 0.4, 5)) + data_grp.create_dataset("chi", data=np.linspace(-1.0, -0.4, 7)) + data_grp.create_dataset("d", data=np.linspace(2.05, 2.06, 6)) + + ds_path = discover_primary_volume_path(h5_path) + self.assertEqual(ds_path, "/entry_custom/instrument/detector/frames") + loaded = load_primary_volume(h5_path) + self.assertEqual(loaded.shape, (5, 6, 7)) + + meta = extract_scan_metadata(h5_path) + self.assertEqual(meta["title"], "custom_operando_scan") + self.assertIsNotNone(meta["start_time"]) + + cal = extract_axis_calibration(h5_path) + self.assertTrue(cal.calibrated) + self.assertAlmostEqual(cal.mu_step, 0.1, places=6) + self.assertAlmostEqual(cal.chi_origin, -1.0, places=6) + self.assertAlmostEqual(cal.d_origin, 2.05, places=6) + + def test_calibrated_features_preserve_voxel_bbox_and_fix_crop_offset_strain(self) -> None: + shape = (16, 32, 32) + zz, yy, xx = np.indices(shape, dtype=np.float64) + + # Two scans where a spot shifts by +2 voxels along y (d-axis) in a cropped ROI. + # Uncalibrated voxel strain would be 2.0 / 10.0 = +0.20 (20% artificial!), + # whereas calibrated physical strain with d_origin=2.000 A, d_step=0.001 A/px + # is (2 * 0.001) / (2.000 + 10 * 0.001) = 0.002 / 2.010 = 9.95e-4. + cal = AxisCalibration( + mu_origin=5.0, + mu_step=0.05, + chi_origin=-2.0, + chi_step=0.04, + d_origin=2.000, + d_step=0.001, + calibrated=True, + ) + + track_rows = [] + for scan_idx, y_center in enumerate((10.0, 12.0)): + vol = 100.0 * np.exp(-0.5 * ((zz - 8.0) ** 2 + (yy - y_center) ** 2 + (xx - 15.0) ** 2)) + labels = (vol >= 10.0).astype(np.int32) + rows = extract_instance_table(labels, vol, calibration=cal) + self.assertEqual(len(rows), 1) + row = rows[0] + # Bounding box indices MUST stay integer voxel coordinates for cropping! + self.assertIsInstance(row["bbox_min_y"], int) + self.assertGreaterEqual(row["bbox_min_y"], 6) + self.assertLessEqual(row["bbox_max_y"], 16) + row["track_id"] = 1 + row["scan_idx"] = scan_idx + track_rows.append(row) + + gk = compute_grain_kinematics(track_rows) + self.assertEqual(len(gk), 1) + expected_strain = (2.0 * 0.001) / (2.000 + 10.0 * 0.001) + self.assertAlmostEqual(float(gk[0].strain[1]), expected_strain, places=4) + self.assertAlmostEqual(float(gk[0].delta_d[1]), 0.002, places=5) + + # Default table preserves strict 18-column contract; include_delta_d=True adds delta_d. + tbl_default = kinematics_to_table(gk) + self.assertNotIn("delta_d", tbl_default[0]) + tbl_ext = kinematics_to_table(gk, include_delta_d=True) + self.assertIn("delta_d", tbl_ext[0]) + + # Verify segment_dataset CLI --calibration-json support on synthetic h5. + with tempfile.TemporaryDirectory() as tmp: + tmp_path = Path(tmp) + cal_path = tmp_path / "cal.json" + cal_path.write_text(json.dumps(cal.to_dict())) + scan_dir = tmp_path / "data" / "scan0001" + scan_dir.mkdir(parents=True) + vol = 100.0 * np.exp(-0.5 * ((zz - 8.0) ** 2 + (yy - 10.0) ** 2 + (xx - 15.0) ** 2)) + with h5py.File(scan_dir / "scan.h5", "w") as h5: + h5.create_dataset("/entry_0000/ESRF-ID03/pco_nf/data", data=vol.astype(np.float32)) + + from braggtrack.cli import segment_dataset + + out_seg = tmp_path / "seg_out" + rc = segment_dataset.main( + [str(tmp_path / "data"), "--outdir", str(out_seg), "--calibration-json", str(cal_path)] + ) + self.assertEqual(rc, 0) + seg_summary = json.loads((out_seg / "segmentation_summary.json").read_text()) + self.assertTrue(seg_summary[0]["calibrated"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_events_acceptance.py b/tests/test_events_acceptance.py new file mode 100644 index 0000000..f487900 --- /dev/null +++ b/tests/test_events_acceptance.py @@ -0,0 +1,24 @@ +import json +import subprocess +import sys +import unittest + + +class TestEventsAcceptance(unittest.TestCase): + def test_events_acceptance_script(self) -> None: + proc = subprocess.run( + [sys.executable, "scripts/check_events_acceptance.py"], + check=False, + capture_output=True, + text=True, + ) + self.assertEqual(proc.returncode, 0, msg=proc.stdout + proc.stderr) + payload = json.loads(proc.stdout) + self.assertEqual(payload["failures"], []) + self.assertEqual(payload["synthetic_fracture"]["split_count"], 1) + self.assertEqual(payload["synthetic_fracture"]["merge_count"], 1) + self.assertEqual(payload["pipeline_manifest"]["manifest_schema"], "manifest.v1") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_events_and_precursors.py b/tests/test_events_and_precursors.py new file mode 100644 index 0000000..b31d32f --- /dev/null +++ b/tests/test_events_and_precursors.py @@ -0,0 +1,198 @@ +from __future__ import annotations + +import json +import tempfile +import unittest +from pathlib import Path + +import h5py +import numpy as np + +from braggtrack.cli import detect_events +from braggtrack.cli._utils import write_csv +from braggtrack.semantic import make_patch_encoder +from braggtrack.tracking import ( + PositionShapeCost, + PrecursorConfig, + SplitMergeConfig, + build_tracks, + compute_fracture_precursors, + compute_grain_kinematics, + compute_tracking_metrics, + events_to_table, + generate_fracture_scenario, + precursors_to_table, + tracks_to_table, +) + + +class TestEventsAndPrecursors(unittest.TestCase): + def test_fracture_scenario_recovers_split_merge_and_top_precursor(self) -> None: + volumes, label_volumes, scan_tables, expected = generate_fracture_scenario(n_scans=5, seed=42) + sm_cfg = SplitMergeConfig(max_distance=20.0) + G = build_tracks( + scan_tables, + cost_fn=PositionShapeCost(), + split_merge_config=sm_cfg, + scan_timestamps={i: f"2026-01-15T12:0{i}:00Z" for i in range(5)}, + ) + metrics = compute_tracking_metrics(G, n_scans=5) + self.assertEqual(metrics["split_count"], 1) + self.assertEqual(metrics["merge_count"], 1) + + lineage_events = G.graph["lineage_events"] + splits = [e for e in lineage_events if e.event_type == "split"] + merges = [e for e in lineage_events if e.event_type == "merge"] + self.assertEqual(len(splits), 1) + self.assertEqual(len(merges), 1) + + split_ev = splits[0] + self.assertEqual(split_ev.scan_idx_from, expected["split_scan_from"]) + self.assertEqual(split_ev.scan_idx_to, expected["split_scan_to"]) + self.assertEqual(len(split_ev.parent_track_ids), 1) + self.assertEqual(len(split_ev.child_track_ids), 2) + # Daughter track IDs must be distinct from each other and from parent. + self.assertEqual(len(set(split_ev.child_track_ids)), 2) + self.assertNotIn(split_ev.parent_track_ids[0], split_ev.child_track_ids) + + merge_ev = merges[0] + self.assertEqual(merge_ev.scan_idx_from, expected["merge_scan_from"]) + self.assertEqual(merge_ev.scan_idx_to, expected["merge_scan_to"]) + self.assertEqual(len(merge_ev.parent_track_ids), 2) + self.assertEqual(len(merge_ev.child_track_ids), 1) + + # Verify diverging daughter kinematics after split. + track_rows = tracks_to_table(G) + gk_by_tid = {gk.track_id: gk for gk in compute_grain_kinematics(track_rows)} + c1, c2 = split_ev.child_track_ids + self.assertIn(c1, gk_by_tid) + self.assertIn(c2, gk_by_tid) + # Daughters drift in opposite directions along d across scans 2..4. + self.assertLess(float(gk_by_tid[c1].strain[-1]) * float(gk_by_tid[c2].strain[-1]), 0.0) + + # Verify fracture precursor ranking with 3D ROI sub-peak + mock patch encoder. + patch_enc = make_patch_encoder("mock") + candidates, obs_scores = compute_fracture_precursors( + track_rows, + PrecursorConfig(score_threshold=0.35, min_persistence=2), + volumes=volumes, + label_volumes=label_volumes, + patch_encoder=patch_enc, + lineage_events=lineage_events, + ) + self.assertGreaterEqual(len(candidates), 1) + top = candidates[0] + self.assertEqual(top.rank, 1) + self.assertEqual(top.track_id, split_ev.parent_track_ids[0]) + self.assertTrue(top.subsequent_split) + self.assertGreaterEqual(top.persistence_scans, 2) + self.assertGreaterEqual(top.max_subpeak_count, 2) + + # Control grain (located at chi ~ 36, d ~ 24) must NOT be ranked as a precursor. + control_tids = { + int(r["track_id"]) + for r in track_rows + if abs(float(r["centroid_chi"]) - 36.0) < 2.0 and abs(float(r["centroid_d"]) - 24.0) < 2.0 + } + self.assertTrue(control_tids) + ranked_tids = {c.track_id for c in candidates} + self.assertTrue(control_tids.isdisjoint(ranked_tids)) + + # Verify table serializers. + self.assertEqual(len(events_to_table(lineage_events)), 2) + self.assertEqual(len(precursors_to_table(candidates)), len(candidates)) + self.assertGreater(len(obs_scores), 0) + + def test_anti_noise_intensity_guard_rejects_tiny_spurious_speck(self) -> None: + """A tiny background speck appearing next to a steady grain must NOT trigger a false split.""" + scan0 = [ + { + "label": 1, + "centroid_mu": 10.0, + "centroid_chi": 10.0, + "centroid_d": 10.0, + "integrated_intensity": 1000.0, + "voxel_count": 50, + "eig_1": 1.0, + "eig_2": 1.0, + "eig_3": 1.0, + } + ] + scan1 = [ + { + "label": 1, + "centroid_mu": 10.1, + "centroid_chi": 10.0, + "centroid_d": 10.0, + "integrated_intensity": 995.0, + "voxel_count": 50, + "eig_1": 1.0, + "eig_2": 1.0, + "eig_3": 1.0, + }, + # Spurious 2% intensity noise speck nearby: fails min_fragment_share=0.10! + { + "label": 2, + "centroid_mu": 12.0, + "centroid_chi": 11.0, + "centroid_d": 10.0, + "integrated_intensity": 20.0, + "voxel_count": 8, + "eig_1": 0.5, + "eig_2": 0.5, + "eig_3": 0.5, + }, + ] + G = build_tracks([scan0, scan1], split_merge_config=SplitMergeConfig(max_distance=15.0)) + self.assertEqual(G.graph["lineage_events"], []) + + def test_single_frame_spike_filtered_by_persistence(self) -> None: + """A transient 1-scan anisotropy spike must be rejected when min_persistence=2.""" + rows = [ + {"track_id": 1, "scan_idx": 0, "label": 1, "eig_1": 1.0, "eig_2": 1.0, "eig_3": 1.0}, + {"track_id": 1, "scan_idx": 1, "label": 1, "eig_1": 6.0, "eig_2": 1.0, "eig_3": 1.0}, # transient spike + {"track_id": 1, "scan_idx": 2, "label": 1, "eig_1": 1.0, "eig_2": 1.0, "eig_3": 1.0}, + ] + candidates, _ = compute_fracture_precursors( + rows, + PrecursorConfig(score_threshold=0.40, min_persistence=2), + ) + self.assertEqual(candidates, []) + + def test_detect_events_cli_end_to_end(self) -> None: + volumes, label_volumes, scan_tables, _ = generate_fracture_scenario(n_scans=4, seed=7) + with tempfile.TemporaryDirectory() as tmp: + tmp_path = Path(tmp) + data_dir = tmp_path / "data" + seg_dir = tmp_path / "seg" + out_dir = tmp_path / "events" + for idx, (vol, labs, rows) in enumerate(zip(volumes, label_volumes, scan_tables)): + sname = f"scan{idx + 1:04d}" + (data_dir / sname).mkdir(parents=True) + with h5py.File(data_dir / sname / "scan.h5", "w") as h5: + h5.create_dataset("/entry_0000/ESRF-ID03/pco_nf/data", data=vol.astype(np.float32)) + (seg_dir / sname).mkdir(parents=True) + write_csv(seg_dir / sname / "features.csv", rows) + np.savez_compressed(seg_dir / sname / "labels.npz", labels=labs) + + rc = detect_events.main( + [ + str(data_dir), + "--segdir", + str(seg_dir), + "--outdir", + str(out_dir), + "--backend", + "mock", + ] + ) + self.assertEqual(rc, 0) + summary = json.loads((out_dir / "events_summary.json").read_text()) + self.assertEqual(summary["split_count"], 1) + self.assertEqual(summary["merge_count"], 1) + self.assertTrue((out_dir / "events.csv").exists()) + self.assertTrue((out_dir / "precursors.csv").exists()) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_postprocess.py b/tests/test_postprocess.py index b1958e6..ac501c1 100644 --- a/tests/test_postprocess.py +++ b/tests/test_postprocess.py @@ -4,7 +4,7 @@ import numpy as np -from braggtrack.segmentation import fill_holes_binary, relabel_sequential, remove_small_objects +from braggtrack.segmentation import fill_holes_binary, merge_nearby_labels, relabel_sequential, remove_small_objects class RemoveSmallObjectsTests(unittest.TestCase): @@ -92,5 +92,23 @@ def test_empty_volume(self) -> None: self.assertTrue(np.all(out == 0)) +class MergeNearbyLabelsTests(unittest.TestCase): + def test_merges_touching_close_labels(self) -> None: + labels = np.zeros((6, 6, 6), dtype=np.int32) + labels[2, 2, 1:3] = 1 + labels[2, 2, 3:5] = 2 + vol = np.ones((6, 6, 6), dtype=np.float64) * 10.0 + merged = relabel_sequential(merge_nearby_labels(labels, vol, max_centroid_distance=5.0)) + self.assertEqual(sorted(np.unique(merged)), [0, 1]) + + def test_keeps_separated_labels_distinct(self) -> None: + labels = np.zeros((6, 6, 8), dtype=np.int32) + labels[2, 2, 0:2] = 1 + labels[2, 2, 6:8] = 2 # non-adjacent + vol = np.ones((6, 6, 8), dtype=np.float64) * 10.0 + merged = relabel_sequential(merge_nearby_labels(labels, vol, max_centroid_distance=20.0)) + self.assertEqual(sorted(np.unique(merged)), [0, 1, 2]) + + if __name__ == "__main__": unittest.main() diff --git a/tests/test_run_pipeline.py b/tests/test_run_pipeline.py new file mode 100644 index 0000000..749cd07 --- /dev/null +++ b/tests/test_run_pipeline.py @@ -0,0 +1,93 @@ +from __future__ import annotations + +import json +import tempfile +import unittest +from pathlib import Path + +import h5py +import numpy as np + +from braggtrack.cli import run_pipeline +from braggtrack.tracking import generate_fracture_scenario + + +class TestRunPipelineAndAblationCI(unittest.TestCase): + def test_run_pipeline_with_config_produces_manifest_and_all_artifacts(self) -> None: + volumes, _, _, _ = generate_fracture_scenario(n_scans=4, seed=11) + with tempfile.TemporaryDirectory() as tmp: + tmp_path = Path(tmp) + data_dir = tmp_path / "operando" + for idx, vol in enumerate(volumes): + sdir = data_dir / f"scan{idx + 1:04d}" + sdir.mkdir(parents=True) + with h5py.File(sdir / "pco_nf.h5", "w") as h5: + grp = h5.create_group("/entry_0000") + grp.create_dataset("start_time", data=f"2026-02-01T10:0{idx}:00Z") + grp.create_dataset("title", data="synth_operando") + h5.create_dataset("/entry_0000/ESRF-ID03/pco_nf/data", data=vol.astype(np.float32)) + + cfg_path = tmp_path / "pipeline_config.json" + cfg_path.write_text( + json.dumps( + { + "backend": "mock", + "cost_beta": 0.25, + "smooth_window": 3, + "detect_events": True, + "segmentation_extra_args": ["--merge-distance", "0"], + } + ) + ) + out_dir = tmp_path / "pipeline_out" + rc = run_pipeline.main([str(data_dir), "--outdir", str(out_dir), "--config", str(cfg_path)]) + self.assertEqual(rc, 0) + + manifest = json.loads((out_dir / "run_manifest.json").read_text()) + self.assertEqual(manifest["schema_version"], "manifest.v1") + self.assertEqual(len(manifest["inputs"]), 4) + for inp in manifest["inputs"]: + self.assertEqual(len(inp["sha256"]), 64) + + for stage in ("validate", "segment", "embed", "track", "events"): + self.assertIn(stage, manifest["stage_timings_sec"]) + + for art_key in ("kinematics_csv", "kinematics_summary", "events_csv", "precursors_csv"): + self.assertTrue(Path(manifest["artifacts"][art_key]).exists(), msg=f"Missing {art_key}") + + # Test ablation_semantic.py --bootstrap-samples on the generated segmentation + embeddings. + import subprocess + import sys + + ablation_out = tmp_path / "ablation.json" + proc_ab = subprocess.run( + [ + sys.executable, + "scripts/ablation_semantic.py", + "--indir", + str(out_dir / "segmentation"), + "--embedding-dir", + str(out_dir / "embedding"), + "--betas", + "0,0.5", + "--bootstrap-samples", + "20", + "--output", + str(ablation_out), + ], + check=False, + capture_output=True, + text=True, + ) + self.assertEqual(proc_ab.returncode, 0, msg=proc_ab.stdout + proc_ab.stderr) + rep = json.loads(ablation_out.read_text()) + self.assertEqual(rep["bootstrap_samples"], 20) + self.assertEqual(len(rep["runs"]), 2) + for run in rep["runs"]: + self.assertIn("fragmentation_ratio_ci95", run) + self.assertEqual(len(run["fragmentation_ratio_ci95"]), 2) + self.assertIn("id_switch_rate_ci95", run) + + +if __name__ == "__main__": + unittest.main()