diff --git a/.zenodo.json b/.zenodo.json new file mode 100644 index 0000000..7f51d12 --- /dev/null +++ b/.zenodo.json @@ -0,0 +1,49 @@ +{ + "title": "OpenLSR-X: Learnable 2D-to-3D Super-Resolution and Petrophysical Benchmark Suite for X-Ray Computed Tomography", + "description": "Open-source PyTorch and PyTorch Lightning framework for 2D-to-3D super-resolution (SRGAN + 3-Axis Orthogonal Fourier Fusion) and quantitative petrophysical validation of porous-media and synchrotron X-ray computed tomography (XCT) volumes.", + "upload_type": "software", + "license": "BSD-3-Clause", + "version": "0.2.0", + "creators": [ + { + "name": "Green, Calum", + "affiliation": "Department of Mechanical Engineering, Imperial College London; Diamond Light Source" + }, + { + "name": "Ahmed, Sharif", + "affiliation": "Diamond Light Source, Rutherford Appleton Laboratory" + }, + { + "name": "Le Houx, James", + "orcid": "0000-0002-1576-0673", + "affiliation": "BASE Laboratory, University of Greenwich; ISIS Neutron and Muon Source; The Faraday Institution" + } + ], + "keywords": [ + "super-resolution", + "x-ray computed tomography", + "micro-CT", + "synchrotron", + "porous media", + "petrophysics", + "generative adversarial networks", + "pytorch-lightning" + ], + "related_identifiers": [ + { + "identifier": "https://github.com/BASE-Laboratory/OpenLSR-X", + "relation": "isSupplementTo", + "scheme": "url" + }, + { + "identifier": "10.1038/s41597-025-04605-9", + "relation": "references", + "scheme": "doi" + }, + { + "identifier": "10.5281/zenodo.13327692", + "relation": "references", + "scheme": "doi" + } + ] +} diff --git a/docs/assets/quickstart_overview.png b/docs/assets/quickstart_overview.png new file mode 100644 index 0000000..958a8c3 Binary files /dev/null and b/docs/assets/quickstart_overview.png differ diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 0000000..7c9c748 --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,105 @@ +# End-to-End Tutorial + +This tutorial walks through a complete reproducible 2D-to-3D super-resolution and petrophysical evaluation cycle in **OpenLSR-X**—from generating a 3D dual-porosity volume with realistic tomographic blur and noise, to leakage-free slab splitting, `SRGAN` training, 3-axis orthogonal Fourier fusion, and quantitative pore-space validation. + +--- + +## 1. Run the Self-Contained Walkthrough Script + +You can execute the entire tutorial in under 30 seconds on CPU (or seconds on GPU): + +```bash +uv run python examples/quickstart_walkthrough.py \ + --volume-size 64 \ + --epochs 6 \ + --output-figure docs/assets/quickstart_overview.png \ + --output-json results/quickstart_metrics.json +``` + +![OpenLSR-X Quickstart Overview](assets/quickstart_overview.png) + +Notice two key physical behaviors in the output panels above: + +1. **Elimination of slice-stacking artifacts:** Applying a 2D generator along a single axis (`yz`) introduces visible horizontal discontinuities in the orthogonal through-plane (`xz`) view, inflating the through-plane gradient anisotropy error $|\Delta(\nabla_z / \nabla_{xy})|$. **3-Axis Orthogonal Fourier Fusion** blends the directional spatial wavevectors across `yz`, `xz`, and `xy` planes to restore isotropic continuity. +2. **Pore-scale structural fidelity:** Inspecting the inscribed pore-radius density $P(r)$ and radial two-point correlation $S_2(r)$ verifies that super-resolution preserves pore-space statistics rather than merely smoothing high-frequency interfaces. + +--- + +## 2. Step-by-Step Python API + +```python +import pytorch_lightning as pl +from openlsrx import ( + SRGAN, + SyntheticPoreSpyDataModule, + evaluate_image_metrics, + evaluate_petrophysical_metrics, + super_resolve_volume_orthogonal, +) + +# 1. Leakage-free 3D slab splitting (train / val / test separated by guard slices) +dm = SyntheticPoreSpyDataModule( + volume_size=64, + scale_factor=2, + feature_regime="high_feature", + noise_regime="high_noise", + patch_size_lr=16, + batch_size=8, + guard_slices_lr=1, + seed=42, +) +dm.setup() + +# 2. Configure compact 2D SRGAN with generator warmup +model = SRGAN( + adaptive_size=6, + super_res_factor=2, + num_blocks=4, + out_channels=32, + disc_features=[32, 32, 64, 64], + pretrain_epochs=3, + use_vgg_loss=False, + save_val_images=False, +) + +trainer = pl.Trainer(max_epochs=6, logger=False, enable_checkpointing=False) +trainer.fit(model, datamodule=dm) + +# 3. Reconstruct isotropic 3D volume via 3-Axis Orthogonal Fourier Fusion +lr_test, hr_test = dm.splits_3d["test"] + +ortho = super_resolve_volume_orthogonal( + model.gen, + lr_test, + scale_factor=2, + axes=("yz", "xz", "xy"), + fusion="fourier", +) +sr_volume = ortho["fused"] + +# 4. Evaluate volumetric fidelity and 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"]) +``` + +--- + +## 3. Equivalent `openlsrx` CLI Workflow + +For YAML-driven reproducible experiments on laboratory TIFF stacks or synchrotron NeXus/HDF5 reconstructions: + +```bash +# Train with automatic checkpointing +openlsrx fit -c configs/base/config.yaml + +# Reconstruct 3D super-resolved BigTIFF volume +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 \ + --output outputs/evaluation_report.json +``` diff --git a/examples/quickstart_walkthrough.py b/examples/quickstart_walkthrough.py new file mode 100755 index 0000000..ed563c9 --- /dev/null +++ b/examples/quickstart_walkthrough.py @@ -0,0 +1,277 @@ +#!/usr/bin/env python3 +"""Self-contained end-to-end OpenLSR-X walkthrough and overview figure generator. + +Demonstrates: +1. 3D porous-media XCT volume synthesis and realistic PSF + noise degradation. +2. Leakage-free 3D slab splitting across train / val / test. +3. Compact 2D SRGAN training with L1 generator warmup + adversarial fine-tuning. +4. 3D Tricubic vs Single-Axis (yz) vs 3-Axis Orthogonal Fourier Fusion on an + independent isotropic 3D test cube. +5. Quantitative image-fidelity & petrophysical evaluation + publication figure export. +""" + +from __future__ import annotations + +import argparse +import json +import shutil +from pathlib import Path + +import matplotlib + +matplotlib.use("Agg") +import matplotlib.pyplot as plt +import numpy as np +import pytorch_lightning as pl +import torch +from scipy.ndimage import distance_transform_edt + +from openlsrx import ( + SRGAN, + SyntheticPoreSpyDataModule, + evaluate_image_metrics, + evaluate_petrophysical_metrics, + generate_porespy_volume, + super_resolve_volume_orthogonal, + upsample_3d, +) +from openlsrx.metrics.petrophysics import segment_pore_space, two_point_correlation_radial + + +def run_walkthrough( + output_figure: Path, + extra_copy: Path | None = None, + output_json: Path | None = None, + volume_size: int = 64, + epochs: int = 16, + seed: int = 42, +) -> dict[str, dict[str, float]]: + """Execute the end-to-end walkthrough and save the multi-panel overview figure.""" + pl.seed_everything(seed, workers=True) + + dm = SyntheticPoreSpyDataModule( + volume_size=volume_size, + scale_factor=2, + feature_regime="low_feature", + noise_regime="high_noise", + patch_size_lr=24, + batch_size=4, + guard_slices_lr=1, + seed=seed, + ) + dm.setup() + + model = SRGAN( + learning_rate=1e-3, + adaptive_size=6, + super_res_factor=2, + num_blocks=4, + out_channels=32, + disc_features=[32, 32, 64, 64], + pixel_loss_type="l1", + pretrain_epochs=max(2, (3 * epochs) // 4), + use_vgg_loss=False, + use_adversarial_loss=True, + adversarial_weight=5e-4, + save_val_images=False, + ) + + trainer = pl.Trainer( + max_epochs=epochs, + accelerator="gpu" if torch.cuda.is_available() else "cpu", + devices=1, + logger=False, + enable_checkpointing=False, + enable_model_summary=False, + enable_progress_bar=False, + ) + trainer.fit(model, datamodule=dm) + + device = torch.device("cuda" if torch.cuda.is_available() else "cpu") + model.gen.to(device).eval() + + # Evaluate on an independent, strictly unseen isotropic 3D test cube (seed + 1000) + lr_test, hr_test, _ = generate_porespy_volume( + shape=volume_size, + feature_regime="low_feature", + noise_regime="high_noise", + scale_factor=2, + seed=seed + 1000, + ) + + pred_tricubic = upsample_3d(lr_test, scale_factors=2, mode="tricubic") + ortho = super_resolve_volume_orthogonal( + model.gen, + lr_test, + scale_factor=2, + axes=("yz", "xz", "xy"), + fusion="fourier", + batch_size=8, + device=device, + ) + pred_yz = ortho["yz"] + pred_fourier = ortho["fused"] + + methods = { + "3D Tricubic": pred_tricubic, + "Single-Axis (yz)": pred_yz, + "3-Axis Fourier Fusion": pred_fourier, + } + summary: dict[str, dict[str, float]] = {} + for name, vol in methods.items(): + img_m = evaluate_image_metrics(vol, hr_test) + petro_m = evaluate_petrophysical_metrics(vol, hr_test, threshold_method="otsu") + summary[name] = {**img_m, **petro_m} + + # Render publication-style 2-row overview figure + lr_nn = upsample_3d(lr_test, scale_factors=2, mode="nearest") + mid_y = hr_test.shape[1] // 2 # Through-plane (xz) cross-section highlights slice-stacking + + fig = plt.figure(figsize=(14.0, 6.4), constrained_layout=True) + gs = fig.add_gridspec(2, 5, height_ratios=[1.15, 1.0]) + + panels = [ + ("LR Input (2x)", lr_nn[:, mid_y, :]), + ("3D Tricubic", pred_tricubic[:, mid_y, :]), + ("Single-Axis SR (yz)", pred_yz[:, mid_y, :]), + ("3-Axis Fourier Fusion", pred_fourier[:, mid_y, :]), + ("HR Ground Truth", hr_test[:, mid_y, :]), + ] + for col, (title, slc) in enumerate(panels): + ax = fig.add_subplot(gs[0, col]) + ax.imshow(slc, cmap="gray", vmin=0.0, vmax=1.0, aspect="equal") + ax.set_title(title, fontsize=10, fontweight="bold") + ax.set_xlabel("x (voxels)", fontsize=8) + if col == 0: + ax.set_ylabel("Through-plane z (voxels)", fontsize=8) + ax.tick_params(labelsize=7) + + # Bottom-left (cols 0-1): Inscribed pore-radius distribution via EDT + ax_psd = fig.add_subplot(gs[1, 0:2]) + hr_mask, thr = segment_pore_space(hr_test, method="otsu") + dt_gt = distance_transform_edt(hr_mask) + r_gt = dt_gt[hr_mask] + bins = np.linspace(0.5, max(float(r_gt.max(initial=6.0)), 6.0), 14) + centers = 0.5 * (bins[:-1] + bins[1:]) + gt_hist, _ = np.histogram(r_gt, bins=bins, density=True) + ax_psd.plot(centers, gt_hist, "k-", lw=2.0, label="HR Ground Truth") + colors = { + "3D Tricubic": "#6c757d", + "Single-Axis (yz)": "#e76f51", + "3-Axis Fourier Fusion": "#1d6fb8", + } + styles = {"3D Tricubic": "--", "Single-Axis (yz)": "-.", "3-Axis Fourier Fusion": "-"} + for name, vol in methods.items(): + m_mask, _ = segment_pore_space(vol, method="fixed", fixed_value=thr) + r_pred = distance_transform_edt(m_mask)[m_mask] + if r_pred.size > 0: + hist, _ = np.histogram(r_pred, bins=bins, density=True) + ax_psd.plot( + centers, hist, linestyle=styles[name], color=colors[name], lw=1.7, label=name + ) + ax_psd.set_title("Inscribed Pore-Radius PDF P(r)", fontsize=10, fontweight="bold") + ax_psd.set_xlabel("Pore Radius r (voxels)", fontsize=8.5) + ax_psd.set_ylabel("Probability Density", fontsize=8.5) + ax_psd.legend(fontsize=7.5, frameon=False) + ax_psd.grid(alpha=0.25) + + # Bottom-middle (cols 2-3): Radial two-point correlation S2(r) + ax_s2 = fig.add_subplot(gs[1, 2:4]) + s2_gt = two_point_correlation_radial(hr_mask) + radii_gt = np.arange(len(s2_gt)) + ax_s2.plot(radii_gt, s2_gt, "k-", lw=2.0, label="HR Ground Truth") + for name, vol in methods.items(): + m_mask, _ = segment_pore_space(vol, method="fixed", fixed_value=thr) + s2_p = two_point_correlation_radial(m_mask) + ax_s2.plot( + np.arange(len(s2_p)), + s2_p, + linestyle=styles[name], + color=colors[name], + lw=1.7, + label=name, + ) + ax_s2.set_title("Radial Two-Point Correlation S2(r)", fontsize=10, fontweight="bold") + ax_s2.set_xlabel("Lag Distance r (voxels)", fontsize=8.5) + ax_s2.set_ylabel("S2(r)", fontsize=8.5) + ax_s2.grid(alpha=0.25) + + # Bottom-right (col 4): Through-plane gradient anisotropy error + ax_ani = fig.add_subplot(gs[1, 4]) + labels = ["Tricubic", "1-Axis\n(yz)", "3-Axis\nFourier"] + ani_vals = [ + summary["3D Tricubic"]["through_plane_anisotropy_error"], + summary["Single-Axis (yz)"]["through_plane_anisotropy_error"], + summary["3-Axis Fourier Fusion"]["through_plane_anisotropy_error"], + ] + bars = ax_ani.bar(labels, ani_vals, color=["#6c757d", "#e76f51", "#1d6fb8"], width=0.6) + ax_ani.set_title( + "Stacking Anisotropy\nError (lower is better)", fontsize=9.5, fontweight="bold" + ) + ax_ani.set_ylabel("|Δ(∇z / ∇xy)|", fontsize=8.5) + ax_ani.tick_params(labelsize=7.5) + ax_ani.set_ylim(0.0, max(ani_vals) * 1.18 + 1e-4) + ax_ani.grid(axis="y", alpha=0.25) + for bar, val in zip(bars, ani_vals, strict=True): + ax_ani.text( + bar.get_x() + bar.get_width() / 2.0, + val + max(ani_vals) * 0.02, + f"{val:.3f}", + ha="center", + va="bottom", + fontsize=7.5, + ) + + output_figure.parent.mkdir(parents=True, exist_ok=True) + fig.savefig(output_figure, dpi=220) + plt.close(fig) + + if extra_copy is not None: + extra_copy.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(output_figure, extra_copy) + + if output_json is not None: + output_json.parent.mkdir(parents=True, exist_ok=True) + output_json.write_text(json.dumps(summary, indent=2), encoding="utf-8") + + return summary + + +def main() -> None: + parser = argparse.ArgumentParser(description="Run OpenLSR-X quickstart walkthrough.") + parser.add_argument( + "--output-figure", + type=Path, + default=Path("docs/assets/quickstart_overview.png"), + help="Destination path for the rendered overview figure.", + ) + parser.add_argument( + "--paper-figure", + type=Path, + default=Path("paper/figures/joss_overview.png"), + help="Optional copy path for the JOSS manuscript figure.", + ) + parser.add_argument("--output-json", type=Path, default=None) + parser.add_argument("--volume-size", type=int, default=64) + parser.add_argument("--epochs", type=int, default=16) + parser.add_argument("--seed", type=int, default=42) + args = parser.parse_args() + + summary = run_walkthrough( + output_figure=args.output_figure, + extra_copy=args.paper_figure, + output_json=args.output_json, + volume_size=args.volume_size, + epochs=args.epochs, + seed=args.seed, + ) + for method, metrics in summary.items(): + print( + f"{method:24s} | PSNR={metrics['psnr']:.2f} dB | SSIM={metrics['ssim']:.4f} " + f"| |Δφ|={metrics['porosity_abs_error']:.4f} " + f"| AnisotropyErr={metrics['through_plane_anisotropy_error']:.4f}" + ) + + +if __name__ == "__main__": + main() diff --git a/mkdocs.yml b/mkdocs.yml index 064bdca..54892ef 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ markdown_extensions: nav: - Home: index.md - Getting Started: getting-started.md + - End-to-End Tutorial: tutorial.md - Datasets & Configuration: datasets-and-configs.md - Benchmarks & Metrics: benchmarks-and-metrics.md - API Reference: api.md diff --git a/paper/figures/joss_overview.png b/paper/figures/joss_overview.png new file mode 100644 index 0000000..958a8c3 Binary files /dev/null and b/paper/figures/joss_overview.png differ diff --git a/paper/paper.bib b/paper/paper.bib index 43b4565..6c9190a 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -91,3 +91,40 @@ @dataset{green2024zn13x_i13 doi={10.5281/zenodo.13327692} } +@software{wang2022basicsr, + title={{BasicSR}: Open Source Image and Video Restoration Toolbox}, + author={Wang, Xintao and Xie, Liangbin and Dong, Chao and Shan, Ying}, + year={2022}, + url={https://github.com/XPixelGroup/BasicSR} +} + +@article{cardoso2022monai, + title={{MONAI}: An open-source framework for deep learning in healthcare}, + author={Cardoso, M. Jorge and Li, Wenqi and Brown, Richard and Ma, Nic and Kerfoot, Eric and Wang, Yiheng and Murrey, Benjamin and Myronenko, Andriy and Zhao, Can and Yang, Dong and others}, + journal={arXiv preprint arXiv:2211.02701}, + year={2022}, + doi={10.48550/arXiv.2211.02701} +} + +@article{perez2021torchio, + title={{TorchIO}: A Python library for efficient loading, preprocessing, augmentation and patch-based sampling of medical images in deep learning}, + author={P{\'e}rez-Garc{\'i}a, Fernando and Sparks, Rachel and Ourselin, Sebastien}, + journal={Computer Methods and Programs in Biomedicine}, + volume={208}, + pages={106236}, + year={2021}, + doi={10.1016/j.cmpb.2021.106236} +} + +@article{gostick2016openpnm, + title={{OpenPNM}: A Pore Network Modeling Package}, + author={Gostick, Jeff and Aghighi, Mahmoudreza and Hinebaugh, James and Tranter, Thomas and Hoeh, Michael A. and Day, Hannah and Spellacy, Brennan and Sharqawy, Mostafa H. and Bazylak, Aimy and Burns, Alan and Lehnert, Werner and Putz, Andreas}, + journal={Computing in Science \& Engineering}, + volume={18}, + number={4}, + pages={60--74}, + year={2016}, + doi={10.1109/MCSE.2016.49} +} + + diff --git a/paper/paper.md b/paper/paper.md index 469c865..7bc10f2 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -44,10 +44,20 @@ While 3D convolutional and generative super-resolution models can recover fine-s OpenLSR-X fills this gap 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. +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. +![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: + +- **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. + # 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: diff --git a/tests/test_configs_and_cli.py b/tests/test_configs_and_cli.py index baf3f9d..24738ae 100644 --- a/tests/test_configs_and_cli.py +++ b/tests/test_configs_and_cli.py @@ -98,3 +98,19 @@ def test_cli_evaluate_shape_mismatch_raises(tmp_path: Path) -> None: np.save(b, np.zeros((10, 8, 8), dtype=np.float32)) with pytest.raises(ValueError, match="Shape mismatch"): cli_main(["evaluate", "--pred", str(a), "--target", str(b)]) + + +def test_release_metadata_consistency() -> None: + import yaml + + import openlsrx + + cff = yaml.safe_load((REPO_ROOT / "CITATION.cff").read_text(encoding="utf-8")) + zenodo = json.loads((REPO_ROOT / ".zenodo.json").read_text(encoding="utf-8")) + + assert cff["version"] == openlsrx.__version__ + assert zenodo["version"] == openlsrx.__version__ + assert cff["license"] == zenodo["license"] == "BSD-3-Clause" + assert len(cff["authors"]) == len(zenodo["creators"]) >= 3 + assert (REPO_ROOT / "paper" / "paper.md").is_file() + assert (REPO_ROOT / "paper" / "paper.bib").is_file()