{"id":17408955,"url":"https://github.com/lukasmosser/porousmediagan","last_synced_at":"2025-08-20T16:31:47.006Z","repository":{"id":62378772,"uuid":"79212796","full_name":"LukasMosser/PorousMediaGan","owner":"LukasMosser","description":"Reconstruction of three-dimensional porous media using generative adversarial neural networks","archived":false,"fork":false,"pushed_at":"2019-08-02T08:27:08.000Z","size":104980,"stargazers_count":180,"open_issues_count":4,"forks_count":65,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-12-10T02:21:12.451Z","etag":null,"topics":["computer-vision","deep-learning","generative-adversarial-network","image-reconstruction","machine-learning","porous-media"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukasMosser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-17T09:46:46.000Z","updated_at":"2024-11-19T13:34:52.000Z","dependencies_parsed_at":"2022-10-31T21:00:53.224Z","dependency_job_id":null,"html_url":"https://github.com/LukasMosser/PorousMediaGan","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasMosser%2FPorousMediaGan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasMosser%2FPorousMediaGan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasMosser%2FPorousMediaGan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasMosser%2FPorousMediaGan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukasMosser","download_url":"https://codeload.github.com/LukasMosser/PorousMediaGan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230438185,"owners_count":18225870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","deep-learning","generative-adversarial-network","image-reconstruction","machine-learning","porous-media"],"created_at":"2024-10-16T23:06:59.254Z","updated_at":"2024-12-19T13:07:33.725Z","avatar_url":"https://github.com/LukasMosser.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"right\" width=\"40%\" height=\"40%\" src=\"https://github.com/LukasMosser/PorousMediaGan/blob/master/misc/render_transp.png\"/\u003e\n\n# PorousMediaGAN \nImplementation and data repository for\n**Reconstruction of three-dimensional porous media using generative adversarial neural networks**\n## Authors\n[Lukas Mosser](mailto:lukas.mosser15@imperial.ac.uk) [Twitter](https://twitter.com/porestar)  \n[Olivier Dubrule](https://www.imperial.ac.uk/people/o.dubrule)  \n[Martin J. Blunt](https://www.imperial.ac.uk/people/m.blunt)  \n*Department of Earth Science and Engineering, Imperial College London*\n\n## Results\nCross-sectional views of the three trained models\n- Beadpack Sample  \n![Beadpack Comparison](https://github.com/LukasMosser/PorousMediaGan/blob/master/paper/figures/beadpack_comparison.png)\n- Berea Sample  \n![Berea Comparison](https://github.com/LukasMosser/PorousMediaGan/blob/master/paper/figures/berea_comparison.png)\n- Ketton Sample  \n![Ketton Comparison](https://github.com/LukasMosser/PorousMediaGan/blob/master/paper/figures/ketton_comparison.png)\n## Methodology\n![Process Overview](https://github.com/LukasMosser/PorousMediaGan/blob/master/paper/figures/GAN_overview.png)\n## Instructions\n### Pre-requisites\n- To run any of the `jupyter` notebooks follow instructions [here](http://jupyter.org/install.html) or install via pip.\n```bash\npip install jupyter\n```\n- In addition we make heavy use of `pandas`, `numpy`, `scipy` and `numba`\n- We recommend the use of [anaconda](https://www.continuum.io/downloads)\n- For numba instructions, you can find a tutorial and installation guideline [here](http://numba.pydata.org/numba-doc/dev/user/installing.html).\n- For the torch version of the code training and generating code please follow the instructions [here](https://github.com/soumith/dcgan.torch)\n- In addition you will need to have installed torch packages `hdf5` and `dpnn`\n```bash\nluarocks install hdf5\nluarocks install dpnn\n```\n- For the pytorch version you will need to have installed `h5py` and `tifffile`\n```bash\npip install h5py\npip install tifffile\n```\n- Clone this repo\n```bash\ngit clone https://github.com/LukasMosser/PorousMediaGAN\ncd PorousMediaGAN\n```\n\n### Pre-trained model (Pytorch version only)\nWe have included a pre-trained model used for the Berea sandstone example in the paper in the repository.\n- From the pytorch folder run `generate.py` as follows\n```bash\npython generator.py --seed 42 --imageSize 64 --ngf 32 --ndf 16 --nz 512 --netG [path to generator checkpoint].pth --experiment berea --imsize 9 --cuda --ngpu 1\n```\nUse the modifier `--imsize` to generate the size of the output images.  \n`--imsize 1` corresponds to the training image size\nReplace `[path to generator checkpoint].pth` with the path to the provided checkpoint e.g. `checkpoints\\berea\\berea_generator_epoch_24.pth`  \nGenerating realizations was tested on GPU and CPU and is very fast even for large reconstructions.\n### Training\nWe highly recommend a modern Nvidia GPU to perform training.  \nAll models were trained on `Nvidia K40` GPUs.  \nTraining on a single GPU takes approximately 24 hours.  \nTo create the training image dataset from the full CT image perform the following steps:\n- Unzipping of the CT image\n```bash\ncd ./data/berea/original/raw\n#unzip using your preferred unzipper\nunzip berea.zip\n```\n- Use `create_training_images.py` to create the subvolume training images. Here an example use:\n```bash\npython create_training_images.py --image berea.tif --name berea --edgelength 64 --stride 32 --target_dir berea_ti\n```\nThis will create the sub-volume training images as an hdf5 format which can then be used for training.  \n- Train the GAN  \nUse `main.py` to train the GAN network. Example usage:\n```bash\npython main.py --dataset 3D --dataroot [path to training images] --imageSize 64 --batchSize 128 --ngf 64 --ndf 16 --nz 512 --niter 1000 --lr 1e-5 --workers 2 --ngpu 2 --cuda \n```\n#### Additional Training Data\nHigh-resolution CT scan data of porous media has been made publicly available via\nthe Department of Earth Science and Engineering, Imperial College London and can be found [here](http://www.imperial.ac.uk/earth-science/research/research-groups/perm/research/pore-scale-modelling/micro-ct-images-and-networks/)\n## Data Analysis\nWe use a number of jupyter notebooks to analyse samples during and after training.\n- Use `code\\notebooks\\Sample Postprocessing.ipynb` to postprocess sampled images\n\t- Converts image from hdf5 to tiff file format\n\t- Computes porosity\n- Use `code\\notebooks\\covariance\\Compute Covariance.ipynb` to compute covariances\n\t- To plot results use `Covariance Analysis.ipynb` and `Covariance Graphs.ipynb` as an example on how to analyse the samples.\n\n### Image Morphological parameters\nWe have used the image analysis software [Fiji](https://fiji.sc/) to analyse generated samples using [MorpholibJ](http://imagej.net/MorphoLibJ).  \nThe images can be loaded as tiff files and analysed using `MorpholibJ\\Analyze\\Analyze Particles 3D`.\n## Results\nWe additionally provide the results used to create our publication in `analysis`.\n- Covariance S2(r)\n- Image Morphology \n- Permeability Results  \nThe Jupyter notebooks included in this repository were used to generate the graphs of the publication.\n## Citation\nIf you use our code for your own research, we would be grateful if you cite our publication\n[ArXiv](http://arxiv.org/abs/1704.03225)\n```\n@article{pmgan2017,\n\ttitle={Reconstruction of three-dimensional porous media using generative adversarial neural networks},\n\tauthor={Mosser, Lukas and Dubrule, Olivier and Blunt, Martin J.},\n\tjournal={arXiv preprint arXiv:1704.03225},\n\tyear={2017}\n}\n```\n\n\n## Acknowledgement\nThe code used for our research is based on [DCGAN](https://github.com/soumith/dcgan.torch)\nfor the [torch](http://torch.ch/) version and the [pytorch](https://github.com/pytorch) example on how to implement a [GAN](https://github.com/pytorch/examples/tree/master/dcgan).  \nOur dataloader has been modified from [DCGAN](https://github.com/soumith/dcgan.torch).\n  \n[O. Dubrule](https://www.imperial.ac.uk/people/o.dubrule) thanks Total for seconding him as a Visiting Professor at Imperial College.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukasmosser%2Fporousmediagan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukasmosser%2Fporousmediagan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukasmosser%2Fporousmediagan/lists"}