<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/porespy_logo.png" width="25%"></img>
</p>
[](https://pypi.python.org/pypi/porespy/)
[](https://codecov.io/gh/PMEAL/PoreSpy)
# What is PoreSpy?
**PoreSpy** is a collection of image analysis tools used to extract
information from 3D images of porous materials (typically obtained from
X-ray tomography). There are many packages that offer generalized image
analysis tools (i.e **Skimage** and **Scipy.NDimage** in the Python environment,
**ImageJ**, **MatLab**'s Image Processing Toolbox), but they all require building
up complex scripts or macros to accomplish tasks of specific use to
porous media. The aim of **PoreSpy** is to provide a set of pre-written
tools for all the common porous media measurements. For instance, it's possible to perform a mercury intrusion simulation with a single function call (e.g. ``porespy.filters.porosimetry``).
**PoreSpy** relies heavily on
[scipy.ndimage](https://docs.scipy.org/doc/scipy/reference/ndimage.html)
and [scikit-image](https://scikit-image.org/) also known as **skimage**.
The former contains an assortment of general image analysis tools such
as image morphology filters, while the latter offers more complex but
still general functions such as watershed segmentation. **PoreSpy** does not
duplicate any of these general functions so you will also have to
install and learn how to use them to get the most from **PoreSpy**. The
functions in PoreSpy are generally built up using several of the general functions offered by **skimage** and **scipy**. There are a few
functions in **PoreSpy** that are implemented natively, but only when
necessary.
# Capabilities
**PoreSpy** consists of the following modules:
- `generators`: Routines for generating artificial images of porous
materials useful for testing and illustration
- `filters`: Functions that accept an image and return an altered
image
- `metrics`: Tools for quantifying properties of images
- `networks`: Algorithms and tools for analyzing images as pore networks
- `simulations`: Physical simulations on images including drainage
- `visualization`: Helper functions for creating useful views of the
image
- `io`: Functions for outputting image data in various formats for use in
common software
- `tools`: Various useful tools for working with images
## Gallery
<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/montage.svg" width="85%"></img>
</p>
## Cite as
> *Gostick J, Khan ZA, Tranter TG, Kok MDR, Agnaou M, Sadeghi MA, Jervis
> R.* **PoreSpy: A Python Toolkit for Quantitative Analysis of Porous Media
> Images.** Journal of Open Source Software, 2019.
> [doi:10.21105/joss.01296](https://doi.org/10.21105/joss.01296)
# Installation
For detailed and up to date installation instructions, [see here](https://porespy.org/installation.html)
# Contributing
If you think you may be interested in contributing to PoreSpy and wish
to both *use* and *edit* the source code, then you should clone the
[repository](https://github.com/PMEAL/porespy) to your local machine,
and install it using the following PIP command:
pip install -e "C:\path\to\the\local\files\"
For information about contributing, refer to the [contributors
guide](https://github.com/PMEAL/porespy/blob/dev/CONTRIBUTING.md)
# Acknowledgements
PoreSpy is grateful to [CANARIE](https://canarie.ca) for their generous funding over the past few years. We would also like to acknowledge the support of [NSERC of Canada](https://www.nserc-crsng.gc.ca/) for funding many of the student that have contributed to PoreSpy since it's inception in 2014.
# Examples
The following code snippets illustrate generating a 2D image, applying
several filters, and calculating some common metrics. A set of examples
is included in this repo, and can be [browsed
here](https://github.com/PMEAL/porespy/tree/dev/examples).
## Generating an image
PoreSpy offers several ways to generate artificial images, for quick
testing and developmnet of work flows, instead of dealing with
reading/writing/storing of large tomograms.
``` python
import porespy as ps
import matplotlib.pyplot as plt
im = ps.generators.blobs(shape=[500, 500], porosity=0.6, blobiness=2)
plt.imshow(im)
```
<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig1.png" width="50%"></img>
</p>
## Applying filters
A common filter to apply is the local thickness, which replaces every
voxel with the radius of a sphere that overlaps it. Analysis of the
histogram of the voxel values provides information about the pore size
distribution.
``` python
lt = ps.filters.local_thickness(im)
plt.imshow(lt)
```
<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig2.png" width="50%"></img>
</p>
A less common filter is the application of chords that span the pore
space in a given direction. It is possible to gain information about
anisotropy of the material by looking at the distributions of chords
lengths in each principle direction.
``` python
cr = ps.filters.apply_chords(im)
cr = ps.filters.flood(cr, mode='size')
plt.imshow(cr)
```
<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig3.png" width="50%"></img>
</p>
## Calculating metrics
The metrics sub-module contains several common functions that analyze
binary tomogram directly. Examples are simple porosity, as well as
two-point correlation function.
``` python
data = ps.metrics.two_point_correlation_fft(im)
fig = plt.plot(*data, 'bo-')
plt.ylabel('probability')
plt.xlabel('correlation length [voxels]')
```
<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig4.png" width="50%"></img>
</p>
The metrics sub-module also contains a suite of functions that produce
plots based on values in images that have passed through a filter, such
as local thickness.
``` python
mip = ps.filters.porosimetry(im)
data = ps.metrics.pore_size_distribution(mip, log=False)
plt.imshow(mip)
# Now show intrusion curve
plt.plot(data.R, data.cdf, 'bo-')
plt.xlabel('invasion size [voxels]')
plt.ylabel('volume fraction invaded [voxels]')
```
<p align="center">
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig5.png" width="50%"></img>
<img src="https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig6.png" width="50%"></img>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "porespy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jeff Gostick <jgostick@gmail.com>, Amin Sadeghi <amin.sadeghi@live.com>",
"keywords": "direct numerical simulation,image analysis,porous materials,voxel images",
"author": null,
"author_email": "PoreSpy Team <jgostick@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/b7/25f77f10cd1aecd10eac5e91550405d0bdd3e9da3d9cf5e00871eaf3fd4a/porespy-2.4.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/porespy_logo.png\" width=\"25%\"></img>\n</p>\n\n[](https://pypi.python.org/pypi/porespy/)\n[](https://codecov.io/gh/PMEAL/PoreSpy)\n\n# What is PoreSpy?\n\n**PoreSpy** is a collection of image analysis tools used to extract\ninformation from 3D images of porous materials (typically obtained from\nX-ray tomography). There are many packages that offer generalized image\nanalysis tools (i.e **Skimage** and **Scipy.NDimage** in the Python environment,\n**ImageJ**, **MatLab**'s Image Processing Toolbox), but they all require building\nup complex scripts or macros to accomplish tasks of specific use to\nporous media. The aim of **PoreSpy** is to provide a set of pre-written\ntools for all the common porous media measurements. For instance, it's possible to perform a mercury intrusion simulation with a single function call (e.g. ``porespy.filters.porosimetry``).\n\n**PoreSpy** relies heavily on\n[scipy.ndimage](https://docs.scipy.org/doc/scipy/reference/ndimage.html)\nand [scikit-image](https://scikit-image.org/) also known as **skimage**.\nThe former contains an assortment of general image analysis tools such\nas image morphology filters, while the latter offers more complex but\nstill general functions such as watershed segmentation. **PoreSpy** does not\nduplicate any of these general functions so you will also have to\ninstall and learn how to use them to get the most from **PoreSpy**. The\nfunctions in PoreSpy are generally built up using several of the general functions offered by **skimage** and **scipy**. There are a few\nfunctions in **PoreSpy** that are implemented natively, but only when\nnecessary.\n\n# Capabilities\n\n**PoreSpy** consists of the following modules:\n\n - `generators`: Routines for generating artificial images of porous\n materials useful for testing and illustration\n - `filters`: Functions that accept an image and return an altered\n image\n - `metrics`: Tools for quantifying properties of images\n - `networks`: Algorithms and tools for analyzing images as pore networks\n - `simulations`: Physical simulations on images including drainage\n - `visualization`: Helper functions for creating useful views of the\n image\n - `io`: Functions for outputting image data in various formats for use in\n common software\n - `tools`: Various useful tools for working with images\n\n## Gallery\n\n<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/montage.svg\" width=\"85%\"></img>\n</p>\n\n## Cite as\n\n> *Gostick J, Khan ZA, Tranter TG, Kok MDR, Agnaou M, Sadeghi MA, Jervis\n> R.* **PoreSpy: A Python Toolkit for Quantitative Analysis of Porous Media\n> Images.** Journal of Open Source Software, 2019.\n> [doi:10.21105/joss.01296](https://doi.org/10.21105/joss.01296)\n\n# Installation\n\nFor detailed and up to date installation instructions, [see here](https://porespy.org/installation.html)\n\n# Contributing\n\nIf you think you may be interested in contributing to PoreSpy and wish\nto both *use* and *edit* the source code, then you should clone the\n[repository](https://github.com/PMEAL/porespy) to your local machine,\nand install it using the following PIP command:\n\n pip install -e \"C:\\path\\to\\the\\local\\files\\\"\n\nFor information about contributing, refer to the [contributors\nguide](https://github.com/PMEAL/porespy/blob/dev/CONTRIBUTING.md)\n\n# Acknowledgements\n\nPoreSpy is grateful to [CANARIE](https://canarie.ca) for their generous funding over the past few years. We would also like to acknowledge the support of [NSERC of Canada](https://www.nserc-crsng.gc.ca/) for funding many of the student that have contributed to PoreSpy since it's inception in 2014.\n\n# Examples\n\nThe following code snippets illustrate generating a 2D image, applying\nseveral filters, and calculating some common metrics. A set of examples\nis included in this repo, and can be [browsed\nhere](https://github.com/PMEAL/porespy/tree/dev/examples).\n\n\n## Generating an image\n\nPoreSpy offers several ways to generate artificial images, for quick\ntesting and developmnet of work flows, instead of dealing with\nreading/writing/storing of large tomograms.\n\n``` python\nimport porespy as ps\nimport matplotlib.pyplot as plt\nim = ps.generators.blobs(shape=[500, 500], porosity=0.6, blobiness=2)\nplt.imshow(im)\n```\n<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig1.png\" width=\"50%\"></img>\n</p>\n\n## Applying filters\n\nA common filter to apply is the local thickness, which replaces every\nvoxel with the radius of a sphere that overlaps it. Analysis of the\nhistogram of the voxel values provides information about the pore size\ndistribution.\n\n``` python\nlt = ps.filters.local_thickness(im)\nplt.imshow(lt)\n```\n<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig2.png\" width=\"50%\"></img>\n</p>\n\nA less common filter is the application of chords that span the pore\nspace in a given direction. It is possible to gain information about\nanisotropy of the material by looking at the distributions of chords\nlengths in each principle direction.\n\n``` python\ncr = ps.filters.apply_chords(im)\ncr = ps.filters.flood(cr, mode='size')\nplt.imshow(cr)\n```\n<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig3.png\" width=\"50%\"></img>\n</p>\n\n## Calculating metrics\n\nThe metrics sub-module contains several common functions that analyze\nbinary tomogram directly. Examples are simple porosity, as well as\ntwo-point correlation function.\n\n``` python\ndata = ps.metrics.two_point_correlation_fft(im)\nfig = plt.plot(*data, 'bo-')\nplt.ylabel('probability')\nplt.xlabel('correlation length [voxels]')\n```\n<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig4.png\" width=\"50%\"></img>\n</p>\n\nThe metrics sub-module also contains a suite of functions that produce\nplots based on values in images that have passed through a filter, such\nas local thickness.\n\n``` python\nmip = ps.filters.porosimetry(im)\ndata = ps.metrics.pore_size_distribution(mip, log=False)\nplt.imshow(mip)\n# Now show intrusion curve\nplt.plot(data.R, data.cdf, 'bo-')\nplt.xlabel('invasion size [voxels]')\nplt.ylabel('volume fraction invaded [voxels]')\n```\n<p align=\"center\">\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig5.png\" width=\"50%\"></img>\n <img src=\"https://github.com/PMEAL/porespy/raw/dev/docs/_static/images/fig6.png\" width=\"50%\"></img>\n</p>\n",
"bugtrack_url": null,
"license": null,
"summary": "A set of tools for analyzing 3D images of porous materials",
"version": "2.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/PMEAL/porespy/issues",
"Documentation": "https://porespy.org",
"Homepage": "https://porespy.org",
"Repository": "https://github.com/PMEAL/porespy"
},
"split_keywords": [
"direct numerical simulation",
"image analysis",
"porous materials",
"voxel images"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb2627a584fc66600c1706da6fe292ea30be670a28002eb75a35243382171669",
"md5": "8b92448a0abc81eb2b535eebecc59799",
"sha256": "6c253ee59e6fcc147f5ed9bf346eeb16175ce0bfc41a8eb691eeeca8b69aec65"
},
"downloads": -1,
"filename": "porespy-2.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b92448a0abc81eb2b535eebecc59799",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 164716,
"upload_time": "2024-03-12T03:51:43",
"upload_time_iso_8601": "2024-03-12T03:51:43.698913Z",
"url": "https://files.pythonhosted.org/packages/eb/26/27a584fc66600c1706da6fe292ea30be670a28002eb75a35243382171669/porespy-2.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e4b725f77f10cd1aecd10eac5e91550405d0bdd3e9da3d9cf5e00871eaf3fd4a",
"md5": "c75ef81372c524940e041e3fc8434314",
"sha256": "104c82c6942b798ece026d66d947a0a259d43479131580617d9186513e7d2273"
},
"downloads": -1,
"filename": "porespy-2.4.1.tar.gz",
"has_sig": false,
"md5_digest": "c75ef81372c524940e041e3fc8434314",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20112672,
"upload_time": "2024-03-12T03:51:46",
"upload_time_iso_8601": "2024-03-12T03:51:46.446368Z",
"url": "https://files.pythonhosted.org/packages/e4/b7/25f77f10cd1aecd10eac5e91550405d0bdd3e9da3d9cf5e00871eaf3fd4a/porespy-2.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-12 03:51:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PMEAL",
"github_project": "porespy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "porespy"
}
JSON
