OpenLSR-X implements a Learnable Super-Resolution Generative Adversarial Network (SRGAN) for X-Ray Computed Tomography (XCT) data using PyTorch and PyTorch Lightning. It is based on Ledig et al. (CVPR 2017) and adapted from Aladdin Persson's implementation.
- Stable Training: Uses a mixture of MSE loss and VGG loss for improved stability.
- High-Quality Results: Employs 'reflect' padding in convolutional layers to reduce border artifacts.
- Modular Design: Easily extendable for new XCT datasets and tasks.
- Batch Job Support: Includes scripts for HPC environments.
- Configurable: All hyperparameters and data paths are set via YAML config files.
- Clone the repository:
git clone <repo-url> cd OpenLSR-X
- Create the environment with uv:
uv venv uv pip install -r requirements.txt uv pip install -e . - (Optional) Reproduce the exact environment:
uv pip install -r requirements.lock
- Run the CLI from source:
python3 -m openlsrx.cli --help
- Run tests:
python3 -m unittest discover -s tests
Train a model using the provided config:
python3 -m openlsrx.cli fit -c configs/base/config.yamlOverride parameters from the command line:
python3 -m openlsrx.cli fit -c configs/base/config.yaml --model.learning_rate 0.0001 --data.batch_size 16For dataset-specific training or prediction, use the corresponding entry points, e.g.:
python3 -m openlsrx.entrypoints.bentsand fit -c configs/labxct/bs_config.yaml
python3 -m openlsrx.entrypoints.porespy_xct fit -c configs/porespy/High_Noise/ps_hn_hf_config.yaml---## DataLoaders Summary
The project provides several PyTorch Lightning DataModules for handling different XCT datasets:
- PoreSpy3D_Volume: Loads 3D PoreSpy volumes, processes orthogonal slices, and creates train/validation/test splits.
- I13XCTDataModule: Handles Diamond Light Source I13 XCT datasets, including normalization, alignment, and manual axis selection.
- IndLimeDataModule: For Indiana Limestone data, loads and aligns 2D images, supports orthogonal predictions.
- BentSandDataModule: For Bentheimer Sandstone, processes and aligns images, supports orthogonal predictions.
- PoreSpyDataModule: Loads PoreSpy data for all three axes, supports parallel and perpendicular test splits.
Each DataModule supports configuration of batch size, patch size, and augmentation via YAML files. All modules use the core DatasetObject class for paired data.
src/openlsrx/- Package codesrc/openlsrx/models/- SRGAN, generator/discriminator, and blockssrc/openlsrx/data/- Data processing and LightningDataModulessrc/openlsrx/entrypoints/- Dataset-specific CLI modulessrc/openlsrx/losses/- Loss functionsconfigs/- YAML config filesscripts/- Batch job scripts for cluster environmentstests/- Unit tests
---## Support & Documentation
- For issues, use the repository's GitHub Issues page.
- For advanced usage and API details, see code comments and docstrings.
Maintained by Calum Green.
- Contributions are welcome! Please see the repository's CONTRIBUTING guidelines (if available) or open an issue to discuss your ideas.
BSD 3-Clause License
See LICENSE for details.
This README was generated using AI.