PoreSpy

PoreSpy: A Python Toolkit for Quantitative Analysis of Porous Media Images - Published in JOSS (2019)

Science Score: 100.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 4 DOI reference(s) in README and JOSS metadata
○
Academic publication links
✓
Committers with academic emails
10 of 40 committers (25.0%) from academic institutions
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

3d-images image-analysis porespy porous-materials porous-media python scientific-visualization tomography voxel-generator

Keywords from Contributors

standardization correlation meshing bioinformatics fem parallel solar effectsize effect-size cohens-d

Scientific Fields

Artificial Intelligence and Machine Learning Computer Science - 87% confidence

Last synced: 4 months ago · JSON representation ·

Repository

A set of tools for characterizing and analyzing 3D images of porous materials

Basic Info

Host: GitHub
Owner: PMEAL
License: mit
Language: Python
Default Branch: dev
Homepage: https://porespy.org
Size: 1.49 GB

Statistics

Stars: 364
Watchers: 24
Forks: 107
Open Issues: 32
Releases: 27

Topics

3d-images image-analysis porespy porous-materials porous-media python scientific-visualization tomography voxel-generator

Created over 10 years ago · Last pushed 4 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

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.

PoreSpy relies heavily on scipy.ndimage and scikit-image 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 tries not to 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

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

Installation

For detailed and up to date installation instructions, see here

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 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

Acknowledgements

PoreSpy is grateful to CANARIE for their generous funding over the past few years. We would also like to acknowledge the support of NSERC of Canada 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.

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)

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)

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)

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]')

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.poresizedistribution(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]') ```

Owner

Name: PMEAL
Login: PMEAL
Kind: organization
Email: jgostick@gmail.com
Location: Waterloo, ON

Website: pmeal.com
Repositories: 9
Profile: https://github.com/PMEAL

Porous Materials Engineering and Analysis Lab

JOSS Publication

PoreSpy: A Python Toolkit for Quantitative Analysis of Porous Media Images

Published

May 01, 2019

DOI

10.21105/joss.01296

Volume 4, Issue 37, Page 1296

Authors

Jeff T. Gostick

Department of Chemical Engineering, University of Waterloo, Waterloo, ON, Canada

Zohaib A. Khan

Department of Chemical Engineering, University of Waterloo, Waterloo, ON, Canada

Thomas G. Tranter

Department of Chemical Engineering, University of Waterloo, Waterloo, ON, Canada, Department of Chemical Engineering, University College London, London, United Kingdom

Matthew D.r. Kok

Department of Chemical Engineering, University College London, London, United Kingdom, Department of Chemical Engineering, McGill University, Montreal, QC, Canada

Mehrez Agnaou

Department of Chemical Engineering, University of Waterloo, Waterloo, ON, Canada

Mohammadamin Sadeghi

Department of Chemical Engineering, McGill University, Montreal, QC, Canada

Rhodri Jervis

Department of Chemical Engineering, University College London, London, United Kingdom

Editor

Bruce E. Wilson

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Gostick"
  given-names: "Jeff"
  orcid: "https://orcid.org/0000-0001-7736-7124"
title: "PoreSpy"
url: "https://github.com/PMEAL/porespy"
preferred-citation:
  type: article
  authors:
  - family-names: "Gostick"
    given-names: "Jeff"
    orcid: "https://orcid.org/0000-0001-7736-7124"
  - family-names: "Khan"
    given-names: "Zohaib A."
  - family-names: "Tranter"
    given-names: "Thomas"
  - family-names: "Kok"
    given-names: "Matthew"
  - family-names: "Agnaou"
    given-names: "Mehrez"
  - family-names: "Sadeghi"
    given-names: "Mohammadamin"
  - family-names: "Jervis"
    given-names: "Rhodri"
  doi: "10.21105/joss.01296"
  journal: "Journal of Open Source Software"
  title: "PoreSpy: A python toolkit for quantitative analysis of porous media images"
  year: 2019

Papers & Mentions

Total mentions: 1

Use of deep learning for structural analysis of computer tomography images of soil samples

DOI: 10.1098/rsos.201275
OpenAlex ID: https://openalex.org/W3150393068
Published: March 2021

Last synced: 2 months ago

GitHub Events

Total

Issues event: 104
Watch event: 52
Delete event: 43
Member event: 1
Issue comment event: 109
Push event: 255
Pull request event: 89
Fork event: 10
Create event: 59

Last Year

Issues event: 104
Watch event: 52
Delete event: 43
Member event: 1
Issue comment event: 109
Push event: 255
Pull request event: 89
Fork event: 10
Create event: 59

Committers

Last synced: 8 months ago

All Time

Total Commits: 3,355
Total Committers: 40
Avg Commits per committer: 83.875
Development Distribution Score (DDS): 0.432

Past Year

Commits: 291
Committers: 9
Avg Commits per committer: 32.333
Development Distribution Score (DDS): 0.241

Top Committers

Name	Email	Commits
Jeff Gostick	j**k@g**m	1,907
Amin Sadeghi	a**i@l**m	662
Author	a**s@g**m	160
Zohaib	z**q@y**m	139
Ni2M	n**h@u**a	116
Tom Tranter	t**r@u**a	71
Hamed Fathiannasab	h**n@u**a	40
Matthew Lam	m**m@e**a	37
madeline_am	m**e@u**a	37
Vasu Venkateshwaran	v**l@g**m	27
Tom Tranter	t**r@g**m	26
rickyfann3265	r**7@l**a	19
mdrkok	m**k@g**m	17
Rafael Arenhart	r**t@l**r	13
Bryan W. Weber	b**r@g**m	7
Mehrez Agnaou	m**b@g**m	7
Pascal Ruzzante	p**e@g**m	7
Anthero1	a**v@g**m	6
Mike McKague	m**9@g**m	6
Sreeyuth Lal	s**h@g**m	6
github-actions	4****]	5
Rômulo Cenci	r**i@l**r	5
Hamed Fathiannasab	h**n@g**m	3
James Butler	j**r@s**m	3
Jihye Oh	j**h@u**a	3
ajavadim	a**m@u**a	3
amirDahari1	a**i@m**l	3
David Haberthür	d**r@u**h	3
Scott Zero	S**o@w**m	3
Zohaib		2
and 10 more...

Committer Domains (Top 20 + Academic)

uwaterloo.ca: 6 ltrace.com.br: 2 ing.uc3m.es: 1 cederstrand.dk: 1 warriorlife.net: 1 dlr.de: 1 wlgore.com: 1 unibe.ch: 1 mail.huji.ac.il: 1 sonovol.com: 1 live.ca: 1 edu.uwaterloo.ca: 1 github.com: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 185
Total pull requests: 189
Average time to close issues: 9 months
Average time to close pull requests: 27 days
Total issue authors: 33
Total pull request authors: 21
Average comments per issue: 1.11
Average comments per pull request: 1.16
Merged pull requests: 151
Bot issues: 0
Bot pull requests: 26

Past Year

Issues: 52
Pull requests: 94
Average time to close issues: about 2 months
Average time to close pull requests: 9 days
Issue authors: 13
Pull request authors: 8
Average comments per issue: 0.67
Average comments per pull request: 0.72
Merged pull requests: 71
Bot issues: 0
Bot pull requests: 20

View more stats

Top Authors

Issue Authors

jgostick (100)
ma-sadeghi (34)
amirDahari1 (5)
heinsimon (5)
morendong (3)
mkaguer (3)
xiaorong117 (3)
lucianoguedes8 (2)
yojeep (1)
Curf (1)
likeduck (1)
ivonindima (1)
Kyle-RuidongLI (1)
Maoxinmaoxin (1)
xiangWu-WW (1)

Pull Request Authors

jgostick (113)
ma-sadeghi (30)
github-actions[bot] (13)
dependabot[bot] (13)
habi (8)
Anthero1 (4)
mkaguer (4)
rickyfann (4)
heinsimon (2)
emmanuel-ferdman (2)
cmaloney111 (2)
amirDahari1 (2)
takeruhukushima (2)
PascalRuzzante (2)
Daniel-olaO (2)

Top Labels

Issue Labels

bug (21) enhancement (14) api (14) discussion (11) easy (11) maint (9) doc (6) feature request (5) help wanted (4) breaking change (3) high priority (3) tests (2) documentation (2) performance (2) maintenance (1) proposal (1) question (1) new (1)

Pull Request Labels

high priority (13) dependencies (13) github_actions (13) maint (5) doc (1)

Packages

Total packages: 2
Total downloads:
- pypi 2,798 last-month

Total dependent packages: 0
(may contain duplicates)
Total dependent repositories: 10
(may contain duplicates)
Total versions: 35
Total maintainers: 2

pypi.org: porespy

A set of tools for analyzing 3D images of porous materials

Homepage: https://porespy.org
Documentation: https://porespy.org
License: MIT License
Latest release: 2.4.3
published 4 months ago

Versions: 26
Dependent Packages: 0
Dependent Repositories: 10
Downloads: 2,798 Last month

Rankings

Stargazers count: 4.2%

Dependent repos count: 4.6%

Forks count: 4.8%

Average: 5.9%

Downloads: 6.0%

Dependent packages count: 10.1%

Maintainers (2)

jgostick aminsadeghi

Last synced: 4 months ago

conda-forge.org: porespy

PoreSpy is a collection of image analysis tool 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 the 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.

Homepage: https://github.com/PMEAL/porespy/
License: MIT
Latest release: 2.2.2
published about 3 years ago

Versions: 9
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Forks count: 19.7%

Stargazers count: 24.7%

Average: 32.4%

Dependent repos count: 34.0%

Dependent packages count: 51.2%

Last synced: 4 months ago

Dependencies

setup.py pypi

dask *
deprecated *
edt *
imageio *
loguru *
matplotlib *
numba *
numpy *
numpy-stl *
openpnm *
pandas *
psutil *
pyevtk *
pyfastnoisesimd *
scikit-fmm *
scikit-image *
scipy *
tqdm *
trimesh *

.github/workflows/bump-version-dev.yml actions

actions/checkout v3 composite
actions/setup-python v2 composite
stefanzweifel/git-auto-commit-action v4 composite

.github/workflows/bump-version.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
repo-sync/pull-request v2 composite

.github/workflows/cleanup-tags.yml actions

actions/checkout v2 composite

.github/workflows/examples.yml actions

FedericoCarboni/setup-ffmpeg v2 composite
actions/cache v2 composite
actions/checkout v2 composite
actions/setup-python v2 composite

.github/workflows/gh-pages.yml actions

actions/cache v2 composite
actions/checkout v2 composite
actions/setup-python v2 composite
conda-incubator/setup-miniconda v2 composite
peaceiris/actions-gh-pages v3 composite

.github/workflows/publish-to-pypi.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
pypa/gh-action-pypi-publish master composite

.github/workflows/release-notes.yml actions

Roang-zero1/github-create-release-action master composite
actions/checkout v2 composite

.github/workflows/test-duration-logger.yml actions

EndBug/add-and-commit v7 composite
actions/cache v2 composite
actions/checkout v2 composite
actions/setup-python v2 composite

.github/workflows/tests.yml actions

actions/cache v2 composite
actions/checkout v2 composite
actions/setup-python v2 composite
codecov/codecov-action v1 composite

.github/workflows/verify-pip-installation.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite

requirements/conda.txt pypi

dask *
deprecated *
edt *
imageio *
matplotlib *
numba *
numpy *
numpy-stl *
pandas *
psutil *
pyevtk *
rich *
scikit-fmm *
scikit-image *
scikit-learn *
scipy *
tqdm *
trimesh *

requirements/docs.txt pypi

ipykernel *
ipython *
ipywidgets *
jupyterlab_widgets *
mock *
myst-nb *
pandoc *
pydata-sphinx-theme =0.9
sphinx *
sphinx-copybutton *
sphinx-design *

requirements/tests.txt pypi

codecov * test
coverage * test
jupyter * test
nbval * test
pytest * test
pytest-cache * test
pytest-cov * test
pytest-custom-exit-code * test
pytest-pycodestyle * test
pytest-split * test

requirements/examples.txt pypi

imageio *
numpy-stl *
pyevtk *
pyfastnoisesimd *
scikit-fmm *
scikit-learn *
tensorflow *
trimesh *

requirements.txt pypi

PoreSpy

Science Score: 100.0%

Keywords

Keywords from Contributors

Scientific Fields

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

What is PoreSpy?

Capabilities

Gallery

Cite as

Installation

Contributing

Acknowledgements

Examples

Generating an image

Applying filters

Calculating metrics

Now show intrusion curve

Owner

JOSS Publication

PoreSpy: A Python Toolkit for Quantitative Analysis of Porous Media Images

Authors

Editor

Tags

Citation (CITATION.cff)

Papers & Mentions

Use of deep learning for structural analysis of computer tomography images of soil samples

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: porespy

Rankings

Maintainers (2)

conda-forge.org: porespy

Rankings

Dependencies