diff --git a/README.md b/README.md index 078d995..62d83b0 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,17 @@ ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE) -**OpenLSR-X** is a reproducible Python framework and benchmark suite for **physics- and topology-guided 2D/2.5D-to-3D Super-Resolution of X-Ray Computed Tomography (XCT)** porous-media scans using shifted-window Transformers (`SwinIR`), Residual-in-Residual Dense Blocks (`RRDB` / `RaGAN`), SRGAN, and **epistemic confidence-weighted 3-axis Fourier fusion**. Originally developed during the PhD research of **Calum Green** (Imperial College London & Diamond Light Source) and maintained by **BASE Laboratory**, OpenLSR-X bridges deep-learning super-resolution with quantitative **synchrotron beamline metrology, reactive multi-phase segmentation, and uncertainty-propagated 3D diffusive transport**. +**OpenLSR-X** is a reproducible Python framework and benchmark suite for **physics- and topology-guided 2D/2.5D-to-3D Super-Resolution of X-Ray Computed Tomography (XCT)** porous-media scans using shifted-window Transformers (`SwinIR`), Residual-in-Residual Dense Blocks (`RRDB` / `RaGAN`), SRGAN, and **confidence-weighted 3-axis Fourier fusion**. Originally developed during the PhD research of **Calum Green** (Imperial College London & Diamond Light Source) and maintained by **BASE Laboratory**, OpenLSR-X bridges deep-learning super-resolution with quantitative **synchrotron beamline metrology, reactive multi-phase segmentation, and uncertainty-propagated 3D diffusive transport**. --- ## Highlights -- **2D & `2.5D` Training → Uncertainty-Aware Isotropic 3D Reconstruction:** Train memory-efficient `1`-slice or `2k + 1` multi-slice (`2.5D`) generators (`SwinIR`, `RRDB` + `RaGAN`, `SRGAN`/`SRResNet`) alongside native `SR3DResNet` baselines across integer and fractional synchrotron optical magnifications (`2x`, `2.5x`, `4x`), and fuse orthogonal sweeps (`yz + xz + xy`) via **Confidence-Weighted Directional Fourier Fusion** (`confidence_fourier`) with zero-overhead voxel-wise epistemic uncertainty $\sigma_{\text{ortho}}(\mathbf{x})$. -- **Physics- & Topology-Preserving Objectives:** Combines Beer–Lambert **X-ray attenuation conservation** (`AttenuationConservationLoss`), differentiable **3D pore-throat skeleton preservation** (`SoftCLDiceLoss`), 2D/3D **Sobel phase-boundary sharpness** (`SobelGradientLoss`), and **Focal Frequency Loss** (`FocalFrequencyLoss`). -- **Leakage-Free 3D Spatial Splitting:** Enforces strictly disjoint 3D sub-volume slabs (with configurable guard margins and per-axis boundary-safe `2.5D` reflect padding) across `train`, `val`, and `test`. -- **Synchrotron Spectral, Petrophysical & Diffusive Transport Metrology:** Evaluates **3D Fourier Shell Correlation (FSC)** & **2D Fourier Ring Correlation (FRC)** (`1/2`-bit and `0.143` effective resolution in $\mu\text{m}$), tri-phase `Zn-13X` reactive core-rim segmentation (`Macropore` / `Na-13X` / `Zn-13X`), porosity/Euler/surface-area metrics, quasi-static drainage capillary pressure $P_c(S_w)$, and **3D steady-state Laplace diffusive tortuosity** ($D_{\text{eff}} / D_0$, $\tau$) with epistemic uncertainty intervals $[D_{\text{eff}}^-, D_{\text{eff}}^+]$ and direct **OpenImpala** export. -- **Out-of-the-Box Benchmarks & Open Synchrotron Profiles:** Ships with deterministic **Factorial PoreSpy** benchmarks, **Open Rock Micro-CT** (Bentheimer Sandstone & Indiana Limestone), and automated Zenodo staging + calibrated phantoms for the open Diamond Light Source I13-2 multi-resolution `Zn-13X` dataset ([*Scientific Data*, 2025](https://doi.org/10.1038/s41597-025-04605-9)). +- **Cell-Centered 2D & `2.5D` Training → Isotropic 3D Reconstruction:** Train memory-efficient `1`-slice or native-LR-strided `2k + 1` multi-slice (`2.5D`) generators (`SwinIR`, `RRDB` + `RaGAN`, `SRGAN`/`SRResNet`) alongside native `SR3DResNet` baselines across integer and fractional synchrotron optical magnifications (`2x`, `2.5x`, `4x`, `8x`), and fuse cell-centered (`grid_mode=True`) orthogonal sweeps (`yz + xz + xy`) via **Confidence-Weighted Directional Fourier Fusion** (`confidence_fourier`) with zero-overhead voxel-wise **orthogonal view-disagreement uncertainty** $\sigma_{\text{ortho}}(\mathbf{x})$ ($n=3$ views). +- **Physics- & Topology-Guided Objectives:** Combines **linear-attenuation ($\mu$) downsampling consistency** (`AttenuationConservationLoss`, with `2.5D` through-plane $z$-PSF curvature correction), differentiable **bimodal pore-throat skeleton preservation** (`SoftCLDiceLoss`), 2D/3D **Sobel phase-boundary sharpness** (`SobelGradientLoss`), and **Focal Frequency Loss** (`FocalFrequencyLoss`). +- **Split-Isolated 3D Spatial Splitting & Normalization:** Partitions 3D volumes into disjoint sub-volume slabs (separated by PSF guard margins) *before* fitting intensity normalization bounds on `train` only and *before* per-split synthetic PSF degradation. +- **Synchrotron Spectral, Petrophysical & Diffusive Transport Metrology:** Evaluates **3D Fourier Shell Correlation (FSC)** & **2D Fourier Ring Correlation (FRC)** (`FSC = 0.5` prediction-vs-reference crossover frequency & spectral AUC), ground-truth-thresholded porosity/Euler/surface-area metrics, tri-phase `Zn-13X` reactive core-rim segmentation (`Macropore` / `Na-13X` / `Zn-13X`), quasi-static drainage capillary pressure $S_{\text{nwp}}(P_c)$, and residual-verified **3D steady-state Laplace diffusive tortuosity** ($D_{\text{eff}} / D_0$, $\tau$) with view-disagreement sensitivity bounds $[D_{\text{eff}}^-, D_{\text{eff}}^+]$ and direct **OpenImpala** export. +- **Provenance-Verified Open Benchmarks:** Ships with deterministic **Factorial PoreSpy** benchmarks, **Open Rock Micro-CT** (Bentheimer Sandstone from Zenodo `5542624` & calibrated carbonate phantom), and coaxial sub-voxel-registered Zenodo staging (`10.5281/zenodo.14245751`) + explicit provenance tracking (`source_kind`, `is_experimental_xct`) for the Diamond Light Source I13-2 multi-resolution `Zn-13X` dataset ([*Scientific Data*, 2025](https://doi.org/10.1038/s41597-025-04605-9)). --- @@ -31,19 +31,30 @@ uv venv --python 3.11 uv pip install -e ".[dev,docs]" ``` -### 2. Train, Test, and Predict via Unified CLI +### 2. Train, Reconstruct 3D Volumes, and Evaluate via Unified CLI -Train the physics- and topology-guided `2.5D SwinIR` configuration on Diamond Light Source I13-2 `Zn-13X` (`2x`) or synthetic PoreSpy media: +Stage the Diamond Light Source I13-2 `Zn-13X` (`2x` & `8x`) benchmark (pass `--offline` on air-gapped nodes for explicit synthetic phantoms) and train the multi-axis `2.5D SwinIR` configuration: ```bash -openlsrx download-zn13x --synthetic-fallback +openlsrx download-zn13x --dest data/benchmarks openlsrx fit -c configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml ``` +Run standalone 3-axis orthogonal `confidence_fourier` super-resolution + view-disagreement uncertainty export on any 3D LR volume: + +```bash +openlsrx predict-volume \ + --ckpt lightning_logs/version_0/checkpoints/last.ckpt \ + --input data/benchmarks/zn13x_2x_lr.tif \ + --output-dir results/zn13x_2x_sr \ + --fusion confidence_fourier \ + --save-uncertainty +``` + Prepare open rock micro-CT benchmark stacks and train on Bentheimer Sandstone: ```bash -openlsrx download-benchmarks +openlsrx download-benchmarks --dest data/benchmarks openlsrx fit -c configs/labxct/bs_config.yaml ``` @@ -51,32 +62,32 @@ Evaluate image-fidelity, petrophysical, 3D FSC spectral, tri-phase `Zn-13X`, and ```bash openlsrx evaluate \ - --pred predicted_stack.tiff \ - --target high_res_stack.tiff \ + --pred results/zn13x_2x_sr/zn13x_2x_lr_sr_confidence_fourier.tif \ + --target data/benchmarks/zn13x_2x_hr.tif \ --voxel-size 0.8125 \ --include-transport \ --include-spectral \ --include-triphase \ - --export-openimpala outputs/openimpala_ready \ - --output metrics.json + --export-openimpala-dir results/openimpala_ready \ + --output results/metrics.json ``` --- ## Reproducing Manuscript Benchmarks -Run the Factorial PoreSpy, Open Rock Micro-CT, and 7-arm Diamond I13-2 `Zn-13X` studies and generate publication-ready LaTeX `booktabs` tables and 300-DPI comparison figures: +Run the Factorial PoreSpy, Open Rock Micro-CT, and 9-arm Diamond I13-2 `Zn-13X` studies and generate publication-ready LaTeX `booktabs` tables and comparison figures (production runs fail loudly if real Zenodo/HDF5 data are unavailable unless `--allow-synthetic-fallback` is explicitly passed): ```bash -# Rapid CPU smoke verification (~2 minutes) +# Rapid offline CPU smoke verification (~2 minutes; explicitly labeled synthetic phantoms) python scripts/benchmarks/porespy_study.py --fast python scripts/benchmarks/public_rock_xct.py --fast python scripts/benchmarks/zn13x_synchrotron_study.py --fast -python scripts/benchmarks/aggregate_campaign.py --inputs outputs --output-dir outputs/campaign_summary +python scripts/benchmarks/aggregate_campaign.py --inputs results --output-dir results/campaign_summary -# Full multi-seed GPU campaign (see docs/npj-study-design.md) -python scripts/benchmarks/zn13x_synchrotron_study.py --volume-size 256 --epochs 300 --seeds 42 43 44 -python scripts/benchmarks/aggregate_campaign.py --inputs outputs --output-dir outputs/campaign_summary +# Full multi-seed GPU campaign on real Zenodo / beamline HDF5 data (see docs/npj-study-design.md) +python scripts/benchmarks/zn13x_synchrotron_study.py --lr-size 48 --epochs 120 --seeds 42 43 44 +python scripts/benchmarks/aggregate_campaign.py --inputs results --output-dir results/campaign_summary ``` --- @@ -90,17 +101,17 @@ OpenLSR-X/ ├── paper/ # JOSS manuscript (paper.md) and bibliography (paper.bib) ├── scripts/ │ ├── benchmarks/ # PoreSpy, Rock XCT & I13-2 Zn-13X runners + multi-seed campaign aggregator -│ └── hpc/ # SLURM and SGE ('Young') GPU batch templates +│ └── hpc/ # Isambard-AI GH200 SLURM array, generic SLURM, and SGE ('Young') templates ├── src/openlsrx/ -│ ├── baselines/ # 2D & 3D classical interpolation baselines (Nearest, Trilinear, Tricubic, Lanczos) -│ ├── data/ # PoreSpy, Rock XCT, DLS I13-2 Zn-13X loaders & 2.5D leakage-free 3D splitting -│ ├── inference/ # Single-axis, 3-axis Fourier, and epistemic confidence-weighted 3D fusion -│ ├── io/ # OpenImpala 3D TIFF + .inputs deck exporter -│ ├── losses/ # Attenuation conservation, soft-clDice topology, Sobel, FFL, RaGAN & VGGLoss -│ ├── metrics/ # 2D/3D PSNR/SSIM, 3D FSC / 2D FRC, tri-phase petrophysics & 3D Laplace transport +│ ├── baselines/ # Cell-centered 2D & 3D classical interpolation baselines +│ ├── data/ # PoreSpy, Rock XCT, DLS I13-2 Zn-13X loaders & split-isolated 2.5D datasets +│ ├── inference/ # Cell-centered single-axis, 3-axis Fourier, and confidence-weighted 3D fusion +│ ├── io/ # OpenImpala 3D TIFF + AMReX .inputs deck exporter +│ ├── losses/ # Attenuation consistency, soft-clDice topology, Sobel, FFL & VGGLoss +│ ├── metrics/ # 2D/3D PSNR/SSIM, 3D FSC / 2D FRC, HR-locked petrophysics & 3D Laplace transport │ ├── models/ # SwinIRGenerator, RRDBGenerator, SRGAN/SRResNet, and native SR3DResNet │ └── cli.py # Unified `openlsrx` CLI entrypoint -└── tests/ # 71 unit, analytical physics/spectral/transport, Lightning & CLI tests (>90% cov) +└── tests/ # Comprehensive unit, analytical physics/spectral/transport & red-team regression suite ``` --- diff --git a/configs/base/config.yaml b/configs/base/config.yaml index 5aea1e6..3d7ebcc 100644 --- a/configs/base/config.yaml +++ b/configs/base/config.yaml @@ -11,7 +11,7 @@ trainer: model: learning_rate: 1.0e-4 - adaptive_size: 16 + adaptive_size: 8 accumulate_n_batches: 1 super_res_factor: 2 num_blocks: 10 diff --git a/configs/base/srresnet_ablation.yaml b/configs/base/srresnet_ablation.yaml index f7895fd..2bc5de9 100644 --- a/configs/base/srresnet_ablation.yaml +++ b/configs/base/srresnet_ablation.yaml @@ -11,7 +11,7 @@ trainer: model: learning_rate: 1.0e-4 - adaptive_size: 16 + adaptive_size: 8 accumulate_n_batches: 1 super_res_factor: 2 num_blocks: 10 diff --git a/configs/i13-xct/i13_predict_config.yaml b/configs/i13-xct/i13_predict_config.yaml index 4196332..8d7a014 100644 --- a/configs/i13-xct/i13_predict_config.yaml +++ b/configs/i13-xct/i13_predict_config.yaml @@ -9,7 +9,7 @@ trainer: model: learning_rate: 1.0e-5 - adaptive_size: 40 + adaptive_size: 8 super_res_factor: 2 num_blocks: 10 sample_id: Zn13X @@ -28,6 +28,8 @@ data: low_y_range: [1010, 1650] low_x_range: [858, 1498] predict_axis: xy + predict_mode: orthogonal_3axis + predict_fusion: confidence_fourier eval_batch_size: 2 num_workers: 0 seed: 42 diff --git a/configs/i13-xct/i13_xct_config.yaml b/configs/i13-xct/i13_xct_config.yaml index 5374750..0dcdeac 100644 --- a/configs/i13-xct/i13_xct_config.yaml +++ b/configs/i13-xct/i13_xct_config.yaml @@ -12,7 +12,7 @@ trainer: model: learning_rate: 1.0e-5 - adaptive_size: 40 + adaptive_size: 8 accumulate_n_batches: 1 super_res_factor: 2 num_blocks: 10 @@ -32,8 +32,8 @@ data: norm_mode: fixed low_vmin: -5.23e-4 low_vmax: 1.11e-3 - high_vmin: -2.50e-4 - high_vmax: 6.79e-4 + high_vmin: -5.23e-4 + high_vmax: 1.11e-3 low_z_range: [845, 1485] low_y_range: [1010, 1650] low_x_range: [858, 1498] diff --git a/configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml b/configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml index 537ed61..15c7f07 100644 --- a/configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml +++ b/configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml @@ -44,7 +44,7 @@ data: train_frac: 0.70 val_frac: 0.15 guard_slices_lr: 1 - train_axes: ["yz"] + train_axes: ["yz", "xz", "xy"] test_axis: perpendicular predict_axis: xy patch_size_lr: 32 diff --git a/configs/labxct/bs_config.yaml b/configs/labxct/bs_config.yaml index 53a35d0..e658443 100644 --- a/configs/labxct/bs_config.yaml +++ b/configs/labxct/bs_config.yaml @@ -13,7 +13,7 @@ trainer: model: learning_rate: 5.0e-5 - adaptive_size: 16 + adaptive_size: 8 accumulate_n_batches: 1 super_res_factor: 2 num_blocks: 10 diff --git a/configs/labxct/bs_config_predict.yaml b/configs/labxct/bs_config_predict.yaml index 81d7aaa..0e32f27 100644 --- a/configs/labxct/bs_config_predict.yaml +++ b/configs/labxct/bs_config_predict.yaml @@ -9,7 +9,7 @@ trainer: model: learning_rate: 5.0e-5 - adaptive_size: 16 + adaptive_size: 8 super_res_factor: 2 num_blocks: 10 sample_id: bentsand @@ -20,7 +20,14 @@ data: high_path: data/benchmarks/bentheimer_sandstone_hr.tif degrade_from_hr: true scale_factor: 2 + psf_sigma: 0.85 + degrade_noise_std: 0.025 + norm_mode: percentile + lower_pct: 0.5 + upper_pct: 99.5 predict_axis: xz + predict_mode: orthogonal_3axis + predict_fusion: confidence_fourier eval_batch_size: 4 num_workers: 0 seed: 42 diff --git a/configs/labxct/il_config.yaml b/configs/labxct/il_config.yaml index 7ab0fe7..0ad1103 100644 --- a/configs/labxct/il_config.yaml +++ b/configs/labxct/il_config.yaml @@ -13,7 +13,7 @@ trainer: model: learning_rate: 5.0e-5 - adaptive_size: 16 + adaptive_size: 8 accumulate_n_batches: 1 super_res_factor: 2 num_blocks: 12 diff --git a/configs/labxct/il_config_predict.yaml b/configs/labxct/il_config_predict.yaml index 44eff8e..74d376b 100644 --- a/configs/labxct/il_config_predict.yaml +++ b/configs/labxct/il_config_predict.yaml @@ -9,7 +9,7 @@ trainer: model: learning_rate: 5.0e-5 - adaptive_size: 16 + adaptive_size: 8 super_res_factor: 2 num_blocks: 12 sample_id: indlime @@ -20,7 +20,14 @@ data: high_path: data/benchmarks/indiana_limestone_hr.tif degrade_from_hr: true scale_factor: 2 + psf_sigma: 0.90 + degrade_noise_std: 0.030 + norm_mode: percentile + lower_pct: 0.5 + upper_pct: 99.5 predict_axis: xz + predict_mode: orthogonal_3axis + predict_fusion: confidence_fourier eval_batch_size: 4 num_workers: 0 seed: 42 diff --git a/docs/benchmarks-and-metrics.md b/docs/benchmarks-and-metrics.md index b59b8eb..90c501c 100644 --- a/docs/benchmarks-and-metrics.md +++ b/docs/benchmarks-and-metrics.md @@ -11,19 +11,21 @@ Standard computer-vision metrics (PSNR and 2D SSIM) can favor overly smooth reco - **2D Slice SSIM & 3D Tri-Planar SSIM:** Structural Similarity averaged across `yz`, `xz`, and `xy` planes. - **MS-SSIM, MAE, and RMSE:** Multi-scale structural similarity (for slices $\ge 161$ px) and pixelwise error norms. -### 2. Petrophysical & Topological Metrics (`openlsrx.metrics.petrophysics`) -- **Porosity Error ($|\Delta\phi|$):** Absolute and relative error in segmented pore volume fraction under Otsu, Yen, or reference-locked HR thresholds. -- **Pore-Phase Dice & IoU:** Voxel-wise overlap of the segmented pore network. -- **Specific Surface Area Error ($S_v$):** Interfacial pore-grain surface area per bulk volume extracted via 3D marching cubes. -- **Euler Characteristic Density ($\chi_V$):** Topological connectivity of the 3D pore space per unit volume. -- **Inscribed Pore-Radius Wasserstein-1 Distance ($W_1$):** Earth-mover distance between exact 3D Euclidean distance transform (EDT) pore-size distributions. -- **Two-Point Correlation RMSE ($S_2(r)$):** Discrepancy in FFT-computed radially averaged two-point probability functions. +### 2. Spectral Agreement Metrics (`openlsrx.metrics.spectral`) +- **3D Fourier Shell Correlation (FSC) & 2D Fourier Ring Correlation (FRC):** Hann-apodized, window-weighted zero-DC radial spectral correlation (`rfftn`-multiplicity weighted, excluding $k=0$). +- **Prediction-vs-Reference `FSC = 0.5` Crossover (`fsc_cutoff_050_cyc_vox`, `fsc_half_pitch_050_um`) & Spectral AUC (`fsc_auc`):** Reports the spatial frequency where prediction-to-reference correlation drops below `0.5`—a blur-sensitive agreement metric appropriate for full-reference super-resolution (unlike cryo-EM `0.143` half-map thresholds, which assume two independent noisy reconstructions). + +### 3. Petrophysical & Topological Metrics (`openlsrx.metrics.petrophysics`) +- **Reference-Locked Thresholding (`threshold_true`):** Headline petrophysical and transport metrics apply the ground-truth HR threshold (`otsu`, `yen`, or `fixed`) to both `pred_vol` and `true_vol` so greyscale gain/offset bias is exposed rather than hidden (with independent `*_auto_otsu` diagnostics reported separately). +- **Porosity Error ($|\Delta\phi|$), Pore-Phase Dice & IoU:** Segmented pore volume fraction error and voxel-wise overlap. +- **Specific Surface Area Error ($S_v$) & Euler Characteristic Density ($\chi_V$):** Interfacial pore-grain surface area via 3D marching cubes and topological connectivity per unit volume. +- **Inscribed Pore-Radius Wasserstein-1 Distance ($W_1$) & Non-Periodic Two-Point Correlation RMSE ($S_2(r)$):** Exact 3D Euclidean distance transform pore-size distributions and 8-octant zero-padded non-periodic `rfftn` radial autocorrelation. - **Through-Plane Anisotropy Error:** Measures slice-stacking gradient discontinuities along the non-trained axis relative to ground-truth structural anisotropy. -### 3. 3D Pore-Scale Transport Physics (`openlsrx.metrics.transport`) -- **Directional Effective Diffusivity ($D_{\text{eff}}/D_0$) & Tortuosity ($\tau_z, \tau_y, \tau_x$):** Solves steady-state 3D Fickian Laplace diffusion ($\nabla \cdot \nabla c = 0$) across all three Cartesian directions on the 6-connected percolating pore network using a cell-centered finite-volume discretization matching `OpenImpala` and `TauFactor`. -- **Formation Factor ($F = (D_{\text{eff}}/D_0)^{-1}$) & Directional Transport Anisotropy:** Detects artificial slice-stacking bottlenecks where pores percolate in-plane (`yz`) but pinch off along the through-plane stacking axis (`x`). -- **Simulated Capillary Drainage Curve RMSE ($S_{\text{nwp}}(P_c)$):** Simulates inlet-connected morphological mercury intrusion / drainage via `PoreSpy` to quantify throat-entry capillary pressure errors. +### 4. 3D Pore-Scale Transport Physics (`openlsrx.metrics.transport`) +- **Residual-Verified Directional Effective Diffusivity ($D_{\text{eff}}/D_0$) & Tortuosity ($\tau_z, \tau_y, \tau_x$):** Solves steady-state 3D Fickian Laplace diffusion ($\nabla \cdot \nabla c = 0$) across all three Cartesian directions on the 6-connected percolating pore network using a cell-centered finite-volume discretization matching `OpenImpala` and `TauFactor`, verifying `cg` convergence (`info == 0`), relative residual norm, inlet/outlet flux conservation, and variational bounds ($0 \le D_{\text{eff}}/D_0 \le \phi_{\text{perc}}$, $\tau \ge 1$). +- **View-Disagreement Transport Sensitivity Bounds (`compute_tortuosity_uncertainty_bounds`):** Evaluates `[D_eff^-, D_eff^+]` under $\hat{V} \pm k\sigma_{\text{ortho}}$ alongside voxel-wise Spearman rank correlation between $\sigma_{\text{ortho}}$ and $|\hat{V} - V_{\text{HR}}|$. +- **Simulated Capillary Drainage Curve RMSE ($S_{\text{nwp}}(P_c)$):** Simulates inlet-connected morphological drainage via `PoreSpy` to quantify throat-entry capillary pressure errors. --- @@ -33,7 +35,7 @@ For full-volume HPC transport simulations on `AMReX` grids using [`BASE-Laborato ```bash openlsrx export-openimpala \ - --volume outputs/predicted_xy/predicted_stack.tiff \ + --volume outputs/predicted_orthogonal/predicted_stack.tiff \ --output-dir outputs/openimpala_ready \ --name zn13x_sr \ --direction x @@ -43,19 +45,18 @@ This writes both an uncompressed 8-bit phase-labeled 3D TIFF (`zn13x_sr.tif`) an --- -## 3D Orthogonal Fourier Stack Fusion & Model Backbones +## Cell-Centered 3D Orthogonal Fourier Fusion & Model Backbones -Given an isotropic low-resolution 3D scan $V_{\text{LR}} \in \mathbb{R}^{d \times h \times w}$ and a 2D generator $G_\theta$ trained only on slices from a single plane: +Given an isotropic low-resolution 3D scan $V_{\text{LR}} \in \mathbb{R}^{d \times h \times w}$ and a 2D or `2.5D` generator $G_\theta$: -1. OpenLSR-X generates three candidate super-resolved 3D volumes ($\hat{V}_{yz}, \hat{V}_{xz}, \hat{V}_{xy} \in \mathbb{R}^{D \times H \times W}$) by cubic-interpolating along each respective slicing axis and applying $G_\theta$ across the two orthogonal in-plane dimensions. -2. In 3D Fourier space, each candidate volume is weighted proportionally to its two super-resolved in-plane wavevector components: - $$W_a(\mathbf{k}) = \frac{\sum_{j \neq a} k_j^2 + \epsilon}{2\,(k_x^2 + k_y^2 + k_z^2) + 3\epsilon}$$ - suppressing low-pass interpolation blur and slice-stacking artifacts along the non-super-resolved axis of each individual pass. +1. OpenLSR-X generates three cell-centered candidate super-resolved 3D volumes ($\hat{V}_{yz}, \hat{V}_{xz}, \hat{V}_{xy} \in \mathbb{R}^{D \times H \times W}$) via `zoom_cell_centered` (`grid_mode=True`) along each slicing axis and native-LR-strided `2.5D` context windows across the two orthogonal in-plane dimensions. +2. In 3D Fourier space (`rfftn` in streaming `float32`/`complex64`), each candidate volume is weighted proportionally to its two super-resolved in-plane wavevector components (`mode="fourier"`), optionally preceded by spatial Winsorization of single-view out-of-plane blur outliers (`mode="confidence_fourier"`). -OpenLSR-X includes three neural model families for controlled ablation: +OpenLSR-X includes four neural model families for controlled ablation: +- **Shifted-Window `SwinIRGenerator` (`2D` / `2.5D`)** (`backbone="swinir"`): Windowed self-attention with native-LR-strided multi-slice context (`context_slices=3`) and multi-axis training (`train_axes=("yz", "xz", "xy")`). - **Classical `SRGAN` / `SRResNet`** (`backbone="srgan"`): Residual blocks with optional pixel/instance/batch normalization. -- **Normalization-Free `RRDBGenerator` + `RaGAN`** (`backbone="rrdb"`, `gan_loss_type="ragan"`): Preserves absolute synchrotron X-ray attenuation contrasts and supports arbitrary fractional beamline magnification ratios (e.g., $2.5\times$ for $0.8125 \to 0.325\ \mu\text{m}$ and $5\times$ for $1.625 \to 0.325\ \mu\text{m}$). -- **Native 3D CNN Baseline (`SR3DResNet`)**: Volumetric 3D residual network with raised-cosine sliding-window inference (`super_resolve_volume_3d`) for benchmarking GPU memory footprint vs. 2D + 3-Axis Fourier Fusion. +- **Normalization-Free `RRDBGenerator` + `RaGAN`** (`backbone="rrdb"`, `gan_loss_type="ragan"`): Preserves greyscale X-ray attenuation contrasts and supports arbitrary fractional beamline magnification ratios (e.g., $2.5\times$ and $5\times$). +- **Native 3D CNN Baseline (`SR3DResNet`)**: Volumetric 3D residual network with 48-element $O_h$ cubic symmetry augmentation and raised-cosine sliding-window inference (`super_resolve_volume_3d`). --- diff --git a/docs/datasets-and-configs.md b/docs/datasets-and-configs.md index 4799fb7..84984bf 100644 --- a/docs/datasets-and-configs.md +++ b/docs/datasets-and-configs.md @@ -7,11 +7,11 @@ OpenLSR-X provides two composable PyTorch Lightning `DataModule` classes selecta --- -## Leakage-Free 3D Spatial Splitting +## Split-Isolated 3D Spatial Splitting & Normalization -When evaluating 2D-trained models on orthogonal 3D XCT planes, naive random 2D slice splits leak structural information across axes because every `xy` or `xz` plane intersects all `yz` slices of the same cube. +When evaluating 2D/`2.5D`-trained models on orthogonal 3D XCT planes, naive random 2D slice splits leak structural information across axes because every `xy` or `xz` plane intersects all `yz` slices of the same cube, and whole-volume intensity normalization or PSF blurring leaks `test` statistics into `train`. -Both DataModules partition the 3D volume along `split_axis` into **strictly non-overlapping 3D slabs** (`train`, `val`, `test`) separated by `guard_slices_lr` buffer slices before extracting 2D training or orthogonal evaluation slices. +Both DataModules partition the 3D volume along `split_axis` into **strictly non-overlapping 3D slabs** (`train`, `val`, `test`) separated by `guard_slices_lr` buffer slices *before* fitting intensity normalization bounds (on `train` only) and *before* applying per-split synthetic PSF degradation, then extract cell-centered (`grid_mode=True`) 2D or native-LR-strided `2.5D` slice pairs. --- @@ -23,37 +23,38 @@ Both DataModules partition the 3D volume along `split_axis` into **strictly non- | `configs/base/srresnet_ablation.yaml` | Synthetic PoreSpy | Non-adversarial L1/CAWR generator ablation | | `configs/porespy/Low_Noise/*.yaml` | Factorial PoreSpy | Low acquisition noise × Low/High feature frequency | | `configs/porespy/High_Noise/*.yaml` | Factorial PoreSpy | High acquisition noise × Low/High feature frequency | -| `configs/labxct/bs_config.yaml` | Bentheimer Sandstone | Well-sorted quartz sandstone (~22% intergranular porosity) | -| `configs/labxct/il_config.yaml` | Indiana Limestone | Bimodal vuggy + microporous carbonate (~18% total porosity) | -| `configs/i13-xct/i13_xct_config.yaml` | Diamond I13 (`Zn13X`) | Raw Savu TomopyRecon HDF5/NeXus template with ROI crops | +| `configs/labxct/bs_config.yaml` | Bentheimer Sandstone | Well-sorted quartz sandstone (~22% intergranular porosity, Zenodo `5542624`) | +| `configs/labxct/il_config.yaml` | Indiana Limestone | Calibrated bimodal vuggy + microporous carbonate phantom (~18% total porosity) | +| `configs/i13-xct/i13_xct_config.yaml` | Diamond I13 (`Zn13X`) | Raw Savu TomopyRecon HDF5/NeXus template with joint `[vmin, vmax]` calibration | | `configs/i13-xct/zn13x_2x_1625_to_08125.yaml` | Diamond I13 (`Zn13X` $2\times$) | Experimental $4\times$ ($1.625\ \mu\text{m}$) $\to 8\times$ ($0.8125\ \mu\text{m}$) aligned slab | +| `configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml` | Diamond I13 (`Zn13X` $2\times$) | Multi-axis `2.5D SwinIR` + physics/topology losses + `confidence_fourier` fusion | | `configs/i13-xct/zn13x_8x_2600_to_0325.yaml` | Diamond I13 (`Zn13X` $8\times$) | Experimental $2.5\times$ ($2.600\ \mu\text{m}$) $\to 20\times$ ($0.325\ \mu\text{m}$) aligned slab | --- ## Preparing Open Rock & Diamond I13-2 `Zn-13X` Benchmarks -Run the built-in fetcher to prepare `bentheimer_sandstone`, `indiana_limestone`, and aligned Diamond Light Source I13-2 `Zn-13X` ($2\times$ & $8\times$) 3D reference volumes with SHA-256 provenance manifests: +Run the built-in fetcher to prepare `bentheimer_sandstone`, `indiana_limestone`, and coaxial sub-voxel-registered Diamond Light Source I13-2 `Zn-13X` ($2\times$ & $8\times$) 3D reference volumes with SHA-256 provenance manifests: ```bash -# Prepare laboratory rock benchmarks (Bentheimer & Indiana Limestone) +# Prepare laboratory rock benchmarks (Bentheimer from Zenodo 5542624 & calibrated carbonate phantom) openlsrx download-benchmarks --dest data/benchmarks --size 128 -# Prepare Diamond Light Source I13-2 Zn-13X synchrotron pairs (from local .h5, Zenodo, or calibrated phantom) -openlsrx download-benchmarks --datasets zn13x_2x zn13x_8x --dest data/benchmarks --size 96 +# Prepare Diamond Light Source I13-2 Zn-13X synchrotron pairs (from local .h5 or Zenodo 14245751) +openlsrx download-zn13x --dest data/benchmarks --lr-size 48 ``` -When running on air-gapped HPC compute nodes without outbound internet access (and when `--raw-h5-dir` is not supplied), `download-benchmarks` automatically synthesizes calibrated digital-rock and two-phase `Zn-13X` synchrotron phantoms and records `"source_kind"` in `_manifest.json`. +Cache validation checks requested size, local `--raw-h5-dir`, and online vs. `--offline` mode so a cached offline smoke phantom never masks real experimental data. Synthetic fallback manifests omit experimental Zenodo DOIs and set `"is_experimental_xct": false`, while full benchmark scripts fail loudly by default unless `--allow-synthetic-fallback` is passed. --- -## Vectorized 3D Registration for Multi-Magnification Synchrotron Scans +## Sub-Voxel 3D Registration for Multi-Magnification Synchrotron Scans -Experimental multi-magnification XCT scans suffer from sub-millimetre stage drift and distinct scintillator point-spread functions across objectives. `openlsrx.data.register_multires_pair_3d` and `openlsrx.data.extract_aligned_slab_from_h5` perform: +Experimental multi-magnification XCT scans exhibit sub-millimetre stage drift and distinct scintillator point-spread functions across objectives. `openlsrx.data.register_multires_pair_3d` and `openlsrx.data.extract_aligned_slab_from_h5` perform: -1. Chunked ROI slab extraction directly from $>50\ \text{GB}$ Savu `4-TomopyRecon-tomo/data` HDF5 files without loading full cubes into host RAM. -2. Calibrated attenuation normalization using verified I13-2 dynamic bounds. -3. Coarse-grid 3D FFT phase cross-correlation (`skimage.registration.phase_cross_correlation`) followed by local 3D SSIM refinement to produce strictly shape-matched `(LR, HR)` slabs. +1. On-disk HDF5 ROI hyperslab slicing directly from $>50\ \text{GB}$ Savu `4-TomopyRecon-tomo/data` files (or coaxial center-ROI cropping of Zenodo `14245751` `16906*_8bit_cropped.h5` sub-volumes) without loading full cubes into host RAM. +2. Joint physical attenuation normalization using shared `[vmin, vmax]` calibration bounds across LR and HR scans. +3. HR-grid sub-voxel 3D FFT phase cross-correlation (`upsample_factor=4`, accurate to $\le 0.25$ HR voxels) followed by sub-voxel cubic shift interpolation and normalized cross-correlation quality verification (`registration_quality_ok`). --- diff --git a/docs/getting-started.md b/docs/getting-started.md index 99014fb..cb0d0dc 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -48,22 +48,34 @@ openlsrx fit -c configs/base/config.yaml \ --data.init_args.noise_regime high_noise ``` -### 2. Resume or Predict from a Checkpoint +### 2. Reconstruct 3D Volumes from a Checkpoint + +Run 3-axis orthogonal fusion (`predict_mode: orthogonal_3axis` by default) via LightningCLI `predict` or the standalone `predict-volume` subcommand: ```bash openlsrx predict -c configs/porespy/Predict/ps_predict_config.yaml \ - --ckpt_path lightning_logs/version_0/checkpoints/last.ckpt \ - --data.init_args.predict_axis xz + --ckpt_path lightning_logs/version_0/checkpoints/last.ckpt +``` + +```bash +openlsrx predict-volume \ + --ckpt lightning_logs/version_0/checkpoints/last.ckpt \ + --input data/benchmarks/zn13x_2x_lr.tif \ + --output-dir outputs/zn13x_sr \ + --fusion confidence_fourier \ + --save-uncertainty ``` -Predictions are exported cleanly under your run's output directory as both individual 2D `.tiff` slices and assembled 3D multi-page BigTIFF stacks (`*_predicted_stack.tiff`, `*_low_res_stack.tiff`, `*_high_res_stack.tiff`). +In `orthogonal_3axis` mode, predictions are exported under `/predicted_orthogonal/` as assembled 3D `(Z, Y, X)` multi-page BigTIFF stacks (`*_predicted_stack.tiff`, `*_uncertainty_std.tiff`, `*_low_res_stack.tiff`, and `*_high_res_stack.tiff` when paired). -### 3. Evaluate Petrophysical & Image Metrics +### 3. Evaluate Petrophysical, Spectral & Transport Metrics ```bash openlsrx evaluate \ - --pred outputs/predicted_xz/ps_predict_predicted_stack.tiff \ - --target outputs/predicted_xz/ps_predict_high_res_stack.tiff \ + --pred outputs/predicted_orthogonal/ps_predict_predicted_stack.tiff \ + --target outputs/predicted_orthogonal/ps_predict_high_res_stack.tiff \ + --include-spectral \ + --include-transport \ --output results/eval_report.json ``` @@ -73,5 +85,6 @@ openlsrx evaluate \ Ready-to-customize batch scripts are provided in `scripts/hpc/`: -- **SLURM clusters:** `sbatch scripts/hpc/slurm_train.sh configs/porespy/High_Noise/ps_hn_hf_config.yaml` +- **Isambard-AI (`GH200` SLURM array):** `sbatch scripts/hpc/isambard_ai_array.slurm` +- **Generic SLURM clusters:** `sbatch scripts/hpc/slurm_train.sh configs/porespy/High_Noise/ps_hn_hf_config.yaml` - **Sun Grid Engine (e.g., UCL MMM Hub `Young`):** `qsub -v CONFIG_PATH=configs/labxct/bs_config.yaml scripts/hpc/sge_young_train.sh` diff --git a/docs/npj-study-design.md b/docs/npj-study-design.md index 749c363..6d784a6 100644 --- a/docs/npj-study-design.md +++ b/docs/npj-study-design.md @@ -6,26 +6,26 @@ This guide documents the scientific thesis, methodology equations, ablation matr ## Working Title -> **Physics-Consistent 2.5D Orthogonal Super-Resolution with Epistemic Uncertainty for Multi-Magnification Synchrotron Tomography and Pore-Scale Transport** +> **Physics-Guided 2.5D Orthogonal Super-Resolution and View-Disagreement Transport Uncertainty for Multi-Magnification Synchrotron Tomography** --- ## 150-Word Draft Abstract -Quantitative X-ray computed tomography (XCT) of functional porous materials at synchrotron beamlines is fundamentally constrained by the hardware coupling between spatial resolution, field of view (FOV), and X-ray dose. Existing deep super-resolution methods either suffer from cubic memory scaling in 3D convolutional networks or rely on 2D natural-image generative adversarial priors that violate linear attenuation conservation and hallucinate disconnected pore throats without uncertainty estimates. Here we introduce a physics-consistent 2.5D-to-3D orthogonal super-resolution framework (`OpenLSR-X`) integrating shifted-window self-attention (`SwinIR`), coarse-voxel X-ray attenuation conservation, and differentiable soft-skeleton (`soft-clDice`) pore-throat topology supervision. Exploiting three-axis orthogonal sweeps (`yz`, `xz`, `xy`), our confidence-weighted 3D Fourier synthesis yields zero-overhead voxel-wise epistemic uncertainty maps that localize sub-resolution bottlenecks and propagate directly into calibrated 3D Fickian diffusive tortuosity bounds. Validated on paired multi-magnification Diamond Light Source I13-2 synchrotron tomograms of reactive Zn-doped Zeolite 13X (`2×` and `8×` scale jumps), our approach recovers effective Fourier Shell Correlation resolution, tri-phase `Pore / Na-13X / Zn-13X` ion-exchange stoichiometry, and pore-scale diffusivity at gigavoxel throughput. +Quantitative X-ray computed tomography (XCT) of functional porous materials at synchrotron beamlines is constrained by the hardware coupling between spatial resolution, field of view (FOV), and X-ray dose. Existing deep super-resolution methods either incur cubic memory scaling in 3D convolutional networks or rely on 2D natural-image adversarial priors that distort greyscale attenuation consistency and pinch off sub-micron pore throats without diagnostic error indicators. Here we introduce a cell-centered `2.5D`-to-3D orthogonal super-resolution framework (`OpenLSR-X`) combining multi-axis shifted-window self-attention (`SwinIR`), linear-attenuation downsampling consistency (`2.5D` $z$-PSF corrected), and differentiable soft-skeleton (`soft-clDice`) pore-throat topology supervision. Across three orthogonal sweeps (`yz`, `xz`, `xy`), outlier-suppressed 3D Fourier synthesis yields zero-overhead voxel-wise view-disagreement maps $\sigma_{\text{ortho}}(\mathbf{x})$ that correlate spatially with reconstruction error and propagate into 3D Fickian diffusive tortuosity sensitivity bounds. Evaluated on sub-voxel-registered multi-magnification Diamond Light Source I13-2 tomograms of reactive Zn-doped Zeolite 13X (`2×` and `8×`), our method improves reference `FSC = 0.5` spectral recovery, tri-phase `Pore / Na-13X / Zn-13X` segmentation, and pore-scale diffusivity fidelity. --- ## Four Core Contributions (Addressing *npj Computational Materials* Criteria) -1. **Zero-Overhead Voxel-Wise Epistemic Uncertainty $\sigma_{\text{ortho}}(\mathbf{x}) \to \tau \pm \Delta\tau$:** - Unlike 3D CNNs or $50\times$-slower conditional diffusion samplers, three-axis orthogonal reconstruction naturally measures directional epistemic disagreement across perpendicular high-resolution planes. Propagating $\hat{V} \pm \sigma_{\text{ortho}}$ through 3D finite-volume Fickian Laplace diffusion (`solve_steady_state_diffusion_axis` / `OpenImpala`) yields **calibrated transport error bars** on unseen low-magnification full-pellet tomograms. -2. **Domain-Grounded Tomographic Physics & Topology Supervision:** - Replaces RGB ImageNet `VGG-19` perceptual priors with `AttenuationConservationLoss` (preserving quantitative 27 keV linear attenuation per coarse scintillator PSF voxel), `SoftCLDiceLoss` (preventing GAN throat pinch-off), and `FocalFrequencyLoss`. -3. **2.5D Windowed Self-Attention (`SwinIR-2.5D`) + Confidence-Fourier Synthesis:** - Provides local through-plane `[z-1, z, z+1]` context at `< 0.3%` parameter overhead over 2D models while avoiding $O(N^3)$ 3D patch stitching, paired with hybrid `confidence_fourier` fusion that suppresses single-axis out-of-plane blur at sharp phase boundaries. -4. **Beamline `3D FSC` Metrology & Tri-Phase Reactive Zeolite Validation (`Zn-13X`):** - Evaluates half-bit and $0.143$ **3D Fourier Shell Correlation (`compute_fsc_3d`)** cutoffs alongside three-phase (`Macropore` / `Na-13X Core` / `Zn-Exchanged Shell`) segmentation fidelity on the open multimodal Diamond I13-2 benchmark (Green et al., *Sci. Data* 2025, `10.1038/s41597-025-04605-9`). +1. **Zero-Overhead Orthogonal View-Disagreement Uncertainty $\sigma_{\text{ortho}}(\mathbf{x}) \to [D_{\text{eff}}^-, D_{\text{eff}}^+]$:** + Three-axis orthogonal reconstruction ($n=3$ sweeps) naturally measures inter-view disagreement between in-plane super-resolution and through-plane structure at sub-resolution interfaces. We evaluate $\sigma_{\text{ortho}}(\mathbf{x})$ rigorously via voxel-wise Spearman rank correlation against ground-truth error $|\hat{V} - V_{\text{HR}}|$ and empirical ground-truth $D_{\text{eff}}$ bracketing rates under $\hat{V} \pm k\sigma_{\text{ortho}}$ sensitivity propagation (`solve_steady_state_diffusion_axis` / `OpenImpala`). +2. **Domain-Grounded Tomographic Attenuation & Topology Supervision:** + Replaces RGB ImageNet `VGG-19` perceptual priors with `AttenuationConservationLoss` (enforcing joint-calibrated linear-attenuation $\mu$ downsampling consistency with a `2.5D` through-plane $z$-PSF Laplacian correction), bimodal `SoftCLDiceLoss` (preventing pore-throat pinch-off), and `FocalFrequencyLoss`. +3. **Multi-Axis Native-LR-Strided `SwinIR-2.5D` + Outlier-Suppressed Fourier Synthesis:** + Samples `[z - s, z, z + s]` neighbors at true physical LR slice spacing ($\pm \Delta z_{\text{LR}}$) across all three training orientations (`train_axes=("yz", "xz", "xy")`) at `< 0.3%` parameter overhead over 2D models, paired with Winsorized `confidence_fourier` fusion tested in a controlled 9-arm stepwise ablation ladder (`SwinIR-2.5D-L1-Fourier` $\to$ `+Physics-Fourier` $\to$ `+ConfFourier`). +4. **Full-Reference `3D FSC` Metrology & Tri-Phase Reactive Zeolite Validation (`Zn-13X`):** + Evaluates blur-sensitive prediction-vs-reference **`FSC = 0.5` crossover frequencies and spectral AUC (`compute_fsc_3d`)** alongside reference-locked petrophysics and three-phase (`Macropore` / `Na-13X Core` / `Zn-Exchanged Shell`) segmentation fidelity on coaxial sub-voxel-registered Diamond I13-2 scans (Green et al., *Sci. Data* 2025, `10.1038/s41597-025-04605-9`). --- @@ -33,12 +33,12 @@ Quantitative X-ray computed tomography (XCT) of functional porous materials at s | Figure | Content & Scientific Message | Generated By | | :--- | :--- | :--- | -| **Fig. 1** | **FOV–Resolution–Dose Trade-off & Architecture:** Diamond I13-2 multi-magnification optics (`2.60 -> 0.325 um`), `2.5D` `SwinIR` trunk, physics/topology losses, and `Confidence-Fourier` + $\sigma_{\text{ortho}}$ pipeline. | Schematic + `quickstart_walkthrough.py` | -| **Fig. 2** | **Paired Synchrotron Visual & Spectral Fidelity (`2×` and `8×`):** Cross-sections (`xy`, `xz`, `yz`), radial **3D FSC curves** with $1/2$-bit cutoffs proving true spatial frequency recovery vs. GAN hallucination. | `compute_fsc_3d` + `zn13x_synchrotron_study.py` | -| **Fig. 3** | **Tri-Phase Reactive `Zn-13X` Ion-Exchange Fidelity:** Three-phase segmentation (`Macropore`, `Na-13X` core, `Zn-13X` shell), radial Zn exchange profile, and attenuation histogram conservation. | `evaluate_triphase_zn13x_metrics` | -| **Fig. 4** | **Orthogonal Epistemic Uncertainty Calibration:** Spatial co-localization of $\sigma_{\text{ortho}}(\mathbf{x})$ with actual HR error $|\hat{V} - V_{\text{HR}}|$ at sub-voxel pore throats (Spearman $\rho$) and outlier suppression under `confidence_fourier` fusion. | `compute_orthogonal_uncertainty` | -| **Fig. 5** | **3D Pore-Scale Diffusive Tortuosity & Capillary Drainage:** Steady-state concentration fields $c(\mathbf{x})$, $D_{\text{eff}}/D_0$ & $\tau$ parity plots with $\pm 1\sigma_{\text{ortho}}$ transport envelopes, and simulated mercury/non-wetting drainage $S_{\text{nwp}}(P_c)$ curves. | `evaluate_transport_metrics` + `compute_tortuosity_uncertainty_bounds` + `OpenImpala` | -| **Fig. 6** | **Compute/VRAM Scaling & Ablation Pareto Frontier:** GPU memory, inference wall-time extrapolated to $2160 \times 2560^2$ full-field synchrotron tomograms, and loss/backbone ablations (`SRGAN` vs `RRDB-RaGAN` vs `SR3DResNet` vs `SwinIR-2.5D + Physics`). | `aggregate_campaign.py` (`campaign_tradeoffs.png` & `campaign_table.tex`) | +| **Fig. 1** | **FOV–Resolution–Dose Trade-off & Architecture:** Diamond I13-2 multi-magnification optics (`2.60 -> 0.325 um`), cell-centered `2.5D` `SwinIR` trunk, physics/topology losses, and `Confidence-Fourier` + $\sigma_{\text{ortho}}$ pipeline. | Schematic + `quickstart_walkthrough.py` | +| **Fig. 2** | **Paired Synchrotron Visual & Spectral Fidelity (`2×` and `8×`):** Cross-sections (`xy`, `xz`, `yz`), radial **3D FSC curves** with `FSC = 0.5` reference crossovers and spectral AUC quantifying spatial frequency recovery. | `compute_fsc_3d` + `zn13x_synchrotron_study.py` | +| **Fig. 3** | **Tri-Phase Reactive `Zn-13X` Ion-Exchange Fidelity:** Three-phase segmentation (`Macropore`, `Na-13X` core, `Zn-13X` shell), phase volume-fraction conservation, and joint-calibrated attenuation histograms. | `evaluate_triphase_zn13x_metrics` | +| **Fig. 4** | **Orthogonal View-Disagreement Diagnostics:** Spatial co-localization of $\sigma_{\text{ortho}}(\mathbf{x})$ with actual HR error $|\hat{V} - V_{\text{HR}}|$ at sub-voxel pore throats (Spearman $\rho$) and single-view outlier suppression under `confidence_fourier` fusion. | `compute_orthogonal_uncertainty` | +| **Fig. 5** | **3D Pore-Scale Diffusive Tortuosity & Capillary Drainage:** Converged steady-state concentration fields $c(\mathbf{x})$, $D_{\text{eff}}/D_0$ & $\tau$ parity plots with $\pm k\sigma_{\text{ortho}}$ sensitivity bounds and empirical bracketing rates, plus simulated drainage $S_{\text{nwp}}(P_c)$ curves. | `evaluate_transport_metrics` + `compute_tortuosity_uncertainty_bounds` + `OpenImpala` | +| **Fig. 6** | **Compute/VRAM Scaling & 9-Arm Controlled Stepwise Ablation:** GPU memory, inference wall-time, and controlled stepwise ablations (`SRResNet` vs `SR3DResNet` vs `SRGAN` vs `RRDB-RaGAN` vs `SwinIR-2.5D-L1` vs `+Physics` vs `+ConfFourier`). | `aggregate_campaign.py` (`campaign_tradeoffs.png` & `campaign_table.tex`) | --- @@ -46,7 +46,8 @@ Quantitative X-ray computed tomography (XCT) of functional porous materials at s 1. **Stage Real Diamond I13-2 `Zn-13X` Zenodo Sub-Volumes (`14245751` or raw `169065`–`169068` HDF5):** ```bash - uv run openlsrx download-benchmarks --datasets zn13x_2x zn13x_8x --output-dir data/benchmarks + openlsrx download-zn13x --dest data/benchmarks --lr-size 48 + openlsrx download-benchmarks --dest data/benchmarks --size 128 ``` 2. **Launch Multi-Seed Array Campaign on Isambard-AI (`GH200`):** ```bash @@ -54,11 +55,11 @@ Quantitative X-ray computed tomography (XCT) of functional porous materials at s ``` Or train the flagship configuration directly via CLI: ```bash - uv run openlsrx fit --config configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml + openlsrx fit --config configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml ``` 3. **Aggregate Multi-Seed Statistics, Booktabs LaTeX Tables & Pareto Figures:** ```bash - uv run python scripts/benchmarks/aggregate_campaign.py \ + python scripts/benchmarks/aggregate_campaign.py \ --inputs results \ --output-dir results/campaign_summary ``` diff --git a/docs/tutorial.md b/docs/tutorial.md index 7c9c748..b689753 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -52,7 +52,7 @@ dm.setup() # 2. Configure compact 2D SRGAN with generator warmup model = SRGAN( - adaptive_size=6, + adaptive_size=8, super_res_factor=2, num_blocks=4, out_channels=32, @@ -77,7 +77,7 @@ ortho = super_resolve_volume_orthogonal( ) sr_volume = ortho["fused"] -# 4. Evaluate volumetric fidelity and porous-media petrophysics +# 4. Evaluate volumetric fidelity and reference-locked porous-media petrophysics img_metrics = evaluate_image_metrics(sr_volume, hr_test) petro_metrics = evaluate_petrophysical_metrics(sr_volume, hr_test, threshold_method="otsu") print(img_metrics["psnr"], petro_metrics["porosity_abs_error"]) @@ -93,13 +93,13 @@ For YAML-driven reproducible experiments on laboratory TIFF stacks or synchrotro # Train with automatic checkpointing openlsrx fit -c configs/base/config.yaml -# Reconstruct 3D super-resolved BigTIFF volume +# Reconstruct 3D super-resolved BigTIFF volume (3-axis orthogonal fusion + uncertainty) openlsrx predict -c configs/base/config.yaml \ --ckpt_path lightning_logs/version_0/checkpoints/last.ckpt # Evaluate image + petrophysical metrics against ground truth openlsrx evaluate \ - --pred outputs/predictions/predicted_stack.tiff \ - --target high_res_reference.tiff \ + --pred outputs/base_run/predicted_orthogonal/base_srgan_predicted_stack.tiff \ + --target outputs/base_run/predicted_orthogonal/base_srgan_high_res_stack.tiff \ --output outputs/evaluation_report.json ``` diff --git a/paper/paper.md b/paper/paper.md index 7bc10f2..b0ae395 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -34,44 +34,44 @@ bibliography: paper.bib # Summary -**OpenLSR-X** is an open-source Python package built on PyTorch [@paszke2019pytorch] and PyTorch Lightning [@falcon2019lightning] for super-resolving three-dimensional X-ray computed tomography (XCT) scans of porous materials using two-dimensional generative adversarial networks (SRGANs) [@ledig2017photo] combined with three-dimensional orthogonal Fourier fusion. Alongside training and inference pipelines supporting synthetic porous media [@gostick2019porespy], laboratory micro-CT stacks, and multi-resolution synchrotron NeXus/HDF5 reconstructions [@green2025multimodal; @green2024zn13x_i13], OpenLSR-X provides a quantitative evaluation suite measuring both classical image fidelity and domain-critical petrophysical properties—including segmented porosity, specific surface area, Euler connectivity, inscribed pore-radius distributions, and two-point spatial correlations. +**OpenLSR-X** is an open-source Python package built on PyTorch [@paszke2019pytorch] and PyTorch Lightning [@falcon2019lightning] for super-resolving three-dimensional X-ray computed tomography (XCT) scans of porous materials using two-dimensional and `2.5D` neural architectures—including shifted-window Transformers (`SwinIR`), Residual-in-Residual Dense Blocks (`RRDB`/`RaGAN`), and residual SRGANs [@ledig2017photo]—combined with cell-centered three-dimensional orthogonal Fourier fusion and a volumetric 3D CNN baseline (`SR3DResNet`). Alongside training and inference pipelines supporting synthetic porous media [@gostick2019porespy], laboratory micro-CT stacks, and multi-resolution synchrotron NeXus/HDF5 reconstructions [@green2025multimodal; @green2024zn13x_i13], OpenLSR-X provides a quantitative evaluation suite measuring classical image fidelity, 3D Fourier Shell Correlation (FSC) agreement, segmented petrophysical properties (porosity, specific surface area, Euler connectivity, inscribed pore-radius distributions, and two-point spatial correlations), and cell-centered finite-volume 3D diffusive tortuosity ($D_{\text{eff}}/D_0$, $\tau$) with direct export to `OpenImpala`. # Statement of Need Three-dimensional X-ray micro-CT is a foundational characterization technique across hydrogeology, carbon capture and storage, battery electrodes, catalysis, and rock mechanics [@blunt2013pore; @green2025multimodal]. However, XCT instruments enforce an inherent trade-off between sample field of view (FOV) and voxel resolution: scans broad enough to capture a representative elementary volume (REV) frequently under-resolve sub-micron pore throats, biasing multiphase flow and transport simulations [@wang2019deep]. -While 3D convolutional and generative super-resolution models can recover fine-scale pore geometry [@janssens2020computed], training fully 3D adversarial networks on gigavoxel tomograms requires substantial GPU memory and registered 3D low/high-resolution scan pairs that are expensive to acquire and align [@green2025multimodal]. Conversely, applying a 2D slice-wise super-resolution network along a single tomographic axis introduces through-plane discontinuities ("venetian blind" stacking artifacts) and anisotropic frequency distortion. Furthermore, general-purpose computer-vision toolboxes evaluate super-resolution almost exclusively via PSNR and SSIM, which correlate poorly with topological pore-throat preservation. +While 3D convolutional and generative super-resolution models can recover fine-scale pore geometry [@janssens2020computed], training fully 3D networks on gigavoxel tomograms requires substantial GPU memory and registered 3D low/high-resolution scan pairs that are expensive to acquire and align [@green2025multimodal]. Conversely, applying a 2D slice-wise super-resolution network along a single tomographic axis introduces through-plane discontinuities ("venetian blind" stacking artifacts) and anisotropic frequency distortion. Furthermore, general-purpose computer-vision toolboxes evaluate super-resolution almost exclusively via PSNR and SSIM, which correlate poorly with topological pore-throat preservation and diffusive transport. -OpenLSR-X fills this gap by providing porous-media and beamline researchers with: +OpenLSR-X addresses these needs by providing porous-media and beamline researchers with: -1. **Memory-efficient 2D-to-3D super-resolution** that trains on 2D slices from spatially disjoint 3D slabs and reconstructs isotropic 3D volumes via directional 3D Fourier fusion across orthogonal (`yz`, `xz`, `xy`) planes (\autoref{fig:overview}). -2. **Leakage-free 3D benchmark infrastructure** that prevents cross-plane train/test voxel intersection when evaluating orthogonal generalization. -3. **Integrated petrophysical diagnostics** that directly test whether super-resolved volumes preserve porosity, interfacial area, topology, and pore-size distributions relative to ground truth and 3D interpolation baselines. +1. **Memory-efficient 2D/`2.5D`-to-3D super-resolution** that trains on slices from spatially disjoint 3D slabs and reconstructs isotropic 3D volumes via cell-centered directional 3D Fourier and outlier-suppressed Fourier fusion across orthogonal (`yz`, `xz`, `xy`) planes, while reporting inter-view disagreement $\sigma_{\text{ortho}}(\mathbf{x})$ across the three sweeps (\autoref{fig:overview}). +2. **Split-isolated 3D benchmark infrastructure** that partitions 3D slabs prior to train-fitted intensity normalization and synthetic point-spread-function (PSF) degradation, preventing cross-plane voxel intersection and intensity leakage. +3. **Integrated petrophysical and pore-scale transport diagnostics** that evaluate reference-thresholded porosity, interfacial area, topology, 3D FSC spectral agreement, capillary drainage curves, and residual-verified steady-state 3D Fickian diffusive tortuosity relative to ground truth and 3D interpolation baselines. ![Through-plane (`xz`) cross-sections and pore-space diagnostics generated by OpenLSR-X on a dual-porosity 3D synthetic XCT benchmark. Three-axis orthogonal Fourier fusion suppresses single-axis slice-stacking discontinuities while recovering the ground-truth pore-radius distribution $P(r)$ and radial two-point correlation $S_2(r)$.\label{fig:overview}](figures/joss_overview.png) # Comparison with Existing Open-Source Software -Several mature open-source packages address adjacent parts of the imaging or porous-media workflow, but none integrate leakage-free 2D-to-3D tomographic super-resolution with quantitative petrophysical validation: +Several mature open-source packages address adjacent parts of the imaging or porous-media workflow, but none integrate split-isolated 2D/`2.5D`-to-3D tomographic super-resolution with quantitative petrophysical and diffusive transport validation: -- **2D Natural-Image Restoration Toolboxes (`BasicSR` [@wang2022basicsr]):** Provide broad 2D RGB super-resolution backbones, but lack 3D orthogonal Fourier volume fusion, spatially guarded 3D slab splitting, scientific 32-bit BigTIFF and synchrotron NeXus/HDF5 loaders, and porous-media metrics. -- **3D Biomedical Deep-Learning Frameworks (`MONAI` [@cardoso2022monai], `TorchIO` [@perez2021torchio]):** Excel at 3D medical patch sampling (`NIfTI`/`DICOM`) and volumetric segmentation, yet do not implement multi-axis 2D-to-3D frequency-domain fusion for memory-constrained gigavoxel micro-CT or topological/petrophysical microstructure diagnostics. -- **Porous-Media Characterization Suites (`PoreSpy` [@gostick2019porespy], `OpenPNM` [@gostick2016openpnm]):** Provide synthetic microstructure generators, morphological filters, and pore-network transport solvers, but do not include learnable deep super-resolution models. OpenLSR-X directly complements `PoreSpy` and `OpenPNM` as an upstream super-resolution and fidelity-benchmarking framework prior to pore-network or direct numerical transport simulation. +- **2D Natural-Image Restoration Toolboxes (`BasicSR` [@wang2022basicsr]):** Provide broad 2D RGB super-resolution backbones, but lack cell-centered 3D orthogonal Fourier volume fusion, spatially guarded 3D slab splitting, scientific 32-bit BigTIFF and synchrotron NeXus/HDF5 ROI loaders, and porous-media transport metrics. +- **3D Biomedical Deep-Learning Frameworks (`MONAI` [@cardoso2022monai], `TorchIO` [@perez2021torchio]):** Excel at 3D medical patch sampling (`NIfTI`/`DICOM`) and volumetric segmentation, yet do not implement multi-axis 2D/`2.5D`-to-3D frequency-domain fusion for memory-constrained gigavoxel micro-CT or topological/petrophysical microstructure diagnostics. +- **Porous-Media Characterization Suites (`PoreSpy` [@gostick2019porespy], `OpenPNM` [@gostick2016openpnm]):** Provide synthetic microstructure generators, morphological filters, and pore-network transport solvers, but do not include learnable deep super-resolution models. OpenLSR-X directly complements `PoreSpy`, `OpenPNM`, and `OpenImpala` as an upstream super-resolution and fidelity-benchmarking framework prior to pore-network or direct numerical transport simulation. # Architecture and Orthogonal 3D Fusion -OpenLSR-X adapts the residual sub-pixel generator and discriminator architecture of @ledig2017photo specifically for single-channel quantitative XCT attenuation data: +OpenLSR-X provides modular generator backbones (`SwinIRGenerator`, `RRDBGenerator`, `Generator`, and `SR3DResNet`) and domain-specific objectives tailored for single-channel quantitative XCT attenuation data: -- **Artifact-suppressed convolutions:** Reflection padding (`padding_mode="reflect"`) eliminates bright-rim zero-padding boundary artifacts across cropped sub-slices, while channel-wise feature vector normalization (`PixelNorm`) [@karras2018progressive] stabilizes adversarial training under small batch sizes without cross-sample batch-normalization drift. -- **Controlled ablation and warmup:** A unified `SRGAN` `LightningModule` supports generator-only `SRResNet` training ($L_1$/MSE), scheduled generator warmup epochs prior to discriminator activation, and ImageNet-normalized VGG-19 perceptual losses whose frozen weights are isolated from checkpoint files. -- **3D Orthogonal Fourier Fusion:** Given a low-resolution 3D scan $V_{\text{LR}} \in \mathbb{R}^{d \times h \times w}$ and scale factor $s$, OpenLSR-X generates three candidate reconstructions $\hat{V}_{yz}, \hat{V}_{xz}, \hat{V}_{xy} \in \mathbb{R}^{sd \times sh \times sw}$ by applying the 2D generator across each orthogonal plane and fuses their 3D discrete Fourier transforms weighted by each view's super-resolved in-plane spatial wavevectors. +- **Boundary-safe convolutions & normalization:** Reflection/replicate padding eliminates zero-padding rim artifacts across cropped sub-slices, while channel-wise feature vector normalization (`PixelNorm`) [@karras2018progressive] or normalization-free residual trunks (`RRDB`/`SwinIR`) preserve greyscale attenuation scales under small batch sizes. +- **Domain-specific loss functions:** A unified `SRGAN` `LightningModule` supports generator-only $L_1$/MSE training, scheduled generator warmup prior to standard or relativistic (`RaGAN`) adversarial activation, linear-attenuation downsampling consistency (`AttenuationConservationLoss`), soft-skeleton connectivity (`SoftCLDiceLoss`), Sobel gradient sharpness, Focal Frequency Loss, and optional VGG-19 perceptual supervision. +- **Cell-Centered 3D Orthogonal Fourier Fusion:** Given a low-resolution 3D scan $V_{\text{LR}} \in \mathbb{R}^{d \times h \times w}$ and scale factor $s$, OpenLSR-X generates three cell-centered candidate reconstructions $\hat{V}_{yz}, \hat{V}_{xz}, \hat{V}_{xy} \in \mathbb{R}^{sd \times sh \times sw}$ (`scipy.ndimage.zoom(..., grid_mode=True)`) using native-LR-strided `2.5D` slice context and fuses their 3D discrete Fourier transforms (`rfftn`) weighted by each view's super-resolved in-plane spatial wavevectors, while computing the voxel-wise inter-view standard deviation $\sigma_{\text{ortho}}(\mathbf{x})$ ($n=3$). # Petrophysical Validation and Reproducible Benchmarks -To support reproducible methods comparisons across synthetic, laboratory, and synchrotron regimes, OpenLSR-X ships with automated benchmark suites (`scripts/benchmarks/`) and beamline configuration profiles (`configs/`): +To support reproducible methods comparisons across synthetic, laboratory, and synchrotron regimes, OpenLSR-X ships with provenance-tracked benchmark suites (`scripts/benchmarks/`) and beamline configuration profiles (`configs/`): -1. **Factorial PoreSpy Study:** Evaluates single-scale and dual-porosity 3D synthetic media generated with PoreSpy [@gostick2019porespy] across controlled detector blur and noise regimes, comparing 3D Nearest, Trilinear, and Tricubic B-spline interpolation against `SRResNet`, single-axis `OpenLSR-X`, and 3-axis Fourier-fused `OpenLSR-X`. -2. **Open Rock Micro-CT & Synchrotron Profiles:** Evaluates super-resolution on Bentheimer Sandstone and bimodal Indiana Limestone micro-CT benchmarks—exporting publication-ready `booktabs` LaTeX tables and multi-panel error and pore-radius distribution figures—and provides ready-to-run NeXus/HDF5 profiles for the open Diamond Light Source I13-2 multi-resolution zinc-doped Zeolite 13X dataset [@green2025multimodal; @green2024zn13x_i13]. +1. **Factorial PoreSpy Study:** Evaluates single-scale and dual-porosity 3D synthetic media generated with PoreSpy [@gostick2019porespy] across controlled detector blur and noise regimes, comparing cell-centered 3D Nearest, Trilinear, and Tricubic B-spline interpolation against `SRResNet`, single-axis `OpenLSR-X`, and 3-axis Fourier-fused `OpenLSR-X`. +2. **Open Rock Micro-CT & Synchrotron Transport Profiles:** Evaluates super-resolution on Bentheimer Sandstone micro-CT stacks, calibrated carbonate phantoms, and coaxial sub-voxel-registered pairs from the open Diamond Light Source I13-2 multi-resolution zinc-doped Zeolite 13X dataset [@green2025multimodal; @green2024zn13x_i13]—recording explicit dataset provenance (`source_kind`) in every output table and exporting publication-ready `booktabs` LaTeX tables and `OpenImpala` simulation decks. # Acknowledgements diff --git a/pyproject.toml b/pyproject.toml index d2a1fd1..a54a1b6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,7 +41,7 @@ dependencies = [ "imageio>=2.31.0", "jsonargparse[signatures]>=4.27.7", "matplotlib>=3.7.0", - "numpy>=1.24.0,<2.3.0", + "numpy>=1.24.0,<3.0.0", "opencv-python-headless>=4.8.0", "porespy>=2.4.0", "pytorch-lightning>=2.2.0", diff --git a/scripts/benchmarks/aggregate_campaign.py b/scripts/benchmarks/aggregate_campaign.py index 097e9e0..28cb9df 100644 --- a/scripts/benchmarks/aggregate_campaign.py +++ b/scripts/benchmarks/aggregate_campaign.py @@ -61,16 +61,21 @@ def aggregate_csv_files(csv_paths: list[Path], output_dir: Path) -> dict[str, ob if not csv_paths: raise FileNotFoundError("No *_results.csv files found in provided input paths.") - # Group by (dataset_or_regime, method) -> metric -> list[float] + # Group by (dataset_or_regime, method) -> metric -> list[float], plus total row count & provenance grouped: dict[tuple[str, str], dict[str, list[float]]] = defaultdict(lambda: defaultdict(list)) + row_counts: dict[tuple[str, str], int] = defaultdict(int) + source_kinds: dict[tuple[str, str], set[str]] = defaultdict(set) for p in csv_paths: with p.open("r", encoding="utf-8") as f: reader = csv.DictReader(f) for row in reader: ds_key = str(row.get("dataset") or row.get("regime") or p.stem) method = str(row.get("method", "unknown")) + row_counts[(ds_key, method)] += 1 + if row.get("source_kind"): + source_kinds[(ds_key, method)].add(str(row["source_kind"])) for k, v in row.items(): - if k in ("dataset", "regime", "pair", "method", "seed"): + if k in ("dataset", "regime", "pair", "method", "seed", "source_kind"): continue fv = _parse_float(v) if fv is not None: @@ -78,15 +83,24 @@ def aggregate_csv_files(csv_paths: list[Path], output_dir: Path) -> dict[str, ob summary_records: list[dict[str, object]] = [] for (ds_key, method), metric_map in sorted(grouped.items()): + total_rows = int(row_counts[(ds_key, method)]) rec: dict[str, object] = { "dataset": ds_key, "method": method, - "n_seeds": max((len(vals) for vals in metric_map.values()), default=0), + "n_seeds": total_rows, + "source_kinds": sorted(source_kinds.get((ds_key, method), {"synthetic"})), } for m_key, vals in sorted(metric_map.items()): arr = np.asarray(vals, dtype=np.float64) + ddof = 1 if arr.size >= 2 else 0 rec[f"{m_key}_mean"] = float(np.mean(arr)) - rec[f"{m_key}_std"] = float(np.std(arr, ddof=0)) + rec[f"{m_key}_std"] = float(np.std(arr, ddof=ddof)) + rec[f"{m_key}_n_valid"] = int(arr.size) + if "pred_tortuosity_mean" in metric_map or "tortuosity_mae" in metric_map: + n_perc = len( + metric_map.get("pred_tortuosity_mean", metric_map.get("tortuosity_mae", [])) + ) + rec["n_percolating_seeds"] = int(n_perc) summary_records.append(rec) # 1) JSON summary @@ -114,11 +128,15 @@ def aggregate_csv_files(csv_paths: list[Path], output_dir: Path) -> dict[str, ob for m, _, _ in active_metrics: mean_v = rec.get(f"{m}_mean") std_v = rec.get(f"{m}_std") + n_val = rec.get(f"{m}_n_valid", n_seeds) if isinstance(mean_v, float) and isinstance(std_v, float): - if n_seeds > 1: - cells.append(f"{mean_v:.4f} ± {std_v:.4f}") + suffix = ( + f" ({n_val}/{n_seeds})" if isinstance(n_val, int) and n_val < n_seeds else "" + ) + if isinstance(n_val, int) and n_val > 1: + cells.append(f"{mean_v:.4f} ± {std_v:.4f}{suffix}") else: - cells.append(f"{mean_v:.4f}") + cells.append(f"{mean_v:.4f}{suffix}") else: cells.append("—") md_lines.append( diff --git a/scripts/benchmarks/make_paper_outputs.py b/scripts/benchmarks/make_paper_outputs.py index 447b355..4782819 100755 --- a/scripts/benchmarks/make_paper_outputs.py +++ b/scripts/benchmarks/make_paper_outputs.py @@ -38,13 +38,20 @@ def _aggregate_csv( g = str(row[group_col]) m = str(row["method"]) for col, _, _ in KEY_METRICS: - if col in row and row[col] != "": - buckets[(g, m)][col].append(float(row[col])) + raw_v = row.get(col, "") + if raw_v not in ("", None, "None", "nan", "NaN", "inf", "-inf"): + fv = float(raw_v) + if np.isfinite(fv): + buckets[(g, m)][col].append(fv) summary: dict[tuple[str, str], dict[str, tuple[float, float]]] = {} for key, metric_lists in buckets.items(): summary[key] = { - col: (float(np.mean(vals)), float(np.std(vals))) for col, vals in metric_lists.items() + col: ( + float(np.mean(vals)), + float(np.std(vals, ddof=1 if len(vals) >= 2 else 0)), + ) + for col, vals in metric_lists.items() } return summary diff --git a/scripts/benchmarks/porespy_study.py b/scripts/benchmarks/porespy_study.py index 463bedc..7b4b01e 100755 --- a/scripts/benchmarks/porespy_study.py +++ b/scripts/benchmarks/porespy_study.py @@ -14,6 +14,8 @@ import pytorch_lightning as pl import tifffile +import torch +from pytorch_lightning.callbacks import ModelCheckpoint from openlsrx.baselines import upsample_3d from openlsrx.data import FeatureRegime, NoiseRegime, SyntheticPoreSpyDataModule @@ -73,17 +75,33 @@ def _train_model( output_dir=str(work_dir), save_val_images=False, ) + use_ckpt = epochs > 10 + ckpt_cb: ModelCheckpoint | None = None + callbacks: list[pl.Callback] = [] + if use_ckpt: + ckpt_cb = ModelCheckpoint( + dirpath=str(work_dir / "checkpoints"), + filename="best", + monitor="val/psnr", + mode="max", + save_top_k=1, + ) + callbacks.append(ckpt_cb) trainer = pl.Trainer( default_root_dir=str(work_dir), max_epochs=epochs, accelerator="auto", devices=1, logger=False, - enable_checkpointing=False, + enable_checkpointing=use_ckpt, + callbacks=callbacks, enable_progress_bar=False, enable_model_summary=False, ) trainer.fit(model, datamodule=dm) + if ckpt_cb is not None and ckpt_cb.best_model_path: + ckpt = torch.load(ckpt_cb.best_model_path, map_location=model.device, weights_only=False) + model.load_state_dict(ckpt["state_dict"], strict=False) return model diff --git a/scripts/benchmarks/public_rock_xct.py b/scripts/benchmarks/public_rock_xct.py index 5e5a4a8..e2f429b 100755 --- a/scripts/benchmarks/public_rock_xct.py +++ b/scripts/benchmarks/public_rock_xct.py @@ -8,6 +8,8 @@ from pathlib import Path import pytorch_lightning as pl +import torch +from pytorch_lightning.callbacks import ModelCheckpoint from openlsrx.baselines import upsample_3d from openlsrx.data import PairedVolumeDataModule, fetch_or_generate_rock_sample @@ -24,9 +26,11 @@ def run_public_rock_benchmark( epochs: int = 120, seeds: list[int] | None = None, fast: bool = False, + allow_synthetic_fallback: bool | None = None, ) -> Path: output_dir.mkdir(parents=True, exist_ok=True) seed_list = seeds or ([42] if fast else [42, 43, 44]) + fallback = bool(fast) if allow_synthetic_fallback is None else bool(allow_synthetic_fallback) if fast: volume_size = 48 @@ -45,13 +49,14 @@ def run_public_rock_benchmark( dataset_name=rock_name, dest_dir=data_dir, shape=(volume_size, volume_size, volume_size), - allow_offline_fallback=True, + allow_offline_fallback=fallback, + prefer_offline=fast, seed=42, ) + src_kind = str(manifest.get("source_kind", "unknown")) + is_exp = int(bool(manifest.get("is_experimental_xct", False))) for seed in seed_list: - print( - f"[public_rock_xct] Running {rock_name} (source={manifest['source_kind']}) seed={seed} ..." - ) + print(f"[public_rock_xct] Running {rock_name} (source={src_kind}) seed={seed} ...") dm = PairedVolumeDataModule( high_path=str(hr_tif), degrade_from_hr=True, @@ -71,15 +76,22 @@ def run_public_rock_benchmark( for mode, name in (("trilinear", "Trilinear-3D"), ("tricubic", "Tricubic-3D")): pred = upsample_3d(lr_test, scale_factors=scale_factor, mode=mode) # type: ignore[arg-type] - row: dict[str, object] = {"dataset": rock_name, "seed": seed, "method": name} + row: dict[str, object] = { + "dataset": rock_name, + "source_kind": src_kind, + "is_experimental_xct": is_exp, + "seed": seed, + "method": name, + } row.update(evaluate_image_metrics(pred, hr_test)) row.update(evaluate_petrophysical_metrics(pred, hr_test, pore_is_low=True)) rows.append(row) pl.seed_everything(seed, workers=True) + run_dir = output_dir / "runs" / f"{rock_name}_s{seed}" model = SRGAN( learning_rate=2e-4 if fast else 5e-5, - adaptive_size=4 if fast else 16, + adaptive_size=4 if fast else 8, super_res_factor=scale_factor, num_blocks=num_blocks, out_channels=out_channels, @@ -87,20 +99,37 @@ def run_public_rock_benchmark( pretrain_epochs=max(1, epochs // 4), use_adversarial_loss=True, use_vgg_loss=False, - output_dir=str(output_dir / "runs" / f"{rock_name}_s{seed}"), + output_dir=str(run_dir), save_val_images=False, ) + ckpt_cb: ModelCheckpoint | None = None + callbacks: list[pl.Callback] = [] + if not fast: + ckpt_cb = ModelCheckpoint( + dirpath=str(run_dir / "checkpoints"), + filename="best", + monitor="val/psnr", + mode="max", + save_top_k=1, + ) + callbacks.append(ckpt_cb) trainer = pl.Trainer( default_root_dir=str(output_dir / "runs"), max_epochs=epochs, accelerator="auto", devices=1, logger=False, - enable_checkpointing=False, + enable_checkpointing=(not fast), + callbacks=callbacks, enable_progress_bar=False, enable_model_summary=False, ) trainer.fit(model, datamodule=dm) + if ckpt_cb is not None and ckpt_cb.best_model_path: + ckpt = torch.load( + ckpt_cb.best_model_path, map_location=model.device, weights_only=False + ) + model.load_state_dict(ckpt["state_dict"], strict=False) vols = super_resolve_volume_orthogonal( model.gen, lr_test, scale_factor=scale_factor, fusion="fourier" @@ -109,7 +138,13 @@ def run_public_rock_benchmark( ("yz", "OpenLSR-X-SingleAxis(yz)", 0), ("fused", "OpenLSR-X-3Axis-Fourier", 0), ): - row = {"dataset": rock_name, "seed": seed, "method": label} + row = { + "dataset": rock_name, + "source_kind": src_kind, + "is_experimental_xct": is_exp, + "seed": seed, + "method": label, + } row.update(evaluate_image_metrics(vols[key], hr_test)) row.update( evaluate_petrophysical_metrics( @@ -136,6 +171,11 @@ def main() -> None: parser.add_argument("--epochs", type=int, default=120, help="Training epochs.") parser.add_argument("--seeds", type=int, nargs="+", default=None, help="Random seeds.") parser.add_argument("--fast", action="store_true", help="Rapid CPU smoke benchmark.") + parser.add_argument( + "--allow-synthetic-fallback", + action="store_true", + help="Allow synthetic fallback if live Zenodo download fails during a full campaign.", + ) ns = parser.parse_args() run_public_rock_benchmark( @@ -146,6 +186,7 @@ def main() -> None: epochs=ns.epochs, seeds=ns.seeds, fast=ns.fast, + allow_synthetic_fallback=(True if ns.allow_synthetic_fallback else None), ) diff --git a/scripts/benchmarks/zn13x_synchrotron_study.py b/scripts/benchmarks/zn13x_synchrotron_study.py index 1aac2be..9a1e203 100644 --- a/scripts/benchmarks/zn13x_synchrotron_study.py +++ b/scripts/benchmarks/zn13x_synchrotron_study.py @@ -13,11 +13,12 @@ import json import time from pathlib import Path -from typing import Literal +from typing import Any, Literal import numpy as np import pytorch_lightning as pl import torch +from pytorch_lightning.callbacks import ModelCheckpoint from torch import nn from openlsrx.baselines import upsample_3d @@ -26,7 +27,8 @@ prepare_zn13x_benchmark, synthesize_zn13x_phantom_pair, ) -from openlsrx.inference import super_resolve_volume_orthogonal +from openlsrx.inference import fuse_orthogonal_volumes, super_resolve_volume_orthogonal +from openlsrx.inference.orthogonal import AxisName from openlsrx.io import export_for_openimpala from openlsrx.metrics import ( compute_tortuosity_uncertainty_bounds, @@ -35,6 +37,7 @@ evaluate_spectral_metrics, evaluate_transport_metrics, evaluate_triphase_zn13x_metrics, + precompute_reference_transport, ) from openlsrx.models import ( SRGAN, @@ -48,6 +51,51 @@ def _count_params(module: nn.Module) -> int: return sum(p.numel() for p in module.parameters() if p.requires_grad) +def _fit_with_best_checkpoint( + model: pl.LightningModule, + root_dir: Path, + run_tag: str, + epochs: int, + fast: bool, + monitor: str = "val/psnr", + **fit_kwargs: Any, +) -> float: + """Fit ``model`` and restore the best validation PSNR checkpoint in full runs.""" + callbacks: list[pl.Callback] = [] + ckpt_cb: ModelCheckpoint | None = None + if not fast: + ckpt_dir = root_dir / "checkpoints" / run_tag + ckpt_cb = ModelCheckpoint( + dirpath=str(ckpt_dir), + filename="best", + monitor=monitor, + mode="max", + save_top_k=1, + save_last=True, + ) + callbacks.append(ckpt_cb) + + trainer = pl.Trainer( + default_root_dir=str(root_dir), + max_epochs=epochs, + accelerator="auto", + devices=1, + logger=False, + enable_checkpointing=(not fast), + callbacks=callbacks, + enable_progress_bar=False, + enable_model_summary=False, + ) + t0 = time.perf_counter() + trainer.fit(model, **fit_kwargs) + elapsed = time.perf_counter() - t0 + + if ckpt_cb is not None and ckpt_cb.best_model_path: + ckpt = torch.load(ckpt_cb.best_model_path, map_location=model.device, weights_only=False) + model.load_state_dict(ckpt["state_dict"], strict=False) + return elapsed + + def _evaluate_method( dataset_name: str, pair: str, @@ -56,6 +104,9 @@ def _evaluate_method( pred_vol: np.ndarray, hr_test: np.ndarray, voxel_size_um: float, + source_kind: str = "unknown", + is_experimental_xct: bool = False, + precomputed_true: dict[str, Any] | None = None, stack_axis: int = 0, gen_params: int = 0, train_sec: float = 0.0, @@ -65,6 +116,8 @@ def _evaluate_method( row: dict[str, object] = { "dataset": dataset_name, "pair": pair, + "source_kind": source_kind, + "is_experimental_xct": int(bool(is_experimental_xct)), "seed": seed, "method": method, "gen_params": gen_params, @@ -90,11 +143,16 @@ def _evaluate_method( pore_is_low=True, voxel_size=voxel_size_um, drainage_steps=10, + precomputed_true=precomputed_true, ) ) if uncertainty_std is not None: unc_bounds = compute_tortuosity_uncertainty_bounds( - pred_vol, uncertainty_std, true_vol=hr_test, pore_is_low=True + pred_vol, + uncertainty_std, + true_vol=hr_test, + pore_is_low=True, + precomputed_true=precomputed_true, ) row["mean_epistemic_std"] = unc_bounds["mean_epistemic_std"] row["d_eff_halfwidth"] = unc_bounds["d_eff_halfwidth"] @@ -113,14 +171,17 @@ def run_zn13x_study( data_dir: Path = Path("data/benchmarks"), pairs: list[str] | None = None, lr_size: int = 48, + volume_size: int | None = None, epochs: int = 120, seeds: list[int] | None = None, raw_h5_dir: Path | None = None, fast: bool = False, + allow_synthetic_fallback: bool | None = None, ) -> Path: output_dir.mkdir(parents=True, exist_ok=True) pair_list = pairs or (["2x"] if fast else ["2x", "8x"]) seed_list = seeds or ([42] if fast else [42, 43, 44]) + fallback = bool(fast) if allow_synthetic_fallback is None else bool(allow_synthetic_fallback) if fast: lr_size = 20 @@ -133,32 +194,44 @@ def run_zn13x_study( c3d_channels = 12 c3d_blocks = 2 c3d_samples = 8 + base_lr = 2e-4 else: - srgan_blocks = 10 - rrdb_blocks = 8 - out_channels = 64 - growth_channels = 32 + # Parameter-balanced regimes (~0.35M-1.15M generator params across 2D/2.5D/3D families) + srgan_blocks = 8 + rrdb_blocks = 4 + out_channels = 48 + growth_channels = 24 disc_features = [32, 64, 128, 128] - c3d_channels = 28 - c3d_blocks = 4 + c3d_channels = 32 + c3d_blocks = 5 c3d_samples = 48 + base_lr = 1.5e-4 rows: list[dict[str, object]] = [] + runs_root = output_dir / "runs" for pair in pair_list: pair_lit: Literal["2x", "8x"] = "2x" if pair == "2x" else "8x" scale = 2 if pair_lit == "2x" else 8 - cur_lr_size = max(12, lr_size // 2) if (pair_lit == "8x" and fast) else lr_size + if fast: + cur_lr_size = max(12, lr_size // 2) if pair_lit == "8x" else lr_size + elif volume_size is not None: + cur_lr_size = max(12, int(volume_size) // scale) + else: + cur_lr_size = lr_size lr_tif, hr_tif, manifest = prepare_zn13x_benchmark( pair=pair_lit, dest_dir=data_dir, lr_size=cur_lr_size, raw_h5_dir=raw_h5_dir, - allow_offline_fallback=True, + allow_offline_fallback=fallback, + prefer_offline=fast, seed=42, ) dataset_name = f"zn13x_{pair_lit}" voxel_um = float(manifest["high_resolution_um"]) # type: ignore[arg-type] + src_kind = str(manifest.get("source_kind", "unknown")) + is_exp = bool(manifest.get("is_experimental_xct", False)) for seed in seed_list: print( @@ -190,7 +263,15 @@ def run_zn13x_study( else: lr_test, hr_test = dm.test_volumes - # 1) 3D Tricubic baseline + # Solve ground-truth HR 3D Fickian diffusion & drainage ONCE per seed + ref_transport = precompute_reference_transport( + hr_test, + pore_is_low=True, + voxel_size=voxel_um, + drainage_steps=10, + ) + + # 1) 3D Tricubic baseline (cell-centered grid_mode=True) t0 = time.perf_counter() pred_tricubic = upsample_3d(lr_test, scale_factors=scale, mode="tricubic") infer_tricubic = time.perf_counter() - t0 @@ -203,38 +284,35 @@ def run_zn13x_study( pred_tricubic, hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, infer_sec=infer_tricubic, ) ) - # 2) SRResNet (2D + 3-Axis Fourier, generator-only ablation) + # 2) SRResNet (2D L1 + 3-Axis Fourier, generator-only baseline) pl.seed_everything(seed, workers=True) srresnet = SRGAN( - learning_rate=2e-4 if fast else 1e-4, + learning_rate=base_lr, adaptive_size=4 if fast else 8, super_res_factor=scale, num_blocks=srgan_blocks, out_channels=out_channels, - disc_features=disc_features, + pixel_loss_type="l1", use_adversarial_loss=False, use_vgg_loss=False, - output_dir=str(output_dir / "runs" / f"{dataset_name}_s{seed}_srresnet"), + output_dir=str(runs_root / f"{dataset_name}_s{seed}_srresnet"), save_val_images=False, ) - trainer_srres = pl.Trainer( - default_root_dir=str(output_dir / "runs"), - max_epochs=epochs, - accelerator="auto", - devices=1, - logger=False, - enable_checkpointing=False, - enable_progress_bar=False, - enable_model_summary=False, + train_srres = _fit_with_best_checkpoint( + srresnet, + runs_root, + f"{dataset_name}_s{seed}_srresnet", + epochs=epochs, + fast=fast, + datamodule=dm, ) - t0 = time.perf_counter() - trainer_srres.fit(srresnet, datamodule=dm) - train_srres = time.perf_counter() - t0 - t0 = time.perf_counter() srres_vols = super_resolve_volume_orthogonal( srresnet.gen, @@ -253,6 +331,9 @@ def run_zn13x_study( srres_vols["fused"], hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, gen_params=_count_params(srresnet.gen), train_sec=train_srres, infer_sec=infer_srres, @@ -260,10 +341,10 @@ def run_zn13x_study( ) ) - # 3) Native 3D CNN baseline (SR3DResNet) + # 3) Native 3D CNN baseline (SR3DResNet with full O_h 3D augmentation) pl.seed_everything(seed, workers=True) sr3d = SR3DResNet( - learning_rate=2e-4, + learning_rate=base_lr, super_res_factor=scale, out_channels=c3d_channels, num_blocks=c3d_blocks, @@ -278,22 +359,18 @@ def run_zn13x_study( train_samples=c3d_samples, val_samples=max(2, c3d_samples // 4), batch_size=2 if scale == 2 else 1, + augment=True, seed=seed, ) - trainer_3d = pl.Trainer( - default_root_dir=str(output_dir / "runs"), - max_epochs=epochs, - accelerator="auto", - devices=1, - logger=False, - enable_checkpointing=False, - enable_progress_bar=False, - enable_model_summary=False, + train_3d = _fit_with_best_checkpoint( + sr3d, + runs_root, + f"{dataset_name}_s{seed}_sr3d", + epochs=epochs, + fast=fast, + train_dataloaders=tr_3d_loader, + val_dataloaders=va_3d_loader, ) - t0 = time.perf_counter() - trainer_3d.fit(sr3d, train_dataloaders=tr_3d_loader, val_dataloaders=va_3d_loader) - train_3d = time.perf_counter() - t0 - t0 = time.perf_counter() pred_3d = super_resolve_volume_3d( sr3d.gen, @@ -312,6 +389,9 @@ def run_zn13x_study( pred_3d, hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, gen_params=_count_params(sr3d.gen), train_sec=train_3d, infer_sec=infer_3d, @@ -321,7 +401,7 @@ def run_zn13x_study( # 4 & 5) Classical OpenLSR-X SRGAN (Single-Axis yz vs 3-Axis Fourier) pl.seed_everything(seed, workers=True) srgan = SRGAN( - learning_rate=2e-4 if fast else 1e-4, + learning_rate=base_lr, adaptive_size=4 if fast else 8, super_res_factor=scale, num_blocks=srgan_blocks, @@ -330,23 +410,17 @@ def run_zn13x_study( pretrain_epochs=max(1, epochs // 3), use_adversarial_loss=True, use_vgg_loss=False, - output_dir=str(output_dir / "runs" / f"{dataset_name}_s{seed}_srgan"), + output_dir=str(runs_root / f"{dataset_name}_s{seed}_srgan"), save_val_images=False, ) - trainer_srgan = pl.Trainer( - default_root_dir=str(output_dir / "runs"), - max_epochs=epochs, - accelerator="auto", - devices=1, - logger=False, - enable_checkpointing=False, - enable_progress_bar=False, - enable_model_summary=False, + train_srgan = _fit_with_best_checkpoint( + srgan, + runs_root, + f"{dataset_name}_s{seed}_srgan", + epochs=epochs, + fast=fast, + datamodule=dm, ) - t0 = time.perf_counter() - trainer_srgan.fit(srgan, datamodule=dm) - train_srgan = time.perf_counter() - t0 - t0 = time.perf_counter() srgan_vols = super_resolve_volume_orthogonal( srgan.gen, @@ -365,6 +439,9 @@ def run_zn13x_study( srgan_vols["yz"], hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, stack_axis=0, gen_params=_count_params(srgan.gen), train_sec=train_srgan, @@ -380,6 +457,9 @@ def run_zn13x_study( srgan_vols["fused"], hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, stack_axis=0, gen_params=_count_params(srgan.gen), train_sec=train_srgan, @@ -391,7 +471,7 @@ def run_zn13x_study( # 6) Normalization-free RRDB-RaGAN + 3-Axis Fourier Fusion pl.seed_everything(seed, workers=True) rrdb_ragan = SRGAN( - learning_rate=2e-4 if fast else 1e-4, + learning_rate=base_lr, adaptive_size=4 if fast else 8, super_res_factor=scale, num_blocks=rrdb_blocks, @@ -405,23 +485,17 @@ def run_zn13x_study( pretrain_epochs=max(1, epochs // 3), use_adversarial_loss=True, use_vgg_loss=False, - output_dir=str(output_dir / "runs" / f"{dataset_name}_s{seed}_rrdb_ragan"), + output_dir=str(runs_root / f"{dataset_name}_s{seed}_rrdb_ragan"), save_val_images=False, ) - trainer_rrdb = pl.Trainer( - default_root_dir=str(output_dir / "runs"), - max_epochs=epochs, - accelerator="auto", - devices=1, - logger=False, - enable_checkpointing=False, - enable_progress_bar=False, - enable_model_summary=False, + train_rrdb = _fit_with_best_checkpoint( + rrdb_ragan, + runs_root, + f"{dataset_name}_s{seed}_rrdb_ragan", + epochs=epochs, + fast=fast, + datamodule=dm, ) - t0 = time.perf_counter() - trainer_rrdb.fit(rrdb_ragan, datamodule=dm) - train_rrdb = time.perf_counter() - t0 - t0 = time.perf_counter() rrdb_vols = super_resolve_volume_orthogonal( rrdb_ragan.gen, @@ -440,6 +514,9 @@ def run_zn13x_study( rrdb_vols["fused"], hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, stack_axis=0, gen_params=_count_params(rrdb_ragan.gen), train_sec=train_rrdb, @@ -448,13 +525,13 @@ def run_zn13x_study( ) ) - # 7) Physics-Consistent SwinIR-2.5D + Confidence-Fourier Fusion (npj Flagship) - pl.seed_everything(seed, workers=True) + # Shared multi-axis 2.5D DataModule for controlled SwinIR stepwise ablation ladder dm_25d = PairedVolumeDataModule( low_path=str(lr_tif), high_path=str(hr_tif), scale_factor=scale, context_slices=3, + train_axes=("yz", "xz", "xy"), norm_mode="none", train_frac=0.65, val_frac=0.20, @@ -464,8 +541,67 @@ def run_zn13x_study( eval_batch_size=4 if scale == 2 else 2, seed=seed, ) + + # 7) Stepwise Ablation A: SwinIR-2.5D (Pure L1 + Standard Fourier; isolates 2.5D SwinIR backbone) + pl.seed_everything(seed, workers=True) + swin_l1 = SRGAN( + learning_rate=base_lr, + adaptive_size=4 if fast else 8, + super_res_factor=scale, + num_blocks=2 if fast else 4, + out_channels=16 if fast else 48, + context_slices=3, + backbone="swinir", + swin_window_size=4 if fast else 8, + swin_num_heads=4, + output_activation="clamp", + pixel_loss_type="l1", + use_adversarial_loss=False, + use_vgg_loss=False, + output_dir=str(runs_root / f"{dataset_name}_s{seed}_swinir_25d_l1"), + save_val_images=False, + ) + train_swin_l1 = _fit_with_best_checkpoint( + swin_l1, + runs_root, + f"{dataset_name}_s{seed}_swinir_25d_l1", + epochs=epochs, + fast=fast, + datamodule=dm_25d, + ) + t0 = time.perf_counter() + swin_l1_vols = super_resolve_volume_orthogonal( + swin_l1.gen, + lr_test, + scale_factor=scale, + fusion="fourier", + return_uncertainty=True, + ) + infer_swin_l1 = time.perf_counter() - t0 + rows.append( + _evaluate_method( + dataset_name, + pair_lit, + seed, + "OpenLSR-X-SwinIR-2.5D-L1-Fourier", + swin_l1_vols["fused"], + hr_test, + voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, + stack_axis=0, + gen_params=_count_params(swin_l1.gen), + train_sec=train_swin_l1, + infer_sec=infer_swin_l1, + uncertainty_std=swin_l1_vols["uncertainty_std"], + ) + ) + + # 8 & 9) Stepwise Ablations B & C: + Physics/Topology Supervision (Fourier vs Confidence-Fourier) + pl.seed_everything(seed, workers=True) swin_phys = SRGAN( - learning_rate=2e-4, + learning_rate=base_lr, adaptive_size=4 if fast else 8, super_res_factor=scale, num_blocks=2 if fast else 4, @@ -476,7 +612,6 @@ def run_zn13x_study( swin_num_heads=4, output_activation="clamp", pixel_loss_type="l1", - disc_features=disc_features, use_adversarial_loss=False, use_vgg_loss=False, conservation_loss_weight=0.25, @@ -484,23 +619,17 @@ def run_zn13x_study( topology_loss_weight=0.05, gradient_loss_weight=0.10, ffl_loss_weight=0.05, - output_dir=str(output_dir / "runs" / f"{dataset_name}_s{seed}_swinir_25d_phys"), + output_dir=str(runs_root / f"{dataset_name}_s{seed}_swinir_25d_phys"), save_val_images=False, ) - trainer_swin = pl.Trainer( - default_root_dir=str(output_dir / "runs"), - max_epochs=epochs, - accelerator="auto", - devices=1, - logger=False, - enable_checkpointing=False, - enable_progress_bar=False, - enable_model_summary=False, + train_swin = _fit_with_best_checkpoint( + swin_phys, + runs_root, + f"{dataset_name}_s{seed}_swinir_25d_phys", + epochs=epochs, + fast=fast, + datamodule=dm_25d, ) - t0 = time.perf_counter() - trainer_swin.fit(swin_phys, datamodule=dm_25d) - train_swin = time.perf_counter() - t0 - t0 = time.perf_counter() swin_vols = super_resolve_volume_orthogonal( swin_phys.gen, @@ -510,6 +639,36 @@ def run_zn13x_study( return_uncertainty=True, ) infer_swin = time.perf_counter() - t0 + + # Fuse the exact same 3 orthogonal sweeps under standard Fourier to isolate ConfFourier cleanly + t0_four = time.perf_counter() + per_axis_swin: dict[AxisName, np.ndarray] = { + "yz": swin_vols["yz"], + "xz": swin_vols["xz"], + "xy": swin_vols["xy"], + } + swin_phys_fourier = fuse_orthogonal_volumes(per_axis_swin, mode="fourier") + infer_swin_fourier = infer_swin + (time.perf_counter() - t0_four) + + rows.append( + _evaluate_method( + dataset_name, + pair_lit, + seed, + "OpenLSR-X-SwinIR-2.5D-Physics-Fourier", + swin_phys_fourier, + hr_test, + voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, + stack_axis=0, + gen_params=_count_params(swin_phys.gen), + train_sec=train_swin, + infer_sec=infer_swin_fourier, + uncertainty_std=swin_vols["uncertainty_std"], + ) + ) rows.append( _evaluate_method( dataset_name, @@ -519,6 +678,9 @@ def run_zn13x_study( swin_vols["fused"], hr_test, voxel_um, + source_kind=src_kind, + is_experimental_xct=is_exp, + precomputed_true=ref_transport, stack_axis=0, gen_params=_count_params(swin_phys.gen), train_sec=train_swin, @@ -565,11 +727,27 @@ def main() -> None: default=None, help="I13-2 magnification pairs to evaluate.", ) - parser.add_argument("--lr-size", type=int, default=48, help="LR cubic side length.") + parser.add_argument( + "--lr-size", + type=int, + default=48, + help="LR cubic side length (default: 48).", + ) + parser.add_argument( + "--volume-size", + type=int, + default=None, + help="Optional target HR cubic side length (overrides --lr-size as volume_size // scale).", + ) parser.add_argument("--epochs", type=int, default=120, help="Training epochs.") parser.add_argument("--seeds", type=int, nargs="+", default=None, help="Random seeds.") parser.add_argument("--raw-h5-dir", type=str, default=None, help="Optional raw I13-2 HDF5 dir.") parser.add_argument("--fast", action="store_true", help="Rapid CPU smoke benchmark.") + parser.add_argument( + "--allow-synthetic-fallback", + action="store_true", + help="Allow synthetic fallback if live Zenodo/HDF5 loading fails during a full campaign.", + ) ns = parser.parse_args() run_zn13x_study( @@ -577,10 +755,12 @@ def main() -> None: data_dir=Path(ns.data_dir), pairs=ns.pairs, lr_size=ns.lr_size, + volume_size=ns.volume_size, epochs=ns.epochs, seeds=ns.seeds, raw_h5_dir=Path(ns.raw_h5_dir) if ns.raw_h5_dir else None, fast=ns.fast, + allow_synthetic_fallback=(True if ns.allow_synthetic_fallback else None), ) diff --git a/scripts/hpc/isambard_ai_array.slurm b/scripts/hpc/isambard_ai_array.slurm index 571b42a..91735de 100644 --- a/scripts/hpc/isambard_ai_array.slurm +++ b/scripts/hpc/isambard_ai_array.slurm @@ -20,8 +20,9 @@ # Array 3..5 -> Public Micro-CT Rock Suite (Bentheimer & Indiana, seeds 42, 43, 44) # Array 6..8 -> Diamond I13-2 Multi-Resolution Zn-13X Synchrotron Study (2x & 8x) # -# Usage: -# mkdir -p logs +# Usage (stage Zenodo benchmarks on the login node first if compute nodes are air-gapped): +# mkdir -p logs data/benchmarks +# openlsrx download-benchmarks --datasets bentheimer_sandstone indiana_limestone zn13x_2x zn13x_8x --dest data/benchmarks # export I13_RAW_H5_DIR=/lus/lfs1aip1/projects/openlsrx/i13_zn13x_h5 # optional # sbatch scripts/hpc/isambard_ai_array.slurm # @@ -31,7 +32,7 @@ set -euo pipefail -mkdir -p logs results/campaign +mkdir -p logs results/campaign data/benchmarks # Activate project virtual environment (uv / venv) if [ -f ".venv/bin/activate" ]; then @@ -56,8 +57,7 @@ if [ "${SUITE_IDX}" -eq 0 ]; then --volume-size 128 \ --scale-factor 2 \ --epochs 120 \ - --seeds "${SEED}" \ - --use-vgg + --seeds "${SEED}" elif [ "${SUITE_IDX}" -eq 1 ]; then python scripts/benchmarks/public_rock_xct.py \ --output-dir "results/campaign/public_rock_s${SEED}" \ @@ -75,7 +75,7 @@ elif [ "${SUITE_IDX}" -eq 2 ]; then --output-dir "results/campaign/zn13x_s${SEED}" \ --data-dir "data/benchmarks" \ --pairs 2x 8x \ - --lr-size 64 \ + --lr-size 48 \ --epochs 150 \ --seeds "${SEED}" \ "${EXTRA_H5_ARGS[@]}" diff --git a/src/openlsrx/baselines/interpolation.py b/src/openlsrx/baselines/interpolation.py index 0bf1192..0c073dd 100644 --- a/src/openlsrx/baselines/interpolation.py +++ b/src/openlsrx/baselines/interpolation.py @@ -8,21 +8,22 @@ import numpy as np import torch import torch.nn.functional as F -from scipy.ndimage import zoom from torch import Tensor +from openlsrx.data.transforms import sanitize_xct_volume, zoom_cell_centered + Interp2DMode = Literal["nearest", "bilinear", "bicubic", "lanczos4"] Interp3DMode = Literal["nearest", "trilinear", "tricubic"] def upsample_2d( low_res: Tensor | np.ndarray, - scale_factor: int = 2, + scale_factor: float = 2, mode: Interp2DMode = "bicubic", clamp_01: bool = True, ) -> np.ndarray: """Upsample a 2D image ``(H, W)`` or stack of 2D slices ``(N, H, W)`` by ``scale_factor``.""" - arr = np.asarray(low_res, dtype=np.float32) + arr = sanitize_xct_volume(np.asarray(low_res, dtype=np.float32)) single = arr.ndim == 2 if single: arr = arr[np.newaxis, ...] @@ -30,7 +31,8 @@ def upsample_2d( raise ValueError(f"Expected 2D (H, W) or 3D (N, H, W) slice stack, got shape {arr.shape}.") n, h, w = arr.shape - out_h, out_w = h * scale_factor, w * scale_factor + out_h = max(1, int(round(h * float(scale_factor)))) + out_w = max(1, int(round(w * float(scale_factor)))) out: np.ndarray if mode == "lanczos4": @@ -55,24 +57,33 @@ def upsample_2d( def upsample_3d( low_volume: Tensor | np.ndarray, - scale_factors: int | tuple[int, int, int] = 2, + scale_factors: float | tuple[float, float, float] = 2, mode: Interp3DMode = "trilinear", clamp_01: bool = True, ) -> np.ndarray: - """Upsample a 3D volume ``(D, H, W)`` isotropically or anisotropically.""" - arr = np.asarray(low_volume, dtype=np.float32) + """Upsample a 3D volume ``(D, H, W)`` isotropically or anisotropically with cell-centered alignment.""" + arr = sanitize_xct_volume(np.asarray(low_volume, dtype=np.float32)) if arr.ndim != 3: raise ValueError(f"Expected 3D volume (D, H, W), got shape {arr.shape}.") factors = ( - (scale_factors, scale_factors, scale_factors) - if isinstance(scale_factors, int) - else tuple(int(s) for s in scale_factors) + (float(scale_factors), float(scale_factors), float(scale_factors)) + if isinstance(scale_factors, (int, float)) + else tuple(float(s) for s in scale_factors) + ) + out_shape = ( + max(1, int(round(arr.shape[0] * factors[0]))), + max(1, int(round(arr.shape[1] * factors[1]))), + max(1, int(round(arr.shape[2] * factors[2]))), ) - out_shape = (arr.shape[0] * factors[0], arr.shape[1] * factors[1], arr.shape[2] * factors[2]) if mode == "tricubic": - out = zoom(arr, zoom=factors, order=3, mode="reflect").astype(np.float32, copy=False) + eff_zoom = ( + out_shape[0] / float(arr.shape[0]), + out_shape[1] / float(arr.shape[1]), + out_shape[2] / float(arr.shape[2]), + ) + out = zoom_cell_centered(arr, zoom_factors=eff_zoom, order=3) elif mode in ("nearest", "trilinear"): t = torch.from_numpy(arr).unsqueeze(0).unsqueeze(0) align = None if mode == "nearest" else False diff --git a/src/openlsrx/cli.py b/src/openlsrx/cli.py index d1f3354..3428616 100644 --- a/src/openlsrx/cli.py +++ b/src/openlsrx/cli.py @@ -7,19 +7,26 @@ import sys from collections.abc import Sequence from pathlib import Path -from typing import Any, Literal +from typing import Any, Literal, cast +import numpy as np import pytorch_lightning as pl +import tifffile +import torch from pytorch_lightning.cli import LightningCLI from .data import ( AVAILABLE_PUBLIC_DATASETS, PairedVolumeDataModule, # noqa: F401 - registered for LightningCLI subclass discovery SyntheticPoreSpyDataModule, # noqa: F401 - registered for LightningCLI subclass discovery + build_circular_fov_mask, fetch_or_generate_rock_sample, load_volume_any, + normalize_volume, prepare_zn13x_benchmark, ) +from .inference import super_resolve_volume_orthogonal +from .inference.orthogonal import AxisName, FusionMode from .io import export_for_openimpala from .metrics import ( evaluate_image_metrics, @@ -39,10 +46,10 @@ def _run_evaluate(argv: Sequence[str]) -> int: description="Compute 2D/3D image-fidelity, spectral FSC, petrophysical, and transport metrics on XCT volumes.", ) parser.add_argument( - "--pred", required=True, help="Path to super-resolved TIFF/HDF5/NPY volume." + "--pred", required=True, help="Path to super-resolved TIFF/HDF5/NPY volume or 2D slice." ) parser.add_argument( - "--target", required=True, help="Path to ground-truth HR TIFF/HDF5/NPY volume." + "--target", required=True, help="Path to ground-truth HR TIFF/HDF5/NPY volume or 2D slice." ) parser.add_argument( "--threshold", @@ -70,7 +77,7 @@ def _run_evaluate(argv: Sequence[str]) -> int: parser.add_argument( "--include-spectral", action="store_true", - help="Also compute 2D FRC / 3D FSC resolution cutoffs (1/2-bit and 0.143 criteria).", + help="Also compute 2D FRC / 3D FSC reference crossover (FSC=0.5) and spectral AUC.", ) parser.add_argument( "--include-triphase", @@ -84,6 +91,8 @@ def _run_evaluate(argv: Sequence[str]) -> int: ) parser.add_argument( "--export-openimpala-dir", + "--export-openimpala", + dest="export_openimpala_dir", type=str, default=None, help="Optional directory to export segmented 8-bit TIFF + AMReX .inputs for OpenImpala.", @@ -91,8 +100,8 @@ def _run_evaluate(argv: Sequence[str]) -> int: parser.add_argument("--output", type=str, default=None, help="Optional JSON output file path.") ns = parser.parse_args(list(argv)) - pred_vol = load_volume_any(ns.pred) - target_vol = load_volume_any(ns.target) + pred_vol = load_volume_any(ns.pred, preserve_2d=True) + target_vol = load_volume_any(ns.target, preserve_2d=True) if pred_vol.shape != target_vol.shape: raise ValueError( f"Shape mismatch between --pred {pred_vol.shape} and --target {target_vol.shape}." @@ -202,6 +211,8 @@ def _run_download_benchmarks(argv: Sequence[str]) -> int: ) parser.add_argument( "--dest", + "--output-dir", + dest="dest", default="data/benchmarks", help="Destination directory (default: data/benchmarks).", ) @@ -215,7 +226,12 @@ def _run_download_benchmarks(argv: Sequence[str]) -> int: "--raw-h5-dir", type=str, default=None, - help="Optional local directory containing raw Diamond I13-2 16906*_recon.h5 files.", + help="Optional local directory containing raw Diamond I13-2 16906*_recon.h5 or tomo_p4_tomopy_recon.h5 files.", + ) + parser.add_argument( + "--offline", + action="store_true", + help="Synthesize deterministic calibrated digital-rock/synchrotron phantoms offline without network fetches.", ) parser.add_argument( "--no-offline-fallback", @@ -237,6 +253,7 @@ def _run_download_benchmarks(argv: Sequence[str]) -> int: lr_size=lr_size, raw_h5_dir=ns.raw_h5_dir, allow_offline_fallback=(not ns.no_offline_fallback), + prefer_offline=bool(ns.offline), seed=ns.seed, ) print( @@ -249,6 +266,7 @@ def _run_download_benchmarks(argv: Sequence[str]) -> int: dest_dir=ns.dest, shape=shape, allow_offline_fallback=(not ns.no_offline_fallback), + prefer_offline=bool(ns.offline), seed=ns.seed, ) print( @@ -258,6 +276,171 @@ def _run_download_benchmarks(argv: Sequence[str]) -> int: return 0 +def _run_download_zn13x(argv: Sequence[str]) -> int: + parser = argparse.ArgumentParser( + prog="openlsrx download-zn13x", + description="Prepare Diamond Light Source I13-2 multi-magnification Zn-13X paired synchrotron volumes.", + ) + parser.add_argument( + "--pair", + choices=["2x", "8x", "all"], + default="all", + help="Magnification pair(s) to prepare: 2x, 8x, or all (default: all).", + ) + parser.add_argument( + "--dest", + "--output-dir", + dest="dest", + default="data/benchmarks", + help="Destination directory (default: data/benchmarks).", + ) + parser.add_argument( + "--lr-size", + type=int, + default=32, + help="Cubic LR side length in voxels (default: 32).", + ) + parser.add_argument("--raw-h5-dir", type=str, default=None) + parser.add_argument( + "--offline", + action="store_true", + help="Synthesize deterministic calibrated Zn-13X phantoms offline without network fetches.", + ) + parser.add_argument( + "--synthetic-fallback", + action="store_true", + help="Allow calibrated synthetic Zn-13X fallback when offline (enabled by default unless --no-offline-fallback).", + ) + parser.add_argument("--no-offline-fallback", action="store_true") + parser.add_argument("--seed", type=int, default=42) + ns = parser.parse_args(list(argv)) + + pairs: list[Literal["2x", "8x"]] = ( + ["2x", "8x"] if ns.pair == "all" else [cast(Literal["2x", "8x"], ns.pair)] + ) + allow_fb = bool(ns.synthetic_fallback) or (not ns.no_offline_fallback) + for pair in pairs: + lr_tif, hr_tif, manifest = prepare_zn13x_benchmark( + pair=pair, + dest_dir=ns.dest, + lr_size=ns.lr_size, + raw_h5_dir=ns.raw_h5_dir, + allow_offline_fallback=allow_fb, + prefer_offline=bool(ns.offline), + seed=ns.seed, + ) + print( + f"[zn13x_{pair}] ready at {lr_tif} & {hr_tif} " + f"(source={manifest['source_kind']}, hr_sha256={str(manifest['hr_sha256'])[:12]}...)" + ) + return 0 + + +def _run_predict_volume(argv: Sequence[str]) -> int: + parser = argparse.ArgumentParser( + prog="openlsrx predict-volume", + description="Run 3-axis orthogonal 2D/2.5D-to-3D XCT super-resolution and epistemic uncertainty export.", + ) + parser.add_argument( + "--checkpoint", + "--ckpt", + dest="checkpoint", + required=True, + help="Path to trained SRGAN/RRDB/SwinIR .ckpt file.", + ) + parser.add_argument("--input", required=True, help="Path to 3D LR TIFF/HDF5/NPY volume.") + parser.add_argument( + "--output", required=True, help="Output path for super-resolved 3D BigTIFF volume." + ) + parser.add_argument( + "--uncertainty-output", + default=None, + help="Optional output path for 3-axis epistemic uncertainty std map (.tiff).", + ) + parser.add_argument( + "--fusion", + choices=["mean", "median", "fourier", "confidence", "confidence_fourier"], + default="confidence_fourier", + help="Multi-axis volumetric fusion operator (default: confidence_fourier).", + ) + parser.add_argument( + "--axes", + nargs="+", + choices=["yz", "xz", "xy"], + default=["yz", "xz", "xy"], + help="Orthogonal sweep axes (default: yz xz xy).", + ) + parser.add_argument("--batch-size", type=int, default=8, help="Slice inference batch size.") + parser.add_argument( + "--norm-mode", + choices=["percentile", "minmax", "none", "fixed"], + default="percentile", + help="Input LR intensity normalization mode (default: percentile).", + ) + parser.add_argument( + "--vmin", type=float, default=None, help="Lower bound when --norm-mode=fixed." + ) + parser.add_argument( + "--vmax", type=float, default=None, help="Upper bound when --norm-mode=fixed." + ) + parser.add_argument("--circular-fov-mask", action="store_true") + parser.add_argument("--h5-dataset-key", default="4-TomopyRecon-tomo/data") + parser.add_argument( + "--device", + default=None, + help="Torch device override (e.g., 'cpu' or 'cuda:0'; auto-detected by default).", + ) + ns = parser.parse_args(list(argv)) + + dev = ( + torch.device(ns.device) + if ns.device is not None + else torch.device("cuda" if torch.cuda.is_available() else "cpu") + ) + model = SRGAN.load_from_checkpoint(ns.checkpoint, map_location=dev) + model.eval().to(dev) + + raw_lr = load_volume_any(ns.input, h5_dataset_key=ns.h5_dataset_key) + fov = build_circular_fov_mask(raw_lr.shape) if ns.circular_fov_mask else None + lr_norm = normalize_volume( + raw_lr, + mode=ns.norm_mode, + vmin=ns.vmin, + vmax=ns.vmax, + mask=fov, + ) + + axes = [cast(AxisName, ax) for ax in ns.axes] + ortho = super_resolve_volume_orthogonal( + generator=model.gen, + low_volume=lr_norm, + scale_factor=model.super_res_factor, + axes=axes, + fusion=cast(FusionMode, ns.fusion), + batch_size=ns.batch_size, + device=dev, + context_slices=model.context_slices, + return_uncertainty=(ns.uncertainty_output is not None), + ) + + out_path = Path(ns.output) + out_path.parent.mkdir(parents=True, exist_ok=True) + fused = np.ascontiguousarray(ortho["fused"], dtype=np.float32) + tifffile.imwrite(out_path, fused, bigtiff=True, photometric="minisblack") + + if ns.uncertainty_output is not None and "uncertainty_std" in ortho: + unc_path = Path(ns.uncertainty_output) + unc_path.parent.mkdir(parents=True, exist_ok=True) + tifffile.imwrite( + unc_path, + np.ascontiguousarray(ortho["uncertainty_std"], dtype=np.float32), + bigtiff=True, + photometric="minisblack", + ) + print(f"[predict-volume] fused shape={fused.shape} saved to {out_path}") + return 0 + + class OpenLSRXLightningCLI(LightningCLI): """LightningCLI binding ``SRGAN`` to any ``LightningDataModule`` subclass via YAML ``class_path``.""" @@ -271,6 +454,10 @@ def main(args: Sequence[str] | None = None) -> None: raise SystemExit(_run_export_openimpala(raw_args[1:])) if raw_args and raw_args[0] == "download-benchmarks": raise SystemExit(_run_download_benchmarks(raw_args[1:])) + if raw_args and raw_args[0] == "download-zn13x": + raise SystemExit(_run_download_zn13x(raw_args[1:])) + if raw_args and raw_args[0] == "predict-volume": + raise SystemExit(_run_predict_volume(raw_args[1:])) OpenLSRXLightningCLI( model_class=SRGAN, diff --git a/src/openlsrx/data/__init__.py b/src/openlsrx/data/__init__.py index 53d5d27..8b3684a 100644 --- a/src/openlsrx/data/__init__.py +++ b/src/openlsrx/data/__init__.py @@ -14,11 +14,17 @@ PairedSliceDataset, VolumeAlignment, apply_alignment, + build_circular_fov_mask, + build_multi_axis_slice_dataset, + compute_normalization_bounds, degrade_xct_volume, downsample_orthogonal_slabs, extract_paired_slices_from_subvolume, + minimum_psf_guard_slices_lr, normalize_volume, + sanitize_xct_volume, split_volume_spatially, + zoom_cell_centered, ) from .volumes import PairedVolumeDataModule, load_volume_any from .zn13x import ( @@ -48,6 +54,9 @@ "Zn13XPairName", "Zn13XResolutionSpec", "apply_alignment", + "build_circular_fov_mask", + "build_multi_axis_slice_dataset", + "compute_normalization_bounds", "degrade_xct_volume", "downsample_orthogonal_slabs", "extract_aligned_slab_from_h5", @@ -55,9 +64,12 @@ "fetch_or_generate_rock_sample", "generate_porespy_volume", "load_volume_any", + "minimum_psf_guard_slices_lr", "normalize_volume", "prepare_zn13x_benchmark", "register_multires_pair_3d", + "sanitize_xct_volume", "split_volume_spatially", "synthesize_zn13x_phantom_pair", + "zoom_cell_centered", ] diff --git a/src/openlsrx/data/public_benchmarks.py b/src/openlsrx/data/public_benchmarks.py index f817110..1737809 100644 --- a/src/openlsrx/data/public_benchmarks.py +++ b/src/openlsrx/data/public_benchmarks.py @@ -1,9 +1,13 @@ -"""Open-access micro-CT rock benchmark fetcher with SHA-256 verification and offlineHPC fallback.""" +"""Open-access micro-CT rock benchmark fetcher with cryptographic checksum verification and HPC-safe locking.""" from __future__ import annotations +import fcntl import hashlib import json +import os +import shutil +import urllib.parse import urllib.request from dataclasses import dataclass from pathlib import Path @@ -13,6 +17,7 @@ from scipy.ndimage import distance_transform_edt, gaussian_filter from .synthetic import _porespy_blobs +from .transforms import normalize_volume @dataclass(frozen=True) @@ -26,6 +31,8 @@ class PublicRockSpec: license_name: str url: str | None sha256: str | None + md5: str | None + file_format: str raw_dtype: str raw_shape: tuple[int, int, int] target_porosity: float @@ -36,27 +43,47 @@ class PublicRockSpec: AVAILABLE_PUBLIC_DATASETS: dict[str, PublicRockSpec] = { "bentheimer_sandstone": PublicRockSpec( name="bentheimer_sandstone", - description="Bentheimer Sandstone micro-CT benchmark (well-sorted quartz arenite, ~22% porosity).", + description="Bentheimer Sandstone experimental micro-CT subvolume (Core 1 Subvol 1, 6 um voxel size, ~22% porosity).", lithology="Sandstone", - reference="Imperial College London Pore-Scale Modelling Micro-CT Collection (Blunt et al., Adv. Water Resour. 2013)", + reference="Jackson, S. J., Niu, Y., Manoorkar, S., Mostaghimi, P. & Armstrong, R. T., Multi-resolution Bentheimer Sandstone micro-CT dataset, Zenodo (2021), https://doi.org/10.5281/zenodo.5542624", license_name="CC-BY-4.0", - url="https://imperialcollegelondon.box.com/shared/static/bentheimer_microct_subvolume.raw", + url="https://zenodo.org/records/5542624/files/Core1_Subvol1_LR.tif?download=1", sha256=None, + md5="e6a30d40ef987571fab6b8393cef272a", + file_format="tif", raw_dtype="uint8", - raw_shape=(128, 128, 128), + raw_shape=(225, 225, 225), target_porosity=0.22, macro_blobiness=1.1, micro_blobiness=None, ), + "bentheimer_laminated": PublicRockSpec( + name="bentheimer_laminated", + description="Laminated Bentheimer Sandstone experimental micro-CT subvolume (Core 2 Subvol 2, 6 um voxel size).", + lithology="Sandstone", + reference="Jackson, S. J., Niu, Y., Manoorkar, S., Mostaghimi, P. & Armstrong, R. T., Multi-resolution Bentheimer Sandstone micro-CT dataset, Zenodo (2021), https://doi.org/10.5281/zenodo.5542624", + license_name="CC-BY-4.0", + url="https://zenodo.org/records/5542624/files/Core2_Subvol2_LR.tif?download=1", + sha256=None, + md5="762404de42a61484134bb27c5d910f33", + file_format="tif", + raw_dtype="uint8", + raw_shape=(225, 225, 225), + target_porosity=0.20, + macro_blobiness=1.25, + micro_blobiness=None, + ), "indiana_limestone": PublicRockSpec( name="indiana_limestone", - description="Indiana Limestone micro-CT benchmark (bimodal fossiliferous/oolitic carbonate, ~18% total porosity).", + description="Calibrated bimodal vuggy + microporous carbonate XCT phantom (~18% total porosity).", lithology="Carbonate", - reference="Imperial College London Pore-Scale Modelling Micro-CT Collection (Blunt et al., Adv. Water Resour. 2013)", + reference="Calibrated bimodal carbonate phantom parameterized after Blunt et al., Adv. Water Resour. 51, 197-216 (2013)", license_name="CC-BY-4.0", - url="https://imperialcollegelondon.box.com/shared/static/indiana_microct_subvolume.raw", + url=None, sha256=None, - raw_dtype="uint8", + md5=None, + file_format="phantom", + raw_dtype="float32", raw_shape=(128, 128, 128), target_porosity=0.18, macro_blobiness=0.65, @@ -65,14 +92,31 @@ class PublicRockSpec: } -def _sha256_file(path: Path) -> str: - h = hashlib.sha256() +def _hash_file(path: Path, algorithm: str = "sha256") -> str: + h = hashlib.new(algorithm) with path.open("rb") as f: for chunk in iter(lambda: f.read(65536), b""): h.update(chunk) return h.hexdigest() +def _download_https_file(url: str, dest: Path, timeout_s: float = 30.0) -> None: + parsed = urllib.parse.urlparse(url) + if parsed.scheme.lower() != "https": + raise ValueError(f"Refusing non-HTTPS benchmark download URL: {url!r}") + req = urllib.request.Request(url, headers={"User-Agent": "OpenLSR-X/0.2.0"}) + with urllib.request.urlopen(req, timeout=timeout_s) as resp, dest.open("wb") as out_f: # noqa: S310 + shutil.copyfileobj(resp, out_f) + + +def _center_crop_3d(arr: np.ndarray, shape: tuple[int, int, int]) -> np.ndarray: + d, h, w = (min(int(arr.shape[i]), int(shape[i])) for i in range(3)) + z0 = max(0, (arr.shape[0] - d) // 2) + y0 = max(0, (arr.shape[1] - h) // 2) + x0 = max(0, (arr.shape[2] - w) // 2) + return np.ascontiguousarray(arr[z0 : z0 + d, y0 : y0 + h, x0 : x0 + w], dtype=np.float32) + + def _synthesize_calibrated_rock_phantom( spec: PublicRockSpec, shape: tuple[int, int, int], @@ -82,7 +126,6 @@ def _synthesize_calibrated_rock_phantom( rng = np.random.default_rng(seed) if spec.micro_blobiness is None: - # Intergranular sandstone with realistic sub-grain cementation gradients pore_mask = _porespy_blobs( shape=shape, blobiness=spec.macro_blobiness, @@ -97,7 +140,6 @@ def _synthesize_calibrated_rock_phantom( 0.78 + 0.12 * grain_dt, ).astype(np.float32) else: - # Bimodal vuggy + intragranular microporous carbonate (Indiana Limestone) macro_pores = _porespy_blobs( shape=shape, blobiness=spec.macro_blobiness, @@ -118,12 +160,10 @@ def _synthesize_calibrated_rock_phantom( ) effective_micro = np.logical_and(micro_pores, microporous_zone) attenuation = np.full(shape, 0.86, dtype=np.float32) - # Sub-resolvable microporous calcite rims have intermediate greyscale attenuation attenuation[microporous_zone] = 0.72 attenuation[effective_micro] = 0.22 attenuation[macro_pores] = 0.12 - # Detector partial-volume smoothing + subtle XCT acquisition noise attenuation = gaussian_filter(attenuation, sigma=0.5, mode="reflect") attenuation = attenuation + rng.normal(0.0, 0.012, size=shape).astype(np.float32) return np.clip(attenuation, 0.0, 1.0).astype(np.float32, copy=False) @@ -134,12 +174,16 @@ def fetch_or_generate_rock_sample( dest_dir: str | Path = "data/benchmarks", shape: tuple[int, int, int] = (128, 128, 128), allow_offline_fallback: bool = True, + prefer_offline: bool = False, + timeout_s: float = 30.0, seed: int = 42, ) -> tuple[Path, dict[str, object]]: - """Download an open micro-CT benchmark stack (or synthesize a calibrated phantom offline). + """Download a verified open micro-CT benchmark stack (or synthesize an explicitly labeled phantom). Writes ``/_hr.tif`` and ``/_manifest.json`` - recording exact provenance, checksum, shape, and parameters. + atomically under an exclusive file lock (safe across concurrent SLURM array tasks on Lustre). + Provenance is strictly recorded in ``manifest['source_kind']`` (``'downloaded_zenodo_5542624'`` + vs. ``'calibrated_carbonate_phantom'`` / ``'offline_calibrated_phantom'``). """ if dataset_name not in AVAILABLE_PUBLIC_DATASETS: raise KeyError( @@ -151,57 +195,96 @@ def fetch_or_generate_rock_sample( out_dir.mkdir(parents=True, exist_ok=True) tif_path = out_dir / f"{spec.name}_hr.tif" manifest_path = out_dir / f"{spec.name}_manifest.json" + lock_path = out_dir / f".{spec.name}.lock" + + with lock_path.open("w") as lf: + fcntl.flock(lf.fileno(), fcntl.LOCK_EX) + if tif_path.is_file() and manifest_path.is_file(): + cached_manifest: dict[str, object] = json.loads( + manifest_path.read_text(encoding="utf-8") + ) + shape_ok = cached_manifest.get("requested_shape", cached_manifest.get("shape")) == list( + shape + ) + offline_cached = cached_manifest.get("source_kind") == "offline_calibrated_phantom" + want_real = (spec.url is not None) and (not prefer_offline) + if shape_ok and not (want_real and offline_cached): + return tif_path, cached_manifest + + pid = os.getpid() + source_kind = ( + "calibrated_carbonate_phantom" if spec.url is None else "downloaded_zenodo_5542624" + ) + vol: np.ndarray | None = None - if tif_path.is_file() and manifest_path.is_file(): - cached_manifest: dict[str, object] = json.loads(manifest_path.read_text(encoding="utf-8")) - return tif_path, cached_manifest - - source_kind = "downloaded" - vol: np.ndarray | None = None - - if spec.url is not None: - raw_tmp = out_dir / f".{spec.name}.download" - try: - urllib.request.urlretrieve(spec.url, raw_tmp) # noqa: S310 - if spec.sha256 is not None: - actual = _sha256_file(raw_tmp) - if actual.lower() != spec.sha256.lower(): - raise ValueError( - f"SHA-256 mismatch for {spec.name}: expected {spec.sha256}, got {actual}" + if spec.url is not None and not prefer_offline: + raw_tmp = out_dir / f".{spec.name}.{pid}.download" + try: + _download_https_file(spec.url, raw_tmp, timeout_s=timeout_s) + if spec.sha256 is not None: + actual_sha = _hash_file(raw_tmp, "sha256") + if actual_sha.lower() != spec.sha256.lower(): + raise ValueError( + f"SHA-256 mismatch for {spec.name}: expected {spec.sha256}, got {actual_sha}" + ) + if spec.md5 is not None: + actual_md5 = _hash_file(raw_tmp, "md5") + if actual_md5.lower() != spec.md5.lower(): + raise ValueError( + f"MD5 mismatch for {spec.name}: expected {spec.md5}, got {actual_md5}" + ) + + if spec.file_format == "tif": + loaded = tifffile.imread(raw_tmp) + cropped = _center_crop_3d(loaded, shape=shape) + vol = normalize_volume( + cropped, mode="percentile", lower_pct=0.2, upper_pct=99.8 + ) + else: + raw_bytes = np.fromfile(raw_tmp, dtype=spec.raw_dtype) + expected_elems = int(np.prod(spec.raw_shape)) + if raw_bytes.size >= expected_elems: + arr = raw_bytes[:expected_elems].reshape(spec.raw_shape) + cropped = _center_crop_3d(arr, shape=shape) + vol = normalize_volume(cropped, mode="minmax") + except Exception as exc: + if not allow_offline_fallback: + raise RuntimeError( + f"Failed to download {spec.name} from {spec.url} and offline fallback is disabled." + ) from exc + source_kind = "offline_calibrated_phantom" + finally: + raw_tmp.unlink(missing_ok=True) + + if vol is None: + if spec.url is not None: + if not allow_offline_fallback and not prefer_offline: + raise RuntimeError( + f"Real dataset {spec.name} was not loaded and offline fallback is disabled." ) - raw_bytes = np.fromfile(raw_tmp, dtype=spec.raw_dtype) - expected_elems = int(np.prod(spec.raw_shape)) - if raw_bytes.size >= expected_elems: - arr = raw_bytes[:expected_elems].reshape(spec.raw_shape).astype(np.float32) - lo, hi = float(arr.min()), float(arr.max()) - vol = (arr - lo) / max(hi - lo, 1e-8) - vol = vol[: shape[0], : shape[1], : shape[2]] - except Exception as exc: - if not allow_offline_fallback: - raise RuntimeError( - f"Failed to download {spec.name} from {spec.url} and offline fallback is disabled." - ) from exc - source_kind = "offline_calibrated_phantom" - finally: - if raw_tmp.exists(): - raw_tmp.unlink() - - if vol is None: - source_kind = "offline_calibrated_phantom" - vol = _synthesize_calibrated_rock_phantom(spec=spec, shape=shape, seed=seed) - - tifffile.imwrite(tif_path, vol.astype(np.float32), photometric="minisblack") - sha = _sha256_file(tif_path) - manifest: dict[str, object] = { - "name": spec.name, - "lithology": spec.lithology, - "description": spec.description, - "source_kind": source_kind, - "reference": spec.reference, - "license": spec.license_name, - "shape": list(vol.shape), - "sha256": sha, - "seed": seed, - } - manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8") - return tif_path, manifest + source_kind = "offline_calibrated_phantom" + vol = _synthesize_calibrated_rock_phantom(spec=spec, shape=shape, seed=seed) + + is_exp = source_kind.startswith("downloaded") + tif_tmp = out_dir / f".{spec.name}_hr.{pid}.tif" + man_tmp = out_dir / f".{spec.name}_manifest.{pid}.json" + tifffile.imwrite(tif_tmp, vol.astype(np.float32), photometric="minisblack") + sha = _hash_file(tif_tmp, "sha256") + manifest: dict[str, object] = { + "name": spec.name, + "lithology": spec.lithology, + "description": spec.description, + "source_kind": source_kind, + "is_experimental_xct": is_exp, + "source_url": spec.url if is_exp else None, + "reference": spec.reference, + "license": spec.license_name, + "requested_shape": list(shape), + "shape": list(vol.shape), + "sha256": sha, + "seed": seed, + } + man_tmp.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8") + tif_tmp.replace(tif_path) + man_tmp.replace(manifest_path) + return tif_path, manifest diff --git a/src/openlsrx/data/synthetic.py b/src/openlsrx/data/synthetic.py index a614d88..c770dc9 100644 --- a/src/openlsrx/data/synthetic.py +++ b/src/openlsrx/data/synthetic.py @@ -2,9 +2,11 @@ from __future__ import annotations +import fcntl import hashlib import inspect import json +import os from pathlib import Path from typing import Literal @@ -13,10 +15,13 @@ import pytorch_lightning as pl import tifffile from scipy.ndimage import gaussian_filter -from torch.utils.data import DataLoader +from torch import Tensor +from torch.utils.data import DataLoader, Dataset from .transforms import ( PairedSliceDataset, + build_multi_axis_slice_dataset, + compute_normalization_bounds, degrade_xct_volume, extract_paired_slices_from_subvolume, normalize_volume, @@ -66,46 +71,15 @@ def _porespy_local_thickness(pore_mask: np.ndarray, sizes: int = 25) -> np.ndarr ) -def generate_porespy_volume( - shape: int | tuple[int, int, int] = 128, - feature_regime: FeatureRegime = "high_feature", - noise_regime: NoiseRegime = "low_noise", - representation: SyntheticRepresentation = "attenuation", - scale_factor: int = 2, - hr_noise_std: float | None = None, - lr_noise_std: float | None = None, - psf_sigma: float = 0.8, - seed: int = 42, -) -> tuple[np.ndarray, np.ndarray, np.ndarray]: - """Generate a deterministic 3D porous-media benchmark tuple ``(lr_vol, hr_vol, pore_mask)``. - - Args: - shape: Isotropic integer side length or ``(D, H, W)`` tuple for the HR volume. - feature_regime: - - ``'low_feature'``: Single-scale coarse pore network (``blobiness=1.0, porosity=0.40``). - - ``'high_feature'``: Multi-scale dual-porosity network combining macro-pores - and micro-throats (inspired by carbonate/sandstone XCT). - noise_regime: ``'low_noise'`` vs. ``'high_noise'`` acquisition presets. - representation: - - ``'attenuation'``: Realistic two-phase greyscale X-ray attenuation volume where - pore phase has low intensity (~0.15) and solid matrix has high intensity (~0.85) - with partial-volume boundary smoothing. - - ``'local_thickness'``: Normalized 3D local pore-throat thickness field (matching - Calum Green's original PoreSpy synthetic formulation). - scale_factor: Spatial downsampling factor between ``hr_vol`` and ``lr_vol``. - hr_noise_std: Optional override for HR Gaussian acquisition noise. - lr_noise_std: Optional override for LR Gaussian acquisition noise. - psf_sigma: Detector point-spread Gaussian sigma applied before voxel binning. - seed: Deterministic RNG seed. - - Returns: - ``(lr_vol, hr_vol, pore_mask)`` where ``hr_vol`` and ``pore_mask`` have shape ``(D, H, W)`` - and ``lr_vol`` has isotropic shape ``(D // s, H // s, W // s)``. - """ - vol_shape = (shape, shape, shape) if isinstance(shape, int) else tuple(int(x) for x in shape) - if len(vol_shape) != 3: - raise ValueError(f"shape must be an int or 3-tuple, got {shape!r}.") - +def _generate_hr_porespy_field( + vol_shape: tuple[int, int, int], + feature_regime: FeatureRegime, + noise_regime: NoiseRegime, + representation: SyntheticRepresentation, + hr_noise_std: float | None, + seed: int, +) -> tuple[np.ndarray, np.ndarray, float]: + """Generate unsplit HR field + boolean pore mask + contrast_shift before LR degradation.""" rng = np.random.default_rng(seed) if feature_regime == "low_feature": @@ -120,31 +94,62 @@ def generate_porespy_volume( ) default_hr_sigma = 0.008 if noise_regime == "low_noise" else 0.018 - default_lr_sigma = 0.015 if noise_regime == "low_noise" else 0.055 sigma_hr = default_hr_sigma if hr_noise_std is None else float(hr_noise_std) - sigma_lr = default_lr_sigma if lr_noise_std is None else float(lr_noise_std) if representation == "attenuation": - # Solid grain matrix = 0.85, pore space = 0.15, with mild partial-volume interface blur clean = np.where(pore_mask, 0.15, 0.85).astype(np.float32) clean = gaussian_filter(clean, sigma=0.45, mode="reflect") if sigma_hr > 0.0: clean = clean + rng.normal(0.0, sigma_hr, size=clean.shape).astype(np.float32) - hr_vol = np.clip(clean, 0.0, 1.0).astype(np.float32, copy=False) + hr_raw = np.clip(clean, 0.0, 1.0).astype(np.float32, copy=False) contrast_shift = 0.0 elif representation == "local_thickness": thk = _porespy_local_thickness(pore_mask, sizes=25) hr_clean = normalize_volume(thk, mode="minmax") if sigma_hr > 0.0: - hr_noisy = hr_clean + rng.normal(0.0, sigma_hr, size=hr_clean.shape).astype(np.float32) - hr_vol = normalize_volume(hr_noisy, mode="minmax") + hr_raw = ( + hr_clean + rng.normal(0.0, sigma_hr, size=hr_clean.shape).astype(np.float32) + ).astype(np.float32, copy=False) else: - hr_vol = hr_clean + hr_raw = hr_clean contrast_shift = 0.05 if noise_regime == "high_noise" else 0.02 else: raise ValueError( f"Unsupported representation={representation!r}. Expected 'attenuation' or 'local_thickness'." ) + return hr_raw, pore_mask, contrast_shift + + +def generate_porespy_volume( + shape: int | tuple[int, int, int] = 128, + feature_regime: FeatureRegime = "high_feature", + noise_regime: NoiseRegime = "low_noise", + representation: SyntheticRepresentation = "attenuation", + scale_factor: float = 2, + hr_noise_std: float | None = None, + lr_noise_std: float | None = None, + psf_sigma: float = 0.8, + seed: int = 42, +) -> tuple[np.ndarray, np.ndarray, np.ndarray]: + """Generate a deterministic 3D porous-media benchmark tuple ``(lr_vol, hr_vol, pore_mask)``.""" + vol_shape = (shape, shape, shape) if isinstance(shape, int) else tuple(int(x) for x in shape) + if len(vol_shape) != 3: + raise ValueError(f"shape must be an int or 3-tuple, got {shape!r}.") + + default_lr_sigma = 0.015 if noise_regime == "low_noise" else 0.055 + sigma_lr = default_lr_sigma if lr_noise_std is None else float(lr_noise_std) + + hr_raw, pore_mask, contrast_shift = _generate_hr_porespy_field( + vol_shape=vol_shape, + feature_regime=feature_regime, + noise_regime=noise_regime, + representation=representation, + hr_noise_std=hr_noise_std, + seed=seed, + ) + hr_vol = ( + normalize_volume(hr_raw, mode="minmax") if representation == "local_thickness" else hr_raw + ) lr_vol = degrade_xct_volume( hr_volume=hr_vol, @@ -160,10 +165,10 @@ def generate_porespy_volume( class SyntheticPoreSpyDataModule(pl.LightningDataModule): """Leakage-free 3D synthetic PoreSpy LightningDataModule for XCT super-resolution. - Generates (or loads from ``cache_dir``) a 3D HR/LR porous-media volume pair, splits it - into spatially disjoint 3D slabs along ``split_axis``, trains on 2D slices along - ``train_axes`` (default ``('yz',)``), and evaluates on parallel (``'yz'``) or - perpendicular (``'xz'``, ``'xy'``) orthogonal planes. + Enforces strict spatial isolation across ``train`` / ``val`` / ``test``: + - Splits the 3D HR volume spatially *before* fitting ``minmax`` bounds (on ``train`` only) + and *before* applying 3D PSF Gaussian blur + downsampling independently per split, so no + ``val``/``test`` voxel or intensity bound ever leaks into ``train``. """ def __init__( @@ -172,7 +177,8 @@ def __init__( feature_regime: FeatureRegime = "high_feature", noise_regime: NoiseRegime = "low_noise", representation: SyntheticRepresentation = "attenuation", - scale_factor: int = 2, + scale_factor: float = 2, + psf_sigma: float = 0.8, train_frac: float = 0.70, val_frac: float = 0.15, split_axis: int = 0, @@ -180,7 +186,10 @@ def __init__( train_axes: tuple[str, ...] = ("yz",), test_axis: TestAxisMode = "perpendicular", predict_axis: Literal["yz", "xz", "xy"] = "xy", + predict_mode: Literal["orthogonal_3axis", "single_axis"] = "orthogonal_3axis", + predict_fusion: str = "confidence_fourier", patch_size_lr: int | None = None, + context_slices: int = 1, augment: bool = True, batch_size: int = 4, eval_batch_size: int = 4, @@ -192,12 +201,22 @@ def __init__( ) -> None: super().__init__() self.save_hyperparameters() + if context_slices < 1 or context_slices % 2 == 0: + raise ValueError( + f"context_slices must be a positive odd integer (1, 3, 5, ...), got {context_slices}." + ) self.volume_size = volume_size self.feature_regime: FeatureRegime = feature_regime self.noise_regime: NoiseRegime = noise_regime self.representation: SyntheticRepresentation = representation - self.scale_factor = int(scale_factor) + s_round = int(round(float(scale_factor))) + self.scale_factor: float = ( + int(s_round) + if abs(float(scale_factor) - float(s_round)) < 1e-6 + else float(scale_factor) + ) + self.psf_sigma = float(psf_sigma) self.train_frac = float(train_frac) self.val_frac = float(val_frac) self.split_axis = int(split_axis) @@ -205,7 +224,10 @@ def __init__( self.train_axes = tuple(train_axes) self.test_axis: TestAxisMode = test_axis self.predict_axis = predict_axis + self.predict_mode = predict_mode + self.predict_fusion = str(predict_fusion) self.patch_size_lr = patch_size_lr + self.context_slices = int(context_slices) self.augment = bool(augment) self.batch_size = int(batch_size) self.eval_batch_size = int(eval_batch_size) @@ -215,14 +237,29 @@ def __init__( self.seed = int(seed) self.cache_dir = cache_dir - self.train_dataset: PairedSliceDataset | None = None - self.val_dataset: PairedSliceDataset | None = None - self.test_dataset: PairedSliceDataset | None = None + self.train_dataset: Dataset[tuple[Tensor, Tensor]] | None = None + self.val_dataset: Dataset[tuple[Tensor, Tensor]] | None = None + self.test_dataset: Dataset[tuple[Tensor, Tensor]] | None = None self.predict_dataset: PairedSliceDataset | None = None + self.predict_lr_volume: np.ndarray | None = None + self.predict_Spatial_shape_hr: tuple[int, int, int] | None = None self.splits_3d: dict[str, tuple[np.ndarray, np.ndarray]] = {} - def _load_or_generate(self) -> tuple[np.ndarray, np.ndarray]: + def _prepare_leakage_free_splits(self) -> None: + vol_shape: tuple[int, int, int] = ( + (self.volume_size, self.volume_size, self.volume_size) + if isinstance(self.volume_size, int) + else (int(self.volume_size[0]), int(self.volume_size[1]), int(self.volume_size[2])) + ) + sigma_lr = 0.015 if self.noise_regime == "low_noise" else 0.055 + contrast_shift = ( + (0.05 if self.noise_regime == "high_noise" else 0.02) + if self.representation == "local_thickness" + else 0.0 + ) + + hr_raw: np.ndarray | None = None if self.cache_dir is not None: cache_root = Path(self.cache_dir) cache_root.mkdir(parents=True, exist_ok=True) @@ -233,6 +270,7 @@ def _load_or_generate(self) -> tuple[np.ndarray, np.ndarray]: "noise_regime": self.noise_regime, "representation": self.representation, "scale_factor": self.scale_factor, + "psf_sigma": self.psf_sigma, "seed": self.seed, }, sort_keys=True, @@ -240,68 +278,107 @@ def _load_or_generate(self) -> tuple[np.ndarray, np.ndarray]: digest = hashlib.sha256(spec.encode("utf-8")).hexdigest()[:12] hr_file = cache_root / f"porespy_hr_{digest}.tif" lr_file = cache_root / f"porespy_lr_{digest}.tif" - if hr_file.is_file() and lr_file.is_file(): - return ( - tifffile.imread(lr_file).astype(np.float32), - tifffile.imread(hr_file).astype(np.float32), - ) - - lr_vol, hr_vol, _ = generate_porespy_volume( - shape=self.volume_size, + lock_file = cache_root / f".porespy_{digest}.lock" + with lock_file.open("w") as lf: + fcntl.flock(lf.fileno(), fcntl.LOCK_EX) + if hr_file.is_file() and lr_file.is_file(): + hr_raw = tifffile.imread(hr_file).astype(np.float32) + else: + hr_gen, _, _ = _generate_hr_porespy_field( + vol_shape=vol_shape, + feature_regime=self.feature_regime, + noise_regime=self.noise_regime, + representation=self.representation, + hr_noise_std=None, + seed=self.seed, + ) + lr_preview = degrade_xct_volume( + hr_volume=normalize_volume(hr_gen, mode="minmax") + if self.representation == "local_thickness" + else hr_gen, + scale_factor=self.scale_factor, + psf_sigma=self.psf_sigma, + noise_std=sigma_lr, + contrast_shift=contrast_shift, + seed=self.seed + 999, + ) + pid = os.getpid() + hr_tmp = cache_root / f".porespy_hr_{digest}.{pid}.tmp" + lr_tmp = cache_root / f".porespy_lr_{digest}.{pid}.tmp" + tifffile.imwrite(hr_tmp, hr_gen, photometric="minisblack") + tifffile.imwrite(lr_tmp, lr_preview, photometric="minisblack") + hr_tmp.replace(hr_file) + lr_tmp.replace(lr_file) + hr_raw = hr_gen + + if hr_raw is None: + hr_raw, _, _ = _generate_hr_porespy_field( + vol_shape=vol_shape, feature_regime=self.feature_regime, noise_regime=self.noise_regime, representation=self.representation, - scale_factor=self.scale_factor, + hr_noise_std=None, seed=self.seed, ) - tifffile.imwrite(hr_file, hr_vol, photometric="minisblack") - tifffile.imwrite(lr_file, lr_vol, photometric="minisblack") - return lr_vol, hr_vol - - lr_vol, hr_vol, _ = generate_porespy_volume( - shape=self.volume_size, - feature_regime=self.feature_regime, - noise_regime=self.noise_regime, - representation=self.representation, + + raw_splits = split_volume_spatially( + hr_volume=hr_raw, + lr_volume=None, scale_factor=self.scale_factor, - seed=self.seed, + train_frac=self.train_frac, + val_frac=self.val_frac, + split_axis=self.split_axis, + guard_slices_lr=self.guard_slices_lr, ) - return lr_vol, hr_vol - def setup(self, stage: str | None = None) -> None: - if not self.splits_3d: - lr_vol, hr_vol = self._load_or_generate() - raw_splits = split_volume_spatially( - hr_volume=hr_vol, - lr_volume=lr_vol, + # Fit normalization strictly on train split when local_thickness is used + if self.representation == "local_thickness": + tr_lo, tr_hi = compute_normalization_bounds(raw_splits["train"][1], mode="minmax") + else: + tr_lo, tr_hi = 0.0, 1.0 + + for idx_split, (split_name, (_, hr_sub_raw)) in enumerate(raw_splits.items()): + hr_sub = ( + normalize_volume(hr_sub_raw, mode="fixed", vmin=tr_lo, vmax=tr_hi) + if self.representation == "local_thickness" + else np.clip(hr_sub_raw, 0.0, 1.0).astype(np.float32, copy=False) + ) + lr_sub = degrade_xct_volume( + hr_volume=hr_sub, scale_factor=self.scale_factor, - train_frac=self.train_frac, - val_frac=self.val_frac, - split_axis=self.split_axis, - guard_slices_lr=self.guard_slices_lr, + psf_sigma=self.psf_sigma, + noise_std=sigma_lr, + contrast_shift=contrast_shift, + seed=self.seed + 999 + 131 * idx_split, ) - self.splits_3d = {k: (v[0], v[1]) for k, v in raw_splits.items() if v[0] is not None} + self.splits_3d[split_name] = (lr_sub, hr_sub) + + def setup(self, stage: str | None = None) -> None: + if not self.splits_3d: + self._prepare_leakage_free_splits() if stage in (None, "fit"): lr_tr, hr_tr = self.splits_3d["train"] - tr_low, tr_high = extract_paired_slices_from_subvolume( - lr_tr, hr_tr, scale_factor=self.scale_factor, axes=self.train_axes - ) - self.train_dataset = PairedSliceDataset( - tr_low, - tr_high, - patch_size_lr=self.patch_size_lr, + self.train_dataset = build_multi_axis_slice_dataset( + lr_tr, + hr_tr, scale_factor=self.scale_factor, + axes=self.train_axes, + patch_size_lr=self.patch_size_lr, augment=self.augment, + context_slices=self.context_slices, ) if stage in (None, "fit", "validate"): lr_va, hr_va = self.splits_3d["val"] - va_low, va_high = extract_paired_slices_from_subvolume( - lr_va, hr_va, scale_factor=self.scale_factor, axes=self.train_axes - ) - self.val_dataset = PairedSliceDataset( - va_low, va_high, scale_factor=self.scale_factor, augment=False + self.val_dataset = build_multi_axis_slice_dataset( + lr_va, + hr_va, + scale_factor=self.scale_factor, + axes=self.train_axes, + patch_size_lr=None, + augment=False, + context_slices=self.context_slices, ) if stage in (None, "test"): @@ -312,20 +389,37 @@ def setup(self, stage: str | None = None) -> None: axes = ("xz", "xy") else: axes = ("yz", "xz", "xy") - te_low, te_high = extract_paired_slices_from_subvolume( - lr_te, hr_te, scale_factor=self.scale_factor, axes=axes - ) - self.test_dataset = PairedSliceDataset( - te_low, te_high, scale_factor=self.scale_factor, augment=False + self.test_dataset = build_multi_axis_slice_dataset( + lr_te, + hr_te, + scale_factor=self.scale_factor, + axes=axes, + patch_size_lr=None, + augment=False, + context_slices=self.context_slices, ) if stage in (None, "predict"): lr_te, hr_te = self.splits_3d["test"] + self.predict_lr_volume = lr_te + self.predict_Spatial_shape_hr = ( + int(hr_te.shape[0]), + int(hr_te.shape[1]), + int(hr_te.shape[2]), + ) pr_low, pr_high = extract_paired_slices_from_subvolume( - lr_te, hr_te, scale_factor=self.scale_factor, axes=(self.predict_axis,) + lr_te, + hr_te, + scale_factor=self.scale_factor, + axes=(self.predict_axis,), + context_slices=self.context_slices, ) self.predict_dataset = PairedSliceDataset( - pr_low, pr_high, scale_factor=self.scale_factor, augment=False + pr_low, + pr_high, + scale_factor=self.scale_factor, + augment=False, + context_slices=self.context_slices, ) @property diff --git a/src/openlsrx/data/transforms.py b/src/openlsrx/data/transforms.py index e3bc695..27d6d77 100644 --- a/src/openlsrx/data/transforms.py +++ b/src/openlsrx/data/transforms.py @@ -1,16 +1,18 @@ -"""Vectorized XCT normalization, alignment, realistic degradation, and leakage-free 3D splitting.""" +"""Vectorized XCT normalization, alignment, cell-centered resampling, and leakage-free 3D splitting.""" from __future__ import annotations +import math from dataclasses import dataclass from typing import Literal import cv2 import numpy as np import torch +import torch.nn.functional as F from scipy.ndimage import gaussian_filter, zoom from torch import Tensor -from torch.utils.data import Dataset +from torch.utils.data import ConcatDataset, Dataset NormMode = Literal["minmax", "percentile", "fixed", "none"] @@ -25,6 +27,89 @@ class VolumeAlignment: rotation_deg: float = 0.0 +def sanitize_xct_volume( + volume: np.ndarray, + nan_fill: float | None = None, +) -> np.ndarray: + """Replace non-finite (``NaN``, ``±Inf``) Savu/TomoPy reconstruction artifacts safely. + + Synchrotron reconstruction pipelines (e.g., cylindrical FOV masks, Paganin phase retrieval, + or dead detector stripes) frequently emit ``NaN`` or ``±Inf`` voxels that would otherwise + corrupt global percentiles, 3D convolutions, and FFTs across 100% of the volume. + """ + raw = np.asarray(volume) + orig_kind = raw.dtype.kind + orig_itemsize = raw.dtype.itemsize + arr = np.asarray(raw, dtype=np.float32) + if orig_kind == "u": + max_int = float((1 << (8 * orig_itemsize)) - 1) + if max_int > 0.0 and float(np.nanmax(arr)) > 1.0: + arr = arr / max_int + + finite_mask = np.isfinite(arr) + if bool(finite_mask.all()): + return arr + + if not bool(finite_mask.any()): + fill = 0.0 if nan_fill is None else float(nan_fill) + return np.full_like(arr, fill, dtype=np.float32) + + finite_vals = arr[finite_mask] + f_min = float(finite_vals.min()) + f_max = float(finite_vals.max()) + default_fill = f_min if nan_fill is None else float(nan_fill) + out = arr.copy() + out[np.isnan(out)] = default_fill + out[np.isneginf(out)] = f_min + out[np.isposinf(out)] = f_max + return out + + +def build_circular_fov_mask(shape: tuple[int, ...], radius_fraction: float = 0.98) -> np.ndarray: + """Build an inscribed circular cylindrical XCT field-of-view mask along ``(H, W)``.""" + if len(shape) == 2: + h, w = shape + yy, xx = np.ogrid[:h, :w] + cy, cx = (h - 1) / 2.0, (w - 1) / 2.0 + ry = max(h / 2.0 * float(radius_fraction), 1.0) + rx = max(w / 2.0 * float(radius_fraction), 1.0) + return (((yy - cy) / ry) ** 2 + ((xx - cx) / rx) ** 2) <= 1.0 + if len(shape) == 3: + _, h, w = shape + mask_2d = build_circular_fov_mask((h, w), radius_fraction=radius_fraction) + return np.broadcast_to(mask_2d[np.newaxis, :, :], shape).copy() + raise ValueError(f"Expected 2D or 3D shape for circular FOV mask, got {shape}.") + + +def compute_normalization_bounds( + volume: np.ndarray, + mode: NormMode = "minmax", + vmin: float | None = None, + vmax: float | None = None, + lower_pct: float = 0.5, + upper_pct: float = 99.5, + mask: np.ndarray | None = None, +) -> tuple[float, float]: + """Compute ``(lo, hi)`` intensity bounds on finite (and optionally masked) reference voxels.""" + arr = sanitize_xct_volume(volume) + vals = arr[np.asarray(mask, dtype=bool)] if mask is not None else arr.ravel() + if vals.size == 0: + vals = arr.ravel() + + if mode == "none": + return 0.0, 1.0 + if mode == "minmax": + return float(vals.min()), float(vals.max()) + if mode == "percentile": + lo, hi = (float(v) for v in np.percentile(vals, [lower_pct, upper_pct])) + return lo, hi + if mode == "fixed": + if vmin is None or vmax is None: + raise ValueError("vmin and vmax must be provided when mode='fixed'.") + return float(vmin), float(vmax) + raise ValueError(f"Unsupported normalization mode={mode!r}.") + + def normalize_volume( volume: np.ndarray, mode: NormMode = "minmax", @@ -33,28 +118,50 @@ def normalize_volume( lower_pct: float = 0.5, upper_pct: float = 99.5, eps: float = 1e-8, + mask: np.ndarray | None = None, ) -> np.ndarray: - """Vectorized normalization of a 2D/3D XCT array into ``[0, 1]`` float32.""" - arr = np.asarray(volume, dtype=np.float32) + """Vectorized, ``NaN``-safe normalization of a 2D/3D XCT array into ``[0, 1]`` float32.""" + arr = sanitize_xct_volume(volume) if mode == "none": return np.clip(arr, 0.0, 1.0).astype(np.float32, copy=False) - if mode == "minmax": - lo = float(arr.min()) - hi = float(arr.max()) - elif mode == "percentile": - lo, hi = (float(v) for v in np.percentile(arr, [lower_pct, upper_pct])) - elif mode == "fixed": - if vmin is None or vmax is None: - raise ValueError("vmin and vmax must be provided when mode='fixed'.") - lo, hi = float(vmin), float(vmax) - else: - raise ValueError(f"Unsupported normalization mode={mode!r}.") + lo, hi = compute_normalization_bounds( + arr, + mode=mode, + vmin=vmin, + vmax=vmax, + lower_pct=lower_pct, + upper_pct=upper_pct, + mask=mask, + ) denom = hi - lo if abs(denom) < eps: return np.zeros_like(arr, dtype=np.float32) normed = (arr - lo) / denom - return np.clip(normed, 0.0, 1.0).astype(np.float32, copy=False) + out = np.clip(normed, 0.0, 1.0).astype(np.float32, copy=False) + if mask is not None: + out = np.where(np.asarray(mask, dtype=bool), out, 0.0).astype(np.float32, copy=False) + return out + + +def zoom_cell_centered( + arr: np.ndarray, + zoom_factors: float | tuple[float, ...], + order: int = 3, +) -> np.ndarray: + """Cell-centered spline resampling matching ``PixelShuffle`` & ``F.interpolate(align_corners=False)``. + + Standard ``scipy.ndimage.zoom(..., grid_mode=False)`` aligns corner centers ``0 -> 0`` and + ``N - 1 -> s*N - 1``, shifting interior coordinates by up to ``0.5 * (s - 1)`` HR voxels. + Setting ``grid_mode=True`` preserves exact half-voxel cell centers across all magnifications. + """ + return zoom( + np.asarray(arr, dtype=np.float32), + zoom=zoom_factors, + order=order, + mode="nearest", + grid_mode=True, + ).astype(np.float32, copy=False) def rotate_slice(image: np.ndarray, angle_deg: float) -> np.ndarray: @@ -75,20 +182,21 @@ def rotate_slice(image: np.ndarray, angle_deg: float) -> np.ndarray: def apply_alignment(volume: np.ndarray, alignment: VolumeAlignment | None) -> np.ndarray: """Apply optional 3D bounding-box crop and slice-wise rotation to a 3D volume.""" - arr = np.asarray(volume, dtype=np.float32) + arr = sanitize_xct_volume(volume) if alignment is None: return arr - if abs(alignment.rotation_deg) >= 1e-6: - rotated = np.empty_like(arr) - for i in range(arr.shape[0]): - rotated[i] = rotate_slice(arr[i], alignment.rotation_deg) - arr = rotated - z_sl = slice(*alignment.z_range) if alignment.z_range is not None else slice(None) y_sl = slice(*alignment.y_range) if alignment.y_range is not None else slice(None) x_sl = slice(*alignment.x_range) if alignment.x_range is not None else slice(None) - return np.ascontiguousarray(arr[z_sl, y_sl, x_sl], dtype=np.float32) + cropped = np.ascontiguousarray(arr[z_sl, y_sl, x_sl], dtype=np.float32) + + if abs(alignment.rotation_deg) >= 1e-6: + rotated = np.empty_like(cropped) + for i in range(cropped.shape[0]): + rotated[i] = rotate_slice(cropped[i], alignment.rotation_deg) + cropped = rotated + return cropped def apply_contrast_shift(volume: np.ndarray, shift: float = 0.0) -> np.ndarray: @@ -103,7 +211,7 @@ def apply_contrast_shift(volume: np.ndarray, shift: float = 0.0) -> np.ndarray: def degrade_xct_volume( hr_volume: np.ndarray, - scale_factor: int = 2, + scale_factor: float = 2, psf_sigma: float = 0.8, noise_std: float = 0.02, poisson_peak: float | None = None, @@ -112,27 +220,38 @@ def degrade_xct_volume( ) -> np.ndarray: """Simulate realistic isotropic 3D low-resolution XCT acquisition from an HR volume. - Models detector optical/scintillator blur (Gaussian PSF), optional photon shot noise - (Poisson), electronic readout noise (Gaussian), and ``scale_factor`` voxel binning. + Supports both integer and fractional optical magnification ratios (e.g., ``2x``, ``2.5x``, ``4x``) + via exact cell-centered box-area integration. """ - hr = np.asarray(hr_volume, dtype=np.float32) + if scale_factor <= 0.0: + raise ValueError(f"scale_factor must be > 0, got {scale_factor}.") + hr = sanitize_xct_volume(hr_volume) if hr.ndim != 3: raise ValueError(f"Expected 3D HR volume (D, H, W), got shape {hr.shape}.") - for dim in hr.shape: - if dim % scale_factor != 0: - raise ValueError( - f"HR volume shape {hr.shape} must be divisible by scale_factor={scale_factor}." - ) + + s_int = int(round(float(scale_factor))) + is_int_scale = abs(float(scale_factor) - float(s_int)) < 1e-6 + if is_int_scale: + for dim in hr.shape: + if dim % s_int != 0: + raise ValueError( + f"HR volume shape {hr.shape} must be divisible by scale_factor={s_int}." + ) rng = np.random.default_rng(seed) work = apply_contrast_shift(hr, shift=contrast_shift) if psf_sigma > 0.0: work = gaussian_filter(work, sigma=float(psf_sigma), mode="reflect") - # Voxel-binning / Lanczos-equivalent antialiasing downsample to (D/s, H/s, W/s) - s = scale_factor - d, h, w = work.shape - binned = work.reshape(d // s, s, h // s, s, w // s, s).mean(axis=(1, 3, 5)) + if is_int_scale: + d, h, w = work.shape + binned = work.reshape(d // s_int, s_int, h // s_int, s_int, w // s_int, s_int).mean( + axis=(1, 3, 5), dtype=np.float32 + ) + else: + target_lr = tuple(max(1, int(round(dim / float(scale_factor)))) for dim in work.shape) + t_work = torch.from_numpy(np.ascontiguousarray(work)).unsqueeze(0).unsqueeze(0) + binned = F.interpolate(t_work, size=target_lr, mode="area").squeeze(0).squeeze(0).numpy() if poisson_peak is not None and poisson_peak > 0.0: counts = rng.poisson(np.clip(binned, 0.0, 1.0) * float(poisson_peak)) @@ -146,21 +265,15 @@ def degrade_xct_volume( def downsample_orthogonal_slabs( hr_volume: np.ndarray, - scale_factor: int = 2, + scale_factor: float = 2, psf_sigma: float = 0.6, noise_std: float = 0.02, variable_slice_noise: bool = False, contrast_shift: float = 0.0, seed: int = 42, ) -> dict[str, np.ndarray]: - """Create paired orthogonal LR slice stacks ``yz``, ``xz``, and ``xy`` from a 3D HR cube. - - For each axis: - - ``'yz'`` has shape ``(D, H // s, W // s)`` paired with ``hr_volume`` ``(D, H, W)`` - - ``'xz'`` has shape ``(H, D // s, W // s)`` paired with ``np.moveaxis(hr_volume, 1, 0)`` - - ``'xy'`` has shape ``(W, D // s, H // s)`` paired with ``np.moveaxis(hr_volume, 2, 0)`` - """ - hr = np.asarray(hr_volume, dtype=np.float32) + """Create paired orthogonal LR slice stacks ``yz``, ``xz``, and ``xy`` from a 3D HR cube.""" + hr = sanitize_xct_volume(hr_volume) if hr.ndim != 3: raise ValueError(f"Expected 3D HR volume, got shape {hr.shape}.") @@ -172,9 +285,10 @@ def downsample_orthogonal_slabs( slabs: dict[str, np.ndarray] = {} axis_map = {"yz": 0, "xz": 1, "xy": 2} for name, dim in axis_map.items(): - ordered = np.moveaxis(work, dim, 0) # (N, H_in, W_in) + ordered = np.moveaxis(work, dim, 0) n_slices, h_in, w_in = ordered.shape - h_out, w_out = h_in // scale_factor, w_in // scale_factor + h_out = max(1, int(round(h_in / float(scale_factor)))) + w_out = max(1, int(round(w_in / float(scale_factor)))) down = np.empty((n_slices, h_out, w_out), dtype=np.float32) for i in range(n_slices): sl = cv2.resize( @@ -197,23 +311,23 @@ def downsample_orthogonal_slabs( def split_volume_spatially( hr_volume: np.ndarray, lr_volume: np.ndarray | None = None, - scale_factor: int = 2, + scale_factor: float = 2, train_frac: float = 0.7, val_frac: float = 0.15, split_axis: int = 0, guard_slices_lr: int = 0, ) -> dict[str, tuple[np.ndarray | None, np.ndarray]]: - """Partition a 3D HR (and optional isotropic 3D LR) volume into disjoint spatial sub-volumes. - - Splitting along ``split_axis`` into contiguous non-overlapping 3D slabs guarantees - that orthogonal ``xy``, ``xz``, and ``yz`` slices extracted from the ``test`` sub-volume - never share voxels with ``train`` or ``val`` slices. - """ - hr = np.asarray(hr_volume, dtype=np.float32) + """Partition a 3D HR (and optional 3D LR) volume into disjoint spatial sub-volumes.""" + hr = sanitize_xct_volume(hr_volume) if hr.ndim != 3: raise ValueError(f"Expected 3D HR volume, got shape {hr.shape}.") + s_float = float(scale_factor) total_hr = hr.shape[split_axis] - total_lr = total_hr // scale_factor + total_lr = ( + int(lr_volume.shape[split_axis]) + if lr_volume is not None + else int(round(total_hr / s_float)) + ) if total_lr < 3: raise ValueError( f"Volume dimension {total_hr} along axis {split_axis} is too small for 3-way split " @@ -243,32 +357,73 @@ def _slice_axis(arr: np.ndarray, start: int, stop: int) -> np.ndarray: return np.ascontiguousarray(arr[tuple(idx)], dtype=np.float32) splits: dict[str, tuple[np.ndarray | None, np.ndarray]] = {} + lr_clean = sanitize_xct_volume(lr_volume) if lr_volume is not None else None for name, (a_lr, b_lr) in ( ("train", (t0_lr, t1_lr)), ("val", (v0_lr, v1_lr)), ("test", (s0_lr, s1_lr)), ): - hr_sub = _slice_axis(hr, a_lr * scale_factor, b_lr * scale_factor) - lr_sub = _slice_axis(lr_volume, a_lr, b_lr) if lr_volume is not None else None + n_len_hr = max(1, int(round((b_lr - a_lr) * s_float))) + a_hr = int(round(a_lr * s_float)) + b_hr = min(total_hr, a_hr + n_len_hr) + a_hr = max(0, b_hr - n_len_hr) + hr_sub = _slice_axis(hr, a_hr, b_hr) + lr_sub = _slice_axis(lr_clean, a_lr, b_lr) if lr_clean is not None else None splits[name] = (lr_sub, hr_sub) return splits +def _safe_pad_spatial(arr: np.ndarray, target_h: int, target_w: int) -> np.ndarray: + """Reflect/edge pad trailing ``(H, W)`` dimensions of a slice stack up to ``(target_h, target_w)``.""" + cur_h, cur_w = int(arr.shape[-2]), int(arr.shape[-1]) + pad_h = max(0, target_h - cur_h) + pad_w = max(0, target_w - cur_w) + if pad_h == 0 and pad_w == 0: + return arr + pad_spec = [(0, 0)] * (arr.ndim - 2) + [ + (0, pad_h), + (0, pad_w), + ] + mode: Literal["reflect", "edge"] = ( + "reflect" if (cur_h > 1 and cur_w > 1 and pad_h < cur_h and pad_w < cur_w) else "edge" + ) + return np.pad(arr, pad_spec, mode=mode).astype(np.float32, copy=False) + + +def build_strided_context_windows( + slices: np.ndarray, + context_slices: int, + context_stride: int = 1, +) -> np.ndarray: + """Build ``(N, context_slices, h, w)`` windows separated by ``context_stride`` slices. + + When an LR slice stack has been zoomed along the stacking axis by ``s = scale_factor``, + setting ``context_stride = round(s)`` samples neighbors separated by one true physical LR + voxel ``+-Delta z_LR`` rather than redundant cubic sub-slice blends. + """ + if context_slices < 1 or context_slices % 2 == 0: + raise ValueError( + f"context_slices must be a positive odd integer (1, 3, 5, ...), got {context_slices}." + ) + if context_slices == 1: + return slices[:, np.newaxis, :, :] + stride = max(1, int(context_stride)) + half_span = (context_slices // 2) * stride + pad_mode: Literal["reflect", "edge"] = "reflect" if slices.shape[0] > half_span else "edge" + padded = np.pad(slices, ((half_span, half_span), (0, 0), (0, 0)), mode=pad_mode) + n = int(slices.shape[0]) + channels = [padded[m * stride : m * stride + n] for m in range(context_slices)] + return np.ascontiguousarray(np.stack(channels, axis=1), dtype=np.float32) + + def extract_paired_slices_from_subvolume( lr_sub: np.ndarray, hr_sub: np.ndarray, - scale_factor: int = 2, + scale_factor: float = 2, axes: tuple[str, ...] = ("yz",), context_slices: int = 1, ) -> tuple[np.ndarray, np.ndarray]: - """Extract aligned ``(low_slices, high_slices)`` from paired isotropic 3D ``(lr_sub, hr_sub)``. - - For each requested axis in ``('yz', 'xz', 'xy')``, ``lr_sub`` is cubic-interpolated along - that slicing axis by ``scale_factor`` so its slice count matches ``hr_sub`` along that axis. - When ``context_slices = 2k + 1 > 1`` (``2.5D`` mode), returns ``low_slices`` of shape - ``(N_total, context_slices, h, w)`` strictly reflect-padded *within* each axis slab so adjacent - orthogonal axes never bleed across boundaries. - """ + """Extract cell-centered aligned ``(low_slices, high_slices)`` from paired 3D ``(lr_sub, hr_sub)``.""" if context_slices < 1 or context_slices % 2 == 0: raise ValueError( f"context_slices must be a positive odd integer (1, 3, 5, ...), got {context_slices}." @@ -281,33 +436,38 @@ def extract_paired_slices_from_subvolume( dim = axis_map[ax] lr_ord = np.moveaxis(lr_sub, dim, 0) hr_ord = np.moveaxis(hr_sub, dim, 0) + ctx_stride = 1 if lr_ord.shape[0] != hr_ord.shape[0]: zoom_f = hr_ord.shape[0] / float(lr_ord.shape[0]) - lr_ord = zoom(lr_ord, zoom=(zoom_f, 1, 1), order=3, mode="reflect").astype( - np.float32, copy=False - ) + lr_ord = zoom_cell_centered(lr_ord, zoom_factors=(zoom_f, 1.0, 1.0), order=3) lr_ord = np.clip(lr_ord, 0.0, 1.0) + ctx_stride = max(1, int(round(zoom_f))) if context_slices > 1: - half = context_slices // 2 - padded = np.pad(lr_ord, ((half, half), (0, 0), (0, 0)), mode="reflect") - win = np.lib.stride_tricks.sliding_window_view( - padded, window_shape=context_slices, axis=0 + lr_ctx = build_strided_context_windows( + lr_ord, context_slices=context_slices, context_stride=ctx_stride ) - lr_ctx = np.ascontiguousarray(np.moveaxis(win, -1, 1), dtype=np.float32) low_list.append(lr_ctx) else: low_list.append(lr_ord) high_list.append(hr_ord) + if len(low_list) > 1: + max_lh = max(int(a.shape[-2]) for a in low_list) + max_lw = max(int(a.shape[-1]) for a in low_list) + max_hh = max(int(a.shape[-2]) for a in high_list) + max_hw = max(int(a.shape[-1]) for a in high_list) + low_list = [_safe_pad_spatial(a, max_lh, max_lw) for a in low_list] + high_list = [_safe_pad_spatial(a, max_hh, max_hw) for a in high_list] + return np.concatenate(low_list, axis=0), np.concatenate(high_list, axis=0) class PairedSliceDataset(Dataset[tuple[Tensor, Tensor]]): """PyTorch Dataset of paired ``(low_res, high_res)`` 2D or 2.5D XCT slices. - Supports optional ``context_slices = 2k + 1`` multi-slice LR inputs, aligned random spatial - patch cropping, and full ``O(3)`` slab-equivariant augmentations (dihedral ``D_4`` in-plane - rotations/flips plus through-plane ``z``-stack reversal when ``context_slices > 1``). + Supports integer and fractional ``scale_factor`` values, non-square slices (applying + shape-preserving ``D_2`` flips/180-deg rotations when ``H != W`` and full ``D_4`` symmetry + when ``H == W``), and ``O(3)`` through-plane ``z``-stack reversal when ``context_slices > 1``. """ def __init__( @@ -315,9 +475,10 @@ def __init__( low_res: Tensor | np.ndarray, high_res: Tensor | np.ndarray | None = None, patch_size_lr: int | None = None, - scale_factor: int = 2, + scale_factor: float = 2, augment: bool = False, context_slices: int = 1, + context_stride: int = 1, ) -> None: super().__init__() if context_slices < 1 or context_slices % 2 == 0: @@ -325,19 +486,23 @@ def __init__( f"context_slices must be a positive odd integer (1, 3, 5, ...), got {context_slices}." ) self.context_slices = int(context_slices) + self.context_stride = max(1, int(context_stride)) - lr_arr = np.asarray(low_res, dtype=np.float32) + lr_arr = sanitize_xct_volume(np.asarray(low_res, dtype=np.float32)) if lr_arr.ndim == 3 and self.context_slices > 1: - half = self.context_slices // 2 - padded = np.pad(lr_arr, ((half, half), (0, 0), (0, 0)), mode="reflect") - win = np.lib.stride_tricks.sliding_window_view( - padded, window_shape=self.context_slices, axis=0 + lr_arr = build_strided_context_windows( + lr_arr, + context_slices=self.context_slices, + context_stride=self.context_stride, ) - lr_arr = np.ascontiguousarray(np.moveaxis(win, -1, 1), dtype=np.float32) self.low_res = torch.as_tensor(lr_arr, dtype=torch.float32) self.high_res = ( - torch.as_tensor(high_res, dtype=torch.float32) if high_res is not None else None + torch.as_tensor( + sanitize_xct_volume(np.asarray(high_res, dtype=np.float32)), dtype=torch.float32 + ) + if high_res is not None + else None ) if self.low_res.ndim == 4 and self.low_res.shape[1] == 1 and self.context_slices == 1: self.low_res = self.low_res.squeeze(1) @@ -350,7 +515,7 @@ def __init__( ) self.patch_size_lr = int(patch_size_lr) if patch_size_lr is not None else None - self.scale_factor = int(scale_factor) + self.scale_factor = float(scale_factor) self.augment = bool(augment) def __len__(self) -> int: @@ -366,28 +531,106 @@ def __getitem__(self, idx: int) -> tuple[Tensor, Tensor]: if self.patch_size_lr is not None and self.high_res is not None: p_lr = self.patch_size_lr + p_hr = max(1, int(round(p_lr * self.scale_factor))) h_lr, w_lr = int(lr.shape[-2]), int(lr.shape[-1]) - if h_lr >= p_lr and w_lr >= p_lr: - top = int(torch.randint(0, h_lr - p_lr + 1, (1,)).item()) - left = int(torch.randint(0, w_lr - p_lr + 1, (1,)).item()) - lr = lr[..., top : top + p_lr, left : left + p_lr] - s = self.scale_factor - hr = hr[..., top * s : (top + p_lr) * s, left * s : (left + p_lr) * s] + if h_lr < p_lr or w_lr < p_lr: + lr_np = _safe_pad_spatial(lr.numpy(), max(h_lr, p_lr), max(w_lr, p_lr)) + hr_np = _safe_pad_spatial( + hr.numpy(), + max(int(hr.shape[-2]), p_hr), + max(int(hr.shape[-1]), p_hr), + ) + lr = torch.from_numpy(lr_np) + hr = torch.from_numpy(hr_np) + h_lr, w_lr = int(lr.shape[-2]), int(lr.shape[-1]) + + top = int(torch.randint(0, h_lr - p_lr + 1, (1,)).item()) + left = int(torch.randint(0, w_lr - p_lr + 1, (1,)).item()) + lr = lr[..., top : top + p_lr, left : left + p_lr] + + h_hr, w_hr = int(hr.shape[-2]), int(hr.shape[-1]) + top_hr = min(max(0, int(round(top * self.scale_factor))), max(0, h_hr - p_hr)) + left_hr = min(max(0, int(round(left * self.scale_factor))), max(0, w_hr - p_hr)) + hr = hr[..., top_hr : top_hr + p_hr, left_hr : left_hr + p_hr] if self.augment and self.high_res is not None: - k_rot = int(torch.randint(0, 4, (1,)).item()) + is_square = int(lr.shape[-2]) == int(lr.shape[-1]) and int(hr.shape[-2]) == int( + hr.shape[-1] + ) + if is_square: + k_rot = int(torch.randint(0, 4, (1,)).item()) + else: + k_rot = int(torch.randint(0, 2, (1,)).item()) * 2 if k_rot > 0: lr = torch.rot90(lr, k=k_rot, dims=(-2, -1)) hr = torch.rot90(hr, k=k_rot, dims=(-2, -1)) if bool(torch.randint(0, 2, (1,)).item()): lr = torch.flip(lr, dims=(-1,)) hr = torch.flip(hr, dims=(-1,)) + if not is_square and bool(torch.randint(0, 2, (1,)).item()): + lr = torch.flip(lr, dims=(-2,)) + hr = torch.flip(hr, dims=(-2,)) if lr.ndim == 3 and lr.shape[0] > 1 and bool(torch.randint(0, 2, (1,)).item()): - # Reversing adjacent LR context slices preserves the central HR target slice lr = torch.flip(lr, dims=(0,)) return lr.contiguous(), hr.contiguous() +def build_multi_axis_slice_dataset( + lr_sub: np.ndarray, + hr_sub: np.ndarray, + scale_factor: float = 2, + axes: tuple[str, ...] = ("yz",), + patch_size_lr: int | None = None, + augment: bool = False, + context_slices: int = 1, +) -> Dataset[tuple[Tensor, Tensor]]: + """Build a multi-axis slice dataset without artificial border padding when ``patch_size_lr`` is set.""" + if len(axes) <= 1 or patch_size_lr is None: + lo, hi = extract_paired_slices_from_subvolume( + lr_sub, + hr_sub, + scale_factor=scale_factor, + axes=axes, + context_slices=context_slices, + ) + return PairedSliceDataset( + lo, + hi, + patch_size_lr=patch_size_lr, + scale_factor=scale_factor, + augment=augment, + context_slices=context_slices, + ) + + per_axis: list[Dataset[tuple[Tensor, Tensor]]] = [] + for ax in axes: + lo_ax, hi_ax = extract_paired_slices_from_subvolume( + lr_sub, + hr_sub, + scale_factor=scale_factor, + axes=(ax,), + context_slices=context_slices, + ) + per_axis.append( + PairedSliceDataset( + lo_ax, + hi_ax, + patch_size_lr=patch_size_lr, + scale_factor=scale_factor, + augment=augment, + context_slices=context_slices, + ) + ) + return ConcatDataset(per_axis) + + +def minimum_psf_guard_slices_lr(psf_sigma: float, scale_factor: float) -> int: + """Minimum LR guard slices needed to prevent 3-sigma HR Gaussian PSF bleed across splits.""" + if psf_sigma <= 0.0: + return 0 + return int(math.ceil(3.0 * float(psf_sigma) / max(float(scale_factor), 1e-6))) + + # Alias preserving clean familiarity with original OpenLSR-X naming DatasetObject = PairedSliceDataset diff --git a/src/openlsrx/data/volumes.py b/src/openlsrx/data/volumes.py index db5170c..0dafa45 100644 --- a/src/openlsrx/data/volumes.py +++ b/src/openlsrx/data/volumes.py @@ -11,18 +11,25 @@ import numpy as np import pytorch_lightning as pl import tifffile -from scipy.ndimage import zoom -from torch.utils.data import DataLoader +import torch.nn.functional as F +from torch import Tensor +from torch.utils.data import DataLoader, Dataset from .transforms import ( NormMode, PairedSliceDataset, VolumeAlignment, apply_alignment, + build_circular_fov_mask, + build_multi_axis_slice_dataset, + compute_normalization_bounds, degrade_xct_volume, extract_paired_slices_from_subvolume, + minimum_psf_guard_slices_lr, normalize_volume, + sanitize_xct_volume, split_volume_spatially, + zoom_cell_centered, ) _NATURAL_RE = re.compile(r"(\d+)") @@ -37,12 +44,20 @@ def load_volume_any( h5_dataset_key: str = "4-TomopyRecon-tomo/data", transpose_axes: tuple[int, int, int] | None = None, max_slices: int | None = None, + roi_slices: tuple[slice, slice, slice] | None = None, + preserve_2d: bool = False, ) -> np.ndarray: - """Load a 3D XCT volume from a multi-page TIFF, a directory of 2D slices, or an HDF5/NeXus file.""" + """Load a 2D/3D XCT volume from multi-page TIFF, a slice directory, `.npy`, or HDF5/NeXus. + + When loading large synchrotron HDF5 reconstructions (e.g., 53 GB Savu/TomoPy files), + ``roi_slices`` (specified in post-transpose ``(Z, Y, X)`` coordinates) are mapped back to + the on-disk HDF5 axis order and sliced *before* materializing the array in host RAM. + """ p = Path(path) if not p.exists(): raise FileNotFoundError(f"XCT data path does not exist: {p}") + roi_applied_on_disk = False if p.is_dir(): exts = {".tif", ".tiff", ".png", ".bmp", ".jpg", ".jpeg"} files = sorted([f for f in p.iterdir() if f.suffix.lower() in exts], key=_natural_key) @@ -55,47 +70,115 @@ def load_volume_any( img = tifffile.imread(f) if f.suffix.lower() in {".tif", ".tiff"} else iio.imread(f) if img.ndim == 3: img = img[..., 0] - slices.append(np.asarray(img, dtype=np.float32)) + slices.append(sanitize_xct_volume(img)) vol = np.stack(slices, axis=0) elif p.suffix.lower() in {".h5", ".hdf5", ".nxs"}: with h5py.File(p, "r") as hf: if h5_dataset_key not in hf: - raise KeyError( - f"HDF5 dataset key {h5_dataset_key!r} not found in {p}. " - f"Top-level keys: {list(hf.keys())}" - ) - dset = hf[h5_dataset_key] - vol = np.asarray( - dset[:max_slices] if max_slices is not None else dset[()], dtype=np.float32 - ) + # Fall back to single top-level dataset when unambiguous (e.g., Zenodo cropped .h5) + top_dsets = [k for k in hf.keys() if isinstance(hf[k], h5py.Dataset)] + if len(top_dsets) == 1: + dset = hf[top_dsets[0]] + else: + raise KeyError( + f"HDF5 dataset key {h5_dataset_key!r} not found in {p}. " + f"Top-level keys: {list(hf.keys())}" + ) + else: + dset = hf[h5_dataset_key] + + if roi_slices is not None and dset.ndim == 3: + raw_slices = [slice(None), slice(None), slice(None)] + if transpose_axes is not None: + for out_ax, sl in enumerate(roi_slices): + raw_slices[transpose_axes[out_ax]] = sl + else: + raw_slices = list(roi_slices) + vol = sanitize_xct_volume(np.asarray(dset[tuple(raw_slices)])) + roi_applied_on_disk = True + elif max_slices is not None and dset.ndim == 3: + if transpose_axes is not None: + raw_slices = [slice(None), slice(None), slice(None)] + raw_slices[transpose_axes[0]] = slice(0, int(max_slices)) + vol = sanitize_xct_volume(np.asarray(dset[tuple(raw_slices)])) + else: + vol = sanitize_xct_volume(np.asarray(dset[: int(max_slices)])) + else: + vol = sanitize_xct_volume(np.asarray(dset[()])) elif p.suffix.lower() in {".tif", ".tiff"}: - vol = np.asarray(tifffile.imread(p), dtype=np.float32) - if max_slices is not None and vol.ndim == 3: + vol = sanitize_xct_volume(tifffile.imread(p)) + if max_slices is not None and vol.ndim == 3 and transpose_axes is None: vol = vol[: int(max_slices)] elif p.suffix.lower() == ".npy": - vol = np.asarray(np.load(p), dtype=np.float32) - if max_slices is not None and vol.ndim == 3: + vol = sanitize_xct_volume(np.load(p)) + if max_slices is not None and vol.ndim == 3 and transpose_axes is None: vol = vol[: int(max_slices)] else: raise ValueError(f"Unsupported XCT volume file format: {p.suffix} ({p})") if vol.ndim == 2: + if preserve_2d: + return np.ascontiguousarray(vol, dtype=np.float32) vol = vol[np.newaxis, ...] if vol.ndim != 3: raise ValueError(f"Loaded array must be 3D (D, H, W), got shape {vol.shape} from {p}.") if transpose_axes is not None: vol = np.transpose(vol, transpose_axes) + if max_slices is not None and p.suffix.lower() not in {".h5", ".hdf5", ".nxs"}: + vol = vol[: int(max_slices)] + if roi_slices is not None and not roi_applied_on_disk: + vol = vol[roi_slices] return np.ascontiguousarray(vol, dtype=np.float32) +def _alignment_to_roi_and_Residual( + alignment: VolumeAlignment, +) -> tuple[tuple[slice, slice, slice] | None, VolumeAlignment | None]: + has_crop = any(r is not None for r in (alignment.z_range, alignment.y_range, alignment.x_range)) + roi = ( + ( + slice(*alignment.z_range) if alignment.z_range is not None else slice(None), + slice(*alignment.y_range) if alignment.y_range is not None else slice(None), + slice(*alignment.x_range) if alignment.x_range is not None else slice(None), + ) + if has_crop + else None + ) + residual = ( + VolumeAlignment(rotation_deg=alignment.rotation_deg) + if abs(alignment.rotation_deg) >= 1e-6 + else None + ) + return roi, residual + + +def _downsample_slab_along_axis(slab: np.ndarray, axis: int, target_len: int) -> np.ndarray: + """Cell-centered 1D box-area downsampling of an anisotropic slab along ``axis``.""" + moved = np.moveaxis(np.asarray(slab, dtype=np.float32), axis, -1) + orig_lead = moved.shape[:-1] + c_len = moved.shape[-1] + if c_len == target_len: + return np.asarray(slab, dtype=np.float32) + if c_len % target_len == 0: + f = c_len // target_len + binned = moved.reshape(*orig_lead, target_len, f).mean(axis=-1, dtype=np.float32) + return np.moveaxis(binned, -1, axis) + import torch + + flat = torch.from_numpy(np.ascontiguousarray(moved.reshape(-1, 1, c_len))) + out = F.interpolate(flat, size=target_len, mode="area").numpy().reshape(*orig_lead, target_len) + return np.ascontiguousarray(np.moveaxis(out, -1, axis), dtype=np.float32) + + class PairedVolumeDataModule(pl.LightningDataModule): """Config-driven LightningDataModule for LabXCT, Synchrotron HDF5 (Diamond I13), and PoreSpy stacks. - Supports three operating modes: - 1. **Paired real LR + HR volumes** (``high_path`` + ``low_path``). - 2. **Pre-downsampled orthogonal LR slabs** (``high_path`` + ``low_yz_path`` / ``low_xz_path`` / ``low_xy_path``). - 3. **Single HR volume with controlled XCT degradation** (``high_path`` only, ``degrade_from_hr=True``). - And during ``predict`` stage, supports standalone ``predict_path`` without requiring training paths! + Enforces strict spatial split isolation: + 1. Splits raw 3D volumes into disjoint ``train`` / ``val`` / ``test`` slabs *before* computing + intensity normalization bounds (fitted exclusively on ``train``) or applying synthetic + 3D PSF degradation (applied independently per split so ``val``/``test`` never leak). + 2. Uses cell-centered ``grid_mode=True`` spline resampling across integer and fractional + ``scale_factor`` values (e.g., ``2``, ``2.5``, ``4``, ``8``). """ def __init__( @@ -108,11 +191,12 @@ def __init__( predict_path: str | None = None, h5_dataset_key: str = "4-TomopyRecon-tomo/data", transpose_axes: tuple[int, int, int] | None = None, - scale_factor: int = 2, + scale_factor: float = 2, degrade_from_hr: bool = False, psf_sigma: float = 0.8, degrade_noise_std: float = 0.02, norm_mode: NormMode = "percentile", + circular_fov_mask: bool = False, low_vmin: float | None = None, low_vmax: float | None = None, high_vmin: float | None = None, @@ -133,6 +217,8 @@ def __init__( train_axes: tuple[str, ...] = ("yz",), test_axis: Literal["parallel", "perpendicular", "all"] = "perpendicular", predict_axis: Literal["yz", "xz", "xy"] = "xy", + predict_mode: Literal["orthogonal_3axis", "single_axis"] = "orthogonal_3axis", + predict_fusion: str = "confidence_fourier", patch_size_lr: int | None = None, context_slices: int = 1, augment: bool = True, @@ -149,6 +235,8 @@ def __init__( raise ValueError( f"context_slices must be a positive odd integer (1, 3, 5, ...), got {context_slices}." ) + if float(scale_factor) <= 0.0: + raise ValueError(f"scale_factor must be > 0, got {scale_factor}.") self.high_path = high_path self.low_path = low_path @@ -158,12 +246,18 @@ def __init__( self.predict_path = predict_path self.h5_dataset_key = h5_dataset_key self.transpose_axes = transpose_axes - self.scale_factor = int(scale_factor) + s_round = int(round(float(scale_factor))) + self.scale_factor: float = ( + int(s_round) + if abs(float(scale_factor) - float(s_round)) < 1e-6 + else float(scale_factor) + ) self.degrade_from_hr = bool(degrade_from_hr) self.psf_sigma = float(psf_sigma) self.degrade_noise_std = float(degrade_noise_std) self.norm_mode: NormMode = norm_mode + self.circular_fov_mask = bool(circular_fov_mask) self.low_vmin = low_vmin self.low_vmax = low_vmax self.high_vmin = high_vmin @@ -191,6 +285,8 @@ def __init__( self.train_axes = tuple(train_axes) self.test_axis = test_axis self.predict_axis = predict_axis + self.predict_mode = predict_mode + self.predict_fusion = str(predict_fusion) self.patch_size_lr = patch_size_lr self.context_slices = int(context_slices) self.augment = bool(augment) @@ -201,24 +297,58 @@ def __init__( self.persistent_workers = bool(persistent_workers and self.num_workers > 0) self.seed = int(seed) - self.train_dataset: PairedSliceDataset | None = None - self.val_dataset: PairedSliceDataset | None = None - self.test_dataset: PairedSliceDataset | None = None + self.train_dataset: Dataset[tuple[Tensor, Tensor]] | None = None + self.val_dataset: Dataset[tuple[Tensor, Tensor]] | None = None + self.test_dataset: Dataset[tuple[Tensor, Tensor]] | None = None self.predict_dataset: PairedSliceDataset | None = None + self.predict_lr_volume: np.ndarray | None = None + self.predict_Spatial_shape_hr: tuple[int, int, int] | None = None self.splits_3d: dict[str, tuple[np.ndarray, np.ndarray]] = {} + self.norm_bounds_hr: tuple[float, float] | None = None + self.norm_bounds_lr: tuple[float, float] | None = None - def _norm(self, vol: np.ndarray, is_high: bool) -> np.ndarray: + def _fit_bounds(self, vol: np.ndarray, is_high: bool) -> tuple[float, float]: vmin = self.high_vmin if is_high else self.low_vmin vmax = self.high_vmax if is_high else self.low_vmax mode: NormMode = "fixed" if (vmin is not None and vmax is not None) else self.norm_mode - return normalize_volume( + fov = build_circular_fov_mask(vol.shape) if self.circular_fov_mask else None + return compute_normalization_bounds( vol, mode=mode, vmin=vmin, vmax=vmax, lower_pct=self.lower_pct, upper_pct=self.upper_pct, + mask=fov, + ) + + def _apply_bounds( + self, vol: np.ndarray, bounds: tuple[float, float], is_high: bool + ) -> np.ndarray: + vmin = self.high_vmin if is_high else self.low_vmin + vmax = self.high_vmax if is_high else self.low_vmax + has_fixed = vmin is not None and vmax is not None + if not has_fixed and self.norm_mode == "none": + fov = build_circular_fov_mask(vol.shape) if self.circular_fov_mask else None + return normalize_volume(vol, mode="none", mask=fov) + fov = build_circular_fov_mask(vol.shape) if self.circular_fov_mask else None + return normalize_volume(vol, mode="fixed", vmin=bounds[0], vmax=bounds[1], mask=fov) + + def _aligned_crop_shapes( + self, raw_hr_shape: tuple[int, int, int] + ) -> tuple[tuple[int, int, int], tuple[int, int, int]]: + s_float = float(self.scale_factor) + s_int = int(round(s_float)) + if abs(s_float - float(s_int)) < 1e-6: + lr_shape = tuple(max(1, dim // s_int) for dim in raw_hr_shape) + hr_shape = tuple(d * s_int for d in lr_shape) + return (lr_shape[0], lr_shape[1], lr_shape[2]), (hr_shape[0], hr_shape[1], hr_shape[2]) + lr_shape = tuple(max(1, int(round(dim / s_float))) for dim in raw_hr_shape) + hr_shape = tuple( + min(raw_d, max(1, int(round(lr_d * s_float)))) + for raw_d, lr_d in zip(raw_hr_shape, lr_shape, strict=True) ) + return (lr_shape[0], lr_shape[1], lr_shape[2]), (hr_shape[0], hr_shape[1], hr_shape[2]) def _prepare_paired_3d(self) -> None: if self.splits_3d: @@ -226,87 +356,147 @@ def _prepare_paired_3d(self) -> None: if not self.high_path: raise ValueError("high_path is required for fit/validate/test stages.") + hi_roi, hi_res = _alignment_to_roi_and_Residual(self.high_alignment) raw_hr = load_volume_any( self.high_path, h5_dataset_key=self.h5_dataset_key, transpose_axes=self.transpose_axes, + roi_slices=hi_roi, + ) + hr_aligned = apply_alignment(raw_hr, hi_res) + target_lr_shape, (d_hr, h_hr, w_hr) = self._aligned_crop_shapes( + (int(hr_aligned.shape[0]), int(hr_aligned.shape[1]), int(hr_aligned.shape[2])) + ) + hr_aligned = hr_aligned[:d_hr, :h_hr, :w_hr] + + has_orthogonal_slabs = any( + p is not None for p in (self.low_yz_path, self.low_xz_path, self.low_xy_path) ) - hr_vol = self._norm(apply_alignment(raw_hr, self.high_alignment), is_high=True) - # Ensure HR dimensions are exact multiples of scale_factor - s = self.scale_factor - d_hr = (hr_vol.shape[0] // s) * s - h_hr = (hr_vol.shape[1] // s) * s - w_hr = (hr_vol.shape[2] // s) * s - hr_vol = hr_vol[:d_hr, :h_hr, :w_hr] + lr_aligned: np.ndarray | None = None if self.low_path: + lo_roi, lo_res = _alignment_to_roi_and_Residual(self.low_alignment) raw_lr = load_volume_any( self.low_path, h5_dataset_key=self.h5_dataset_key, transpose_axes=self.transpose_axes, + roi_slices=lo_roi, ) - lr_vol = self._norm(apply_alignment(raw_lr, self.low_alignment), is_high=False) - target_lr_shape = (d_hr // s, h_hr // s, w_hr // s) - if lr_vol.shape != target_lr_shape: - factors = tuple(t / c for t, c in zip(target_lr_shape, lr_vol.shape, strict=True)) - lr_vol = np.clip( - zoom(lr_vol, zoom=factors, order=1, mode="reflect").astype(np.float32), - 0.0, - 1.0, + lr_aligned = apply_alignment(raw_lr, lo_res) + if lr_aligned.shape != target_lr_shape: + factors = tuple( + t / float(c) for t, c in zip(target_lr_shape, lr_aligned.shape, strict=True) ) - elif self.low_yz_path: - # Anisotropic slab input (D_hr, H_lr, W_lr): downsample along axis 0 to form isotropic LR - yz_slab = load_volume_any(self.low_yz_path) - yz_slab = self._norm(yz_slab[:d_hr, : h_hr // s, : w_hr // s], is_high=False) - lr_vol = yz_slab.reshape(d_hr // s, s, h_hr // s, w_hr // s).mean(axis=1) - elif self.degrade_from_hr: - lr_vol = degrade_xct_volume( - hr_volume=hr_vol, - scale_factor=s, - psf_sigma=self.psf_sigma, - noise_std=self.degrade_noise_std, - seed=self.seed, + lr_aligned = zoom_cell_centered(lr_aligned, zoom_factors=factors, order=1) + elif has_orthogonal_slabs: + slab_estimates: list[np.ndarray] = [] + d_lr, h_lr, w_lr = target_lr_shape + if self.low_yz_path is not None: + yz = load_volume_any(self.low_yz_path)[:d_hr, :h_lr, :w_lr] + slab_estimates.append(_downsample_slab_along_axis(yz, axis=0, target_len=d_lr)) + if self.low_xz_path is not None: + # xz slab stored as (H_hr, D_lr, W_lr) -> moveaxis(0 -> 1) -> (D_lr, H_hr, W_lr) + xz_raw = load_volume_any(self.low_xz_path)[:h_hr, :d_lr, :w_lr] + xz = np.moveaxis(xz_raw, 0, 1) + slab_estimates.append(_downsample_slab_along_axis(xz, axis=1, target_len=h_lr)) + if self.low_xy_path is not None: + # xy slab stored as (W_hr, D_lr, H_lr) -> moveaxis(0 -> 2) -> (D_lr, H_lr, W_hr) + xy_raw = load_volume_any(self.low_xy_path)[:w_hr, :d_lr, :h_lr] + xy = np.moveaxis(xy_raw, 0, 2) + slab_estimates.append(_downsample_slab_along_axis(xy, axis=2, target_len=w_lr)) + lr_aligned = np.asarray( + np.mean(np.stack(slab_estimates, axis=0), axis=0, dtype=np.float32), + dtype=np.float32, ) - else: + elif not self.degrade_from_hr: raise ValueError( - "Provide either low_path, low_yz_path, or set degrade_from_hr=True alongside high_path." + "Provide low_path, low_yz_path/low_xz_path/low_xy_path, or set degrade_from_hr=True alongside high_path." ) + eff_guard = ( + max( + self.guard_slices_lr, minimum_psf_guard_slices_lr(self.psf_sigma, self.scale_factor) + ) + if (lr_aligned is not None and self.psf_sigma > 0.0) + else self.guard_slices_lr + ) + if target_lr_shape[self.split_axis] - 2 * eff_guard < 3: + eff_guard = self.guard_slices_lr + raw_splits = split_volume_spatially( - hr_volume=hr_vol, - lr_volume=lr_vol, - scale_factor=s, + hr_volume=hr_aligned, + lr_volume=lr_aligned, + scale_factor=self.scale_factor, train_frac=self.train_frac, val_frac=self.val_frac, split_axis=self.split_axis, - guard_slices_lr=self.guard_slices_lr, + guard_slices_lr=eff_guard, ) - self.splits_3d = {k: (v[0], v[1]) for k, v in raw_splits.items() if v[0] is not None} + + # Fit normalization bounds STRICTLY on train split only (zero test/val intensity leakage) + _, hr_tr_raw = raw_splits["train"] + self.norm_bounds_hr = self._fit_bounds(hr_tr_raw, is_high=True) + + if lr_aligned is not None: + lr_tr_raw = raw_splits["train"][0] + assert lr_tr_raw is not None + self.norm_bounds_lr = self._fit_bounds(lr_tr_raw, is_high=False) + for split_name, (lr_raw_sub, hr_raw_sub) in raw_splits.items(): + assert lr_raw_sub is not None + hr_sub = self._apply_bounds(hr_raw_sub, self.norm_bounds_hr, is_high=True) + lr_sub = self._apply_bounds(lr_raw_sub, self.norm_bounds_lr, is_high=False) + self.splits_3d[split_name] = (lr_sub, hr_sub) + else: + # Degrade each spatial split independently AFTER splitting (zero cross-split PSF bleed) + for idx_split, (split_name, (_, hr_raw_sub)) in enumerate(raw_splits.items()): + hr_sub = self._apply_bounds(hr_raw_sub, self.norm_bounds_hr, is_high=True) + lr_sub = degrade_xct_volume( + hr_volume=hr_sub, + scale_factor=self.scale_factor, + psf_sigma=self.psf_sigma, + noise_std=self.degrade_noise_std, + seed=self.seed + 1009 * (idx_split + 1), + ) + self.splits_3d[split_name] = (lr_sub, hr_sub) def setup(self, stage: str | None = None) -> None: if stage == "predict" and self.predict_path: + lo_roi, lo_res = _alignment_to_roi_and_Residual(self.low_alignment) raw_pred = load_volume_any( self.predict_path, h5_dataset_key=self.h5_dataset_key, transpose_axes=self.transpose_axes, + roi_slices=lo_roi, + ) + aligned_pred = apply_alignment(raw_pred, lo_res) + bounds = self.norm_bounds_lr or self._fit_bounds(aligned_pred, is_high=False) + pred_lr = self._apply_bounds(aligned_pred, bounds, is_high=False) + self.predict_lr_volume = pred_lr + self.predict_Spatial_shape_hr = ( + int(round(pred_lr.shape[0] * float(self.scale_factor))), + int(round(pred_lr.shape[1] * float(self.scale_factor))), + int(round(pred_lr.shape[2] * float(self.scale_factor))), ) - pred_lr = self._norm(apply_alignment(raw_pred, self.low_alignment), is_high=False) + axis_map = {"yz": 0, "xz": 1, "xy": 2} ordered = np.moveaxis(pred_lr, axis_map[self.predict_axis], 0) - if self.scale_factor > 1: + ctx_stride = 1 + if float(self.scale_factor) != 1.0: ordered = np.clip( - zoom(ordered, zoom=(self.scale_factor, 1, 1), order=3, mode="reflect").astype( - np.float32 + zoom_cell_centered( + ordered, zoom_factors=(float(self.scale_factor), 1.0, 1.0), order=3 ), 0.0, 1.0, ) + ctx_stride = max(1, int(round(float(self.scale_factor)))) self.predict_dataset = PairedSliceDataset( ordered, high_res=None, scale_factor=self.scale_factor, augment=False, context_slices=self.context_slices, + context_stride=ctx_stride, ) return @@ -314,35 +504,24 @@ def setup(self, stage: str | None = None) -> None: if stage in (None, "fit"): lr_tr, hr_tr = self.splits_3d["train"] - tr_low, tr_high = extract_paired_slices_from_subvolume( + self.train_dataset = build_multi_axis_slice_dataset( lr_tr, hr_tr, scale_factor=self.scale_factor, axes=self.train_axes, - context_slices=self.context_slices, - ) - self.train_dataset = PairedSliceDataset( - tr_low, - tr_high, patch_size_lr=self.patch_size_lr, - scale_factor=self.scale_factor, augment=self.augment, context_slices=self.context_slices, ) if stage in (None, "fit", "validate"): lr_va, hr_va = self.splits_3d["val"] - va_low, va_high = extract_paired_slices_from_subvolume( + self.val_dataset = build_multi_axis_slice_dataset( lr_va, hr_va, scale_factor=self.scale_factor, axes=self.train_axes, - context_slices=self.context_slices, - ) - self.val_dataset = PairedSliceDataset( - va_low, - va_high, - scale_factor=self.scale_factor, + patch_size_lr=None, augment=False, context_slices=self.context_slices, ) @@ -355,23 +534,24 @@ def setup(self, stage: str | None = None) -> None: axes = ("xz", "xy") else: axes = ("yz", "xz", "xy") - te_low, te_high = extract_paired_slices_from_subvolume( + self.test_dataset = build_multi_axis_slice_dataset( lr_te, hr_te, scale_factor=self.scale_factor, axes=axes, - context_slices=self.context_slices, - ) - self.test_dataset = PairedSliceDataset( - te_low, - te_high, - scale_factor=self.scale_factor, + patch_size_lr=None, augment=False, context_slices=self.context_slices, ) if stage in (None, "predict"): lr_te, hr_te = self.splits_3d["test"] + self.predict_lr_volume = lr_te + self.predict_Spatial_shape_hr = ( + int(hr_te.shape[0]), + int(hr_te.shape[1]), + int(hr_te.shape[2]), + ) pr_low, pr_high = extract_paired_slices_from_subvolume( lr_te, hr_te, diff --git a/src/openlsrx/data/zn13x.py b/src/openlsrx/data/zn13x.py index c6f4b87..6f17e21 100644 --- a/src/openlsrx/data/zn13x.py +++ b/src/openlsrx/data/zn13x.py @@ -1,8 +1,8 @@ -"""Diamond Light Source I13-2 multi-resolution Zn-13X synchrotron dataset & 3D aligner. +"""Diamond Light Source I13-2 multi-resolution Zn-13X synchrotron dataset & sub-voxel 3D aligner. Implements automated preparation, Zenodo fetching, offline calibrated phantom synthesis, -and vectorized 3D phase-cross-correlation + SSIM registration for the open multi-resolution -zinc-doped Zeolite 13X dataset published in: +and vectorized HR-grid 3D phase-cross-correlation + tri-planar SSIM registration for the open +multi-resolution zinc-doped Zeolite 13X dataset published in: Green, C., Ahmed, S., Marathe, S. et al., "Three-dimensional, multimodal synchrotron data for machine learning applications", Scientific Data 12, 329 (2025), @@ -11,8 +11,12 @@ from __future__ import annotations +import fcntl import hashlib import json +import os +import shutil +import urllib.parse import urllib.request from dataclasses import dataclass from pathlib import Path @@ -25,7 +29,7 @@ from skimage.metrics import structural_similarity from skimage.registration import phase_cross_correlation -from .transforms import normalize_volume +from .transforms import normalize_volume, sanitize_xct_volume Zn13XPairName = Literal["2x", "8x"] Zn13XTier = Literal["preview", "full"] @@ -36,10 +40,12 @@ class Zn13XResolutionSpec: """Metadata and calibrated alignment anchors for one I13-2 magnification.""" key: str + scan_id: str magnification: str voxel_size_um: float zenodo_record: str recon_filename: str + preview_filename: str vmin: float vmax: float anchor_z: int @@ -52,10 +58,12 @@ class Zn13XResolutionSpec: ZN13X_I13_RESOLUTIONS: dict[str, Zn13XResolutionSpec] = { "2p600um": Zn13XResolutionSpec( key="2p600um", + scan_id="169068", magnification="2.5x", voxel_size_um=2.600, zenodo_record="12206815", recon_filename="169068_recon.h5", + preview_filename="169068_8bit_cropped.h5", vmin=-5.41e-4, vmax=1.68e-3, anchor_z=934, @@ -64,10 +72,12 @@ class Zn13XResolutionSpec: ), "1p625um": Zn13XResolutionSpec( key="1p625um", + scan_id="169067", magnification="4x", voxel_size_um=1.625, zenodo_record="13327651", recon_filename="169067_recon.h5", + preview_filename="169067_8bit_cropped.h5", vmin=-5.23e-4, vmax=1.11e-3, anchor_z=894, @@ -76,10 +86,12 @@ class Zn13XResolutionSpec: ), "0p8125um": Zn13XResolutionSpec( key="0p8125um", + scan_id="169066", magnification="8x", voxel_size_um=0.8125, zenodo_record="13327682", recon_filename="169066_recon.h5", + preview_filename="169066_8bit_cropped.h5", vmin=-2.50e-4, vmax=6.79e-4, anchor_z=804, @@ -88,10 +100,12 @@ class Zn13XResolutionSpec: ), "0p325um": Zn13XResolutionSpec( key="0p325um", + scan_id="169065", magnification="20x", voxel_size_um=0.325, zenodo_record="13327692", recon_filename="169065_recon.h5", + preview_filename="169065_8bit_cropped.h5", vmin=-2.50e-4, vmax=6.79e-4, anchor_z=509, @@ -109,6 +123,15 @@ def _sha256_file(path: Path) -> str: return h.hexdigest() +def _download_https_file(url: str, dest: Path, timeout_s: float = 45.0) -> None: + parsed = urllib.parse.urlparse(url) + if parsed.scheme.lower() != "https": + raise ValueError(f"Refusing non-HTTPS Zenodo download URL: {url!r}") + req = urllib.request.Request(url, headers={"User-Agent": "OpenLSR-X/0.2.0"}) + with urllib.request.urlopen(req, timeout=timeout_s) as resp, dest.open("wb") as out_f: # noqa: S310 + shutil.copyfileobj(resp, out_f) + + def _block_downsample_3d(vol: np.ndarray, factor: int) -> np.ndarray: """Exact block-average 3D downsampling along all 3 axes by integer ``factor``.""" d, h, w = vol.shape @@ -126,23 +149,45 @@ def _block_downsample_3d(vol: np.ndarray, factor: int) -> np.ndarray: ).mean(axis=(1, 3, 5), dtype=np.float32) +def _triplanar_mid_ssim(a: np.ndarray, b: np.ndarray) -> tuple[float, float]: + """Compute both z-midplane SSIM and 3-axis tri-planar mid-slice SSIM on 3D cubes.""" + planes = [ + (a[a.shape[0] // 2], b[b.shape[0] // 2]), + (a[:, a.shape[1] // 2, :], b[:, b.shape[1] // 2, :]), + (a[:, :, a.shape[2] // 2], b[:, :, b.shape[2] // 2]), + ] + scores: list[float] = [] + for p_a, p_b in planes: + win = min(7, int(min(p_a.shape[0], p_a.shape[1]))) + if win % 2 == 0: + win -= 1 + if win >= 3: + scores.append( + float(structural_similarity(p_a, p_b, data_range=1.0, win_size=max(3, win))) + ) + else: + scores.append(-float(np.mean((p_a - p_b) ** 2))) + return scores[0], float(np.mean(scores)) + + def register_multires_pair_3d( low_vol: np.ndarray, high_vol: np.ndarray, scale_factor: int = 2, local_refine_radius: int = 1, + min_triplanar_ssim: float = 0.20, ) -> tuple[np.ndarray, np.ndarray, dict[str, object]]: - """Vectorized 3D registration of paired multi-magnification XCT volumes. + """HR-voxel sub-pixel 3D registration of paired multi-magnification XCT volumes. - Replaces brute-force 3D slice scanning with FFT phase cross-correlation at coarse - resolution followed by local 3D SSIM refinement, returning strictly shape-matched - ``(aligned_lr, aligned_hr, metadata)`` with ``aligned_hr.shape == s * aligned_lr.shape``. + Uses sub-voxel FFT phase cross-correlation (``upsample_factor=scale_factor``) followed by + integer HR-grid translation search scored by tri-planar 3D SSIM, eliminating residual + half-LR-voxel (up to ``scale_factor // 2`` HR voxels) misregistration. """ if scale_factor < 1: raise ValueError(f"scale_factor must be >= 1, got {scale_factor}.") - lr = np.asarray(low_vol, dtype=np.float32) - hr = np.asarray(high_vol, dtype=np.float32) + lr = sanitize_xct_volume(low_vol) + hr = sanitize_xct_volume(high_vol) if lr.ndim != 3 or hr.ndim != 3: raise ValueError(f"Expected 3D volumes, got {lr.shape} and {hr.shape}.") @@ -151,82 +196,123 @@ def register_multires_pair_3d( lr_ref = lr[: common_lr_shape[0], : common_lr_shape[1], : common_lr_shape[2]] hr_ref = hr_coarse[: common_lr_shape[0], : common_lr_shape[1], : common_lr_shape[2]] - shift_est, _, _ = phase_cross_correlation(lr_ref, hr_ref, upsample_factor=1) - base_shift = tuple(int(round(float(s))) for s in shift_est) + shift_est_lr, _, _ = phase_cross_correlation( + lr_ref, hr_ref, upsample_factor=max(1, int(scale_factor)) + ) + # shift_est_lr maps coarse HR coordinate c -> LR coordinate c + shift_lr. + # In HR voxel units: hr_coord + shift_hr <-> s * lr_coord => shift_hr = round(s * shift_est_lr). + s = int(scale_factor) + base_shift_hr = tuple(int(round(float(sh) * s)) for sh in shift_est_lr) - def _extract_overlap( - shift_lr: tuple[int, int, int], + def _extract_hr_grid_overlap( + shift_hr: tuple[int, int, int], ) -> tuple[np.ndarray, np.ndarray, np.ndarray] | None: - dz, dy, dx = shift_lr - # Map coarse HR coordinate c -> LR coordinate c + shift_lr - z0_hr = max(0, -dz) - y0_hr = max(0, -dy) - x0_hr = max(0, -dx) - - z1_hr = min(hr_coarse.shape[0], lr.shape[0] - dz) - y1_hr = min(hr_coarse.shape[1], lr.shape[1] - dy) - x1_hr = min(hr_coarse.shape[2], lr.shape[2] - dx) - - if (z1_hr - z0_hr) < 8 or (y1_hr - y0_hr) < 8 or (x1_hr - x0_hr) < 8: + dz_h, dy_h, dx_h = shift_hr + # Represent shift_hr = s * q_lr - r_hr with r_hr in [0, s - 1] so HR start is r_hr + s * z0_c + qz, rz = divmod(dz_h, s) + qy, ry = divmod(dy_h, s) + qx, rx = divmod(dx_h, s) + # Convert: lr_idx = c + q + (1 if r > 0? Wait: hr_slice starts at h_off in [0, s-1]: + # Specifically, if we offset HR by h_off in [0, s-1], block c of hr[h_off:] covers HR [h_off + c*s, h_off + (c+1)*s), + # which corresponds to LR index c + q_lr where s * q_lr - h_off == shift_hr => h_off = (-shift_hr) % s, q_lr = (shift_hr + h_off) // s! + hz = (-dz_h) % s + hy = (-dy_h) % s + hx = (-dx_h) % s + qz = (dz_h + hz) // s + qy = (dy_h + hy) // s + qx = (dx_h + hx) // s + + avail_z_c = (hr.shape[0] - hz) // s + avail_y_c = (hr.shape[1] - hy) // s + avail_x_c = (hr.shape[2] - hx) // s + + z0_c = max(0, -qz) + y0_c = max(0, -qy) + x0_c = max(0, -qx) + + z1_c = min(avail_z_c, lr.shape[0] - qz) + y1_c = min(avail_y_c, lr.shape[1] - qy) + x1_c = min(avail_x_c, lr.shape[2] - qx) + + min_overlap = min(8, int(min(common_lr_shape))) + if ( + (z1_c - z0_c) < min_overlap + or (y1_c - y0_c) < min_overlap + or (x1_c - x0_c) < min_overlap + ): return None - lr_sub = lr[z0_hr + dz : z1_hr + dz, y0_hr + dy : y1_hr + dy, x0_hr + dx : x1_hr + dx] - hr_c_sub = hr_coarse[z0_hr:z1_hr, y0_hr:y1_hr, x0_hr:x1_hr] - s = scale_factor - hr_sub = hr[z0_hr * s : z1_hr * s, y0_hr * s : y1_hr * s, x0_hr * s : x1_hr * s] + lr_sub = lr[z0_c + qz : z1_c + qz, y0_c + qy : y1_c + qy, x0_c + qx : x1_c + qx] + hr_sub = hr[ + hz + z0_c * s : hz + z1_c * s, + hy + y0_c * s : hy + y1_c * s, + hx + x0_c * s : hx + x1_c * s, + ] + hr_c_sub = _block_downsample_3d(hr_sub, s) return lr_sub, hr_c_sub, hr_sub - best_score = -2.0 - best_shift = (0, 0, 0) - best_pair: tuple[np.ndarray, np.ndarray] | None = None + hr_radius = max(1, int(local_refine_radius)) + candidates_hr = { + (base_shift_hr[0] + dz, base_shift_hr[1] + dy, base_shift_hr[2] + dx) + for dz in range(-hr_radius, hr_radius + 1) + for dy in range(-hr_radius, hr_radius + 1) + for dx in range(-hr_radius, hr_radius + 1) + } + candidates_hr.add((0, 0, 0)) - candidates = [ - (base_shift[0] + dz, base_shift[1] + dy, base_shift[2] + dx) - for dz in range(-local_refine_radius, local_refine_radius + 1) - for dy in range(-local_refine_radius, local_refine_radius + 1) - for dx in range(-local_refine_radius, local_refine_radius + 1) - ] - if (0, 0, 0) not in candidates: - candidates.append((0, 0, 0)) + zero_extracted = _extract_hr_grid_overlap((0, 0, 0)) + zero_tri_score = ( + _triplanar_mid_ssim(zero_extracted[0], zero_extracted[1])[1] + if zero_extracted is not None + else -2.0 + ) + + best_tri_score = -2.0 + best_mid_score = -2.0 + best_shift_hr = (0, 0, 0) + best_pair: tuple[np.ndarray, np.ndarray] | None = None - for cand in candidates: - extracted = _extract_overlap(cand) + for cand_hr in sorted(candidates_hr): + extracted = _extract_hr_grid_overlap(cand_hr) if extracted is None: continue lr_sub, hr_c_sub, hr_sub = extracted - mid = lr_sub.shape[0] // 2 - win = min(7, min(lr_sub.shape[1], lr_sub.shape[2])) - if win % 2 == 0: - win -= 1 - score = ( - float( - structural_similarity( - lr_sub[mid], - hr_c_sub[mid], - data_range=1.0, - win_size=max(3, win), - ) - ) - if win >= 3 - else -float(np.mean((lr_sub - hr_c_sub) ** 2)) - ) - if score > best_score: - best_score = score - best_shift = cand + mid_score, tri_score = _triplanar_mid_ssim(lr_sub, hr_c_sub) + if tri_score > best_tri_score: + best_tri_score = tri_score + best_mid_score = mid_score + best_shift_hr = cand_hr best_pair = (lr_sub.copy(), hr_sub.copy()) if best_pair is None: d, h, w = common_lr_shape - s = scale_factor best_pair = (lr[:d, :h, :w].copy(), hr[: d * s, : h * s, : w * s].copy()) - best_shift = (0, 0, 0) + best_mid_score, best_tri_score = _triplanar_mid_ssim( + best_pair[0], _block_downsample_3d(best_pair[1], s) + ) + best_shift_hr = (0, 0, 0) + + min_ssim = float(min_triplanar_ssim) + if best_tri_score < min_ssim: + import warnings + + warnings.warn( + f"Low 3D registration tri-planar SSIM ({best_tri_score:.4f} < {min_ssim:.2f}); " + "verify that LR and HR ROIs physically overlap.", + UserWarning, + stacklevel=2, + ) info: dict[str, object] = { - "coarse_shift_zyx": list(best_shift), - "coarse_mid_slice_ssim": best_score, + "coarse_shift_zyx": [round(sh / float(s), 4) for sh in best_shift_hr], + "hr_shift_zyx": list(best_shift_hr), + "initial_triplanar_ssim": zero_tri_score, + "coarse_mid_slice_ssim": best_mid_score, + "hr_triplanar_ssim": best_tri_score, + "registration_quality_ok": bool(best_tri_score >= min_ssim), "aligned_lr_shape": list(best_pair[0].shape), "aligned_hr_shape": list(best_pair[1].shape), - "scale_factor": scale_factor, + "scale_factor": s, } return best_pair[0], best_pair[1], info @@ -236,7 +322,7 @@ def synthesize_zn13x_phantom_pair( lr_shape: tuple[int, int, int] = (48, 48, 48), seed: int = 42, ) -> tuple[np.ndarray, np.ndarray]: - """Synthesize a calibrated two-phase Zn-doped Zeolite 13X synchrotron XCT pair. + """Synthesize a calibrated tri-phase Zn-doped Zeolite 13X synchrotron XCT pair (low-RAM float32). Models the physical structure described in Green et al. (*Sci. Data* 2025): - Cleaved Zeolite 13X fragment inside a thin-walled capillary FOV @@ -248,43 +334,48 @@ def synthesize_zn13x_phantom_pair( hr_shape = (lr_shape[0] * scale, lr_shape[1] * scale, lr_shape[2] * scale) rng = np.random.default_rng(seed) - # Coordinate grid in [-1, 1]^3 for cleaved pellet fragment + Zn diffusion rim - zz, yy, xx = np.meshgrid( - np.linspace(-1.0, 1.0, hr_shape[0], dtype=np.float32), - np.linspace(-1.0, 1.0, hr_shape[1], dtype=np.float32), - np.linspace(-1.0, 1.0, hr_shape[2], dtype=np.float32), - indexing="ij", - ) - radial = np.sqrt(0.85 * zz**2 + yy**2 + 1.1 * xx**2) - - # Hierarchical macropores + mesopores generated via multi-scale Gaussian random fields - coarse_field = gaussian_filter( - rng.standard_normal(hr_shape).astype(np.float32), sigma=max(2.0, scale * 1.4) - ) - fine_field = gaussian_filter( - rng.standard_normal(hr_shape).astype(np.float32), sigma=max(0.9, scale * 0.45) - ) - macro_pores = coarse_field > np.quantile(coarse_field, 0.78) - meso_pores = fine_field > np.quantile(fine_field, 0.84) - pore_mask = np.logical_or(macro_pores, meso_pores) - - # Zn2+ ion-exchange rim (outer shell of pellet has higher X-ray attenuation at 27 keV) - zn_rim = radial > 0.52 - hr_clean = np.where(zn_rim, 0.88, 0.68).astype(np.float32) - hr_clean[pore_mask] = 0.14 + # Broadcasted 1D grids avoid allocating three full 3D coordinate tensors + zz = np.linspace(-1.0, 1.0, hr_shape[0], dtype=np.float32)[:, np.newaxis, np.newaxis] + yy = np.linspace(-1.0, 1.0, hr_shape[1], dtype=np.float32)[np.newaxis, :, np.newaxis] + xx = np.linspace(-1.0, 1.0, hr_shape[2], dtype=np.float32)[np.newaxis, np.newaxis, :] + radial_sq = 0.85 * (zz * zz) + (yy * yy) + 1.1 * (xx * xx) + + # Generate float32 random fields directly (half the peak RAM of float64 standard_normal) + coarse_field = rng.standard_normal(hr_shape, dtype=np.float32) + gaussian_filter(coarse_field, sigma=max(2.0, scale * 1.4), output=coarse_field) + stride = max(1, int(round((hr_shape[0] * hr_shape[1] * hr_shape[2] / 500_000) ** (1.0 / 3.0)))) + q_coarse = float(np.quantile(coarse_field[::stride, ::stride, ::stride], 0.78)) + pore_mask = coarse_field > q_coarse + del coarse_field + + fine_field = rng.standard_normal(hr_shape, dtype=np.float32) + gaussian_filter(fine_field, sigma=max(0.9, scale * 0.45), output=fine_field) + q_fine = float(np.quantile(fine_field[::stride, ::stride, ::stride], 0.84)) + pore_mask |= fine_field > q_fine + del fine_field + + # Zn2+ ion-exchange rim (radial > 0.52 <=> radial_sq > 0.2704) + hr_clean = np.where(radial_sq > (0.52 * 0.52), np.float32(0.88), np.float32(0.68)) + del radial_sq + hr_clean[pore_mask] = np.float32(0.14) + del pore_mask # High-magnification GGG:Eu / LuAG scintillator PSF + mild FBP noise hr_vol = gaussian_filter(hr_clean, sigma=0.55, mode="reflect") - hr_vol = hr_vol + rng.normal(0.0, 0.015, size=hr_shape).astype(np.float32) - hr_vol = np.clip(hr_vol, 0.0, 1.0).astype(np.float32, copy=False) + hr_noise = rng.normal(0.0, 0.015, size=hr_shape).astype(np.float32, copy=False) + hr_vol += hr_noise + del hr_noise + np.clip(hr_vol, 0.0, 1.0, out=hr_vol) # Lower-magnification thick LuAG (500 um) scintillator blur + lens browning noise lr_blurred = gaussian_filter(hr_clean, sigma=0.85 * scale, mode="reflect") + del hr_clean lr_binned = _block_downsample_3d(lr_blurred, scale) - noise_sigma = 0.024 if pair == "2x" else 0.035 # 2.5x lens browning increases photon noise + del lr_blurred + noise_sigma = 0.024 if pair == "2x" else 0.035 lr_vol = lr_binned + rng.normal(0.0, noise_sigma, size=lr_binned.shape).astype(np.float32) - lr_vol = np.clip(lr_vol, 0.0, 1.0).astype(np.float32, copy=False) - return lr_vol, hr_vol + np.clip(lr_vol, 0.0, 1.0, out=lr_vol) + return lr_vol.astype(np.float32, copy=False), hr_vol.astype(np.float32, copy=False) def extract_aligned_slab_from_h5( @@ -294,8 +385,15 @@ def extract_aligned_slab_from_h5( lr_slab_depth: int = 64, lr_crop_yx: int | None = None, dataset_key: str = "4-TomopyRecon-tomo/data", + consistent_attenuation_window: bool = True, ) -> tuple[np.ndarray, np.ndarray, dict[str, object]]: - """Extract and normalize an aligned 3D slab from raw >50 GB I13-2 HDF5 files without loading full cubes.""" + """Extract and normalize an aligned 3D slab from raw >50 GB I13-2 HDF5 files without loading full cubes. + + When ``consistent_attenuation_window=True`` (default), both magnifications are normalized + using the joint physical linear-attenuation range ``[min(vmin), max(vmax)]`` so identical + physical ``mu`` values map to identical ``[0, 1]`` intensities across LR and HR (essential + for linear-attenuation downsampling consistency in ``AttenuationConservationLoss``). + """ if pair == "2x": lo_spec = ZN13X_I13_RESOLUTIONS["1p625um"] hi_spec = ZN13X_I13_RESOLUTIONS["0p8125um"] @@ -310,12 +408,6 @@ def extract_aligned_slab_from_h5( hi_yx = hi_spec.roi_812um_yx assert lo_yx is not None and hi_yx is not None - half_d = lr_slab_depth // 2 - lo_z0 = max(0, lo_spec.anchor_z - half_d) - lo_z1 = lo_z0 + lr_slab_depth - hi_z0 = max(0, hi_spec.anchor_z - half_d * scale) - hi_z1 = hi_z0 + lr_slab_depth * scale - lo_y0, lo_y1 = lo_yx[0] lo_x0, lo_x1 = lo_yx[1] hi_y0, hi_y1 = hi_yx[0] @@ -327,22 +419,119 @@ def extract_aligned_slab_from_h5( hi_y1 = min(hi_y1, hi_y0 + lr_crop_yx * scale) hi_x1 = min(hi_x1, hi_x0 + lr_crop_yx * scale) - # Note: Raw Savu TomopyRecon HDF5 stores axes (y_orig, z_orig, x_orig) -> transposed (1, 2, 0) in Calum's notebook - with h5py.File(low_h5_path, "r") as f_lo: + # Raw Savu TomopyRecon HDF5 stores axes (x_orig, z_orig, y_orig) -> transposed (1, 2, 0) -> (Z, Y, X) + with h5py.File(low_h5_path, "r") as f_lo, h5py.File(high_h5_path, "r") as f_hi: dset_lo = f_lo[dataset_key] - raw_lo = np.asarray(dset_lo[lo_x0:lo_x1, lo_z0:lo_z1, lo_y0:lo_y1], dtype=np.float32) + dset_hi = f_hi[dataset_key] + max_lo_z = int(dset_lo.shape[1]) + max_hi_z = int(dset_hi.shape[1]) + + eff_depth = min(int(lr_slab_depth), max_lo_z, max_hi_z // scale) + if eff_depth < 1: + raise ValueError( + f"HDF5 z-dimensions ({max_lo_z}, {max_hi_z}) cannot satisfy scale={scale}." + ) + half_d = eff_depth // 2 + + lo_z0 = min(max(0, lo_spec.anchor_z - half_d), max_lo_z - eff_depth) + lo_z1 = lo_z0 + eff_depth + hi_z0 = min(max(0, hi_spec.anchor_z - half_d * scale), max_hi_z - eff_depth * scale) + hi_z1 = hi_z0 + eff_depth * scale + + raw_lo = sanitize_xct_volume(np.asarray(dset_lo[lo_x0:lo_x1, lo_z0:lo_z1, lo_y0:lo_y1])) slab_lo = np.transpose(raw_lo, (1, 2, 0)) - with h5py.File(high_h5_path, "r") as f_hi: - dset_hi = f_hi[dataset_key] - raw_hi = np.asarray(dset_hi[hi_x0:hi_x1, hi_z0:hi_z1, hi_y0:hi_y1], dtype=np.float32) + raw_hi = sanitize_xct_volume(np.asarray(dset_hi[hi_x0:hi_x1, hi_z0:hi_z1, hi_y0:hi_y1])) slab_hi = np.transpose(raw_hi, (1, 2, 0)) - norm_lo = normalize_volume(slab_lo, mode="fixed", vmin=lo_spec.vmin, vmax=lo_spec.vmax) - norm_hi = normalize_volume(slab_hi, mode="fixed", vmin=hi_spec.vmin, vmax=hi_spec.vmax) + if consistent_attenuation_window: + joint_vmin = min(lo_spec.vmin, hi_spec.vmin) + joint_vmax = max(lo_spec.vmax, hi_spec.vmax) + norm_lo = normalize_volume(slab_lo, mode="fixed", vmin=joint_vmin, vmax=joint_vmax) + norm_hi = normalize_volume(slab_hi, mode="fixed", vmin=joint_vmin, vmax=joint_vmax) + else: + norm_lo = normalize_volume(slab_lo, mode="fixed", vmin=lo_spec.vmin, vmax=lo_spec.vmax) + norm_hi = normalize_volume(slab_hi, mode="fixed", vmin=hi_spec.vmin, vmax=hi_spec.vmax) + return register_multires_pair_3d(norm_lo, norm_hi, scale_factor=scale) +def _resolve_local_h5_path(h5_root: Path, spec: Zn13XResolutionSpec) -> Path | None: + """Locate local Diamond I13-2 Savu HDF5 under standard or Zenodo-extracted layouts.""" + candidates = [ + h5_root / spec.recon_filename, + h5_root / f"{spec.scan_id}_tomo_p4_tomopy_recon.h5", + h5_root / spec.scan_id / "tomo_p4_tomopy_recon.h5", + h5_root / f"zenodo_{spec.zenodo_record}" / "tomo_p4_tomopy_recon.h5", + ] + for p in candidates: + if p.is_file(): + return p + return None + + +def _read_centered_preview_h5_pair( + lo_h5_path: Path, + hi_h5_path: Path, + lr_size: int, + scale: int, +) -> tuple[np.ndarray, np.ndarray]: + """Read coaxial center-cropped 8-bit subvolumes from Zenodo 14245751 HDF5 files.""" + with h5py.File(lo_h5_path, "r") as f_lo, h5py.File(hi_h5_path, "r") as f_hi: + lo_keys = [k for k in f_lo.keys() if isinstance(f_lo[k], h5py.Dataset)] + hi_keys = [k for k in f_hi.keys() if isinstance(f_hi[k], h5py.Dataset)] + if not lo_keys or not hi_keys: + raise KeyError("Zenodo preview HDF5 file contained no top-level dataset.") + d_lo = f_lo[lo_keys[0]] + d_hi = f_hi[hi_keys[0]] + + eff_dz = min(int(lr_size), int(d_lo.shape[0]), int(d_hi.shape[0]) // scale) + eff_dy = min(int(lr_size), int(d_lo.shape[1]), int(d_hi.shape[1]) // scale) + eff_dx = min(int(lr_size), int(d_lo.shape[2]), int(d_hi.shape[2]) // scale) + + lo_z0 = max(0, (int(d_lo.shape[0]) - eff_dz) // 2) + lo_y0 = max(0, (int(d_lo.shape[1]) - eff_dy) // 2) + lo_x0 = max(0, (int(d_lo.shape[2]) - eff_dx) // 2) + + hi_dz, hi_dy, hi_dx = eff_dz * scale, eff_dy * scale, eff_dx * scale + hi_z0 = max(0, (int(d_hi.shape[0]) - hi_dz) // 2) + hi_y0 = max(0, (int(d_hi.shape[1]) - hi_dy) // 2) + hi_x0 = max(0, (int(d_hi.shape[2]) - hi_dx) // 2) + + lo_arr = sanitize_xct_volume( + np.asarray(d_lo[lo_z0 : lo_z0 + eff_dz, lo_y0 : lo_y0 + eff_dy, lo_x0 : lo_x0 + eff_dx]) + ) + hi_arr = sanitize_xct_volume( + np.asarray(d_hi[hi_z0 : hi_z0 + hi_dz, hi_y0 : hi_y0 + hi_dy, hi_x0 : hi_x0 + hi_dx]) + ) + return normalize_volume(lo_arr, mode="none"), normalize_volume(hi_arr, mode="none") + + +def _is_zn13x_cache_valid( + cached: dict[str, object], + lr_size: int, + raw_h5_dir: str | Path | None, + prefer_offline: bool, + allow_offline_fallback: bool, +) -> bool: + """Ensure cached Zn-13X files match requested ``lr_size`` and never mask real data with stale phantoms.""" + if cached.get("requested_lr_size") != int(lr_size): + return False + src = str(cached.get("source_kind", "")) + is_exp = bool(cached.get("is_experimental_xct", False)) + if raw_h5_dir is not None and src not in ( + "local_i13_hdf5_slab", + "local_i13_preview_h5_registered", + ): + return False + if not prefer_offline and not is_exp: + # Cached artifact is a synthetic phantom, whereas caller requested real experimental data! + if not allow_offline_fallback or raw_h5_dir is not None: + return False + return False + return True + + def prepare_zn13x_benchmark( pair: Zn13XPairName = "2x", dest_dir: str | Path = "data/benchmarks", @@ -350,15 +539,20 @@ def prepare_zn13x_benchmark( lr_size: int = 48, raw_h5_dir: str | Path | None = None, allow_offline_fallback: bool = True, + prefer_offline: bool = False, + timeout_s: float = 10.0, seed: int = 42, ) -> tuple[Path, Path, dict[str, object]]: """Prepare aligned LR & HR 3D TIFF volumes + provenance manifest for Diamond I13-2 ``Zn-13X``. Resolution priority: - 1. Cached ``zn13x__lr.tif`` + ``zn13x__hr.tif`` + manifest if already present. - 2. Local synchrotron HDF5 reconstructions in ``raw_h5_dir`` (e.g., on Diamond/Isambard Lustre). - 3. Public Zenodo 8-bit preview sub-volumes (``10.5281/zenodo.14245751``) when online. - 4. Calibrated two-phase ``Zn-13X`` synchrotron phantom when offline or air-gapped. + 1. Cached ``zn13x__lr.tif`` + ``zn13x__hr.tif`` + manifest if size and source provenance match. + 2. Local synchrotron HDF5 reconstructions in ``raw_h5_dir`` (supports ``_recon.h5``, + Zenodo ``/tomo_p4_tomopy_recon.h5``, and ``16906*_8bit_cropped.h5`` layouts). + 3. Public Zenodo 8-bit preview HDF5 sub-volumes (``10.5281/zenodo.14245751``, + ``16906*_8bit_cropped.h5``) when online and ``prefer_offline=False``. + 4. Calibrated tri-phase ``Zn-13X`` synchrotron phantom when offline or ``prefer_offline=True`` + (raises ``RuntimeError`` when ``allow_offline_fallback=False``). """ out_dir = Path(dest_dir) out_dir.mkdir(parents=True, exist_ok=True) @@ -366,103 +560,162 @@ def prepare_zn13x_benchmark( lr_tif = out_dir / f"{name}_lr.tif" hr_tif = out_dir / f"{name}_hr.tif" manifest_path = out_dir / f"{name}_manifest.json" + lock_path = out_dir / f".{name}.lock" + + with lock_path.open("w") as lf: + fcntl.flock(lf.fileno(), fcntl.LOCK_EX) + if lr_tif.is_file() and hr_tif.is_file() and manifest_path.is_file(): + cached: dict[str, object] = json.loads(manifest_path.read_text(encoding="utf-8")) + if _is_zn13x_cache_valid( + cached, + lr_size=lr_size, + raw_h5_dir=raw_h5_dir, + prefer_offline=prefer_offline, + allow_offline_fallback=allow_offline_fallback, + ): + return lr_tif, hr_tif, cached + + pid = os.getpid() + scale = 2 if pair == "2x" else 8 + lo_key, hi_key = ("1p625um", "0p8125um") if pair == "2x" else ("2p600um", "0p325um") + lo_spec = ZN13X_I13_RESOLUTIONS[lo_key] + hi_spec = ZN13X_I13_RESOLUTIONS[hi_key] + + lr_vol: np.ndarray | None = None + hr_vol: np.ndarray | None = None + reg_info: dict[str, object] = {} + source_kind = "offline_calibrated_zn13x_phantom" - if lr_tif.is_file() and hr_tif.is_file() and manifest_path.is_file(): - cached: dict[str, object] = json.loads(manifest_path.read_text(encoding="utf-8")) - return lr_tif, hr_tif, cached - - scale = 2 if pair == "2x" else 8 - lo_key, hi_key = ("1p625um", "0p8125um") if pair == "2x" else ("2p600um", "0p325um") - lo_spec = ZN13X_I13_RESOLUTIONS[lo_key] - hi_spec = ZN13X_I13_RESOLUTIONS[hi_key] - - lr_vol: np.ndarray | None = None - hr_vol: np.ndarray | None = None - reg_info: dict[str, object] = {} - source_kind = "offline_calibrated_zn13x_phantom" - - # 1. Check local HDF5 directory if provided - if raw_h5_dir is not None: - h5_root = Path(raw_h5_dir) - lo_h5 = h5_root / lo_spec.recon_filename - hi_h5 = h5_root / hi_spec.recon_filename - if lo_h5.is_file() and hi_h5.is_file(): - lr_vol, hr_vol, reg_info = extract_aligned_slab_from_h5( - lo_h5, - hi_h5, - pair=pair, - lr_slab_depth=lr_size, - lr_crop_yx=lr_size, - ) - source_kind = "local_i13_hdf5_slab" - - # 2. Try Zenodo 8-bit preview record API if online and tier == 'preview' - if lr_vol is None and tier == "preview": - api_url = f"https://zenodo.org/api/records/{ZN13X_SUBVOLUMES_ZENODO_RECORD}" - try: - with urllib.request.urlopen(api_url, timeout=8) as resp: # noqa: S310 - record_meta = json.loads(resp.read().decode("utf-8")) - files = {f["key"]: f["links"]["self"] for f in record_meta.get("files", [])} - # Match TIF/H5 files mentioning pixel sizes if present in record - lo_candidates = [ - u for k, u in files.items() if lo_spec.magnification in k or lo_key in k - ] - hi_candidates = [ - u for k, u in files.items() if hi_spec.magnification in k or hi_key in k - ] - if lo_candidates and hi_candidates: - tmp_lo = out_dir / f".{name}_lo.tmp" - tmp_hi = out_dir / f".{name}_hi.tmp" - try: - urllib.request.urlretrieve(lo_candidates[0], tmp_lo) # noqa: S310 - urllib.request.urlretrieve(hi_candidates[0], tmp_hi) # noqa: S310 - raw_lo_arr = normalize_volume(tifffile.imread(tmp_lo), mode="minmax") - raw_hi_arr = normalize_volume(tifffile.imread(tmp_hi), mode="minmax") - lr_vol, hr_vol, reg_info = register_multires_pair_3d( - raw_lo_arr[:lr_size, :lr_size, :lr_size], - raw_hi_arr[: lr_size * scale, : lr_size * scale, : lr_size * scale], - scale_factor=scale, + # 1. Check local HDF5 directory if provided + if raw_h5_dir is not None: + h5_root = Path(raw_h5_dir) + lo_h5 = _resolve_local_h5_path(h5_root, lo_spec) + hi_h5 = _resolve_local_h5_path(h5_root, hi_spec) + lo_prev = h5_root / lo_spec.preview_filename + hi_prev = h5_root / hi_spec.preview_filename + if lo_h5 is not None and hi_h5 is not None: + lr_vol, hr_vol, reg_info = extract_aligned_slab_from_h5( + lo_h5, + hi_h5, + pair=pair, + lr_slab_depth=lr_size, + lr_crop_yx=lr_size, + ) + source_kind = "local_i13_hdf5_slab" + elif lo_prev.is_file() and hi_prev.is_file(): + raw_lo, raw_hi = _read_centered_preview_h5_pair( + lo_prev, hi_prev, lr_size=lr_size, scale=scale + ) + lr_vol, hr_vol, reg_info = register_multires_pair_3d( + raw_lo, raw_hi, scale_factor=scale + ) + source_kind = "local_i13_preview_h5_registered" + + # 2. Try Zenodo 8-bit preview HDF5 record API if online and tier == 'preview' + if lr_vol is None and tier == "preview" and not prefer_offline: + api_url = f"https://zenodo.org/api/records/{ZN13X_SUBVOLUMES_ZENODO_RECORD}" + try: + req = urllib.request.Request(api_url, headers={"User-Agent": "OpenLSR-X/0.2.0"}) + with urllib.request.urlopen(req, timeout=timeout_s) as resp: # noqa: S310 + record_meta = json.loads(resp.read().decode("utf-8")) + files = { + f["key"]: f.get("links", {}).get("content") or f.get("links", {}).get("self") + for f in record_meta.get("files", []) + } + lo_candidates = [ + u + for k, u in files.items() + if u + and ( + k == lo_spec.preview_filename + or lo_spec.scan_id in k + or lo_spec.magnification in k + or lo_key in k + ) + ] + hi_candidates = [ + u + for k, u in files.items() + if u + and ( + k == hi_spec.preview_filename + or hi_spec.scan_id in k + or hi_spec.magnification in k + or hi_key in k ) - source_kind = "zenodo_14245751_preview" - finally: - tmp_lo.unlink(missing_ok=True) - tmp_hi.unlink(missing_ok=True) - except Exception as exc: + ] + if lo_candidates and hi_candidates: + tmp_lo = out_dir / f".{name}_lo.{pid}.h5" + tmp_hi = out_dir / f".{name}_hi.{pid}.h5" + try: + _download_https_file(str(lo_candidates[0]), tmp_lo, timeout_s=60.0) + _download_https_file(str(hi_candidates[0]), tmp_hi, timeout_s=60.0) + raw_lo_arr, raw_hi_arr = _read_centered_preview_h5_pair( + tmp_lo, tmp_hi, lr_size=lr_size, scale=scale + ) + lr_vol, hr_vol, reg_info = register_multires_pair_3d( + raw_lo_arr, + raw_hi_arr, + scale_factor=scale, + ) + source_kind = "zenodo_14245751_preview" + finally: + tmp_lo.unlink(missing_ok=True) + tmp_hi.unlink(missing_ok=True) + except Exception as exc: + if not allow_offline_fallback: + raise RuntimeError( + f"Unable to download Zn-13X preview from Zenodo ({api_url}) and fallback is disabled." + ) from exc + + # 3. Offline calibrated Zn-13X tri-phase synchrotron phantom + if lr_vol is None or hr_vol is None: if not allow_offline_fallback: - raise RuntimeError( - f"Unable to download Zn-13X preview from Zenodo ({api_url}) and fallback is disabled." - ) from exc - - # 3. Offline calibrated Zn-13X two-phase synchrotron phantom - if lr_vol is None or hr_vol is None: - if not allow_offline_fallback: - raise RuntimeError(f"No local HDF5 or online Zenodo files available for {name}.") - lr_vol, hr_vol = synthesize_zn13x_phantom_pair( - pair=pair, - lr_shape=(lr_size, lr_size, lr_size), - seed=seed, - ) - source_kind = "offline_calibrated_zn13x_phantom" - - tifffile.imwrite(lr_tif, lr_vol.astype(np.float32), photometric="minisblack") - tifffile.imwrite(hr_tif, hr_vol.astype(np.float32), photometric="minisblack") - - manifest: dict[str, object] = { - "name": name, - "pair": pair, - "scale_factor": scale, - "low_resolution_um": lo_spec.voxel_size_um, - "high_resolution_um": hi_spec.voxel_size_um, - "low_zenodo_doi": f"10.5281/zenodo.{lo_spec.zenodo_record}", - "high_zenodo_doi": f"10.5281/zenodo.{hi_spec.zenodo_record}", - "paper_doi": "10.1038/s41597-025-04605-9", - "source_kind": source_kind, - "lr_shape": list(lr_vol.shape), - "hr_shape": list(hr_vol.shape), - "lr_sha256": _sha256_file(lr_tif), - "hr_sha256": _sha256_file(hr_tif), - "registration": reg_info, - "seed": seed, - } - manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8") - return lr_tif, hr_tif, manifest + raise RuntimeError(f"No local HDF5 or online Zenodo files available for {name}.") + lr_vol, hr_vol = synthesize_zn13x_phantom_pair( + pair=pair, + lr_shape=(lr_size, lr_size, lr_size), + seed=seed, + ) + source_kind = "offline_calibrated_zn13x_phantom" + + lr_tmp = out_dir / f".{name}_lr.{pid}.tif" + hr_tmp = out_dir / f".{name}_hr.{pid}.tif" + man_tmp = out_dir / f".{name}_manifest.{pid}.json" + tifffile.imwrite(lr_tmp, lr_vol.astype(np.float32), photometric="minisblack") + tifffile.imwrite(hr_tmp, hr_vol.astype(np.float32), photometric="minisblack") + + is_exp = source_kind in { + "local_i13_hdf5_slab", + "local_i13_preview_h5_registered", + "zenodo_14245751_preview", + } + manifest: dict[str, object] = { + "name": name, + "pair": pair, + "scale_factor": scale, + "requested_lr_size": int(lr_size), + "low_resolution_um": lo_spec.voxel_size_um, + "high_resolution_um": hi_spec.voxel_size_um, + "low_zenodo_doi": f"10.5281/zenodo.{lo_spec.zenodo_record}" if is_exp else None, + "high_zenodo_doi": f"10.5281/zenodo.{hi_spec.zenodo_record}" if is_exp else None, + "zenodo_preview_doi": ( + f"10.5281/zenodo.{ZN13X_SUBVOLUMES_ZENODO_RECORD}" + if source_kind in {"zenodo_14245751_preview", "local_i13_preview_h5_registered"} + else None + ), + "calibrated_reference_paper_doi": "10.1038/s41597-025-04605-9", + "source_kind": source_kind, + "is_experimental_xct": is_exp, + "lr_shape": list(lr_vol.shape), + "hr_shape": list(hr_vol.shape), + "lr_sha256": _sha256_file(lr_tmp), + "hr_sha256": _sha256_file(hr_tmp), + "registration": reg_info, + "seed": seed, + } + man_tmp.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8") + lr_tmp.replace(lr_tif) + hr_tmp.replace(hr_tif) + man_tmp.replace(manifest_path) + return lr_tif, hr_tif, manifest diff --git a/src/openlsrx/inference/orthogonal.py b/src/openlsrx/inference/orthogonal.py index c24c28f..03d8d38 100644 --- a/src/openlsrx/inference/orthogonal.py +++ b/src/openlsrx/inference/orthogonal.py @@ -1,4 +1,4 @@ -"""2D-to-3D and 2.5D-to-3D multi-axis orthogonal XCT super-resolution & epistemic uncertainty.""" +"""2D-to-3D and 2.5D-to-3D multi-axis orthogonal XCT super-resolution & view-disagreement uncertainty.""" from __future__ import annotations @@ -7,9 +7,11 @@ import numpy as np import torch -from scipy.ndimage import gaussian_filter, zoom +from scipy.ndimage import gaussian_filter from torch import nn +from ..data.transforms import build_strided_context_windows, zoom_cell_centered + AxisName = Literal["yz", "xz", "xy"] FusionMode = Literal["mean", "median", "fourier", "confidence", "confidence_fourier"] @@ -30,18 +32,15 @@ def _move_slice_axis_back(vol: np.ndarray, axis: AxisName) -> np.ndarray: return np.moveaxis(vol, 0, dim) -def _build_slice_context_windows(slices: np.ndarray, context_slices: int) -> np.ndarray: - """Construct ``(N, context_slices, h, w)`` reflect-padded adjacent slice windows.""" - if context_slices < 1 or context_slices % 2 == 0: - raise ValueError( - f"context_slices must be a positive odd integer (1, 3, 5, ...), got {context_slices}." - ) - if context_slices == 1: - return slices[:, np.newaxis, :, :] - half = context_slices // 2 - padded = np.pad(slices, ((half, half), (0, 0), (0, 0)), mode="reflect") - win = np.lib.stride_tricks.sliding_window_view(padded, window_shape=context_slices, axis=0) - return np.moveaxis(win, -1, 1) +def _build_slice_context_windows( + slices: np.ndarray, + context_slices: int, + context_stride: int = 1, +) -> np.ndarray: + """Construct ``(N, context_slices, h, w)`` adjacent slice windows at ``context_stride``.""" + return build_strided_context_windows( + slices, context_slices=context_slices, context_stride=context_stride + ) @torch.no_grad() @@ -51,13 +50,9 @@ def super_resolve_slice_stack( batch_size: int = 8, device: torch.device | str | None = None, context_slices: int | None = None, + context_stride: int = 1, ) -> np.ndarray: - """Run a 2D or 2.5D generator over a ``(N, h, w)`` stack of slices and return ``(N, H, W)``. - - When ``context_slices`` is ``None``, automatically inspects ``generator.in_channels`` so - that ``2.5D`` multi-slice generators (``in_channels = 2k + 1``) seamlessly receive - reflect-padded adjacent slice windows ``[z - k, ..., z + k]``. - """ + """Run a 2D or 2.5D generator over a ``(N, h, w)`` stack of slices and return ``(N, H, W)``.""" arr = np.asarray(slices, dtype=np.float32) if arr.ndim != 3: raise ValueError(f"Expected 3D slice stack (N, h, w), got shape {arr.shape}.") @@ -67,7 +62,7 @@ def super_resolve_slice_stack( if context_slices is not None else int(getattr(generator, "in_channels", 1)) ) - windows = _build_slice_context_windows(arr, ctx) + windows = _build_slice_context_windows(arr, ctx, context_stride=context_stride) if device is None: try: @@ -104,23 +99,25 @@ def super_resolve_volume_single_axis( device: torch.device | str | None = None, context_slices: int | None = None, ) -> np.ndarray: - """Super-resolve a 3D XCT volume ``(D, H, W)`` using a 2D/2.5D generator along ``axis``.""" + """Super-resolve a 3D XCT volume ``(D, H, W)`` using a 2D/2.5D generator along ``axis``. + + Uses ``zoom_cell_centered`` (``grid_mode=True``) along the stacking axis so half-voxel + cell centers remain strictly aligned with ``PixelShuffle`` across all 3 orthogonal sweeps, + and samples 2.5D context neighbors at native-LR spacing (``context_stride = round(zoom_n)``). + """ vol = np.asarray(low_volume, dtype=np.float32) if vol.ndim != 3: raise ValueError(f"Expected 3D volume, got shape {vol.shape}.") ordered = _move_slice_axis_first(vol, axis) # (N_axis, h, w) sf = float(scale_factor) + ctx_stride = 1 if interpolate_stack_axis and sf > 1.0: - target_n = int(round(ordered.shape[0] * sf)) + target_n = max(1, int(round(ordered.shape[0] * sf))) zoom_n = target_n / float(ordered.shape[0]) - ordered = zoom( - ordered, - zoom=(zoom_n, 1, 1), - order=3, - mode="reflect", - ).astype(np.float32, copy=False) + ordered = zoom_cell_centered(ordered, zoom_factors=(zoom_n, 1.0, 1.0), order=3) ordered = np.clip(ordered, 0.0, 1.0) + ctx_stride = max(1, int(round(zoom_n))) sr_ordered = super_resolve_slice_stack( generator=generator, @@ -128,6 +125,7 @@ def super_resolve_volume_single_axis( batch_size=batch_size, device=device, context_slices=context_slices, + context_stride=ctx_stride, ) return _move_slice_axis_back(sr_ordered, axis) @@ -136,17 +134,7 @@ def compute_orthogonal_uncertainty( volumes: Mapping[AxisName, np.ndarray], eps: float = 1e-6, ) -> dict[str, np.ndarray]: - """Compute zero-overhead voxel-wise epistemic uncertainty across orthogonal SR reconstructions. - - Because each voxel ``x`` is reconstructed from perpendicular high-resolution sweep planes, - inter-axis disagreement ``sigma_ortho(x) = std(V_yz, V_xz, V_xy)`` concentrates selectively - at sub-resolution pore throats and multi-phase grain boundaries where out-of-plane blur or - hallucination occurs. - - Returns: - Dictionary with keys ``'mean'``, ``'std'``, ``'range'``, and ``'cv'`` (coefficient of - variation), each of shape ``(D, H, W)`` in ``float32``. - """ + """Compute zero-overhead voxel-wise orthogonal view-disagreement uncertainty (``n=3`` sweeps).""" if not volumes: raise ValueError("At least one orthogonal volume is required.") items = [(ax, np.asarray(v, dtype=np.float32)) for ax, v in volumes.items()] @@ -177,61 +165,115 @@ def _fourier_directional_fuse( ref_shape: tuple[int, ...], psf_cutoff: float | None = None, ) -> np.ndarray: + """Streaming ``float32`` / ``complex64`` ``rfftn`` directional synthesis (6x lower RAM, NaN-free).""" d, h, w = ref_shape - kz = np.fft.fftfreq(d)[:, None, None] ** 2 - ky = np.fft.fftfreq(h)[None, :, None] ** 2 - kx = np.fft.fftfreq(w)[None, None, :] ** 2 + kz = (np.fft.fftfreq(d).astype(np.float32)[:, None, None]) ** 2 + ky = (np.fft.fftfreq(h).astype(np.float32)[None, :, None]) ** 2 + kx = (np.fft.rfftfreq(w).astype(np.float32)[None, None, :]) ** 2 k_dims = [kz, ky, kx] - weights: list[np.ndarray] = [] - spectra: list[np.ndarray] = [] + rfft_shape = (d, h, w // 2 + 1) + acc_spec = np.zeros(rfft_shape, dtype=np.complex64) + weight_sum = np.zeros(rfft_shape, dtype=np.float32) + dc_values: list[complex] = [] + + if psf_cutoff is not None and psf_cutoff > 0.0: + use_otf = True + inv_two_sigma_sq = np.float32(1.0 / max(2.0 * (psf_cutoff**2), 1e-12)) + else: + use_otf = False + inv_two_sigma_sq = np.float32(0.0) + for ax, v in items: + v_f32 = np.ascontiguousarray(v, dtype=np.float32) stack_dim = AXIS_TO_DIM[ax] in_plane_energy = sum(k_dims[i] for i in range(3) if i != stack_dim) - w_ax = np.asarray(in_plane_energy, dtype=np.float64) + 1e-12 - if psf_cutoff is not None and psf_cutoff > 0.0: - # Attenuate interpolated stacking-axis frequencies above optical OTF roll-off - k_stack_sq = np.asarray(k_dims[stack_dim], dtype=np.float64) - w_ax = w_ax * np.exp(-k_stack_sq / (2.0 * float(psf_cutoff) ** 2)) - weights.append(w_ax) - spectra.append(np.fft.fftn(v)) - - weight_sum = sum(weights) - fused_spec = sum(w_i * s_i for w_i, s_i in zip(weights, spectra, strict=True)) / weight_sum - fused_spec[0, 0, 0] = np.mean([s[0, 0, 0] for s in spectra]) - return np.fft.ifftn(fused_spec).real.astype(np.float32) - - -def _confidence_consensus_fuse(stacked: np.ndarray) -> np.ndarray: + if use_otf: + otf_stack = np.exp(-k_dims[stack_dim] * inv_two_sigma_sq).astype(np.float32, copy=False) + # Positive floor added AFTER OTF roll-off guarantees w_ax >= 1e-6 > 0 everywhere (never 0/0 = NaN) + w_ax = (in_plane_energy * otf_stack + np.float32(1e-6)).astype(np.float32, copy=False) + else: + w_ax = (in_plane_energy + np.float32(1e-6)).astype(np.float32, copy=False) + + spec = np.fft.rfftn(v_f32).astype(np.complex64, copy=False) + dc_values.append(complex(spec[0, 0, 0])) + acc_spec += w_ax * spec + weight_sum += w_ax + + fused_spec = acc_spec / np.maximum(weight_sum, np.float32(1e-12)) + fused_spec[0, 0, 0] = np.complex64(sum(dc_values) / len(dc_values)) + return np.fft.irfftn(fused_spec, s=(d, h, w), axes=(0, 1, 2)).astype(np.float32, copy=False) + + +def _through_plane_roughness(vol: np.ndarray, stack_dim: int) -> np.ndarray: + """Local stacking-axis discontinuity magnitude used to weight 2-axis consensus.""" + if vol.shape[stack_dim] < 2: + return np.zeros_like(vol, dtype=np.float32) + diff = np.abs(np.diff(vol, axis=stack_dim)) + pad_spec = [(0, 0), (0, 0), (0, 0)] + pad_spec[stack_dim] = (0, 1) + padded = np.pad(diff, pad_spec, mode="edge") + return gaussian_filter(padded, sigma=1.0, mode="reflect").astype(np.float32, copy=False) + + +def _confidence_consensus_fuse(items: list[tuple[AxisName, np.ndarray]]) -> np.ndarray: """Inverse-disagreement spatial consensus suppressing isolated single-axis blur/artifacts.""" - med = np.median(stacked, axis=0) + stacked = np.stack([v for _, v in items], axis=0) + if stacked.shape[0] == 2: + # With only 2 axes, median == mean identically; weight inversely by local stacking roughness + r0 = _through_plane_roughness(items[0][1], AXIS_TO_DIM[items[0][0]]) + r1 = _through_plane_roughness(items[1][1], AXIS_TO_DIM[items[1][0]]) + w0 = 1.0 / ((r0 + np.float32(1e-3)) ** 2) + w1 = 1.0 / ((r1 + np.float32(1e-3)) ** 2) + return np.asarray((w0 * stacked[0] + w1 * stacked[1]) / (w0 + w1), dtype=np.float32) + + med = np.median(stacked, axis=0).astype(np.float32, copy=False) weights = np.empty_like(stacked, dtype=np.float32) for idx in range(stacked.shape[0]): dev = gaussian_filter(np.abs(stacked[idx] - med), sigma=1.0, mode="reflect") - weights[idx] = 1.0 / ((dev + 1e-4) ** 2) + weights[idx] = 1.0 / ((dev + np.float32(1e-4)) ** 2) w_sum = np.sum(weights, axis=0, dtype=np.float32) return np.asarray(np.sum(weights * stacked, axis=0, dtype=np.float32) / w_sum, dtype=np.float32) +def _outlier_suppressed_fourier_fuse( + items: list[tuple[AxisName, np.ndarray]], + ref_shape: tuple[int, ...], + psf_cutoff: float | None = None, +) -> np.ndarray: + """Outlier-clamped directional Fourier synthesis (suppresses single-axis defects without stacking noise). + + Instead of blending spatial consensus directly into high-contrast pore walls (which re-injects + slice-stacking jitter wherever ``sigma_ortho`` rises), each single-axis sweep is Winsorized + toward the perpendicular-axes consensus wherever the remaining axes agree tightly, and the + cleaned sweeps are then synthesized via directional 3D Fourier fusion. + """ + v_conf = _confidence_consensus_fuse(items) + if len(items) < 3: + v_four = _fourier_directional_fuse(items, ref_shape, psf_cutoff=psf_cutoff) + return np.asarray(0.5 * (v_conf + v_four), dtype=np.float32) + + cleaned_items: list[tuple[AxisName, np.ndarray]] = [] + n_axes = len(items) + for idx, (ax, v_ax) in enumerate(items): + others = [items[j][1] for j in range(n_axes) if j != idx] + other_spread = np.ptp(np.stack(others, axis=0), axis=0).astype(np.float32) + # Tolerance scales with perpendicular-axes spread; when perpendicular axes agree (spread ~ 0), + # isolated out-of-plane blur or corruption on v_ax is pulled cleanly to v_conf. + tol = 1.25 * other_spread + np.float32(0.015) + v_clean = v_conf + np.clip(v_ax - v_conf, -tol, tol) + cleaned_items.append((ax, v_clean.astype(np.float32, copy=False))) + + return _fourier_directional_fuse(cleaned_items, ref_shape, psf_cutoff=psf_cutoff) + + def fuse_orthogonal_volumes( volumes: Mapping[AxisName, np.ndarray], mode: FusionMode = "mean", clamp_01: bool = True, psf_cutoff: float | None = None, ) -> np.ndarray: - """Fuse aligned single-axis 3D super-resolved volumes into an isotropic 3D reconstruction. - - Supported fusion modes: - - ``'mean'``: Equal-weight voxel-wise average across provided axes. - - ``'median'``: Voxel-wise median (robust against isolated slice artifacts). - - ``'fourier'``: 3D Fourier-space directional fusion weighting each single-axis - reconstruction by its in-plane spatial frequencies (and optional OTF ``psf_cutoff``). - - ``'confidence'``: Inverse-disagreement local consensus weighting that suppresses the - out-of-plane blurred axis when the two perpendicular axes agree on a sharp throat. - - ``'confidence_fourier'``: Hybrid spectral-consensus fusion applying directional 3D - Fourier synthesis in high-agreement bulk regions while transitioning smoothly to - outlier-resistant consensus where inter-axis epistemic uncertainty ``sigma_ortho`` spikes. - """ + """Fuse aligned single-axis 3D super-resolved volumes into an isotropic 3D reconstruction.""" if not volumes: raise ValueError("At least one orthogonal volume is required for fusion.") @@ -257,15 +299,9 @@ def fuse_orthogonal_volumes( elif mode == "fourier": out = _fourier_directional_fuse(items, ref_shape, psf_cutoff=psf_cutoff) elif mode == "confidence": - stacked = np.stack([v for _, v in items], axis=0) - out = _confidence_consensus_fuse(stacked) + out = _confidence_consensus_fuse(items) elif mode == "confidence_fourier": - stacked = np.stack([v for _, v in items], axis=0) - v_fourier = _fourier_directional_fuse(items, ref_shape, psf_cutoff=psf_cutoff) - v_conf = _confidence_consensus_fuse(stacked) - sigma = np.std(stacked, axis=0, ddof=1, dtype=np.float32) - alpha = np.clip(sigma / 0.08, 0.0, 1.0) - out = ((1.0 - alpha) * v_fourier + alpha * v_conf).astype(np.float32) + out = _outlier_suppressed_fourier_fuse(items, ref_shape, psf_cutoff=psf_cutoff) else: raise ValueError( f"Unsupported fusion mode={mode!r}. Expected 'mean', 'median', 'fourier', " diff --git a/src/openlsrx/io/openimpala.py b/src/openlsrx/io/openimpala.py index ca6a223..8883f59 100644 --- a/src/openlsrx/io/openimpala.py +++ b/src/openlsrx/io/openimpala.py @@ -2,6 +2,7 @@ from __future__ import annotations +import re from pathlib import Path from typing import Literal @@ -11,6 +12,7 @@ from ..metrics.petrophysics import ThresholdMethod, segment_pore_space ImpalaDirection = Literal["x", "y", "z"] +_SAFE_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$") def export_for_openimpala( @@ -33,6 +35,13 @@ def export_for_openimpala( 2. ``/_openimpala.inputs``: Ready-to-run AMReX ``ParmParse`` input deck for ``OpenImpala``'s ``Tortuosity`` / ``Diffusion`` executable. """ + clean_name = str(name).strip() + if not clean_name or ".." in clean_name or _SAFE_NAME_RE.fullmatch(clean_name) is None: + raise ValueError( + f"Invalid OpenImpala sample name {name!r}: expected alphanumeric/underscore/hyphen/dot " + "identifier without path separators, '..', quotes, or whitespace." + ) + arr = np.asarray(volume_or_mask) if arr.ndim != 3: raise ValueError(f"OpenImpala requires a 3D volume (D, H, W), got shape {arr.shape}.") @@ -57,8 +66,8 @@ def export_for_openimpala( out_root = Path(output_dir) out_root.mkdir(parents=True, exist_ok=True) - tiff_path = out_root / f"{name}.tif" - inputs_path = out_root / f"{name}_openimpala.inputs" + tiff_path = out_root / f"{clean_name}.tif" + inputs_path = out_root / f"{clean_name}_openimpala.inputs" tifffile.imwrite( tiff_path, diff --git a/src/openlsrx/losses/loss.py b/src/openlsrx/losses/loss.py index 584384d..d6fdd78 100644 --- a/src/openlsrx/losses/loss.py +++ b/src/openlsrx/losses/loss.py @@ -2,6 +2,7 @@ from __future__ import annotations +import warnings from typing import Literal import torch @@ -19,14 +20,21 @@ def custom_sigmoid(x: torch.Tensor, k: float = 1.0) -> torch.Tensor: class PixelNorm(nn.Module): - """Channel-wise pixel feature vector normalization (Karras et al., 2018).""" + """Channel-wise pixel feature vector normalization (Karras et al., 2018). - def __init__(self, epsilon: float = 1e-8) -> None: + Upcasts internally to ``float32`` before computing ``x^2`` and ``rsqrt`` so + mixed-precision (``16-mixed`` / FP16) training never overflows ``65504`` or + underflows ``epsilon`` to ``0.0`` (``0 / 0 = NaN``). + """ + + def __init__(self, epsilon: float = 1e-6) -> None: super().__init__() - self.epsilon = float(epsilon) + self.epsilon = max(float(epsilon), 1e-8) def forward(self, x: torch.Tensor) -> torch.Tensor: - return x * torch.rsqrt(torch.mean(x.square(), dim=1, keepdim=True) + self.epsilon) + x_f32 = x.to(torch.float32) + normed = x_f32 * torch.rsqrt(torch.mean(x_f32.square(), dim=1, keepdim=True) + self.epsilon) + return normed.to(dtype=x.dtype) class VGGLoss(nn.Module): @@ -47,17 +55,21 @@ def __init__( reduction: Literal["mse", "l1"] = "mse", pretrained: bool = True, normalize_inputs: bool = True, + allow_offline_fallback: bool = True, ) -> None: super().__init__() self.vgg_layers = int(vgg_layers) self.pretrained = bool(pretrained) self.normalize_inputs = bool(normalize_inputs) - weights = VGG19_Weights.DEFAULT if self.pretrained else None - backbone = vgg19(weights=weights).features[: self.vgg_layers].eval() + backbone = self._load_vgg_features( + pretrained=self.pretrained, + vgg_layers=self.vgg_layers, + allow_offline_fallback=allow_offline_fallback, + ) for param in backbone.parameters(): param.requires_grad = False - # Store outside _modules so frozen ImageNet weights (~550 MB) never bloat checkpoints + # Store outside _modules so frozen ImageNet weights never bloat checkpoints self._vgg_holder: tuple[nn.Module] = (backbone,) self.criterion: nn.Module = nn.MSELoss() if reduction == "mse" else nn.L1Loss() @@ -67,26 +79,60 @@ def __init__( self.register_buffer("mean", mean, persistent=False) self.register_buffer("std", std, persistent=False) + @staticmethod + def _load_vgg_features( + pretrained: bool, + vgg_layers: int, + allow_offline_fallback: bool, + ) -> nn.Module: + if pretrained: + try: + full = vgg19(weights=VGG19_Weights.DEFAULT) + except Exception as exc: + if not allow_offline_fallback: + raise + warnings.warn( + f"Unable to load pretrained VGG19 weights ({exc}); " + "falling back to random frozen VGG19 features on air-gapped node.", + RuntimeWarning, + stacklevel=2, + ) + full = vgg19(weights=None) + else: + full = vgg19(weights=None) + features = full.features[:vgg_layers].eval() + del full # Immediately release ~500 MB dense classifier parameters + return features + def _apply(self, fn): # type: ignore[override] super()._apply(fn) self._vgg_holder[0]._apply(fn) return self - def _prepare(self, x: torch.Tensor) -> torch.Tensor: - if x.shape[1] == 1: - x = x.repeat(1, 3, 1, 1) + def _prepare(self, x: torch.Tensor, target_dtype: torch.dtype) -> torch.Tensor: + out = x.to(dtype=target_dtype) + if out.shape[1] == 1: + out = out.repeat(1, 3, 1, 1) + elif out.shape[1] != 3: + c_mid = out.shape[1] // 2 + out = out[:, c_mid : c_mid + 1].repeat(1, 3, 1, 1) if self.normalize_inputs: - x = (x - self.mean.to(dtype=x.dtype, device=x.device)) / self.std.to( - dtype=x.dtype, device=x.device + out = (out - self.mean.to(dtype=target_dtype, device=out.device)) / self.std.to( + dtype=target_dtype, device=out.device ) - return x + return out def forward(self, generated: torch.Tensor, target: torch.Tensor) -> torch.Tensor: backbone = self._vgg_holder[0] backbone.eval() - gen_in = self._prepare(generated) - tgt_in = self._prepare(target) + param = next(backbone.parameters(), None) + if param is not None and param.device != generated.device: + backbone.to(device=generated.device) + weight_dtype = param.dtype if param is not None else torch.float32 + + gen_in = self._prepare(generated, target_dtype=weight_dtype) + tgt_in = self._prepare(target, target_dtype=weight_dtype) gen_features = backbone(gen_in) with torch.no_grad(): tgt_features = backbone(tgt_in) - return self.criterion(gen_features, tgt_features) + return self.criterion(gen_features.to(torch.float32), tgt_features.to(torch.float32)) diff --git a/src/openlsrx/losses/physics.py b/src/openlsrx/losses/physics.py index 2504fbf..8343174 100644 --- a/src/openlsrx/losses/physics.py +++ b/src/openlsrx/losses/physics.py @@ -2,9 +2,11 @@ Replaces or complements RGB ImageNet VGG perceptual priors with domain invariants: 1. ``AttenuationConservationLoss``: Coarse-voxel X-ray linear attenuation conservation under - scale-matched optical PSF + area/volume downsampling (supports 2D, 2.5D, and 3D). + scale-matched optical PSF + area/volume downsampling (supports 2D, 2.5D through-plane + Laplacian z-PSF correction, and 3D). 2. ``SoftCLDiceLoss``: Differentiable soft-skeleton topological connectivity loss penalizing - pinched pore throats and spurious isolated pores (adapted from Shit et al., CVPR 2021). + pinched pore throats and spurious isolated pores (adapted from Shit et al., CVPR 2021), + with bimodal quantile thresholding and single-phase homogeneity gating. 3. ``SobelGradientLoss``: 2D/3D interfacial edge sharpness preservation across phase boundaries. 4. ``FocalFrequencyLoss``: Adaptive spectral loss weighting poorly recovered high wavenumbers in 2D/3D Fourier space (adapted from Jiang et al., ICCV 2021). @@ -26,8 +28,13 @@ def _gaussian_kernel_1d(sigma: float, device: torch.device, dtype: torch.dtype) return kernel / kernel.sum() +def _safe_pad_1d(x: Tensor, pad_tuple: tuple[int, ...], dim_size: int, r: int) -> Tensor: + mode = "reflect" if (dim_size > r and dim_size > 1) else "replicate" + return F.pad(x, pad_tuple, mode=mode) + + def _apply_separable_gaussian(x: Tensor, sigma: float) -> Tensor: - """Apply reflect-padded separable Gaussian blur to a 4D (2D) or 5D (3D) single-channel tensor.""" + """Apply reflect/replicate-padded separable Gaussian blur to a 4D (2D) or 5D (3D) tensor.""" if sigma <= 0.0: return x k1d = _gaussian_kernel_1d(sigma, device=x.device, dtype=x.dtype) @@ -36,29 +43,33 @@ def _apply_separable_gaussian(x: Tensor, sigma: float) -> Tensor: if x.ndim == 4: kh = k1d.view(1, 1, -1, 1).expand(c, 1, -1, 1) kw = k1d.view(1, 1, 1, -1).expand(c, 1, 1, -1) - out = F.pad(x, (0, 0, r, r), mode="reflect") + out = _safe_pad_1d(x, (0, 0, r, r), int(x.shape[2]), r) out = F.conv2d(out, kh, groups=c) - out = F.pad(out, (r, r, 0, 0), mode="reflect") + out = _safe_pad_1d(out, (r, r, 0, 0), int(out.shape[3]), r) return F.conv2d(out, kw, groups=c) if x.ndim == 5: kd = k1d.view(1, 1, -1, 1, 1).expand(c, 1, -1, 1, 1) kh = k1d.view(1, 1, 1, -1, 1).expand(c, 1, 1, -1, 1) kw = k1d.view(1, 1, 1, 1, -1).expand(c, 1, 1, 1, -1) - out = F.pad(x, (0, 0, 0, 0, r, r), mode="reflect") + out = _safe_pad_1d(x, (0, 0, 0, 0, r, r), int(x.shape[2]), r) out = F.conv3d(out, kd, groups=c) - out = F.pad(out, (0, 0, r, r, 0, 0), mode="reflect") + out = _safe_pad_1d(out, (0, 0, r, r, 0, 0), int(out.shape[3]), r) out = F.conv3d(out, kh, groups=c) - out = F.pad(out, (r, r, 0, 0, 0, 0), mode="reflect") + out = _safe_pad_1d(out, (r, r, 0, 0, 0, 0), int(out.shape[4]), r) return F.conv3d(out, kw, groups=c) raise ValueError(f"Expected 4D or 5D tensor, got shape {tuple(x.shape)}.") class AttenuationConservationLoss(nn.Module): - """Enforces physical X-ray linear attenuation conservation between HR predictions and LR inputs. - - In absorption micro-CT, coarse voxel attenuation equals the spatial integral (mean) of - sub-voxel attenuation convolved with the detector/scintillator point-spread function. - Automatically selects the central context slice when ``low_res`` has ``2k + 1`` channels. + """Enforces linear-attenuation (``mu``) downsampling consistency between HR predictions and LR inputs. + + In reconstructed absorption micro-CT, coarse voxel linear attenuation approximates the spatial + average of sub-voxel linear attenuation convolved with the system point-spread function (assuming + joint intensity calibration between LR and HR). When ``low_res`` provides ``2.5D`` multi-slice + context (``C >= 3`` sampled at unit native-LR spacing ``+-Delta z_LR``) and ``psf_sigma > 0``, + incorporates the leading-order through-plane ``z``-PSF curvature term + ``0.5 * sigma_{z,LR}^2 * d^2 mu / dz_{LR}^2`` so horizontal phase boundaries are not biased + toward out-of-plane partial-volume blur. """ def __init__( @@ -72,14 +83,30 @@ def __init__( def forward(self, pred_hr: Tensor, low_res: Tensor) -> Tensor: pred_f32 = pred_hr.to(torch.float32) - lr_f32 = low_res.to(torch.float32) - if lr_f32.shape[1] != pred_f32.shape[1]: - mid = lr_f32.shape[1] // 2 - lr_f32 = lr_f32[:, mid : mid + pred_f32.shape[1]] + lr_full = low_res.to(torch.float32) + + z_correction: Tensor | None = None + if lr_full.shape[1] != pred_f32.shape[1]: + mid = lr_full.shape[1] // 2 + lr_f32 = lr_full[:, mid : mid + pred_f32.shape[1]] + if pred_f32.ndim == 4 and lr_full.shape[1] >= 3 and self.psf_sigma > 0.0: + scale_est = max(1.0, float(pred_f32.shape[-1]) / max(float(lr_full.shape[-1]), 1.0)) + sigma_lr_z = self.psf_sigma / scale_est + lap_z = ( + lr_full[:, mid - 1 : mid] + - 2.0 * lr_full[:, mid : mid + 1] + + lr_full[:, mid + 1 : mid + 2] + ) + z_correction = 0.5 * (sigma_lr_z**2) * lap_z + else: + lr_f32 = lr_full blurred = _apply_separable_gaussian(pred_f32, self.psf_sigma) target_size = lr_f32.shape[2:] downsampled = F.interpolate(blurred, size=target_size, mode="area") + if z_correction is not None: + downsampled = downsampled + z_correction + if self.reduction_norm == "mse": return F.mse_loss(downsampled, lr_f32) return F.l1_loss(downsampled, lr_f32) @@ -124,9 +151,9 @@ def soft_skeletonize(img: Tensor, num_iter: int = 5) -> Tensor: class SoftCLDiceLoss(nn.Module): """Differentiable centerline-Dice (soft-clDice) pore-throat connectivity loss for XCT. - Maps continuous greyscale reconstructions ``[0, 1]`` to differentiable soft pore masks - via temperature-scaled sigmoid around a sample-adaptive (or fixed) threshold, extracts - medial pore-throat skeletons, and penalizes broken throats or isolated false pores. + Uses a bimodal quantile midpoint ``0.5 * (Q_20 + Q_80)`` when ``threshold=None`` and gates + out single-phase homogeneous patches (dynamic range ``< min_phase_contrast``) so pure solid + grains or pure macro-pores never have acquisition noise amplified into fake skeletons. """ def __init__( @@ -135,6 +162,7 @@ def __init__( temperature: float = 15.0, pore_is_low: bool = True, threshold: float | None = None, + min_phase_contrast: float = 0.08, smooth: float = 1e-4, ) -> None: super().__init__() @@ -142,6 +170,7 @@ def __init__( self.temperature = float(temperature) self.pore_is_low = bool(pore_is_low) self.threshold = float(threshold) if threshold is not None else None + self.min_phase_contrast = float(min_phase_contrast) self.smooth = float(smooth) def _to_soft_pore_prob(self, x: Tensor, thr: Tensor) -> Tensor: @@ -153,10 +182,23 @@ def forward(self, pred_hr: Tensor, target_hr: Tensor) -> Tensor: true_f32 = target_hr.to(torch.float32) spatial_dims = tuple(range(2, true_f32.ndim)) + b, c = true_f32.shape[0], true_f32.shape[1] + flat_true = true_f32.detach().reshape(b, c, -1) + dyn_range = flat_true.amax(dim=-1) - flat_true.amin(dim=-1) # (B, C) + if self.threshold is not None: thr = torch.full_like(true_f32.mean(dim=spatial_dims, keepdim=True), self.threshold) + active_mask = torch.ones((b, c), device=pred_f32.device, dtype=torch.float32) else: - thr = true_f32.detach().mean(dim=spatial_dims, keepdim=True) + q20 = torch.quantile(flat_true, 0.20, dim=-1) + q80 = torch.quantile(flat_true, 0.80, dim=-1) + mid_q = 0.5 * (q20 + q80) + view_shape = (b, c) + (1,) * len(spatial_dims) + thr = mid_q.reshape(view_shape) + active_mask = (dyn_range >= self.min_phase_contrast).to(torch.float32) + + if float(active_mask.sum().item()) == 0.0: + return pred_f32.sum() * 0.0 p_pred = self._to_soft_pore_prob(pred_f32, thr) p_true = self._to_soft_pore_prob(true_f32, thr) @@ -171,7 +213,8 @@ def forward(self, pred_hr: Tensor, target_hr: Tensor) -> Tensor: skel_true.sum(dim=spatial_dims) + self.smooth ) cl_dice = (2.0 * t_prec * t_sens) / (t_prec + t_sens + self.smooth) - return (1.0 - cl_dice).mean() + per_sample = (1.0 - cl_dice) * active_mask + return per_sample.sum() / active_mask.sum().clamp_min(1.0) class SobelGradientLoss(nn.Module): @@ -184,6 +227,8 @@ def __init__(self) -> None: def _spatial_gradients(x: Tensor) -> list[Tensor]: grads: list[Tensor] = [] for dim in range(2, x.ndim): + if x.shape[dim] < 2: + continue sl_hi = [slice(None)] * x.ndim sl_lo = [slice(None)] * x.ndim sl_hi[dim] = slice(1, None) @@ -194,6 +239,8 @@ def _spatial_gradients(x: Tensor) -> list[Tensor]: def forward(self, pred_hr: Tensor, target_hr: Tensor) -> Tensor: pred_grads = self._spatial_gradients(pred_hr.to(torch.float32)) true_grads = self._spatial_gradients(target_hr.to(torch.float32)) + if not pred_grads: + return pred_hr.to(torch.float32).sum() * 0.0 losses = [F.l1_loss(pg, tg) for pg, tg in zip(pred_grads, true_grads, strict=True)] return torch.stack(losses).mean() diff --git a/src/openlsrx/metrics/__init__.py b/src/openlsrx/metrics/__init__.py index 61abc99..b93f3e9 100644 --- a/src/openlsrx/metrics/__init__.py +++ b/src/openlsrx/metrics/__init__.py @@ -34,6 +34,7 @@ compute_drainage_rmse, compute_tortuosity_uncertainty_bounds, evaluate_transport_metrics, + precompute_reference_transport, solve_steady_state_diffusion_axis, ) @@ -63,6 +64,7 @@ "evaluate_spectral_metrics", "evaluate_transport_metrics", "evaluate_triphase_zn13x_metrics", + "precompute_reference_transport", "segment_pore_space", "solve_steady_state_diffusion_axis", "two_point_correlation_radial", diff --git a/src/openlsrx/metrics/image.py b/src/openlsrx/metrics/image.py index edac5cb..7f0c7f9 100644 --- a/src/openlsrx/metrics/image.py +++ b/src/openlsrx/metrics/image.py @@ -103,6 +103,10 @@ def compute_ssim_3d_isotropic( raise ValueError( f"Expected 3D volumes (D, H, W), got {tuple(p.shape)} and {tuple(t.shape)}." ) + if min(p.shape) < 3: + sq_ax = next(ax for ax, sz in enumerate(p.shape) if sz < 3) + if p.shape[sq_ax] == 1 and t.shape[sq_ax] == 1: + return compute_ssim(p.squeeze(sq_ax), t.squeeze(sq_ax), data_range=data_range) ssim_yz = compute_ssim(p, t, data_range=data_range) ssim_xz = compute_ssim(p.permute(1, 0, 2), t.permute(1, 0, 2), data_range=data_range) ssim_xy = compute_ssim(p.permute(2, 0, 1), t.permute(2, 0, 1), data_range=data_range) @@ -129,16 +133,31 @@ def evaluate_image_metrics( target: Tensor | np.ndarray, data_range: float = 1.0, ) -> dict[str, float]: - """Compute a complete dictionary of image-fidelity metrics.""" + """Compute a complete dictionary of image-fidelity metrics (safe on both 2D slices and 3D cubes).""" p = torch.as_tensor(pred, dtype=torch.float32) t = torch.as_tensor(target, dtype=torch.float32, device=p.device) - results: dict[str, float] = { + if p.ndim == 3 and t.ndim == 3 and p.shape == t.shape and 1 in p.shape: + sq_ax = tuple(p.shape).index(1) + p_2d = p.squeeze(sq_ax) + t_2d = t.squeeze(sq_ax) + results: dict[str, float] = { + "psnr": compute_psnr(p_2d, t_2d, data_range=data_range), + "ssim": compute_ssim(p_2d, t_2d, data_range=data_range), + "mae": compute_mae(p_2d, t_2d), + "rmse": compute_rmse(p_2d, t_2d), + } + ms_2d = compute_ms_ssim(p_2d, t_2d, data_range=data_range) + if ms_2d is not None: + results["ms_ssim"] = ms_2d + return results + + results = { "psnr": compute_psnr(p, t, data_range=data_range), "ssim": compute_ssim(p, t, data_range=data_range), "mae": compute_mae(p, t), "rmse": compute_rmse(p, t), } - if p.ndim == 3: + if p.ndim == 3 and min(p.shape) >= 3: results["ssim_3d_triplanar"] = compute_ssim_3d_isotropic(p, t, data_range=data_range) ms_ssim = compute_ms_ssim(p, t, data_range=data_range) if ms_ssim is not None: diff --git a/src/openlsrx/metrics/petrophysics.py b/src/openlsrx/metrics/petrophysics.py index e87bb58..ecda9e1 100644 --- a/src/openlsrx/metrics/petrophysics.py +++ b/src/openlsrx/metrics/petrophysics.py @@ -41,16 +41,7 @@ def segment_pore_space( fixed_value: float | None = None, pore_is_low: bool = True, ) -> tuple[np.ndarray, float]: - """Segment a greyscale XCT volume into a boolean pore mask and return ``(mask, threshold)``. - - Args: - volume: 2D or 3D greyscale array. - method: Thresholding algorithm (``'otsu'``, ``'yen'``, or ``'fixed'``). - fixed_value: Threshold value when ``method == 'fixed'``. - pore_is_low: ``True`` when pores correspond to lower X-ray attenuation - (standard absorption XCT); ``False`` when pores have higher intensity - (e.g., PoreSpy local-thickness maps or inverted greyscale). - """ + """Segment a greyscale XCT volume into a boolean pore mask and return ``(mask, threshold)``.""" arr = np.asarray(volume, dtype=np.float32) thr = compute_threshold(arr, method=method, fixed_value=fixed_value) mask = (arr < thr) if pore_is_low else (arr > thr) @@ -78,6 +69,9 @@ def compute_dice_iou(pred_mask: np.ndarray, true_mask: np.ndarray) -> tuple[floa def compute_specific_surface_area(pore_mask: np.ndarray, voxel_size: float = 1.0) -> float: """Specific surface area ``S_v`` (interfacial area per bulk volume, or perimeter per area in 2D).""" mask = np.asarray(pore_mask, dtype=bool) + if mask.ndim == 3 and min(mask.shape) < 2: + sq_ax = next(ax for ax, sz in enumerate(mask.shape) if sz < 2) + mask = np.squeeze(mask, axis=sq_ax) if mask.all() or (~mask).all(): return 0.0 if mask.ndim == 2: @@ -99,6 +93,8 @@ def compute_specific_surface_area(pore_mask: np.ndarray, voxel_size: float = 1.0 def compute_euler_density(pore_mask: np.ndarray, voxel_size: float = 1.0) -> float: """Euler characteristic per unit volume/area (measure of pore-network connectivity).""" mask = np.asarray(pore_mask, dtype=bool) + if mask.ndim == 3 and 1 in mask.shape: + mask = np.squeeze(mask, axis=mask.shape.index(1)) chi = float(euler_number(mask)) bulk = float(mask.size) * (voxel_size**mask.ndim) return chi / bulk @@ -127,28 +123,53 @@ def compute_pore_radius_wasserstein( def two_point_correlation_radial(pore_mask: np.ndarray, max_lag: int | None = None) -> np.ndarray: - """FFT-accelerated radially averaged two-point correlation function ``S_2(r)``.""" - f = np.asarray(pore_mask, dtype=np.float64) - fft = np.fft.fftn(f) - power = np.abs(fft) ** 2 - autocorr = np.fft.ifftn(power).real / float(f.size) + """Unbiased, zero-padded, full-sphere/circle radially averaged two-point correlation ``S_2(r)``. - # Shift zero-lag to origin and compute integer radial bins up to max_lag. + Zero-pads by ``limit`` along every spatial dimension before ``rfftn`` autocorrelation to + eliminate periodic wrap-around, normalizes each lag vector ``r`` by the exact count of + in-bounds overlapping voxel pairs ``prod(L_d - |r_d|)``, and radially averages over all + ``2^d`` signed octants/quadrants for full ``O_h`` rotational invariance. + """ + mask = np.asarray(pore_mask, dtype=bool) + if mask.ndim == 3 and 1 in mask.shape: + mask = np.squeeze(mask, axis=mask.shape.index(1)) + f = mask.astype(np.float64) min_dim = min(f.shape) - limit = min(min_dim // 2, 64 if max_lag is None else int(max_lag)) - slices = tuple(slice(0, limit) for _ in range(f.ndim)) - octant = autocorr[slices] - - grids = np.ogrid[slices] - dist_sq = sum(g * g for g in grids) + limit = max(1, min(min_dim // 2, 64 if max_lag is None else int(max_lag))) + + pad_shape = tuple(int(dim + limit) for dim in f.shape) + fft_axes = tuple(range(f.ndim)) + fft = np.fft.rfftn(f, s=pad_shape, axes=fft_axes) + autocorr_full = np.fft.irfftn(np.abs(fft) ** 2, s=pad_shape, axes=fft_axes) + + # Extract centered signed lags in [-(limit - 1), ..., +(limit - 1)]^ndim across all 2^d octants + lag_1d = np.arange(-(limit - 1), limit, dtype=np.int64) + idx_per_dim = [np.mod(lag_1d, p_dim) for p_dim in pad_shape] + sub_corr = autocorr_full[np.ix_(*idx_per_dim)] + + # Exact count of valid non-padded voxel pairs for each signed displacement vector + overlap_1d = [(float(dim) - np.abs(lag_1d).astype(np.float64)) for dim in f.shape] + overlap_counts = overlap_1d[0] + for ov in overlap_1d[1:]: + overlap_counts = overlap_counts[..., np.newaxis] * ov + unbiased_corr = sub_corr / np.maximum(overlap_counts, 1.0) + + sq_1d = (lag_1d * lag_1d).astype(np.float64) + dist_sq = sq_1d + for sq in sq_1d[np.newaxis, :] if f.ndim == 1 else [sq_1d for _ in range(f.ndim - 1)]: + dist_sq = dist_sq[..., np.newaxis] + sq radii = np.rint(np.sqrt(dist_sq)).astype(np.int32) - radial_sum = np.bincount(radii.ravel(), weights=octant.ravel(), minlength=limit) - radial_cnt = np.bincount(radii.ravel(), minlength=limit) + in_shell = radii < limit + r_valid = radii[in_shell] + c_valid = unbiased_corr[in_shell] + + radial_sum = np.bincount(r_valid, weights=c_valid, minlength=limit) + radial_cnt = np.bincount(r_valid, minlength=limit) valid = radial_cnt[:limit] > 0 s2 = np.zeros(limit, dtype=np.float64) s2[valid] = radial_sum[:limit][valid] / radial_cnt[:limit][valid] - return s2 + return np.clip(s2, 0.0, 1.0) def compute_s2_rmse(pred_mask: np.ndarray, true_mask: np.ndarray, max_lag: int = 48) -> float: @@ -165,15 +186,11 @@ def compute_through_plane_anisotropy_error( stack_axis: int = 0, eps: float = 1e-8, ) -> float: - """Relative error in through-plane vs. in-plane gradient energy for 3D reconstructions. - - Directly measures slice-stacking ("venetian blind") discontinuities along ``stack_axis`` - normalized against the natural structural anisotropy of the ground-truth volume. - """ + """Relative error in through-plane vs. in-plane gradient energy for 3D reconstructions.""" p = np.asarray(pred_vol, dtype=np.float32) t = np.asarray(true_vol, dtype=np.float32) - if p.ndim != 3 or t.ndim != 3: - raise ValueError("Through-plane anisotropy error requires 3D volumes.") + if p.ndim != 3 or t.ndim != 3 or min(p.shape) < 2 or min(t.shape) < 2: + raise ValueError("Through-plane anisotropy error requires 3D volumes with dims >= 2.") def _grad_ratio(vol: np.ndarray) -> float: grads = [float(np.mean(np.abs(np.diff(vol, axis=ax)))) for ax in range(3)] @@ -197,57 +214,79 @@ def evaluate_petrophysical_metrics( voxel_size: float = 1.0, stack_axis: int = 0, ) -> dict[str, float]: - """Compute a comprehensive dictionary of porous-media XCT metrics.""" + """Compute a comprehensive dictionary of porous-media XCT metrics. + + Headline morphological metrics (``porosity_abs_error``, ``pore_dice``, ``pore_iou``, + ``specific_surface_rel_error``, ``euler_density_abs_error``, ``pore_radius_wasserstein``, + ``two_point_corr_rmse``) apply the physical ground-truth HR threshold ``threshold_true`` + consistently to both ``target`` and ``pred`` (matching ``evaluate_transport_metrics``), so + greyscale drift or attenuation bias is rigorously penalized. Secondary contrast-invariant + diagnostics under independent Otsu thresholding are reported with ``*_auto_otsu`` keys. + """ pred_arr = np.asarray(pred, dtype=np.float32) true_arr = np.asarray(target, dtype=np.float32) + if ( + pred_arr.ndim == 3 + and true_arr.ndim == 3 + and pred_arr.shape == true_arr.shape + and 1 in pred_arr.shape + ): + sq_ax = pred_arr.shape.index(1) + pred_arr = np.squeeze(pred_arr, axis=sq_ax) + true_arr = np.squeeze(true_arr, axis=sq_ax) + true_mask, hr_thr = segment_pore_space( true_arr, method=threshold_method, fixed_value=fixed_threshold, pore_is_low=pore_is_low, ) - pred_mask_auto, sr_thr = segment_pore_space( - pred_arr, - method=threshold_method, - fixed_value=fixed_threshold, - pore_is_low=pore_is_low, - ) pred_mask_locked, _ = segment_pore_space( pred_arr, method="fixed", fixed_value=hr_thr, pore_is_low=pore_is_low, ) + pred_mask_auto, sr_thr = segment_pore_space( + pred_arr, + method=threshold_method, + fixed_value=fixed_threshold, + pore_is_low=pore_is_low, + ) phi_true = compute_porosity(true_mask) - phi_pred = compute_porosity(pred_mask_auto) - phi_pred_locked = compute_porosity(pred_mask_locked) + phi_pred = compute_porosity(pred_mask_locked) + phi_pred_auto = compute_porosity(pred_mask_auto) - dice, iou = compute_dice_iou(pred_mask_auto, true_mask) - dice_locked, _ = compute_dice_iou(pred_mask_locked, true_mask) + dice_locked, iou_locked = compute_dice_iou(pred_mask_locked, true_mask) + dice_auto, _ = compute_dice_iou(pred_mask_auto, true_mask) sv_true = compute_specific_surface_area(true_mask, voxel_size=voxel_size) - sv_pred = compute_specific_surface_area(pred_mask_auto, voxel_size=voxel_size) + sv_pred = compute_specific_surface_area(pred_mask_locked, voxel_size=voxel_size) sv_rel_err = abs(sv_pred - sv_true) / max(sv_true, 1e-8) euler_true = compute_euler_density(true_mask, voxel_size=voxel_size) - euler_pred = compute_euler_density(pred_mask_auto, voxel_size=voxel_size) + euler_pred = compute_euler_density(pred_mask_locked, voxel_size=voxel_size) - psd_w1 = compute_pore_radius_wasserstein(pred_mask_auto, true_mask, voxel_size=voxel_size) - s2_rmse = compute_s2_rmse(pred_mask_auto, true_mask) + psd_w1 = compute_pore_radius_wasserstein(pred_mask_locked, true_mask, voxel_size=voxel_size) + s2_rmse = compute_s2_rmse(pred_mask_locked, true_mask) metrics: dict[str, float] = { "threshold_true": hr_thr, - "threshold_pred": sr_thr, + "threshold_pred": hr_thr, + "threshold_pred_auto_otsu": sr_thr, "porosity_true": phi_true, "porosity_pred": phi_pred, "porosity_abs_error": abs(phi_pred - phi_true), "porosity_rel_error": abs(phi_pred - phi_true) / max(phi_true, 1e-8), - "porosity_locked_abs_error": abs(phi_pred_locked - phi_true), - "pore_dice": dice, - "pore_iou": iou, + "porosity_locked_abs_error": abs(phi_pred - phi_true), + "porosity_auto_otsu_pred": phi_pred_auto, + "porosity_auto_otsu_abs_error": abs(phi_pred_auto - phi_true), + "pore_dice": dice_locked, + "pore_iou": iou_locked, "pore_dice_locked": dice_locked, + "pore_dice_auto_otsu": dice_auto, "specific_surface_true": sv_true, "specific_surface_pred": sv_pred, "specific_surface_rel_error": sv_rel_err, @@ -257,7 +296,7 @@ def evaluate_petrophysical_metrics( "pore_radius_wasserstein": psd_w1, "two_point_corr_rmse": s2_rmse, } - if pred_arr.ndim == 3 and true_arr.ndim == 3: + if pred_arr.ndim == 3 and true_arr.ndim == 3 and min(pred_arr.shape) >= 2: metrics["through_plane_anisotropy_error"] = compute_through_plane_anisotropy_error( pred_arr, true_arr, stack_axis=stack_axis ) @@ -271,15 +310,9 @@ def evaluate_triphase_zn13x_metrics( ) -> dict[str, float]: """Quantify three-phase reactive microstructure in Zn-doped Zeolite 13X XCT volumes. - Partitions ``Zn-13X`` absorption micro-CT reconstructions (Green et al., *Sci. Data* 2025) - into three physically meaningful chemical/structural domains ordered by 27 keV X-ray - linear attenuation: - 1. **Macropore / Mesopore network** (``I < t_low``) - 2. **Unexchanged ``Na-13X`` zeolite core** (``t_low <= I < t_high``) - 3. **Ion-exchanged ``Zn-13X`` outer shell** (``I >= t_high``) - - Reports per-phase Dice similarity, phase volume-fraction errors, and the macroscopic - ``Zn / (Zn + Na)`` solid ion-exchange fraction error (directly linkable to DIAD ``XRD-CT``). + Locks ``(t_low, t_high)`` on ``target`` (ground-truth HR) and applies those exact physical + attenuation thresholds to ``pred`` so greyscale shift across Pore / ``Na-13X`` / ``Zn-13X`` + phases is faithfully measured. """ from skimage.filters import threshold_multiotsu @@ -290,6 +323,8 @@ def evaluate_triphase_zn13x_metrics( if thresholds is not None: t_lo, t_hi = float(thresholds[0]), float(thresholds[1]) + elif float(np.ptp(true_arr)) < 1e-4: + t_lo, t_hi = 0.40, 0.78 else: try: thrs = threshold_multiotsu(true_arr, classes=3) @@ -297,6 +332,8 @@ def evaluate_triphase_zn13x_metrics( except ValueError: p33, p67 = np.percentile(true_arr, [33.3, 66.7]) t_lo, t_hi = float(p33), float(p67) + if np.isclose(t_lo, t_hi, atol=1e-5): + t_lo, t_hi = 0.40, 0.78 true_pore = true_arr < t_lo true_na = (true_arr >= t_lo) & (true_arr < t_hi) diff --git a/src/openlsrx/metrics/spectral.py b/src/openlsrx/metrics/spectral.py index ddd7e84..0c2a134 100644 --- a/src/openlsrx/metrics/spectral.py +++ b/src/openlsrx/metrics/spectral.py @@ -9,34 +9,61 @@ from typing import Any import numpy as np +from scipy.ndimage import distance_transform_edt def _tukey_window_1d(n: int, alpha: float = 0.15) -> np.ndarray: if n <= 2 or alpha <= 0.0: return np.ones(n, dtype=np.float64) + eff_alpha = max(float(alpha), 0.35) if n < 20 else float(alpha) + eff_alpha = min(eff_alpha, 1.0) x = np.linspace(0.0, 1.0, n, dtype=np.float64) w = np.ones(n, dtype=np.float64) - left = x < (alpha / 2.0) - right = x > (1.0 - alpha / 2.0) - w[left] = 0.5 * (1.0 + np.cos(2.0 * np.pi / alpha * (x[left] - alpha / 2.0))) - w[right] = 0.5 * (1.0 + np.cos(2.0 * np.pi / alpha * (x[right] - 1.0 + alpha / 2.0))) + left = x < (eff_alpha / 2.0) + right = x > (1.0 - eff_alpha / 2.0) + w[left] = 0.5 * (1.0 + np.cos(2.0 * np.pi / eff_alpha * (x[left] - eff_alpha / 2.0))) + w[right] = 0.5 * (1.0 + np.cos(2.0 * np.pi / eff_alpha * (x[right] - 1.0 + eff_alpha / 2.0))) return w -def _apodize_nd(arr: np.ndarray, alpha: float = 0.15) -> np.ndarray: - centered = np.asarray(arr, dtype=np.float64) - float(np.mean(arr)) - win = np.ones_like(centered, dtype=np.float64) - for ax, length in enumerate(centered.shape): - w1d = _tukey_window_1d(length, alpha=alpha) - shape = [1] * centered.ndim - shape[ax] = length - win = win * w1d.reshape(shape) - return centered * win +def _prepare_windowed_zero_dc( + arr: np.ndarray, + apodize: bool = True, + alpha: float = 0.15, + mask: np.ndarray | None = None, +) -> np.ndarray: + """Subtract exact window-weighted mean so ``F(0) == 0`` identically without FOV step-edge leakage.""" + data = np.asarray(arr, dtype=np.float64) + win = np.ones(data.shape, dtype=np.float64) + if apodize: + for ax, length in enumerate(data.shape): + w1d = _tukey_window_1d(length, alpha=alpha) + shape = [1] * data.ndim + shape[ax] = length + win = win * w1d.reshape(shape) + + if mask is not None: + m_bool = np.asarray(mask, dtype=bool) + if m_bool.shape != data.shape: + raise ValueError(f"Mask shape {m_bool.shape} does not match array shape {data.shape}.") + if bool(m_bool.any()) and not bool(m_bool.all()): + dt = distance_transform_edt(m_bool) + taper_width = max(2.0, 0.04 * float(min(data.shape))) + smooth_mask = 0.5 * (1.0 - np.cos(np.pi * np.clip(dt / taper_width, 0.0, 1.0))) + win = win * smooth_mask + elif not bool(m_bool.any()): + return np.zeros_like(data, dtype=np.float64) + + w_sum = float(np.sum(win)) + if w_sum <= 1e-12: + return np.zeros_like(data, dtype=np.float64) + mu_w = float(np.sum(data * win) / w_sum) + return (data - mu_w) * win def _half_bit_threshold(shell_counts: np.ndarray) -> np.ndarray: """van Heel & Schatz (2005) 1/2-bit information threshold per Fourier ring/shell.""" - n_eff = np.maximum(shell_counts.astype(np.float64), 1.0) + n_eff = np.maximum(shell_counts.astype(np.float64), 2.0) sqrt_n = np.sqrt(n_eff) return (0.2071 + 1.9102 / sqrt_n) / (1.2071 + 0.9102 / sqrt_n) @@ -57,7 +84,7 @@ def _find_crossing_frequency( return 0.5 idx = int(below[0]) if idx == 0: - return float(freqs[0]) + return 0.0 # Linear interpolation between (idx - 1) and idx y0 = float(corr[idx - 1] - thr_arr[idx - 1]) y1 = float(corr[idx] - thr_arr[idx]) @@ -71,6 +98,7 @@ def _compute_fourier_correlation_nd( target: np.ndarray, voxel_size_um: float = 1.0, apodize: bool = True, + mask: np.ndarray | None = None, eps: float = 1e-12, ) -> dict[str, Any]: p = np.asarray(pred, dtype=np.float64) @@ -80,46 +108,70 @@ def _compute_fourier_correlation_nd( if min(p.shape) < 4: raise ValueError(f"All spatial dimensions must be >= 4, got {p.shape}.") - w_p = _apodize_nd(p) if apodize else (p - float(np.mean(p))) - w_t = _apodize_nd(t) if apodize else (t - float(np.mean(t))) + w_p = _prepare_windowed_zero_dc(p, apodize=apodize, mask=mask) + w_t = _prepare_windowed_zero_dc(t, apodize=apodize, mask=mask) - f_p = np.fft.fftn(w_p) - f_t = np.fft.fftn(w_t) + # Real half-spectrum FFT avoids redundant conjugate storage while accounting for exact multiplicity + f_p = np.fft.rfftn(w_p) + f_t = np.fft.rfftn(w_t) - freq_grids = [np.fft.fftfreq(n) for n in p.shape] - mesh = np.meshgrid(*freq_grids, indexing="ij") - k_mag = np.sqrt(sum(g * g for g in mesh)) # cycles / voxel in [0, sqrt(ndim)*0.5] + lead_freqs = [np.fft.fftfreq(n) for n in p.shape[:-1]] + last_n = p.shape[-1] + last_freq = np.fft.rfftfreq(last_n) + mesh = np.meshgrid(*lead_freqs, last_freq, indexing="ij") + k_mag = np.sqrt(sum(g * g for g in mesh)) + + # Multiplicity of rfftn entries in the full Hermitian-symmetric DFT: + # kx == 0 (and kx == 0.5 when last_n is even) appear once; interior kx > 0 appear twice. + mult = np.full(f_p.shape, 2.0, dtype=np.float64) + mult[..., 0] = 1.0 + if last_n % 2 == 0 and f_p.shape[-1] > 1: + mult[..., -1] = 1.0 n_shells = max(2, min(p.shape) // 2) edges = np.linspace(0.0, 0.5, n_shells + 1, dtype=np.float64) centers = 0.5 * (edges[:-1] + edges[1:]) - shell_idx = np.digitize(k_mag.ravel(), edges) - 1 - valid_mask = (shell_idx >= 0) & (shell_idx < n_shells) + + # Exclude k == 0 (DC origin) and bin (edges[i], edges[i + 1]] with right=True so fundamental + # modes k = 1/N always populate shell 0 (never leaving a single-voxel DC shell!). + k_flat = k_mag.ravel() + shell_idx = np.digitize(k_flat, edges, right=True) - 1 + valid_mask = (k_flat > 0.0) & (shell_idx >= 0) & (shell_idx < n_shells) bins = shell_idx[valid_mask] + m_valid = mult.ravel()[valid_mask] - cross_real = (f_p * np.conj(f_t)).real.ravel()[valid_mask] - pow_p = (np.abs(f_p) ** 2).ravel()[valid_mask] - pow_t = (np.abs(f_t) ** 2).ravel()[valid_mask] + cross_real = ((f_p * np.conj(f_t)).real.ravel()[valid_mask]) * m_valid + pow_p = ((np.abs(f_p) ** 2).ravel()[valid_mask]) * m_valid + pow_t = ((np.abs(f_t) ** 2).ravel()[valid_mask]) * m_valid num = np.bincount(bins, weights=cross_real, minlength=n_shells) den_p = np.bincount(bins, weights=pow_p, minlength=n_shells) den_t = np.bincount(bins, weights=pow_t, minlength=n_shells) - counts = np.bincount(bins, minlength=n_shells) + counts = np.rint(np.bincount(bins, weights=m_valid, minlength=n_shells)).astype(np.int64) denom = np.sqrt(den_p * den_t) corr = np.where(denom > eps, num / np.maximum(denom, eps), 0.0) corr = np.clip(corr, -1.0, 1.0) + # Reference-normalized effective modulation transfer Re / <|T|^2> captures amplitude roll-off + # even under noiseless zero-phase Gaussian smoothing (where shell-normalized FSC cancels H(k) > 0). + mtf_eff = np.where(den_t > eps, num / np.maximum(den_t, eps), 0.0) + mtf_eff = np.clip(mtf_eff, -1.0, 2.0) half_bit = _half_bit_threshold(counts) k_half_bit = _find_crossing_frequency(centers, corr, half_bit) k_0143 = _find_crossing_frequency(centers, corr, 0.143) k_050 = _find_crossing_frequency(centers, corr, 0.5) + k_mtf_050 = _find_crossing_frequency(centers, mtf_eff, 0.5) vox = float(voxel_size_um) - res_half_bit_um = vox / (2.0 * max(k_half_bit, 1e-6)) - res_0143_um = vox / (2.0 * max(k_0143, 1e-6)) + max_domain_um = vox * float(max(p.shape)) + res_half_bit_um = (vox / (2.0 * k_half_bit)) if k_half_bit > 1e-6 else max_domain_um + res_0143_um = (vox / (2.0 * k_0143)) if k_0143 > 1e-6 else max_domain_um + res_050_um = (vox / (2.0 * k_050)) if k_050 > 1e-6 else max_domain_um + res_mtf_050_um = (vox / (2.0 * k_mtf_050)) if k_mtf_050 > 1e-6 else max_domain_um pos_corr = np.clip(corr, 0.0, 1.0) + pos_mtf = np.clip(mtf_eff, 0.0, 1.0) dx = np.diff(centers) auc = ( float( @@ -128,19 +180,31 @@ def _compute_fourier_correlation_nd( if centers.size >= 2 else float(pos_corr.mean()) ) + mtf_auc = ( + float(np.sum(0.5 * (pos_mtf[:-1] + pos_mtf[1:]) * dx) / max(centers[-1] - centers[0], 1e-8)) + if centers.size >= 2 + else float(pos_mtf.mean()) + ) return { "frequencies_cyc_per_voxel": centers.astype(np.float32), "correlation": corr.astype(np.float32), + "effective_mtf": mtf_eff.astype(np.float32), "half_bit_threshold": half_bit.astype(np.float32), - "shell_counts": counts.astype(np.int64), + "shell_counts": counts, "cutoff_freq_half_bit": k_half_bit, "cutoff_freq_0143": k_0143, "cutoff_freq_050": k_050, + "cutoff_freq_mtf_050": k_mtf_050, + "nyquist_fraction_050": float(np.clip(k_050 / 0.5, 0.0, 1.0)), + "nyquist_fraction_mtf_050": float(np.clip(k_mtf_050 / 0.5, 0.0, 1.0)), "nyquist_fraction_half_bit": float(np.clip(k_half_bit / 0.5, 0.0, 1.0)), + "spatial_half_pitch_050_um": float(res_050_um), + "spatial_half_pitch_mtf_050_um": float(res_mtf_050_um), "effective_resolution_half_bit_um": float(res_half_bit_um), "effective_resolution_0143_um": float(res_0143_um), "spectral_auc": float(np.clip(auc, 0.0, 1.0)), + "mtf_auc": float(np.clip(mtf_auc, 0.0, 1.0)), } @@ -149,13 +213,16 @@ def compute_frc_2d( true_slice: np.ndarray, voxel_size_um: float = 1.0, apodize: bool = True, + mask: np.ndarray | None = None, ) -> dict[str, Any]: - """Compute 2D Fourier Ring Correlation (FRC) and effective half-pitch resolution.""" + """Compute 2D Fourier Ring Correlation (FRC) against a reference slice.""" p = np.asarray(pred_slice, dtype=np.float64) t = np.asarray(true_slice, dtype=np.float64) if p.ndim != 2 or t.ndim != 2: raise ValueError(f"compute_frc_2d expects 2D arrays, got {p.shape} and {t.shape}.") - return _compute_fourier_correlation_nd(p, t, voxel_size_um=voxel_size_um, apodize=apodize) + return _compute_fourier_correlation_nd( + p, t, voxel_size_um=voxel_size_um, apodize=apodize, mask=mask + ) def compute_fsc_3d( @@ -163,29 +230,56 @@ def compute_fsc_3d( true_vol: np.ndarray, voxel_size_um: float = 1.0, apodize: bool = True, + mask: np.ndarray | None = None, ) -> dict[str, Any]: - """Compute 3D Fourier Shell Correlation (FSC) and effective synchrotron resolution cutoff.""" + """Compute 3D Fourier Shell Correlation (FSC) against a reference volume.""" p = np.asarray(pred_vol, dtype=np.float64) t = np.asarray(true_vol, dtype=np.float64) if p.ndim != 3 or t.ndim != 3: raise ValueError(f"compute_fsc_3d expects 3D volumes, got {p.shape} and {t.shape}.") - return _compute_fourier_correlation_nd(p, t, voxel_size_um=voxel_size_um, apodize=apodize) + return _compute_fourier_correlation_nd( + p, t, voxel_size_um=voxel_size_um, apodize=apodize, mask=mask + ) def evaluate_spectral_metrics( pred_vol: np.ndarray, true_vol: np.ndarray, voxel_size_um: float = 1.0, + mask: np.ndarray | None = None, ) -> dict[str, float]: - """Return JSON-serializable scalar summary of 3D FSC (or 2D FRC) resolution metrology.""" - arr = np.asarray(pred_vol) + """Return JSON-serializable scalar summary of 3D FSC/MTF (or 2D FRC/MTF) agreement with ground truth. + + Reports both ``fsc_cutoff_050_cyc_vox`` / ``fsc_half_pitch_050_um`` (phase/SNR=1 shell + correlation ``FSC = 0.5``; Rosenthal & Henderson, *J. Mol. Biol.* 2003) and + ``mtf_cutoff_050_cyc_vox`` / ``mtf_half_pitch_050_um`` (reference-normalized amplitude + modulation transfer ``MTF_eff = 0.5``, sensitive even to noiseless zero-phase Gaussian blur) + alongside legacy ``1/2-bit`` / ``0.143`` shell thresholds. + """ + p = np.asarray(pred_vol) + t = np.asarray(true_vol) + m = np.asarray(mask) if mask is not None else None + if p.ndim == 3 and t.ndim == 3 and 1 in p.shape and p.shape == t.shape: + sq_ax = p.shape.index(1) + p = np.squeeze(p, axis=sq_ax) + t = np.squeeze(t, axis=sq_ax) + if m is not None and m.shape == pred_vol.shape: + m = np.squeeze(m, axis=sq_ax) + res = ( - compute_fsc_3d(pred_vol, true_vol, voxel_size_um=voxel_size_um) - if arr.ndim == 3 - else compute_frc_2d(pred_vol, true_vol, voxel_size_um=voxel_size_um) + compute_fsc_3d(p, t, voxel_size_um=voxel_size_um, mask=m) + if p.ndim == 3 + else compute_frc_2d(p, t, voxel_size_um=voxel_size_um, mask=m) ) return { "fsc_auc": float(res["spectral_auc"]), + "mtf_auc": float(res["mtf_auc"]), + "fsc_cutoff_050_cyc_vox": float(res["cutoff_freq_050"]), + "fsc_nyquist_fraction_050": float(res["nyquist_fraction_050"]), + "fsc_half_pitch_050_um": float(res["spatial_half_pitch_050_um"]), + "mtf_cutoff_050_cyc_vox": float(res["cutoff_freq_mtf_050"]), + "mtf_nyquist_fraction_050": float(res["nyquist_fraction_mtf_050"]), + "mtf_half_pitch_050_um": float(res["spatial_half_pitch_mtf_050_um"]), "fsc_cutoff_half_bit_cyc_vox": float(res["cutoff_freq_half_bit"]), "fsc_cutoff_0143_cyc_vox": float(res["cutoff_freq_0143"]), "fsc_nyquist_fraction": float(res["nyquist_fraction_half_bit"]), diff --git a/src/openlsrx/metrics/transport.py b/src/openlsrx/metrics/transport.py index ff16e6a..7c93b34 100644 --- a/src/openlsrx/metrics/transport.py +++ b/src/openlsrx/metrics/transport.py @@ -2,11 +2,13 @@ from __future__ import annotations +from typing import Any + import numpy as np import porespy as ps from scipy import sparse from scipy.ndimage import distance_transform_edt, generate_binary_structure, label -from scipy.sparse.linalg import LinearOperator, cg +from scipy.sparse.linalg import LinearOperator, cg, spsolve from .petrophysics import ThresholdMethod, segment_pore_space @@ -19,15 +21,9 @@ def solve_steady_state_diffusion_axis( ) -> dict[str, float]: """Solve 3D steady-state Fickian Laplace diffusion ``div(grad c) = 0`` along ``axis``. - Uses a cell-centered 6-neighbor finite-volume discretization matching ``OpenImpala`` - and ``TauFactor``: - - Unit voxel spacing ``dx = 1`` and unit intrinsic diffusivity ``D_0 = 1``. - - Dirichlet boundary conditions ``c = 1`` on the outer inlet face (``x_axis = 0``) and - ``c = 0`` on the outer outlet face (``x_axis = L``) with half-cell boundary conductance ``2``. - - Zero-flux Neumann conditions on all solid-pore interfaces and lateral domain boundaries. - - For an analytical straight pore channel of cross-sectional fraction ``phi``, this yields - ``D_eff / D_0 = phi`` and ``tortuosity = 1.0`` to solver tolerance. + Verifies solver convergence (both ``cg`` exit status and inlet/outlet steady-state flux + conservation), falling back to exact sparse LU (when ``n_nodes <= 40_000``) or extended + high-precision CG when ill-conditioned constrictions stall iterative convergence. """ mask = np.asarray(pore_mask, dtype=bool) if mask.ndim != 3: @@ -44,13 +40,13 @@ def solve_steady_state_diffusion_axis( "tortuosity": float("inf"), "formation_factor": float("inf"), "percolates": 0.0, + "solver_converged": 1.0, } ordered = np.moveaxis(mask, axis, 0) # (L, M, N) length, m_dim, n_dim = ordered.shape a_geom = float(m_dim * n_dim) - # Identify 6-connected (face-sharing) pore clusters spanning inlet (0) to outlet (L - 1) conn6 = generate_binary_structure(3, 1) labels, _ = label(ordered, structure=conn6) inlet_labels = set(np.unique(labels[0])) - {0} @@ -65,6 +61,7 @@ def solve_steady_state_diffusion_axis( "tortuosity": float("inf"), "formation_factor": float("inf"), "percolates": 0.0, + "solver_converged": 1.0, } perc_mask = np.isin(labels, list(perc_labels)) @@ -79,9 +76,9 @@ def solve_steady_state_diffusion_axis( "tortuosity": porosity / d_eff, "formation_factor": 1.0 / d_eff, "percolates": 1.0, + "solver_converged": 1.0, } - # Map percolating pore voxels to compact [0, n_nodes) indices active_flat = np.flatnonzero(perc_mask) n_nodes = int(active_flat.size) node_idx = np.full(perc_mask.shape, -1, dtype=np.int64) @@ -91,7 +88,6 @@ def solve_steady_state_diffusion_axis( cols_list: list[np.ndarray] = [] diag = np.zeros(n_nodes, dtype=np.float64) - # Interior 6-neighbor pore-pore faces (conductance = 1.0) for dim in range(3): sl_lo = [slice(None), slice(None), slice(None)] sl_hi = [slice(None), slice(None), slice(None)] @@ -108,7 +104,6 @@ def solve_steady_state_diffusion_axis( np.add.at(diag, u, 1.0) np.add.at(diag, v, 1.0) - # Half-cell Dirichlet faces on inlet (c = 1.0) and outlet (c = 0.0), conductance = 2.0 rhs = np.zeros(n_nodes, dtype=np.float64) inlet_nodes = node_idx[0][perc_mask[0]] outlet_nodes = node_idx[-1][perc_mask[-1]] @@ -136,14 +131,41 @@ def solve_steady_state_diffusion_axis( dtype=np.float64, matvec=lambda x: inv_diag * x, ) - conc, _ = cg(mat, rhs, rtol=tol, atol=0.0, maxiter=maxiter, M=precond) - - q_in = float(np.sum(2.0 * (1.0 - conc[inlet_nodes]))) - q_out = float(np.sum(2.0 * conc[outlet_nodes])) - q_mean = max(0.0, 0.5 * (q_in + q_out)) - - d_eff = (q_mean * float(length)) / a_geom - if d_eff <= 1e-12: + conc, info = cg(mat, rhs, rtol=tol, atol=0.0, maxiter=maxiter, M=precond) + + def _flux_metrics(c_vec: np.ndarray) -> tuple[float, float, float, float]: + qi = float(np.sum(2.0 * (1.0 - c_vec[inlet_nodes]))) + qo = float(np.sum(2.0 * c_vec[outlet_nodes])) + qm = max(0.0, 0.5 * (qi + qo)) + imbalance = abs(qi - qo) / max(qm, 1e-12) + return qi, qo, qm, imbalance + + _, _, q_mean, flux_imbalance = _flux_metrics(conc) + rhs_norm = max(float(np.linalg.norm(rhs)), 1e-12) + rel_res = float(np.linalg.norm(mat @ conc - rhs)) / rhs_norm + converged = (info == 0) and (flux_imbalance <= 0.02) and (rel_res <= max(tol * 50.0, 1e-4)) + + if not converged: + if n_nodes <= 40_000: + conc = np.asarray(spsolve(mat.tocsc(), rhs), dtype=np.float64) + else: + conc, info = cg( + mat, + rhs, + x0=np.clip(conc, 0.0, 1.0), + rtol=min(tol, 1e-8), + atol=0.0, + maxiter=max(maxiter * 5, 20_000), + M=precond, + ) + conc = np.clip(conc, 0.0, 1.0) + _, _, q_mean, flux_imbalance = _flux_metrics(conc) + rel_res = float(np.linalg.norm(mat @ conc - rhs)) / rhs_norm + converged = (flux_imbalance <= 0.05) and (rel_res <= 1e-3) + + # Variational Dirichlet bound: 0 <= D_eff <= percolating_porosity <= porosity, so tau >= 1.0 + d_eff = float(np.clip((q_mean * float(length)) / a_geom, 0.0, perc_porosity)) + if d_eff <= 1e-12 or not np.isfinite(d_eff): return { "porosity": porosity, "percolating_porosity": perc_porosity, @@ -151,15 +173,17 @@ def solve_steady_state_diffusion_axis( "tortuosity": float("inf"), "formation_factor": float("inf"), "percolates": 0.0, + "solver_converged": float(converged), } return { "porosity": porosity, "percolating_porosity": perc_porosity, "d_eff": d_eff, - "tortuosity": porosity / d_eff, + "tortuosity": max(1.0, porosity / d_eff), "formation_factor": 1.0 / d_eff, "percolates": 1.0, + "solver_converged": float(converged), } @@ -168,15 +192,22 @@ def compute_directional_tortuosity( tol: float = 1e-6, maxiter: int = 4000, ) -> dict[str, float]: - """Compute directional effective diffusivity ``D_eff/D_0``, tortuosity ``tau``, and anisotropy across ``z, y, x``.""" + """Compute directional effective diffusivity ``D_eff/D_0``, tortuosity ``tau``, and anisotropy across ``z, y, x``. + + Reports ``tortuosity_mean = porosity / d_eff_mean`` (the macroscopic 3D tensor-trace bulk + tortuosity ``phi / ((D_z + D_y + D_x) / 3)``), which equals directional ``tau`` for isotropic + media and varies monotonically across single-axis percolation transitions without dropping + disconnected ``inf`` axes. + """ res_z = solve_steady_state_diffusion_axis(pore_mask, axis=0, tol=tol, maxiter=maxiter) res_y = solve_steady_state_diffusion_axis(pore_mask, axis=1, tol=tol, maxiter=maxiter) res_x = solve_steady_state_diffusion_axis(pore_mask, axis=2, tol=tol, maxiter=maxiter) d_vals = [res_z["d_eff"], res_y["d_eff"], res_x["d_eff"]] d_mean = float(np.mean(d_vals)) + tau_mean = max(1.0, res_z["porosity"] / d_mean) if d_mean > 1e-12 else float("inf") finite_taus = [r["tortuosity"] for r in (res_z, res_y, res_x) if np.isfinite(r["tortuosity"])] - tau_mean = float(np.mean(finite_taus)) if finite_taus else float("inf") + tau_arith_perc = float(np.mean(finite_taus)) if len(finite_taus) == 3 else float("inf") ff_mean = (1.0 / d_mean) if d_mean > 1e-12 else float("inf") min_d = min(d_vals) @@ -193,10 +224,14 @@ def compute_directional_tortuosity( "tortuosity_y": res_y["tortuosity"], "tortuosity_x": res_x["tortuosity"], "tortuosity_mean": tau_mean, + "tortuosity_3axis_arithmetic": tau_arith_perc, "formation_factor_mean": ff_mean, "percolating_axes_count": res_z["percolates"] + res_y["percolates"] + res_x["percolates"], "d_eff_anisotropy_spread": max_d - min_d, "transport_anisotropy_ratio": aniso_ratio, + "solver_converged": float( + min(res_z["solver_converged"], res_y["solver_converged"], res_x["solver_converged"]) + ), } @@ -207,11 +242,7 @@ def compute_drainage_curve( inlet_axis: int = 0, pc_grid: np.ndarray | None = None, ) -> tuple[np.ndarray, np.ndarray]: - """Simulate inlet-connected capillary drainage (mercury intrusion) on a 3D pore mask. - - Returns ``(pc_values, non_wetting_saturation)`` evaluated on ``pc_grid`` (or a geometric - capillary-pressure schedule spanning ``[2 / r_max, 2 / r_min]``). - """ + """Simulate inlet-connected capillary drainage (mercury intrusion) on a 3D pore mask.""" mask = np.asarray(pore_mask, dtype=bool) if mask.ndim != 3: raise ValueError(f"Expected 3D boolean pore_mask, got shape {mask.shape}.") @@ -244,13 +275,22 @@ def compute_drainage_curve( pc_transform = np.full(mask.shape, np.inf, dtype=np.float32) pc_transform[mask] = 2.0 / np.maximum(dt[mask], 1e-6).astype(np.float32) - drn = ps.simulations.drainage( - im=mask, - pc=pc_transform, - dt=dt.astype(np.float32), - inlets=inlets, - steps=max(4, int(n_steps)), - ) + try: + drn = ps.simulations.drainage( + im=mask, + pc=pc_transform, + dt=dt.astype(np.float32), + inlets=inlets, + steps=grid, + ) + except Exception: + drn = ps.simulations.drainage( + im=mask, + pc=pc_transform, + dt=dt.astype(np.float32), + inlets=inlets, + steps=max(4, int(len(grid))), + ) im_pc = np.asarray(drn.im_pc, dtype=np.float64) pore_pc = im_pc[mask] snwp = np.array([float(np.sum(pore_pc <= p)) / float(n_pores) for p in grid], dtype=np.float64) @@ -263,17 +303,21 @@ def compute_drainage_rmse( n_steps: int = 16, voxel_size: float = 1.0, inlet_axis: int = 0, + precomputed_true_curve: tuple[np.ndarray, np.ndarray] | None = None, ) -> float: """RMSE between simulated capillary drainage saturation curves ``S_nwp(P_c)``.""" - pc_grid, true_snwp = compute_drainage_curve( - true_mask, - n_steps=n_steps, - voxel_size=voxel_size, - inlet_axis=inlet_axis, - ) + if precomputed_true_curve is not None: + pc_grid, true_snwp = precomputed_true_curve + else: + pc_grid, true_snwp = compute_drainage_curve( + true_mask, + n_steps=n_steps, + voxel_size=voxel_size, + inlet_axis=inlet_axis, + ) _, pred_snwp = compute_drainage_curve( pred_mask, - n_steps=n_steps, + n_steps=len(pc_grid), voxel_size=voxel_size, inlet_axis=inlet_axis, pc_grid=pc_grid, @@ -281,6 +325,35 @@ def compute_drainage_rmse( return float(np.sqrt(np.mean((pred_snwp - true_snwp) ** 2))) +def precompute_reference_transport( + true_vol: np.ndarray, + threshold_method: ThresholdMethod = "otsu", + fixed_threshold: float | None = None, + pore_is_low: bool = True, + voxel_size: float = 1.0, + drainage_steps: int = 16, +) -> dict[str, Any]: + """Precompute HR ground-truth threshold, 3D Laplace tortuosity, and drainage curve once per seed.""" + true_mask, thr = segment_pore_space( + true_vol, + method=threshold_method, + fixed_value=fixed_threshold, + pore_is_low=pore_is_low, + ) + true_t = compute_directional_tortuosity(true_mask) + true_curve = compute_drainage_curve( + true_mask, + n_steps=drainage_steps, + voxel_size=voxel_size, + ) + return { + "threshold": float(thr), + "true_mask": true_mask, + "true_tortuosity": true_t, + "true_drainage_curve": true_curve, + } + + def _json_safe(val: float) -> float | None: return float(val) if np.isfinite(val) else None @@ -293,28 +366,31 @@ def evaluate_transport_metrics( pore_is_low: bool = True, voxel_size: float = 1.0, drainage_steps: int = 16, + precomputed_true: dict[str, Any] | None = None, ) -> dict[str, float | None]: - """Evaluate 3D diffusive transport and capillary drainage fidelity between SR and HR XCT volumes. + """Evaluate 3D diffusive transport and capillary drainage fidelity between SR and HR XCT volumes.""" + if precomputed_true is not None: + thr = float(precomputed_true["threshold"]) + true_mask = np.asarray(precomputed_true["true_mask"], dtype=bool) + true_t = dict(precomputed_true["true_tortuosity"]) + true_curve = precomputed_true.get("true_drainage_curve") + else: + true_mask, thr = segment_pore_space( + true_vol, + method=threshold_method, + fixed_value=fixed_threshold, + pore_is_low=pore_is_low, + ) + true_t = compute_directional_tortuosity(true_mask) + true_curve = None - Uses the ground-truth segmentation threshold consistently across ``true_vol`` and ``pred_vol`` - (matching ``evaluate_petrophysical_metrics``) so greyscale bias or blurring is faithfully - reflected in pore-throat connectivity and effective diffusivity. - """ - true_mask, thr = segment_pore_space( - true_vol, - method=threshold_method, - fixed_value=fixed_threshold, - pore_is_low=pore_is_low, - ) pred_mask, _ = segment_pore_space( pred_vol, method="fixed", fixed_value=thr, pore_is_low=pore_is_low, ) - pred_t = compute_directional_tortuosity(pred_mask) - true_t = compute_directional_tortuosity(true_mask) d_eff_mae = float( np.mean( @@ -340,6 +416,7 @@ def evaluate_transport_metrics( true_mask, n_steps=drainage_steps, voxel_size=voxel_size, + precomputed_true_curve=true_curve, ) return { @@ -374,15 +451,9 @@ def compute_tortuosity_uncertainty_bounds( fixed_threshold: float | None = None, pore_is_low: bool = True, k_sigma: float = 1.0, + precomputed_true: dict[str, Any] | None = None, ) -> dict[str, float | None]: - """Propagate voxel-wise orthogonal epistemic uncertainty ``sigma_ortho`` into 3D tortuosity bounds. - - Evaluates 3D Fickian steady-state diffusion across the nominal reconstruction ``V_hat`` and - its ``+/- k_sigma * sigma_ortho`` epistemic intensity envelope, producing calibrated intervals - for effective diffusivity ``D_eff / D_0`` and diffusive tortuosity ``tau``. When ``true_vol`` - is supplied, also reports epistemic calibration (Spearman rank correlation between - ``sigma_ortho(x)`` and voxel error ``|V_hat(x) - V_HR(x)|``). - """ + """Propagate voxel-wise orthogonal epistemic uncertainty ``sigma_ortho`` into 3D tortuosity bounds.""" from scipy.stats import spearmanr pred_arr = np.asarray(pred_vol, dtype=np.float32) @@ -392,16 +463,18 @@ def compute_tortuosity_uncertainty_bounds( f"Expected matching 3D arrays for pred_vol and uncertainty_std, got {pred_arr.shape} and {unc_arr.shape}." ) - ref_for_thr = np.asarray(true_vol, dtype=np.float32) if true_vol is not None else pred_arr - _, thr = segment_pore_space( - ref_for_thr, - method=threshold_method, - fixed_value=fixed_threshold, - pore_is_low=pore_is_low, - ) + if precomputed_true is not None: + thr = float(precomputed_true["threshold"]) + else: + ref_for_thr = np.asarray(true_vol, dtype=np.float32) if true_vol is not None else pred_arr + _, thr = segment_pore_space( + ref_for_thr, + method=threshold_method, + fixed_value=fixed_threshold, + pore_is_low=pore_is_low, + ) delta = float(k_sigma) * np.maximum(unc_arr, 0.0) - # Dilated vs constricted pore envelopes depending on pore_is_low vol_open = np.clip(pred_arr - delta if pore_is_low else pred_arr + delta, 0.0, 1.0) vol_tight = np.clip(pred_arr + delta if pore_is_low else pred_arr - delta, 0.0, 1.0) @@ -419,10 +492,17 @@ def compute_tortuosity_uncertainty_bounds( t_open = compute_directional_tortuosity(mask_open) t_tight = compute_directional_tortuosity(mask_tight) - d_lo = min(t_tight["d_eff_mean"], t_open["d_eff_mean"]) - d_hi = max(t_tight["d_eff_mean"], t_open["d_eff_mean"]) - tau_lo = min(t_open["tortuosity_mean"], t_tight["tortuosity_mean"]) - tau_hi = max(t_open["tortuosity_mean"], t_tight["tortuosity_mean"]) + d_candidates = [t_tight["d_eff_mean"], t_nom["d_eff_mean"], t_open["d_eff_mean"]] + d_lo = float(min(d_candidates)) + d_hi = float(max(d_candidates)) + + tau_candidates = [ + t_open["tortuosity_mean"], + t_nom["tortuosity_mean"], + t_tight["tortuosity_mean"], + ] + tau_lo = float(min(tau_candidates)) + tau_hi = float(max(tau_candidates)) tau_hw = ( 0.5 * (tau_hi - tau_lo) if (np.isfinite(tau_lo) and np.isfinite(tau_hi)) else float("inf") ) @@ -443,11 +523,14 @@ def compute_tortuosity_uncertainty_bounds( if true_vol is not None: true_arr = np.asarray(true_vol, dtype=np.float32) - true_mask, _ = segment_pore_space( - true_arr, method="fixed", fixed_value=thr, pore_is_low=pore_is_low - ) - t_true = compute_directional_tortuosity(true_mask) - d_true = t_true["d_eff_mean"] + if precomputed_true is not None: + t_true = dict(precomputed_true["true_tortuosity"]) + else: + true_mask, _ = segment_pore_space( + true_arr, method="fixed", fixed_value=thr, pore_is_low=pore_is_low + ) + t_true = compute_directional_tortuosity(true_mask) + d_true = float(t_true["d_eff_mean"]) result["true_d_eff_mean"] = _json_safe(d_true) result["d_eff_bracketed_by_envelope"] = float(d_lo - 1e-8 <= d_true <= d_hi + 1e-8) diff --git a/src/openlsrx/models/__init__.py b/src/openlsrx/models/__init__.py index 6ea9bbd..33d3781 100644 --- a/src/openlsrx/models/__init__.py +++ b/src/openlsrx/models/__init__.py @@ -11,7 +11,7 @@ super_resolve_volume_3d, ) from .srgan import SRGAN, BackboneType, GANLossType -from .submodels import Discriminator, Generator, OutputActivation +from .submodels import Discriminator, Generator, OutputActivation, apply_bounded_output from .swinir import ( ResidualSwinBlock, SwinIRGenerator, @@ -42,6 +42,7 @@ "SwinTransformerLayer", "UpsampleBlock", "WindowAttention2D", + "apply_bounded_output", "build_3d_subcube_dataloaders", "super_resolve_volume_3d", ] diff --git a/src/openlsrx/models/blocks.py b/src/openlsrx/models/blocks.py index 07a2f83..7980346 100644 --- a/src/openlsrx/models/blocks.py +++ b/src/openlsrx/models/blocks.py @@ -4,6 +4,7 @@ from typing import Literal +import torch.nn.functional as F from torch import Tensor, nn from ..losses import PixelNorm @@ -25,6 +26,24 @@ def _build_norm(norm_type: NormType, channels: int, enabled: bool) -> nn.Module: ) +def _safe_conv2d(conv: nn.Conv2d, x: Tensor) -> Tensor: + """Execute ``conv(x)`` falling back from ``reflect`` to ``replicate`` on tiny spatial inputs.""" + if conv.padding_mode == "reflect" and isinstance(conv.padding, tuple): + ph, pw = int(conv.padding[0]), int(conv.padding[1]) + if (ph > 0 or pw > 0) and (x.shape[-2] <= ph or x.shape[-1] <= pw): + padded = F.pad(x, (pw, pw, ph, ph), mode="replicate") + return F.conv2d( + padded, + conv.weight, + conv.bias, + stride=conv.stride, + padding=0, + dilation=conv.dilation, + groups=conv.groups, + ) + return conv(x) + + class ConvBlock(nn.Module): """2D convolution followed by optional normalization and PReLU/LeakyReLU activation.""" @@ -54,7 +73,7 @@ def __init__( ) def forward(self, x: Tensor) -> Tensor: - out = self.bn(self.conv(x)) + out = self.bn(_safe_conv2d(self.conv, x)) return self.act(out) if self.use_act else out @@ -77,7 +96,7 @@ def __init__(self, in_channels: int, scale_factor: int = 2) -> None: self.act = nn.PReLU(num_parameters=in_channels) def forward(self, x: Tensor) -> Tensor: - return self.act(self.pixel_shuffle(self.conv(x))) + return self.act(self.pixel_shuffle(_safe_conv2d(self.conv, x))) class ResidualBlock(nn.Module): diff --git a/src/openlsrx/models/rrdb.py b/src/openlsrx/models/rrdb.py index 63f67d9..749b53f 100644 --- a/src/openlsrx/models/rrdb.py +++ b/src/openlsrx/models/rrdb.py @@ -8,17 +8,12 @@ import torch.nn.functional as F from torch import Tensor, nn -from ..losses import custom_sigmoid -from .blocks import UpsampleBlock -from .submodels import OutputActivation +from .blocks import UpsampleBlock, _safe_conv2d +from .submodels import OutputActivation, apply_bounded_output class DenseResidualBlock(nn.Module): - """5-layer densely connected convolutional block without batch/pixel normalization. - - Omitting feature normalization preserves absolute X-ray attenuation contrasts across - batches (Wang et al., ESRGAN, ECCV Workshops 2018). - """ + """5-layer densely connected convolutional block without batch/pixel normalization.""" def __init__( self, @@ -45,11 +40,11 @@ def __init__( ) def forward(self, x: Tensor) -> Tensor: - x1 = self.act(self.conv1(x)) - x2 = self.act(self.conv2(torch.cat([x, x1], dim=1))) - x3 = self.act(self.conv3(torch.cat([x, x1, x2], dim=1))) - x4 = self.act(self.conv4(torch.cat([x, x1, x2, x3], dim=1))) - x5 = self.conv5(torch.cat([x, x1, x2, x3, x4], dim=1)) + x1 = self.act(_safe_conv2d(self.conv1, x)) + x2 = self.act(_safe_conv2d(self.conv2, torch.cat([x, x1], dim=1))) + x3 = self.act(_safe_conv2d(self.conv3, torch.cat([x, x1, x2], dim=1))) + x4 = self.act(_safe_conv2d(self.conv4, torch.cat([x, x1, x2, x3], dim=1))) + x5 = _safe_conv2d(self.conv5, torch.cat([x, x1, x2, x3, x4], dim=1)) return x + self.res_scale * x5 @@ -74,13 +69,7 @@ def forward(self, x: Tensor) -> Tensor: class ArbitraryScaleUpsample(nn.Module): - """Hybrid sub-pixel + resize-convolution upsampler supporting any scale >= 1.0. - - - Exact powers of two (``1, 2, 4, 8``) use learned ``UpsampleBlock`` (``PixelShuffle``) stages. - - Non-power-of-two beamline ratios (e.g., ``2.5`` for I13-2 ``0.8125 -> 0.325 um`` or ``5.0`` - for ``1.625 -> 0.325 um``) combine ``floor(log2(s))`` sub-pixel stages with an exact - bicubic resize-convolution refinement stage. - """ + """Hybrid sub-pixel + resize-convolution upsampler supporting any scale >= 1.0.""" def __init__(self, channels: int = 64, scale_factor: float | int = 2) -> None: super().__init__() @@ -97,22 +86,22 @@ def __init__(self, channels: int = 64, scale_factor: float | int = 2) -> None: *[UpsampleBlock(in_channels=channels, scale_factor=2) for _ in range(n_pow2)] ) self.has_residual = not math.isclose(self.residual_scale, 1.0, rel_tol=1e-5, abs_tol=1e-5) - self.refine_conv: nn.Module | None = ( - nn.Sequential( - nn.Conv2d(channels, channels, 3, 1, 1, padding_mode="reflect"), - nn.LeakyReLU(0.2, inplace=True), - ) + self.refine_conv: nn.Conv2d | None = ( + nn.Conv2d(channels, channels, 3, 1, 1, padding_mode="reflect") if self.has_residual else None ) + self.refine_act: nn.Module | None = ( + nn.LeakyReLU(0.2, inplace=True) if self.has_residual else None + ) def forward(self, x: Tensor) -> Tensor: - target_h = int(round(x.shape[-2] * self.scale_factor)) - target_w = int(round(x.shape[-1] * self.scale_factor)) + target_h = max(1, int(round(x.shape[-2] * self.scale_factor))) + target_w = max(1, int(round(x.shape[-1] * self.scale_factor))) out = self.pow2_blocks(x) - if self.has_residual and self.refine_conv is not None: + if self.has_residual and self.refine_conv is not None and self.refine_act is not None: out = F.interpolate(out, size=(target_h, target_w), mode="bicubic", align_corners=False) - out = self.refine_conv(out) + out = self.refine_act(_safe_conv2d(self.refine_conv, out)) return out @@ -161,41 +150,35 @@ def __init__( self.upsample = ArbitraryScaleUpsample( channels=self.out_channels, scale_factor=self.super_res_factor ) - final_conv = nn.Conv2d( - self.out_channels, self.out_img_channels, 3, 1, 1, padding_mode="reflect" + self.hr_conv1 = nn.Conv2d( + self.out_channels, self.out_channels, 3, 1, 1, padding_mode="reflect" ) - if final_conv.bias is not None: - nn.init.zeros_(final_conv.bias) - final_conv.weight.data.mul_(0.1) - self.hr_head = nn.Sequential( - nn.Conv2d(self.out_channels, self.out_channels, 3, 1, 1, padding_mode="reflect"), - nn.LeakyReLU(0.2, inplace=True), - final_conv, + self.hr_act = nn.LeakyReLU(0.2, inplace=True) + self.hr_conv2 = nn.Conv2d( + self.out_channels, self.out_img_channels, 3, 1, 1, padding_mode="reflect" ) - - def _apply_output_activation(self, x: Tensor) -> Tensor: - if self.output_activation == "custom_sigmoid": - return custom_sigmoid(x, k=self.sigmoid_k) - if self.output_activation == "sigmoid": - return torch.sigmoid(x) - if self.output_activation == "clamp": - return torch.clamp(x, 0.0, 1.0) - return x + if self.hr_conv2.bias is not None: + nn.init.zeros_(self.hr_conv2.bias) + self.hr_conv2.weight.data.mul_(0.1) def forward(self, x: Tensor) -> Tensor: - target_h = int(round(x.shape[-2] * self.super_res_factor)) - target_w = int(round(x.shape[-1] * self.super_res_factor)) + target_h = max(1, int(round(x.shape[-2] * self.super_res_factor))) + target_w = max(1, int(round(x.shape[-1] * self.super_res_factor))) if x.shape[1] == self.out_img_channels: center = x else: c_mid = x.shape[1] // 2 center = x[:, c_mid : c_mid + self.out_img_channels, :, :] base = F.interpolate(center, size=(target_h, target_w), mode="bicubic", align_corners=False) - feat = self.conv_first(x) - trunk = self.trunk_conv(self.trunk(feat)) + feat = _safe_conv2d(self.conv_first, x) + trunk = _safe_conv2d(self.trunk_conv, self.trunk(feat)) feat = feat + trunk up = self.upsample(feat) - residual = self.hr_head(up) - if self.output_activation in ("clamp", "identity"): - return self._apply_output_activation(base + residual) - return self._apply_output_activation(residual) + residual = _safe_conv2d(self.hr_conv2, self.hr_act(_safe_conv2d(self.hr_conv1, up))) + return apply_bounded_output( + residual, + activation=self.output_activation, + sigmoid_k=self.sigmoid_k, + training=self.training, + base=base, + ) diff --git a/src/openlsrx/models/sr3d.py b/src/openlsrx/models/sr3d.py index da87da9..259d242 100644 --- a/src/openlsrx/models/sr3d.py +++ b/src/openlsrx/models/sr3d.py @@ -19,20 +19,53 @@ from ..metrics import compute_mae, compute_psnr, compute_rmse, compute_ssim_3d_isotropic +def _safe_conv3d(conv: nn.Conv3d, x: Tensor) -> Tensor: + """Apply ``conv`` falling back from ``reflect`` to ``replicate`` when ``min(D, H, W) <= pad``.""" + if conv.padding_mode == "reflect" and isinstance(conv.padding, tuple): + pd, ph, pw = int(conv.padding[0]), int(conv.padding[1]), int(conv.padding[2]) + if (pd > 0 or ph > 0 or pw > 0) and ( + x.shape[2] <= pd or x.shape[3] <= ph or x.shape[4] <= pw + ): + x_pad = F.pad(x, (pw, pw, ph, ph, pd, pd), mode="replicate") + return F.conv3d( + x_pad, + conv.weight, + conv.bias, + stride=conv.stride, + padding=0, + dilation=conv.dilation, + groups=conv.groups, + ) + return conv(x) + + +class _SafeReflectConv3d(nn.Module): + """Thin-slab-safe 3D convolution wrapper preserving exact ``Conv3d`` parameter layout.""" + + def __init__(self, in_ch: int, out_ch: int, kernel_size: int = 3, padding: int = 1) -> None: + super().__init__() + self.conv = nn.Conv3d( + in_ch, out_ch, kernel_size=kernel_size, padding=padding, padding_mode="reflect" + ) + + def forward(self, x: Tensor) -> Tensor: + return _safe_conv3d(self.conv, x) + + class ResidualBlock3D(nn.Module): """3D reflect-padded residual block without batch normalization.""" def __init__(self, channels: int = 32, res_scale: float = 0.2) -> None: super().__init__() self.res_scale = float(res_scale) - self.block = nn.Sequential( - nn.Conv3d(channels, channels, kernel_size=3, padding=1, padding_mode="reflect"), - nn.LeakyReLU(0.2, inplace=True), - nn.Conv3d(channels, channels, kernel_size=3, padding=1, padding_mode="reflect"), - ) + self.conv1 = nn.Conv3d(channels, channels, kernel_size=3, padding=1, padding_mode="reflect") + self.act = nn.LeakyReLU(0.2, inplace=True) + self.conv2 = nn.Conv3d(channels, channels, kernel_size=3, padding=1, padding_mode="reflect") def forward(self, x: Tensor) -> Tensor: - return x + self.res_scale * self.block(x) + h = self.act(_safe_conv3d(self.conv1, x)) + h = _safe_conv3d(self.conv2, h) + return x + self.res_scale * h class Generator3D(nn.Module): @@ -71,12 +104,8 @@ def __init__( up_layers.extend( [ nn.Upsample(scale_factor=2, mode="trilinear", align_corners=False), - nn.Conv3d( - self.out_channels, - self.out_channels, - kernel_size=3, - padding=1, - padding_mode="reflect", + _SafeReflectConv3d( + self.out_channels, self.out_channels, kernel_size=3, padding=1 ), nn.LeakyReLU(0.2, inplace=True), ] @@ -95,14 +124,15 @@ def forward(self, x: Tensor) -> Tensor: mode="trilinear", align_corners=False, ) - feat = self.conv_first(x) - feat = feat + self.trunk_conv(self.trunk(feat)) - out = base + self.conv_last(self.upsample(feat)) - return torch.clamp(out, 0.0, 1.0) + feat = _safe_conv3d(self.conv_first, x) + feat = feat + _safe_conv3d(self.trunk_conv, self.trunk(feat)) + out = base + _safe_conv3d(self.conv_last, self.upsample(feat)) + clamped = torch.clamp(out, 0.0, 1.0) + return out + (clamped - out).detach() if self.training else clamped class PairedSubCubeDataset(Dataset[tuple[Tensor, Tensor]]): - """Random/grid 3D sub-cube sampler for training ``SR3DResNet`` on paired 3D slabs.""" + """Random/grid 3D sub-cube sampler with full 3D octahedral ($O_h$) symmetry augmentation.""" def __init__( self, @@ -112,6 +142,7 @@ def __init__( patch_size_lr: int = 16, samples_per_epoch: int = 32, deterministic: bool = False, + augment: bool = True, seed: int = 42, ) -> None: self.lr_vol = np.asarray(lr_vol, dtype=np.float32) @@ -120,6 +151,7 @@ def __init__( self.patch_size_lr = tuple(min(int(patch_size_lr), s) for s in self.lr_vol.shape) self.samples_per_epoch = int(samples_per_epoch) self.deterministic = bool(deterministic) + self.augment = bool(augment) and not self.deterministic self.rng = np.random.default_rng(seed) def __len__(self) -> int: @@ -145,9 +177,26 @@ def __getitem__(self, idx: int) -> tuple[Tensor, Tensor]: y0 * s : (y0 + ph) * s, x0 * s : (x0 + pw) * s, ] + + if self.augment: + # 1) Independent 3D reflections along (Z, Y, X) + for ax in range(3): + if bool(self.rng.integers(0, 2)): + lr_patch = np.flip(lr_patch, axis=ax) + hr_patch = np.flip(hr_patch, axis=ax) + # 2) Shape-preserving 3D axis permutations (full 48-element O_h group on cubic patches) + if pd == ph == pw: + perm = tuple(int(a) for a in self.rng.permutation(3)) + if perm != (0, 1, 2): + lr_patch = np.transpose(lr_patch, axes=perm) + hr_patch = np.transpose(hr_patch, axes=perm) + elif ph == pw and bool(self.rng.integers(0, 2)): + lr_patch = np.swapaxes(lr_patch, 1, 2) + hr_patch = np.swapaxes(hr_patch, 1, 2) + return ( - torch.from_numpy(lr_patch.copy()).unsqueeze(0), - torch.from_numpy(hr_patch.copy()).unsqueeze(0), + torch.from_numpy(np.ascontiguousarray(lr_patch, dtype=np.float32)).unsqueeze(0), + torch.from_numpy(np.ascontiguousarray(hr_patch, dtype=np.float32)).unsqueeze(0), ) @@ -161,6 +210,7 @@ def build_3d_subcube_dataloaders( train_samples: int = 32, val_samples: int = 8, batch_size: int = 2, + augment: bool = True, seed: int = 42, ) -> tuple[DataLoader[tuple[Tensor, Tensor]], DataLoader[tuple[Tensor, Tensor]]]: """Build train and validation 3D sub-cube DataLoaders from disjoint 3D slabs.""" @@ -171,6 +221,7 @@ def build_3d_subcube_dataloaders( patch_size_lr=patch_size_lr, samples_per_epoch=train_samples, deterministic=False, + augment=augment, seed=seed, ) va_ds = PairedSubCubeDataset( @@ -180,6 +231,7 @@ def build_3d_subcube_dataloaders( patch_size_lr=patch_size_lr, samples_per_epoch=val_samples, deterministic=True, + augment=False, seed=seed, ) return ( @@ -198,6 +250,7 @@ def __init__( out_channels: int = 24, num_blocks: int = 4, loss_type: Literal["l1", "mse"] = "l1", + pore_is_low: bool = True, conservation_loss_weight: float = 0.0, topology_loss_weight: float = 0.0, gradient_loss_weight: float = 0.0, @@ -207,6 +260,7 @@ def __init__( self.save_hyperparameters() self.learning_rate = float(learning_rate) self.super_res_factor = int(super_res_factor) + self.pore_is_low = bool(pore_is_low) self.conservation_loss_weight = float(conservation_loss_weight) self.topology_loss_weight = float(topology_loss_weight) self.gradient_loss_weight = float(gradient_loss_weight) @@ -226,7 +280,7 @@ def __init__( ) self.conservation_criterion = AttenuationConservationLoss() - self.topology_criterion = SoftCLDiceLoss() + self.topology_criterion = SoftCLDiceLoss(pore_is_low=self.pore_is_low) self.gradient_criterion = SobelGradientLoss() self.ffl_criterion = FocalFrequencyLoss() @@ -261,12 +315,15 @@ def validation_step(self, batch: tuple[Tensor, Tensor], batch_idx: int) -> None: pred = self.gen(lr_cube).to(torch.float32) target = hr_cube.to(torch.float32) bs = int(lr_cube.shape[0]) + ssim_mean = float( + np.mean([compute_ssim_3d_isotropic(pred[i, 0], target[i, 0]) for i in range(bs)]) + ) self.log( "val/psnr", compute_psnr(pred, target), prog_bar=True, on_epoch=True, batch_size=bs ) self.log( "val/ssim_3d", - compute_ssim_3d_isotropic(pred[0, 0], target[0, 0]), + ssim_mean, on_epoch=True, batch_size=bs, ) diff --git a/src/openlsrx/models/srgan.py b/src/openlsrx/models/srgan.py index 9a82c82..d3ac6dc 100644 --- a/src/openlsrx/models/srgan.py +++ b/src/openlsrx/models/srgan.py @@ -2,16 +2,24 @@ from __future__ import annotations +import math import re +import warnings from collections.abc import Sequence from pathlib import Path -from typing import Any, Literal +from typing import Any, Literal, cast +import numpy as np import pytorch_lightning as pl import tifffile import torch from torch import Tensor, nn, optim +from ..inference.orthogonal import ( + AXIS_TO_DIM, + FusionMode, + super_resolve_volume_orthogonal, +) from ..losses import ( AttenuationConservationLoss, FocalFrequencyLoss, @@ -56,7 +64,7 @@ class SRGAN(pl.LightningModule): def __init__( self, learning_rate: float = 1e-4, - adaptive_size: int = 40, + adaptive_size: int = 8, accumulate_n_batches: int = 1, super_res_factor: int | float = 2, num_blocks: int = 10, @@ -78,6 +86,7 @@ def __init__( vgg_loss_weight: float = 0.006, vgg_layers: int = 18, vgg_pretrained: bool = True, + pore_is_low: bool = True, conservation_loss_weight: float = 0.0, conservation_psf_sigma: float = 0.0, topology_loss_weight: float = 0.0, @@ -142,11 +151,13 @@ def __init__( self.vgg_loss_weight = float(vgg_loss_weight) self.vgg_layers = int(vgg_layers) self.vgg_pretrained = bool(vgg_pretrained) + self.pore_is_low = bool(pore_is_low) self.conservation_loss_weight = float(conservation_loss_weight) self.conservation_psf_sigma = float(conservation_psf_sigma) self.topology_loss_weight = float(topology_loss_weight) self.gradient_loss_weight = float(gradient_loss_weight) self.ffl_loss_weight = float(ffl_loss_weight) + self.disc_features = list(disc_features) if disc_features is not None else None self.lr_scheduler_type = lr_scheduler_type self.lr_scheduler_args = dict( lr_scheduler_args or {"T_0": 50, "T_mult": 1, "eta_min": 1e-6} @@ -195,11 +206,17 @@ def __init__( output_activation=self.output_activation, out_img_channels=1, ) - self.disc = Discriminator( - in_channels=1, - features=disc_features, - adaptive_size=self.adaptive_size, - norm_type=self.norm_type, + + # Allocate Discriminator ONLY when adversarial training is enabled (avoids multi-GB unused FC weights/Adam states) + self.disc: Discriminator | None = ( + Discriminator( + in_channels=1, + features=self.disc_features, + adaptive_size=self.adaptive_size, + norm_type=self.norm_type, + ) + if self.use_adversarial_loss + else None ) self.bce = nn.BCEWithLogitsLoss() @@ -214,7 +231,7 @@ def __init__( self.conservation_criterion = AttenuationConservationLoss( psf_sigma=self.conservation_psf_sigma ) - self.topology_criterion = SoftCLDiceLoss() + self.topology_criterion = SoftCLDiceLoss(pore_is_low=self.pore_is_low) self.gradient_criterion = SobelGradientLoss() self.ffl_criterion = FocalFrequencyLoss() @@ -236,7 +253,11 @@ def _resolve_root_dir(self) -> Path: return root def _is_adversarial_active(self) -> bool: - return self.use_adversarial_loss and (self.current_epoch >= self.pretrain_epochs) + return ( + self.use_adversarial_loss + and self.disc is not None + and (self.current_epoch >= self.pretrain_epochs) + ) def _compute_physics_loss(self, fake: Tensor, high_res: Tensor, low_res: Tensor) -> Tensor: phys = torch.zeros((), device=self.device, dtype=torch.float32) @@ -248,7 +269,32 @@ def _compute_physics_loss(self, fake: Tensor, high_res: Tensor, low_res: Tensor) phys = phys + self.gradient_loss_weight * self.gradient_criterion(fake, high_res) if self.ffl_loss_weight > 0.0: phys = phys + self.ffl_loss_weight * self.ffl_criterion(fake, high_res) - return phys.to(fake.dtype) + return phys + + def _effective_accum_divisor(self, batch_idx: int) -> int: + if self.accumulate_n_batches <= 1: + return 1 + num_batches = getattr(self.trainer, "num_training_batches", 0) + if ( + isinstance(num_batches, (int, float)) + and math.isfinite(num_batches) + and int(num_batches) > 0 + ): + total = int(num_batches) + rem = total % self.accumulate_n_batches + if rem != 0 and batch_idx >= (total - rem): + return rem + return self.accumulate_n_batches + + def _maybe_clip_gradients(self, optimizer: Any) -> None: + clip_val = getattr(self.trainer, "gradient_clip_val", None) + clip_algo = getattr(self.trainer, "gradient_clip_algorithm", None) + if clip_val is not None and float(clip_val) > 0.0: + self.clip_gradients( + optimizer, + gradient_clip_val=clip_val, + gradient_clip_algorithm=clip_algo, + ) def training_step(self, train_batch: tuple[Tensor, Tensor], batch_idx: int) -> None: low_res, high_res = train_batch @@ -256,22 +302,22 @@ def training_step(self, train_batch: tuple[Tensor, Tensor], batch_idx: int) -> N high_res = _ensure_4d(high_res) optimizers = self.optimizers() - assert isinstance(optimizers, list) - opt_gen, opt_disc = optimizers - schedulers = self.lr_schedulers() - assert isinstance(schedulers, list) - gen_scheduler, disc_scheduler = schedulers - assert isinstance(gen_scheduler, optim.lr_scheduler.LRScheduler) - assert isinstance(disc_scheduler, optim.lr_scheduler.LRScheduler) + if isinstance(optimizers, list): + opt_gen = optimizers[0] + opt_disc = optimizers[1] if len(optimizers) > 1 else None + else: + opt_gen = optimizers + opt_disc = None should_step = ( (batch_idx + 1) % self.accumulate_n_batches == 0 ) or self.trainer.is_last_batch + eff_accum = float(self._effective_accum_divisor(batch_idx)) adv_active = self._is_adversarial_active() # 1) Discriminator update (only when adversarial loss is active) - disc_loss_val = torch.zeros((), device=self.device) - if adv_active: + disc_loss_val = torch.zeros((), device=self.device, dtype=torch.float32) + if adv_active and opt_disc is not None and self.disc is not None: self.toggle_optimizer(opt_disc) with torch.no_grad(): fake_detached = self.gen(low_res) @@ -290,21 +336,21 @@ def training_step(self, train_batch: tuple[Tensor, Tensor], batch_idx: int) -> N disc_loss_real = self.bce(disc_real, smooth_real) disc_loss_fake = self.bce(disc_fake, torch.zeros_like(disc_fake)) disc_loss = disc_loss_real + disc_loss_fake - disc_loss_val = disc_loss.detach() + disc_loss_val = disc_loss.detach().to(torch.float32) - self.manual_backward(disc_loss / self.accumulate_n_batches) + self.manual_backward(disc_loss.to(torch.float32) / eff_accum) if should_step: + self._maybe_clip_gradients(opt_disc) opt_disc.step() opt_disc.zero_grad(set_to_none=True) - disc_scheduler.step() self.untoggle_optimizer(opt_disc) # 2) Generator update self.toggle_optimizer(opt_gen) fake = self.gen(low_res) - pixel_loss = self.pixel_criterion(fake, high_res) + pixel_loss = self.pixel_criterion(fake, high_res).to(torch.float32) - if adv_active: + if adv_active and self.disc is not None: disc_fake_for_gen = self.disc(fake) if self.gan_loss_type == "ragan": with torch.no_grad(): @@ -315,27 +361,28 @@ def training_step(self, train_batch: tuple[Tensor, Tensor], batch_idx: int) -> N self.bce(rel_fake_g, torch.ones_like(rel_fake_g)) + self.bce(rel_real_g, torch.zeros_like(rel_real_g)) ) - adv_loss = self.adversarial_weight * raw_adv + adv_loss = (self.adversarial_weight * raw_adv).to(torch.float32) else: - adv_loss = self.adversarial_weight * self.bce( - disc_fake_for_gen, torch.ones_like(disc_fake_for_gen) - ) + adv_loss = ( + self.adversarial_weight + * self.bce(disc_fake_for_gen, torch.ones_like(disc_fake_for_gen)) + ).to(torch.float32) else: - adv_loss = torch.zeros((), device=self.device, dtype=pixel_loss.dtype) + adv_loss = torch.zeros((), device=self.device, dtype=torch.float32) if self.use_vgg_loss and self.vgg is not None: - vgg_loss = self.vgg_loss_weight * self.vgg(fake, high_res) + vgg_loss = (self.vgg_loss_weight * self.vgg(fake, high_res)).to(torch.float32) else: - vgg_loss = torch.zeros((), device=self.device, dtype=pixel_loss.dtype) + vgg_loss = torch.zeros((), device=self.device, dtype=torch.float32) physics_loss = self._compute_physics_loss(fake, high_res, low_res) gen_loss = pixel_loss + adv_loss + vgg_loss + physics_loss - self.manual_backward(gen_loss / self.accumulate_n_batches) + self.manual_backward(gen_loss / eff_accum) if should_step: + self._maybe_clip_gradients(opt_gen) opt_gen.step() opt_gen.zero_grad(set_to_none=True) - gen_scheduler.step() self.untoggle_optimizer(opt_gen) batch_size = int(low_res.shape[0]) @@ -384,6 +431,18 @@ def training_step(self, train_batch: tuple[Tensor, Tensor], batch_idx: int) -> N batch_size=batch_size, ) + def on_train_epoch_end(self) -> None: + schedulers = self.lr_schedulers() + if schedulers is None: + return + sched_list = schedulers if isinstance(schedulers, list) else [schedulers] + for sched in sched_list: + if ( + isinstance(sched, optim.lr_scheduler.LRScheduler) + and int(getattr(sched.optimizer, "_step_count", 0)) > 1 + ): + sched.step() + @torch.no_grad() def validation_step(self, val_batch: tuple[Tensor, Tensor], batch_idx: int) -> None: low_res, high_res = val_batch @@ -490,8 +549,35 @@ def _predict_base_dir(self) -> Path: folder_name = f"predicted_{pred_axis}" if pred_axis else "predicted" return self._resolve_root_dir() / folder_name + def _clean_stale_predict_slices(self, base_dir: Path) -> None: + if not base_dir.is_dir(): + return + prefix = f"{self.sample_id}_" if self.sample_id else "" + escaped = re.escape(prefix) + patterns = { + "predicted": re.compile(rf"^{escaped}predicted_(\d+)\.tiff$"), + "low_res": re.compile(rf"^{escaped}low_(\d+)\.tiff$"), + "high_res": re.compile(rf"^{escaped}high_(\d+)\.tiff$"), + } + for subdir_name, pat in patterns.items(): + sdir = base_dir / subdir_name + if not sdir.is_dir(): + continue + for p in sdir.iterdir(): + if pat.match(p.name) is not None: + p.unlink(missing_ok=True) + def on_predict_epoch_start(self) -> None: self._predict_slice_counter = 0 + if self._trainer is not None and int(getattr(self.trainer, "world_size", 1)) > 1: + warnings.warn( + "SRGAN.predict writes TIFF stacks on rank 0 only; run predict with devices=1 " + "or `openlsrx predict-volume` so slices are not sharded across ranks.", + UserWarning, + stacklevel=2, + ) + if self.global_rank == 0: + self._clean_stale_predict_slices(self._predict_base_dir()) @torch.no_grad() def predict_step( @@ -522,6 +608,7 @@ def predict_step( prefix = f"{self.sample_id}_" if self.sample_id else "" batch_size = int(low_4d.shape[0]) + c_mid = low_f32.shape[1] // 2 for i in range(batch_size): idx = self._predict_slice_counter self._predict_slice_counter += 1 @@ -531,7 +618,7 @@ def predict_step( ) tifffile.imwrite( low_dir / f"{prefix}low_{idx:05d}.tiff", - low_f32[i, 0].cpu().numpy(), + low_f32[i, c_mid].cpu().numpy(), ) if high_f32 is not None: tifffile.imwrite( @@ -546,8 +633,8 @@ def on_predict_epoch_end(self) -> None: return base_dir = self._predict_base_dir() - if not base_dir.is_dir(): - return + dm = getattr(self.trainer, "datamodule", None) if self._trainer is not None else None + pred_axis = getattr(dm, "predict_axis", None) prefix = f"{self.sample_id}_" if self.sample_id else "" escaped_prefix = re.escape(prefix) @@ -569,44 +656,113 @@ def on_predict_epoch_end(self) -> None: ), ] - for subdir_name, stack_filename, pattern in stack_specs: - slice_dir = base_dir / subdir_name - if not slice_dir.is_dir(): - continue - - matched: list[tuple[int, Path]] = [] - for p in slice_dir.iterdir(): - m = pattern.match(p.name) - if m is not None: - matched.append((int(m.group(1)), p)) - if not matched: - continue - - matched.sort(key=lambda item: item[0]) - output_stack = base_dir / stack_filename - with tifffile.TiffWriter(output_stack, bigtiff=True) as writer: - for _, img_path in matched: - writer.write( - tifffile.imread(img_path), + if base_dir.is_dir(): + for subdir_name, stack_filename, pattern in stack_specs: + slice_dir = base_dir / subdir_name + if not slice_dir.is_dir(): + continue + + matched: list[tuple[int, Path]] = [] + for p in slice_dir.iterdir(): + m = pattern.match(p.name) + if m is not None: + matched.append((int(m.group(1)), p)) + if not matched: + continue + + matched.sort(key=lambda item: item[0]) + output_stack = base_dir / stack_filename + + if pred_axis in AXIS_TO_DIM: + # Restore canonical (D, H, W) axis order after single-axis sweep along pred_axis + ordered_vol = np.stack([tifffile.imread(img_p) for _, img_p in matched], axis=0) + canonical_vol = np.ascontiguousarray( + np.moveaxis(ordered_vol, 0, AXIS_TO_DIM[pred_axis]) + ) + tifffile.imwrite( + output_stack, + canonical_vol, + bigtiff=True, photometric="minisblack", - contiguous=True, ) + else: + with tifffile.TiffWriter(output_stack, bigtiff=True) as writer: + for _, img_path in matched: + writer.write( + tifffile.imread(img_path), + photometric="minisblack", + contiguous=True, + ) + + # True 3-axis orthogonal volumetric reconstruction + epistemic uncertainty when DataModule provides 3D LR + pred_lr_vol = getattr(dm, "predict_lr_volume", None) if dm is not None else None + pred_mode = ( + getattr(dm, "predict_mode", "orthogonal_3axis") if dm is not None else "single_axis" + ) + if pred_lr_vol is not None and pred_mode == "orthogonal_3axis": + fusion_mode = cast(FusionMode, str(getattr(dm, "predict_fusion", "confidence_fourier"))) + eval_bs = int(getattr(dm, "eval_batch_size", 4)) + ortho = super_resolve_volume_orthogonal( + generator=self.gen, + low_volume=np.asarray(pred_lr_vol, dtype=np.float32), + scale_factor=self.super_res_factor, + axes=("yz", "xz", "xy"), + fusion=fusion_mode, + batch_size=eval_bs, + device=self.device, + context_slices=self.context_slices, + return_uncertainty=True, + ) + ortho_dir = self._resolve_root_dir() / "predicted_orthogonal" + ortho_dir.mkdir(parents=True, exist_ok=True) + fused_vol = np.ascontiguousarray(ortho["fused"], dtype=np.float32) + unc_vol = np.ascontiguousarray(ortho["uncertainty_std"], dtype=np.float32) + tifffile.imwrite( + ortho_dir / f"{prefix}predicted_stack.tiff", + fused_vol, + bigtiff=True, + photometric="minisblack", + ) + tifffile.imwrite( + ortho_dir / f"{prefix}uncertainty_std_stack.tiff", + unc_vol, + bigtiff=True, + photometric="minisblack", + ) + if base_dir.is_dir(): + tifffile.imwrite( + base_dir / f"{prefix}predicted_orthogonal_fused.tiff", + fused_vol, + bigtiff=True, + photometric="minisblack", + ) + tifffile.imwrite( + base_dir / f"{prefix}predicted_epistemic_std.tiff", + unc_vol, + bigtiff=True, + photometric="minisblack", + ) def configure_optimizers(self): opt_gen = optim.Adam(self.gen.parameters(), lr=self.learning_rate, betas=(0.9, 0.999)) - opt_disc = optim.Adam(self.disc.parameters(), lr=self.learning_rate, betas=(0.9, 0.999)) - if self.lr_scheduler_type == "constant": gen_scheduler: optim.lr_scheduler.LRScheduler = optim.lr_scheduler.LambdaLR( opt_gen, lr_lambda=lambda _step: 1.0 ) - disc_scheduler: optim.lr_scheduler.LRScheduler = optim.lr_scheduler.LambdaLR( - opt_disc, lr_lambda=lambda _step: 1.0 - ) else: gen_scheduler = optim.lr_scheduler.CosineAnnealingWarmRestarts( opt_gen, **self.lr_scheduler_args ) + + if self.disc is None: + return [{"optimizer": opt_gen, "lr_scheduler": gen_scheduler}] + + opt_disc = optim.Adam(self.disc.parameters(), lr=self.learning_rate, betas=(0.9, 0.999)) + if self.lr_scheduler_type == "constant": + disc_scheduler: optim.lr_scheduler.LRScheduler = optim.lr_scheduler.LambdaLR( + opt_disc, lr_lambda=lambda _step: 1.0 + ) + else: disc_scheduler = optim.lr_scheduler.CosineAnnealingWarmRestarts( opt_disc, **self.lr_scheduler_args ) diff --git a/src/openlsrx/models/submodels.py b/src/openlsrx/models/submodels.py index 813a6f3..8d78c7d 100644 --- a/src/openlsrx/models/submodels.py +++ b/src/openlsrx/models/submodels.py @@ -16,6 +16,34 @@ DEFAULT_DISC_FEATURES: tuple[int, ...] = (64, 64, 128, 128, 256, 256, 512, 512) +def apply_bounded_output( + x: Tensor, + activation: OutputActivation, + sigmoid_k: float = 1.0, + training: bool = False, + base: Tensor | None = None, +) -> Tensor: + """Apply generator output activation with straight-through clamping and skip-aware logits.""" + if activation == "identity": + return (base + x) if base is not None else x + if activation == "clamp": + raw = (base + x) if base is not None else x + clamped = torch.clamp(raw, 0.0, 1.0) + return (raw + (clamped - raw).detach()) if training else clamped + if activation == "sigmoid": + if base is not None: + base_logit = torch.logit(torch.clamp(base, 1e-4, 1.0 - 1e-4)) + return torch.sigmoid(base_logit + x) + return torch.sigmoid(x) + if activation == "custom_sigmoid": + k = max(float(sigmoid_k), 1e-6) + if base is not None: + base_logit = torch.logit(torch.clamp(base, 1e-4, 1.0 - 1e-4)) / k + return custom_sigmoid(base_logit + x, k=k) + return custom_sigmoid(x, k=k) + raise ValueError(f"Unsupported output_activation={activation!r}.") + + class Generator(nn.Module): """SRResNet / SRGAN Generator adapted for single-channel XCT data with reflect padding.""" @@ -95,22 +123,18 @@ def __init__( use_act=False, ) - def _apply_output_activation(self, x: Tensor) -> Tensor: - if self.output_activation == "custom_sigmoid": - return custom_sigmoid(x, k=self.sigmoid_k) - if self.output_activation == "sigmoid": - return torch.sigmoid(x) - if self.output_activation == "clamp": - return torch.clamp(x, 0.0, 1.0) - return x - def forward(self, x: Tensor) -> Tensor: initial = self.initial(x) out = self.res_blocks(initial) out = self.last_res(out) + initial out = self.upsample(out) out = self.final_conv(out) - return self._apply_output_activation(out) + return apply_bounded_output( + out, + activation=self.output_activation, + sigmoid_k=self.sigmoid_k, + training=self.training, + ) class Discriminator(nn.Module): diff --git a/src/openlsrx/models/swinir.py b/src/openlsrx/models/swinir.py index ea161ed..1a040eb 100644 --- a/src/openlsrx/models/swinir.py +++ b/src/openlsrx/models/swinir.py @@ -1,12 +1,10 @@ """Lightweight Shifted-Window Transformer (SwinIR) generator for 2D/2.5D XCT super-resolution. -Implements Residual Swin Transformer Blocks (RSTB) with shifted-window 2D self-attention, -learnable relative position biases, automatic reflect padding for arbitrary slice dimensions, -central-slice global bicubic residual learning, and ``ArbitraryScaleUpsample`` supporting both -power-of-two (``2x, 4x, 8x``) and fractional synchrotron magnification ratios (``2.5x, 5x``). - -Reference: - Liang, J. et al., "SwinIR: Image Restoration Using Swin Transformer", ICCV Workshops (2021). +Implements Residual Swin Transformer Blocks (RSTB) with per-axis shifted-window 2D self-attention, +cached shift masks, learnable relative position biases, automatic reflect/replicate padding for +arbitrary slice dimensions, central-slice global bicubic residual learning, and +``ArbitraryScaleUpsample`` supporting both power-of-two (``2x, 4x, 8x``) and fractional +synchrotron magnification ratios (``2.5x, 5x``). """ from __future__ import annotations @@ -17,9 +15,9 @@ import torch.nn.functional as F from torch import Tensor, nn -from ..losses import custom_sigmoid +from .blocks import _safe_conv2d from .rrdb import ArbitraryScaleUpsample -from .submodels import OutputActivation +from .submodels import OutputActivation, apply_bounded_output def _window_partition(x: Tensor, window_size: int) -> Tensor: @@ -60,14 +58,14 @@ def __init__(self, dim: int, window_size: int = 8, num_heads: int = 4) -> None: coords_h = torch.arange(ws) coords_w = torch.arange(ws) - coords = torch.stack(torch.meshgrid(coords_h, coords_w, indexing="ij")) # (2, ws, ws) - coords_flat = torch.flatten(coords, 1) # (2, ws*ws) - rel_coords = coords_flat[:, :, None] - coords_flat[:, None, :] # (2, N, N) + coords = torch.stack(torch.meshgrid(coords_h, coords_w, indexing="ij")) + coords_flat = torch.flatten(coords, 1) + rel_coords = coords_flat[:, :, None] - coords_flat[:, None, :] rel_coords = rel_coords.permute(1, 2, 0).contiguous() rel_coords[:, :, 0] += ws - 1 rel_coords[:, :, 1] += ws - 1 rel_coords[:, :, 0] *= 2 * ws - 1 - rel_pos_index = rel_coords.sum(-1) # (N, N) + rel_pos_index = rel_coords.sum(-1) self.register_buffer("relative_position_index", rel_pos_index, persistent=False) self.qkv = nn.Linear(dim, dim * 3) @@ -100,7 +98,7 @@ def forward(self, x: Tensor, mask: Tensor | None = None) -> Tensor: class SwinTransformerLayer(nn.Module): - """Single Swin Transformer layer with optional cyclic window shift and pre-LayerNorm MLP.""" + """Single Swin Transformer layer with per-axis cyclic window shift and cached attention masks.""" def __init__( self, @@ -125,30 +123,46 @@ def __init__( nn.GELU(), nn.Linear(hidden_dim, dim), ) + self._mask_cache: dict[tuple[int, int, int, int, torch.device, torch.dtype], Tensor] = {} - @staticmethod - def _build_shift_mask( - h: int, w: int, window_size: int, shift_size: int, device: torch.device, dtype: torch.dtype + def _get_shift_mask( + self, + h: int, + w: int, + shift_h: int, + shift_w: int, + device: torch.device, + dtype: torch.dtype, ) -> Tensor: + key = (h, w, shift_h, shift_w, device, dtype) + cached = self._mask_cache.get(key) + if cached is not None: + return cached + + ws = self.window_size img_mask = torch.zeros((1, h, w, 1), device=device, dtype=dtype) h_slices = ( - slice(0, -window_size), - slice(-window_size, -shift_size), - slice(-shift_size, None), + (slice(0, -ws), slice(-ws, -shift_h), slice(-shift_h, None)) + if shift_h > 0 + else (slice(0, None),) ) w_slices = ( - slice(0, -window_size), - slice(-window_size, -shift_size), - slice(-shift_size, None), + (slice(0, -ws), slice(-ws, -shift_w), slice(-shift_w, None)) + if shift_w > 0 + else (slice(0, None),) ) cnt = 0 for hs in h_slices: - for ws in w_slices: - img_mask[:, hs, ws, :] = cnt + for w_sl in w_slices: + img_mask[:, hs, w_sl, :] = cnt cnt += 1 - mask_windows = _window_partition(img_mask, window_size).view(-1, window_size * window_size) + mask_windows = _window_partition(img_mask, ws).view(-1, ws * ws) attn_mask = mask_windows.unsqueeze(1) - mask_windows.unsqueeze(2) - return attn_mask.masked_fill(attn_mask != 0, -100.0).masked_fill(attn_mask == 0, 0.0) + attn_mask = attn_mask.masked_fill(attn_mask != 0, -100.0).masked_fill(attn_mask == 0, 0.0) + if len(self._mask_cache) >= 8: + self._mask_cache.clear() + self._mask_cache[key] = attn_mask + return attn_mask def forward(self, x: Tensor) -> Tensor: """Forward on ``(B, H, W, C)`` where ``H, W`` are multiples of ``window_size``.""" @@ -156,11 +170,12 @@ def forward(self, x: Tensor) -> Tensor: shortcut = x x_norm = self.norm1(x) - eff_shift = self.shift_size if min(h, w) > self.window_size else 0 - if eff_shift > 0: - shifted = torch.roll(x_norm, shifts=(-eff_shift, -eff_shift), dims=(1, 2)) - attn_mask: Tensor | None = self._build_shift_mask( - h, w, self.window_size, eff_shift, device=x.device, dtype=x.dtype + shift_h = self.shift_size if h > self.window_size else 0 + shift_w = self.shift_size if w > self.window_size else 0 + if shift_h > 0 or shift_w > 0: + shifted = torch.roll(x_norm, shifts=(-shift_h, -shift_w), dims=(1, 2)) + attn_mask: Tensor | None = self._get_shift_mask( + h, w, shift_h, shift_w, device=x.device, dtype=x.dtype ) else: shifted = x_norm @@ -174,8 +189,8 @@ def forward(self, x: Tensor) -> Tensor: ) merged = _window_reverse(attn_windows, self.window_size, h, w) - if eff_shift > 0: - merged = torch.roll(merged, shifts=(eff_shift, eff_shift), dims=(1, 2)) + if shift_h > 0 or shift_w > 0: + merged = torch.roll(merged, shifts=(shift_h, shift_w), dims=(1, 2)) x = shortcut + merged return x + self.mlp(self.norm2(x)) @@ -224,7 +239,7 @@ def forward(self, x: Tensor) -> Tensor: feat = tokens.permute(0, 3, 1, 2).contiguous() if pad_h > 0 or pad_w > 0: feat = feat[:, :, :h, :w] - return x + self.res_scale * self.conv(feat) + return x + self.res_scale * _safe_conv2d(self.conv, feat) class SwinIRGenerator(nn.Module): @@ -250,7 +265,6 @@ def __init__( f"Unsupported output_activation={output_activation!r}. " "Expected 'custom_sigmoid', 'sigmoid', 'clamp', or 'identity'." ) - # Ensure embed_dim is divisible by num_heads eff_heads = int(num_heads) if out_channels % eff_heads != 0: eff_heads = max(1, math.gcd(int(out_channels), eff_heads)) @@ -287,30 +301,20 @@ def __init__( self.upsample = ArbitraryScaleUpsample( channels=self.out_channels, scale_factor=self.super_res_factor ) - final_conv = nn.Conv2d( - self.out_channels, self.out_img_channels, 3, 1, 1, padding_mode="reflect" + self.hr_conv1 = nn.Conv2d( + self.out_channels, self.out_channels, 3, 1, 1, padding_mode="reflect" ) - if final_conv.bias is not None: - nn.init.zeros_(final_conv.bias) - final_conv.weight.data.mul_(0.1) - self.hr_head = nn.Sequential( - nn.Conv2d(self.out_channels, self.out_channels, 3, 1, 1, padding_mode="reflect"), - nn.LeakyReLU(0.2, inplace=True), - final_conv, + self.hr_act = nn.LeakyReLU(0.2, inplace=True) + self.hr_conv2 = nn.Conv2d( + self.out_channels, self.out_img_channels, 3, 1, 1, padding_mode="reflect" ) - - def _apply_output_activation(self, x: Tensor) -> Tensor: - if self.output_activation == "custom_sigmoid": - return custom_sigmoid(x, k=self.sigmoid_k) - if self.output_activation == "sigmoid": - return torch.sigmoid(x) - if self.output_activation == "clamp": - return torch.clamp(x, 0.0, 1.0) - return x + if self.hr_conv2.bias is not None: + nn.init.zeros_(self.hr_conv2.bias) + self.hr_conv2.weight.data.mul_(0.1) def forward(self, x: Tensor) -> Tensor: - target_h = int(round(x.shape[-2] * self.super_res_factor)) - target_w = int(round(x.shape[-1] * self.super_res_factor)) + target_h = max(1, int(round(x.shape[-2] * self.super_res_factor))) + target_w = max(1, int(round(x.shape[-1] * self.super_res_factor))) if x.shape[1] == self.out_img_channels: center = x else: @@ -318,10 +322,14 @@ def forward(self, x: Tensor) -> Tensor: center = x[:, c_mid : c_mid + self.out_img_channels, :, :] base = F.interpolate(center, size=(target_h, target_w), mode="bicubic", align_corners=False) - feat = self.conv_first(x) - feat = feat + self.trunk_conv(self.trunk(feat)) + feat = _safe_conv2d(self.conv_first, x) + feat = feat + _safe_conv2d(self.trunk_conv, self.trunk(feat)) up = self.upsample(feat) - residual = self.hr_head(up) - if self.output_activation in ("clamp", "identity"): - return self._apply_output_activation(base + residual) - return self._apply_output_activation(residual) + residual = _safe_conv2d(self.hr_conv2, self.hr_act(_safe_conv2d(self.hr_conv1, up))) + return apply_bounded_output( + residual, + activation=self.output_activation, + sigmoid_k=self.sigmoid_k, + training=self.training, + base=base, + ) diff --git a/tests/test_configs_and_cli.py b/tests/test_configs_and_cli.py index 24738ae..889f456 100644 --- a/tests/test_configs_and_cli.py +++ b/tests/test_configs_and_cli.py @@ -44,6 +44,7 @@ def test_cli_inprocess_download_and_evaluate(tmp_path: Path) -> None: str(bench_dir), "--size", "24", + "--offline", ] ) assert exc_dl.value.code == 0 @@ -62,6 +63,7 @@ def test_cli_inprocess_download_and_evaluate(tmp_path: Path) -> None: str(bench_dir), "--size", "24", + "--offline", ] ) assert exc_cached.value.code == 0 diff --git a/tests/test_dataset.py b/tests/test_dataset.py index 679aca0..2cde7f6 100644 --- a/tests/test_dataset.py +++ b/tests/test_dataset.py @@ -122,6 +122,7 @@ def test_public_rock_offline_fallback(tmp_path: Path) -> None: dest_dir=tmp_path / "rocks", shape=(32, 32, 32), allow_offline_fallback=True, + prefer_offline=True, seed=11, ) assert tif_path.is_file() diff --git a/tests/test_red_team_regressions.py b/tests/test_red_team_regressions.py new file mode 100644 index 0000000..6dc7638 --- /dev/null +++ b/tests/test_red_team_regressions.py @@ -0,0 +1,622 @@ +"""Comprehensive regression tests for Stage 4 Red-Team Audit (P0-1..P3-5) & external cross-review. + +Explicitly locks in mathematical, physical, numerical, and provenance fixes across: +- Cell-centered half-voxel coordinate alignment (`grid_mode=True`) at 2x and 8x (`P0-1`) +- Split-isolated train-only normalization & per-split PSF degradation (`P0-2`) +- Coaxial Zenodo HDF5 cropping, joint attenuation calibration, cache-key validation, + fail-loud `allow_offline_fallback=False`, and `None` DOIs on synthetic manifests (`P0-3`, `P0-4`) +- Window-weighted zero-DC FSC/FRC, `rfftn` multiplicity, and blur-sensitive `FSC = 0.5` (`P0-5`) +- CG convergence verification (`info == 0`, residual & flux balance) + variational bounds (`P0-6`) +- Streaming `float32`/`complex64` `rfftn` Fourier fusion with zero `NaN` (`P0-7`) +- 2.5D `z`-PSF curvature-corrected `AttenuationConservationLoss` & bimodal `SoftCLDiceLoss` (`P0-8`) +- HR-grid sub-voxel 3D registration + low-correlation quality warning (`P1-1`) +- Native-LR-strided 2.5D slice context & 3-axis orthogonal `predict_step` / `predict-volume` (`P1-2`, `P1-3`) +- Rectangular `PairedSliceDataset` `D_2` & `SwinIRGenerator` mask caching (`P1-4`, `P2-1`) +- Reference-locked petrophysical thresholding, non-periodic 8-octant `S_2(r)`, circular FOV masks, + unimodal triphase guard, straight-through clamp, lazy discriminator, `O_h` 3D symmetry, + tiny-patch padding, OpenImpala path-injection guard, and `ddof=1` provenance aggregation (`P1-5`..`P3-5`). +""" + +from __future__ import annotations + +import csv +import importlib.util +import json +from pathlib import Path + +import h5py +import numpy as np +import pytest +import pytorch_lightning as pl +import tifffile +import torch +from scipy.ndimage import gaussian_filter + +from openlsrx.baselines import upsample_3d +from openlsrx.cli import main as cli_main +from openlsrx.data import ( + AVAILABLE_PUBLIC_DATASETS, + PairedSliceDataset, + PairedVolumeDataModule, + SyntheticPoreSpyDataModule, + build_circular_fov_mask, + degrade_xct_volume, + extract_aligned_slab_from_h5, + fetch_or_generate_rock_sample, + prepare_zn13x_benchmark, + register_multires_pair_3d, + synthesize_zn13x_phantom_pair, + zoom_cell_centered, +) +from openlsrx.data.transforms import extract_paired_slices_from_subvolume +from openlsrx.inference import fuse_orthogonal_volumes, super_resolve_volume_single_axis +from openlsrx.io import export_for_openimpala +from openlsrx.losses import AttenuationConservationLoss, SoftCLDiceLoss +from openlsrx.metrics import ( + compute_fsc_3d, + compute_tortuosity_uncertainty_bounds, + evaluate_image_metrics, + evaluate_petrophysical_metrics, + evaluate_spectral_metrics, + evaluate_triphase_zn13x_metrics, + solve_steady_state_diffusion_axis, + two_point_correlation_radial, +) +from openlsrx.models import ( + SRGAN, + Generator, + RRDBGenerator, + SR3DResNet, + SwinIRGenerator, + apply_bounded_output, + build_3d_subcube_dataloaders, +) + + +@pytest.mark.parametrize("scale", [2, 8]) +def test_p0_1_cell_centered_depth_alignment_zero_shift_on_linear_ramp(scale: int) -> None: + """Verify cell-centered `grid_mode=True` eliminates +/-0.47 (2x) and +/-3.0 (8x) HR-voxel shifts.""" + n_lr = 12 + n_hr = n_lr * scale + # Analytical linear ramp along z in [0.1, 0.9] evaluated at HR voxel centers (i + 0.5) / n_hr + z_hr = (np.arange(n_hr, dtype=np.float32) + 0.5) / float(n_hr) + hr_ramp = np.broadcast_to((0.1 + 0.8 * z_hr)[:, None, None], (n_hr, 16, 16)).copy() + + # Exact block-averaged LR ramp (no PSF blur, no noise) -> LR centers sit at (k + 0.5) / n_lr + lr_ramp = degrade_xct_volume(hr_ramp, scale_factor=scale, psf_sigma=0.0, noise_std=0.0) + + # 1) 3D trilinear upsampling must match interior HR ramp exactly (zero shift) + up_trilin = upsample_3d(lr_ramp, scale_factors=scale, mode="trilinear") + margin = scale + max_err_3d = float(np.max(np.abs(up_trilin[margin:-margin] - hr_ramp[margin:-margin]))) + assert max_err_3d < 1e-5, f"Expected zero depth shift at {scale}x, got max error {max_err_3d}" + + # 2) Paired slice extraction along yz (cubic order=3) has zero systematic shift and exact interior ramp + lo_slices, hi_slices = extract_paired_slices_from_subvolume( + lr_ramp, hr_ramp, scale_factor=scale, axes=("yz",), context_slices=1 + ) + cubic_margin = 3 * scale # Outside 2-LR-voxel cubic B-spline boundary decay zone + mean_signed_shift = float( + np.mean(lo_slices[margin:-margin, 0, 0] - hi_slices[margin:-margin, 0, 0]) + ) + max_err_slices = float( + np.max( + np.abs( + lo_slices[cubic_margin:-cubic_margin, 0, 0] + - hi_slices[cubic_margin:-cubic_margin, 0, 0] + ) + ) + ) + assert abs(mean_signed_shift) < 1e-6 + assert max_err_slices < 5e-4 + + # 3) zoom_cell_centered preserves constant fields and matches single-axis stack interpolation + identity_gen = torch.nn.Upsample(scale_factor=scale, mode="nearest") + identity_gen.in_channels = 1 # type: ignore[assignment] + sr_yz = super_resolve_volume_single_axis(identity_gen, lr_ramp, scale_factor=scale, axis="yz") + assert ( + float( + np.max(np.abs(sr_yz[cubic_margin:-cubic_margin] - hr_ramp[cubic_margin:-cubic_margin])) + ) + < 5e-4 + ) + assert np.allclose(zoom_cell_centered(np.ones((4, 4), dtype=np.float32), 2.0), 1.0) + + +def test_p0_2_split_isolated_normalization_and_psf_degradation(tmp_path: Path) -> None: + """Outlier spikes in `test` slab must NEVER leak into `train` slab normalization or PSF blur.""" + rng = np.random.default_rng(12) + base_hr = rng.uniform(10.0, 20.0, size=(32, 16, 16)).astype(np.float32) + spiked_hr = base_hr.copy() + spiked_hr[-4:, :, :] = 5000.0 # Massive outlier strictly inside the test slab + + tif_clean = tmp_path / "clean.tif" + tif_spiked = tmp_path / "spiked.tif" + tifffile.imwrite(tif_clean, base_hr) + tifffile.imwrite(tif_spiked, spiked_hr) + + dm_clean = PairedVolumeDataModule( + high_path=str(tif_clean), + degrade_from_hr=True, + scale_factor=2, + psf_sigma=0.8, + degrade_noise_std=0.0, + norm_mode="minmax", + guard_slices_lr=1, + seed=42, + ) + dm_spiked = PairedVolumeDataModule( + high_path=str(tif_spiked), + degrade_from_hr=True, + scale_factor=2, + psf_sigma=0.8, + degrade_noise_std=0.0, + norm_mode="minmax", + guard_slices_lr=1, + seed=42, + ) + dm_clean.setup("fit") + dm_spiked.setup("fit") + + assert np.allclose(dm_clean.splits_3d["train"][0], dm_spiked.splits_3d["train"][0], atol=1e-6) + assert np.allclose(dm_clean.splits_3d["train"][1], dm_spiked.splits_3d["train"][1], atol=1e-6) + + # SyntheticPoreSpyDataModule must also keep train bounds isolated + ps_dm = SyntheticPoreSpyDataModule(volume_size=32, scale_factor=2, guard_slices_lr=1, seed=5) + ps_dm.setup("fit") + assert float(ps_dm.splits_3d["train"][1].max()) <= 1.0 + + +def test_p0_3_and_p0_4_provenance_cache_keys_fail_loud_and_coaxial_h5(tmp_path: Path) -> None: + """Verify Zn-13X & rock cache invalidation, fail-loud defaults, None DOIs, and coaxial H5 crop.""" + zn_dir = tmp_path / "zn_cache" + + # 1) Offline synthetic manifest must set Zenodo DOIs to None and is_experimental_xct=False + _, hr_12, man_12 = prepare_zn13x_benchmark( + pair="2x", dest_dir=zn_dir, lr_size=12, prefer_offline=True, seed=1 + ) + assert tifffile.imread(hr_12).shape == (24, 24, 24) + assert man_12["source_kind"] == "offline_calibrated_zn13x_phantom" + assert man_12["is_experimental_xct"] is False + assert man_12["low_zenodo_doi"] is None + assert man_12["high_zenodo_doi"] is None + + # 2) Requesting a larger lr_size=16 MUST invalidate the 12^3 cache! + _, hr_16, man_16 = prepare_zn13x_benchmark( + pair="2x", dest_dir=zn_dir, lr_size=16, prefer_offline=True, seed=1 + ) + assert tifffile.imread(hr_16).shape == (32, 32, 32) + assert man_16["requested_lr_size"] == 16 + + # 3) Failing loudly when allow_offline_fallback=False and real files are missing + with pytest.raises(RuntimeError, match="fallback is disabled"): + prepare_zn13x_benchmark( + pair="2x", + dest_dir=tmp_path / "zn_strict", + lr_size=12, + raw_h5_dir=tmp_path / "nonexistent_h5", + allow_offline_fallback=False, + prefer_offline=False, + timeout_s=0.001, + ) + + # 4) Coaxial Zenodo 14245751 8-bit cropped HDF5 loader + cache upgrade from synthetic -> real! + preview_dir = tmp_path / "preview_h5" + preview_dir.mkdir() + _, hr_ref = synthesize_zn13x_phantom_pair(pair="2x", lr_shape=(16, 16, 16), seed=3) + lr_ref = degrade_xct_volume(hr_ref, scale_factor=2, psf_sigma=0.5, noise_std=0.0) + # Uneven coaxial FOVs around center (simulating 169067_8bit_cropped.h5 vs 169066_8bit_cropped.h5) + lo_pad = np.pad((lr_ref * 255.0).astype(np.uint8), ((4, 4), (6, 6), (2, 2)), mode="edge") + hi_pad = np.pad((hr_ref * 255.0).astype(np.uint8), ((2, 2), (4, 4), (6, 6)), mode="edge") + with h5py.File(preview_dir / "169067_8bit_cropped.h5", "w") as f_lo: + f_lo.create_dataset("data", data=lo_pad) + with h5py.File(preview_dir / "169066_8bit_cropped.h5", "w") as f_hi: + f_hi.create_dataset("data", data=hi_pad) + + # Passing raw_h5_dir into zn_dir (which currently holds offline synthetic!) must NOT return synthetic! + _, hr_real, man_real = prepare_zn13x_benchmark( + pair="2x", + dest_dir=zn_dir, + lr_size=14, + raw_h5_dir=preview_dir, + allow_offline_fallback=False, + prefer_offline=False, + ) + assert man_real["source_kind"] == "local_i13_preview_h5_registered" + assert man_real["is_experimental_xct"] is True + assert man_real["low_zenodo_doi"] is not None + assert tifffile.imread(hr_real).shape == (28, 28, 28) + + # 5) Joint physical [vmin, vmax] attenuation window preserves identical mu across LR and HR H5s + savu_lo = tmp_path / "169067_recon.h5" + savu_hi = tmp_path / "169066_recon.h5" + with h5py.File(savu_lo, "w") as fl: + ds = fl.create_dataset("4-TomopyRecon-tomo/data", shape=(1600, 920, 1700), dtype="f4") + ds[858:874, 886:902, 1010:1026] = 2.0e-4 + with h5py.File(savu_hi, "w") as fh: + ds = fh.create_dataset("4-TomopyRecon-tomo/data", shape=(1800, 840, 2100), dtype="f4") + ds[466:498, 788:820, 763:795] = 2.0e-4 + slab_lo, slab_hi, _ = extract_aligned_slab_from_h5( + savu_lo, + savu_hi, + pair="2x", + lr_slab_depth=16, + lr_crop_yx=16, + consistent_attenuation_window=True, + ) + assert np.allclose(slab_lo.mean(), slab_hi.mean(), atol=1e-5) + + # 6) Public rock benchmarks provenance & cache shape check + assert "zenodo.org/records/5542624" in str( + AVAILABLE_PUBLIC_DATASETS["bentheimer_sandstone"].url + ) + assert AVAILABLE_PUBLIC_DATASETS["indiana_limestone"].url is None + + rock_dir = tmp_path / "rock_cache" + t16, m16 = fetch_or_generate_rock_sample( + "bentheimer_sandstone", dest_dir=rock_dir, shape=(16, 16, 16), prefer_offline=True + ) + assert m16["source_url"] is None and m16["is_experimental_xct"] is False + t20, _ = fetch_or_generate_rock_sample( + "bentheimer_sandstone", dest_dir=rock_dir, shape=(20, 20, 20), prefer_offline=True + ) + assert tifffile.imread(t20).shape == (20, 20, 20) + + +def test_p0_5_fsc_window_zero_dc_and_050_blur_sensitivity() -> None: + """Verify MTF_eff=0.5 catches noiseless Gaussian blur and FSC=0.5 catches downsampling/noisy blur.""" + rng = np.random.default_rng(99) + # Strictly positive mean [0.4, 0.9] tests Hann-apodized DC leakage suppression + hr = rng.uniform(0.4, 0.9, size=(32, 32, 32)).astype(np.float32) + blurred_1vox = gaussian_filter(hr, sigma=1.0).astype(np.float32) + lr_deg = degrade_xct_volume(hr, scale_factor=2, psf_sigma=1.0, noise_std=0.015, seed=99) + sr_interp = upsample_3d(lr_deg, scale_factors=2, mode="tricubic") + + fsc_ident = compute_fsc_3d(hr, hr, voxel_size_um=0.8125) + spec_blur = evaluate_spectral_metrics(blurred_1vox, hr, voxel_size_um=0.8125) + spec_sr = evaluate_spectral_metrics(sr_interp, hr, voxel_size_um=0.8125) + + assert fsc_ident["frequencies_cyc_per_voxel"][0] > 0.0 # k == 0 excluded + assert np.isclose(fsc_ident["nyquist_fraction_050"], 1.0, atol=1e-5) + assert np.isclose(fsc_ident["nyquist_fraction_mtf_050"], 1.0, atol=1e-5) + + # 1) Noiseless zero-phase sigma=1.0 blur: reference-normalized MTF_eff=0.5 drops to ~0.37 of Nyquist! + assert spec_blur["mtf_nyquist_fraction_050"] < 0.55 + assert spec_blur["mtf_half_pitch_050_um"] > 0.8125 * 1.6 + assert spec_blur["mtf_auc"] < 0.50 + + # 2) Downsampled + upsampled noisy XCT: FSC=0.5 drops well below Nyquist while 0.143 stays higher! + assert spec_sr["fsc_nyquist_fraction_050"] < 0.70 + assert spec_sr["fsc_half_pitch_050_um"] > 0.8125 * 1.35 + assert spec_sr["fsc_cutoff_050_cyc_vox"] < spec_sr["fsc_cutoff_0143_cyc_vox"] + + +def test_p0_6_and_p1_8_diffusion_cg_convergence_fallback_and_monotonic_bounds() -> None: + """Capping CG at maxiter=2 must NOT silently return unphysical D_eff > porosity.""" + duct = np.zeros((16, 10, 10), dtype=bool) + duct[:, 2:8, 2:8] = True + duct[5, 2:7, 2:8] = False + duct[11, 3:8, 2:8] = False + + ref = solve_steady_state_diffusion_axis(duct, axis=0, tol=1e-10, maxiter=4000) + capped = solve_steady_state_diffusion_axis(duct, axis=0, tol=1e-10, maxiter=2) + + assert ref["solver_converged"] == 1.0 + assert capped["solver_converged"] == 1.0 + assert 0.0 < capped["d_eff"] <= capped["porosity"] + assert capped["tortuosity"] >= 1.0 + assert capped["d_eff"] == pytest.approx(ref["d_eff"], rel=1e-4) + + # Uncertainty bounds must satisfy lower <= upper even when 1 of 3 axes pinches off + vol = np.where(duct, 0.2, 0.8).astype(np.float32) + unc = np.full_like(vol, 0.08) + bounds = compute_tortuosity_uncertainty_bounds(vol, unc, true_vol=vol, pore_is_low=True) + assert float(bounds["d_eff_lower"]) <= float(bounds["d_eff_upper"]) + 1e-8 # type: ignore[arg-type] + if bounds["tortuosity_lower"] is not None and bounds["tortuosity_upper"] is not None: + assert float(bounds["tortuosity_lower"]) <= float(bounds["tortuosity_upper"]) + 1e-8 + + +def test_p0_7_streaming_rfftn_fourier_fusion_zero_nan_with_psf_cutoff() -> None: + """Streaming float32/complex64 rfftn fusion must never emit NaN even with tight psf_cutoff.""" + rng = np.random.default_rng(4) + v_yz = rng.random((16, 16, 16), dtype=np.float32) + v_xz = rng.random((16, 16, 16), dtype=np.float32) + v_xy = rng.random((16, 16, 16), dtype=np.float32) + + for mode in ("fourier", "confidence", "confidence_fourier"): + fused = fuse_orthogonal_volumes( + {"yz": v_yz, "xz": v_xz, "xy": v_xy}, + mode=mode, # type: ignore[arg-type] + psf_cutoff=0.05, + ) + assert fused.dtype == np.float32 + assert np.isfinite(fused).all() + assert 0.0 <= float(fused.min()) <= float(fused.max()) <= 1.0 + + +def test_p0_8_25d_z_laplacian_conservation_and_homogeneous_soft_cldice() -> None: + """Verify 2.5D z-PSF curvature term in AttenuationConservationLoss and homogeneous SoftCLDice.""" + # Quadratic z profile: mu(z_LR) = 0.4 + 0.04 * z_LR^2 -> d^2 mu / dz_LR^2 = 0.08 + # Under sigma_HR = 1.0 at 2x (sigma_LR = 0.5), 3D Gaussian blur shifts LR by +0.5 * 0.25 * 0.08 = +0.01 + z_lr = torch.tensor([-1.0, 0.0, 1.0], dtype=torch.float32).view(1, 3, 1, 1) + lr_25d = (0.4 + 0.04 * (z_lr**2) + 0.01).expand(2, 3, 8, 8).contiguous() + hr_mid = torch.full((2, 1, 16, 16), 0.4, dtype=torch.float32) + + loss_25d = AttenuationConservationLoss(psf_sigma=1.0) + loss_no_z = AttenuationConservationLoss(psf_sigma=0.0) + assert float(loss_25d(hr_mid, lr_25d)) < 1e-6 + assert float(loss_no_z(hr_mid, lr_25d)) == pytest.approx(0.01, abs=1e-5) + + # Single-phase all-solid or all-pore patch must yield exact 0.0 SoftCLDiceLoss with finite grads + cl = SoftCLDiceLoss(threshold=None) + solid_patch = torch.full((2, 1, 16, 16), 0.85, dtype=torch.float32) + pred_solid = (solid_patch + 0.005 * torch.randn_like(solid_patch)).requires_grad_(True) + val = cl(pred_solid, solid_patch) + assert float(val.detach()) == 0.0 + val.backward() + assert pred_solid.grad is not None and torch.isfinite(pred_solid.grad).all() + + +def test_p1_1_subvoxel_hr_grid_registration_and_quality_warning() -> None: + """Verify sub-LR-voxel (+1 HR voxel at 2x) registration and low-correlation warning.""" + _, hr = synthesize_zn13x_phantom_pair(pair="2x", lr_shape=(20, 20, 20), seed=31) + # Shift HR by +1 HR voxel (= 0.5 LR voxel!) before degrading to LR + hr_shifted = np.pad(hr, ((1, 0), (1, 0), (0, 0)), mode="edge")[:40, :40, :40] + lr_half_shift = degrade_xct_volume(hr_shifted, scale_factor=2, psf_sigma=0.6, noise_std=0.0) + + al_lr, al_hr, info = register_multires_pair_3d( + lr_half_shift, hr, scale_factor=2, local_refine_radius=2 + ) + assert al_hr.shape == tuple(s * 2 for s in al_lr.shape) + assert info["registration_quality_ok"] is True + assert float(info["coarse_mid_slice_ssim"]) > 0.85 # type: ignore[arg-type] + + # Uncorrelated pure noise volumes must trigger a low-SSIM UserWarning + rng = np.random.default_rng(77) + noise_lr = rng.random((16, 16, 16), dtype=np.float32) + noise_hr = rng.random((32, 32, 32), dtype=np.float32) + with pytest.warns(UserWarning, match="Low 3D registration tri-planar SSIM"): + _, _, bad_info = register_multires_pair_3d(noise_lr, noise_hr, scale_factor=2) + assert bad_info["registration_quality_ok"] is False + + +def test_p1_2_and_p1_3_native_lr_25d_stride_orthogonal_predict_and_2d_cli(tmp_path: Path) -> None: + """Verify native-LR 2.5D stride, 3-axis orthogonal `predict_step`, `predict-volume`, and 2D CLI.""" + # 1) At 2x scale, 2.5D context_slices=3 on zoomed stack must step by stride=2 HR slices (= 1 LR slice) + lr_ramp = np.broadcast_to( + np.arange(6, dtype=np.float32)[:, None, None] / 10.0, (6, 8, 8) + ).copy() + hr_dummy = np.zeros((12, 16, 16), dtype=np.float32) + lo_ctx, _ = extract_paired_slices_from_subvolume( + lr_ramp, hr_dummy, scale_factor=2, axes=("yz",), context_slices=3 + ) + # Interior slice z_hr = 4: neighbors are z_hr = 2 and z_hr = 6 -> difference = 2 * (0.1 / 2) = 0.1 (1 full LR step!) + step_diff = float(lo_ctx[4, 2, 0, 0] - lo_ctx[4, 1, 0, 0]) + assert step_diff == pytest.approx(0.1, abs=5e-3) + + # 2) PairedVolumeDataModule + SRGAN trainer.predict -> 3-axis orthogonal BigTIFF + uncertainty + lr_tif = tmp_path / "lr.tif" + hr_tif = tmp_path / "hr.tif" + rng = np.random.default_rng(5) + tifffile.imwrite(lr_tif, rng.random((10, 12, 14), dtype=np.float32)) + tifffile.imwrite(hr_tif, rng.random((20, 24, 28), dtype=np.float32)) + + dm = PairedVolumeDataModule( + low_path=str(lr_tif), + high_path=str(hr_tif), + scale_factor=2, + context_slices=3, + predict_mode="orthogonal_3axis", + predict_fusion="confidence_fourier", + batch_size=2, + eval_batch_size=2, + ) + out_dir = tmp_path / "ortho_pred_out" + model = SRGAN( + super_res_factor=2, + num_blocks=1, + out_channels=8, + context_slices=3, + backbone="swinir", + swin_window_size=4, + swin_num_heads=2, + use_adversarial_loss=False, + use_vgg_loss=False, + sample_id="ortho", + output_dir=str(out_dir), + ) + assert model.disc is None # P1-10 lazy discriminator instantiation! + + trainer = pl.Trainer( + default_root_dir=str(tmp_path), + max_epochs=1, + accelerator="cpu", + devices=1, + logger=False, + enable_checkpointing=False, + enable_progress_bar=False, + enable_model_summary=False, + ) + trainer.predict(model, datamodule=dm) + pred_stack = tifffile.imread(out_dir / "predicted_orthogonal" / "ortho_predicted_stack.tiff") + unc_stack = tifffile.imread( + out_dir / "predicted_orthogonal" / "ortho_uncertainty_std_stack.tiff" + ) + assert pred_stack.shape == unc_stack.shape + + # 3) Standalone `openlsrx predict-volume` CLI + 2D slice `openlsrx evaluate` (`preserve_2d=True`) + ckpt_path = tmp_path / "swin.ckpt" + trainer.fit(model, datamodule=dm) + trainer.save_checkpoint(ckpt_path) + + cli_sr_out = tmp_path / "cli_sr" / "lr_sr_fourier.tif" + cli_unc_out = tmp_path / "cli_sr" / "lr_uncertainty_std.tif" + with pytest.raises(SystemExit) as exc_pv: + cli_main( + [ + "predict-volume", + "--ckpt", + str(ckpt_path), + "--input", + str(lr_tif), + "--output", + str(cli_sr_out), + "--fusion", + "fourier", + "--uncertainty-output", + str(cli_unc_out), + ] + ) + assert exc_pv.value.code == 0 + assert cli_sr_out.is_file() + assert cli_unc_out.is_file() + + slice_pred = tmp_path / "slice_pred.tif" + slice_gt = tmp_path / "slice_gt.tif" + eval_2d_json = tmp_path / "eval_2d.json" + tifffile.imwrite(slice_pred, rng.random((24, 28), dtype=np.float32)) + tifffile.imwrite(slice_gt, rng.random((24, 28), dtype=np.float32)) + with pytest.raises(SystemExit) as exc_2d: + cli_main( + [ + "evaluate", + "--pred", + str(slice_pred), + "--target", + str(slice_gt), + "--include-spectral", + "--output", + str(eval_2d_json), + ] + ) + assert exc_2d.value.code == 0 + rep_2d = json.loads(eval_2d_json.read_text(encoding="utf-8")) + assert "fsc_auc" in rep_2d["spectral_metrics"] + assert "fsc_cutoff_050_cyc_vox" in rep_2d["spectral_metrics"] + + +def test_p1_4_to_p3_5_models_metrics_fov_straight_through_and_security(tmp_path: Path) -> None: + """Verify rectangular D_2/SwinIR, HR-locked thresholding, non-periodic S_2(r), STE, O_h, and OpenImpala.""" + from openlsrx.models import ResidualSwinBlock, SwinTransformerLayer + + # 1) Non-square PairedSliceDataset D_2 augmentation & rectangular SwinIR mask cache + lo_rect = np.random.default_rng(1).random((8, 3, 10, 16), dtype=np.float32) + hi_rect = np.random.default_rng(2).random((8, 20, 32), dtype=np.float32) + ds_rect = PairedSliceDataset(lo_rect, hi_rect, scale_factor=2, augment=True, context_slices=3) + for idx in range(len(ds_rect)): + l_i, h_i = ds_rect[idx] + assert l_i.shape == (3, 10, 16) + assert h_i.shape == (20, 32) + + swin = SwinIRGenerator( + in_channels=3, out_channels=16, num_blocks=1, depth_per_block=2, num_heads=4, window_size=8 + ) + out_rect = swin(torch.rand(1, 3, 10, 18)) + assert out_rect.shape == (1, 1, 20, 36) + blk0 = swin.trunk[0] + assert isinstance(blk0, ResidualSwinBlock) + lyr1 = blk0.layers[1] + assert isinstance(lyr1, SwinTransformerLayer) + assert len(lyr1._mask_cache) == 1 + + # 2) Tiny-patch (1x1 / 2x2) boundary-safe convs + straight-through clamp gradient flow + tiny_gen = Generator(in_channels=1, out_channels=8, num_blocks=1, super_res_factor=2) + tiny_rrdb = RRDBGenerator(in_channels=1, out_channels=8, growth_channels=4, num_blocks=1) + assert tiny_gen(torch.rand(1, 1, 2, 2)).shape == (1, 1, 4, 4) + assert tiny_rrdb(torch.rand(1, 1, 2, 2)).shape == (1, 1, 4, 4) + + raw_overshoot = torch.tensor([-0.4, 0.5, 1.6], requires_grad=True) + clamped = apply_bounded_output(raw_overshoot, activation="clamp", training=True) + assert torch.allclose(clamped, torch.tensor([0.0, 0.5, 1.0])) + clamped.sum().backward() + assert raw_overshoot.grad is not None and torch.allclose(raw_overshoot.grad, torch.ones(3)) + + # 3) Reference-locked petrophysical thresholding catches global greyscale offset bias! + gt = np.zeros((24, 24, 24), dtype=np.float32) + gt[:, :, :12] = 0.2 + gt[:, :, 12:] = 0.8 + # Prediction shifted upward by +0.35 everywhere -> auto-Otsu would hide the error, HR-locked catches it! + biased_pred = np.clip(gt + 0.35, 0.0, 1.0) + petro = evaluate_petrophysical_metrics(biased_pred, gt, pore_is_low=True) + assert petro["porosity_abs_error"] > 0.45 + assert petro["porosity_auto_otsu_abs_error"] == pytest.approx(0.0, abs=1e-6) + + # 4) Non-periodic 8-octant two_point_correlation_radial: opposite-face slabs do NOT wrap around! + non_periodic = np.zeros((16, 16, 16), dtype=bool) + non_periodic[0, :, :] = True + non_periodic[-1, :, :] = True + s2 = two_point_correlation_radial(non_periodic, max_lag=4) + # At lag r=1 along z, non-periodic pairs have zero overlap between z=0 and z=15! + assert s2[0] == pytest.approx(float(non_periodic.mean()), rel=1e-4) + assert s2[1] < s2[0] * 0.75 + + # 5) Circular FOV mask, (1, H, W) single-slice safety, and unimodal triphase guard + fov = build_circular_fov_mask((8, 16, 16)) + assert fov.shape == (8, 16, 16) and not bool(fov[0, 0, 0]) and bool(fov[4, 8, 8]) + thin_1hw = np.random.default_rng(9).random((1, 24, 24), dtype=np.float32) + assert np.isfinite(evaluate_image_metrics(thin_1hw, thin_1hw)["ssim"]) + const_vol = np.full((12, 12, 12), 0.5, dtype=np.float32) + tri_const = evaluate_triphase_zn13x_metrics(const_vol, const_vol) + assert np.isfinite(tri_const["triphase_macro_dice"]) + + # 6) 48-element O_h 3D subcube augmentation & tiny 3D conv safety + lr_3d = np.random.default_rng(6).random((8, 8, 8), dtype=np.float32) + hr_3d = np.random.default_rng(7).random((16, 16, 16), dtype=np.float32) + tr_3d, _ = build_3d_subcube_dataloaders( + lr_3d, hr_3d, lr_3d, hr_3d, scale_factor=2, patch_size_lr=4, train_samples=6, val_samples=2 + ) + b_lo, b_hi = next(iter(tr_3d)) + assert b_lo.shape[-3:] == (4, 4, 4) and b_hi.shape[-3:] == (8, 8, 8) + sr3d = SR3DResNet(super_res_factor=2, out_channels=8, num_blocks=1) + assert sr3d(torch.rand(1, 1, 2, 2, 2)).shape == (1, 1, 4, 4, 4) + + # 7) OpenImpala strict name validation blocks path traversal / quote injection + for bad_name in ("../escape", "bad/name", 'quote"inject', "space name"): + with pytest.raises(ValueError, match="Invalid OpenImpala sample name"): + export_for_openimpala(gt, output_dir=tmp_path / "imp", name=bad_name) + + # 8) Campaign aggregator ddof=1 sample std, n_percolating_seeds, & source_kinds provenance + spec = importlib.util.spec_from_file_location( + "aggregate_campaign", + Path(__file__).resolve().parents[1] / "scripts" / "benchmarks" / "aggregate_campaign.py", + ) + assert spec is not None and spec.loader is not None + agg_mod = importlib.util.module_from_spec(spec) + spec.loader.exec_module(agg_mod) + + csv_p = tmp_path / "sample_results.csv" + with csv_p.open("w", newline="", encoding="utf-8") as f: + writer = csv.DictWriter( + f, + fieldnames=["dataset", "source_kind", "seed", "method", "psnr", "pred_tortuosity_mean"], + ) + writer.writeheader() + writer.writerow( + { + "dataset": "zn13x_2x", + "source_kind": "zenodo_14245751_8bit_cropped_h5_registered", + "seed": 42, + "method": "SwinIR", + "psnr": 20.0, + "pred_tortuosity_mean": 1.8, + } + ) + writer.writerow( + { + "dataset": "zn13x_2x", + "source_kind": "zenodo_14245751_8bit_cropped_h5_registered", + "seed": 43, + "method": "SwinIR", + "psnr": 22.0, + "pred_tortuosity_mean": "inf", # non-percolating seed! + } + ) + out_agg = tmp_path / "agg_out" + agg_mod.aggregate_csv_files([csv_p], out_agg) + summary = json.loads((out_agg / "campaign_summary.json").read_text(encoding="utf-8")) + rec = summary[0] + # Sample std (ddof=1) of [20.0, 22.0] is sqrt(2) = 1.41421356, NOT population std 1.0! + assert rec["psnr_std"] == pytest.approx(np.sqrt(2.0), rel=1e-5) + assert rec["n_seeds"] == 2 + assert rec["n_percolating_seeds"] == 1 + assert rec["source_kinds"] == ["zenodo_14245751_8bit_cropped_h5_registered"] diff --git a/tests/test_stage2_synchrotron_and_transport.py b/tests/test_stage2_synchrotron_and_transport.py index a27a972..5481e7a 100644 --- a/tests/test_stage2_synchrotron_and_transport.py +++ b/tests/test_stage2_synchrotron_and_transport.py @@ -201,7 +201,7 @@ def test_zn13x_registration_h5_extraction_and_cli_download(tmp_path: Path) -> No # CLI download-benchmarks for zn13x_2x and zn13x_8x (offline fallback / cache) bench_dir = tmp_path / "benchmarks" lr_8x, hr_8x, man_8x = prepare_zn13x_benchmark( - pair="8x", dest_dir=bench_dir, tier="full", lr_size=10, seed=5 + pair="8x", dest_dir=bench_dir, tier="full", lr_size=10, prefer_offline=True, seed=5 ) assert lr_8x.is_file() and hr_8x.is_file() assert man_8x["scale_factor"] == 8 @@ -216,6 +216,7 @@ def test_zn13x_registration_h5_extraction_and_cli_download(tmp_path: Path) -> No str(bench_dir), "--size", "16", + "--offline", ] ) assert exc_dl.value.code == 0 @@ -238,7 +239,7 @@ def test_rrdb_arbitrary_scale_ragan_and_sr3d_end_to_end(tmp_path: Path) -> None: # 2) End-to-end RRDB + RaGAN Lightning fit (warmup epoch 0 + active RaGAN epoch 1) lr_p, hr_p, _ = prepare_zn13x_benchmark( - pair="2x", dest_dir=tmp_path / "zn", tier="full", lr_size=16, seed=9 + pair="2x", dest_dir=tmp_path / "zn", tier="full", lr_size=16, prefer_offline=True, seed=9 ) dm = PairedVolumeDataModule( low_path=str(lr_p),