Identification of individual grains in microscopic images
Depending on the features you want to use, the requirements are different:
- Image segmentation algorithms
The only requirements are Python 3 with the following packages:
- scipy
- numpy
- scikit-image (a.k.a. skimage)
- Use ImagePy for manual corrections
- additional packages
- the source code of ImagePy itself
- Conda (only if you want to install it to an isolated environment)
- Use algorithms from ImageJ/Fiji
To call the functions of ImageJ from within Python, the pyimagej connector is used. Its dependencies:
- Conda (not necessary but highly recommended)
- additional packages
To use the algorithms, no installation is needed. Just keep the files grain_segmentation.py and gala_light.py, found in the src/ directory, together.
Note: it is important that you first install pyimagej and not ImagePy because pyimagej has several requirements on the versions of the Python packages and on Python as well. If you want both pyimagej and ImagePy, rather follow the full installation guide. If you want to use ImageJ, you need to have Java installed (OpenJDK 8 is recommended). Check the Java versions installed on your machine:
update-java-alternatives --list
You can now install pyimagej following the official installation instructions.
- For Windows, there is a standalone package (quite an old version)
- You can install ImagePy with pip:
pip install imagepy
. To install it from your current Python environment, usepython -m pip install imagepy
. - If you want the latest version, download the source:
You can now choose to install it to the current Python environment or create a separate environment for it. In the first case, just type
git clone git://github.com/Image-Py/imagepy cd imagepy
If you want an isolated environment, use conda before installing:python setup.py install
conda env create # creates the "imagepy" environment conda activate imagepy python setup.py install
- To check whether ImagePy is recognized:
When the installation is done, you can start ImagePy with
conda list | grep "imagepy"
python -m imagepy
.
If you want to remove the environment you have just created, type
conda remove --name imagepy --all
Since both ImagePy and ImageJ are needed for a good segmentation result, it is recommended to install both.
- Install Conda and Python 3 (Anaconda already ships them)
- Install Java
- Activate the conda-forge channel
conda config --add channels conda-forge conda config --set channel_priority strict
- Install pyimagej and those requirements for ImagePy that can be fetched from conda-forge. We create an isolated environment so that it does not interfere with our existing Python installation.
conda create -n combined pyimagej openjdk=8 numba numpy-stl openpyxl pandas pydicom pypubsub read-roi scikit-image scikit-learn shapely wxpython xlrd xlwt markdown python-markdown-math moderngl
- Activate the new environment, called combined. This is important so that ImagePy is installed there.
conda activate combined
- We will use pip to install the remaining required packages for ImagePy, which couldn't be obtained from conda-forge
python -m pip install pystackreg
- Download and install ImagePy
git clone https://github.com/Image-Py/imagepy cd imagepy python setup.py install
- The following commands must both give a non-empty output
conda list | grep "imagepy" conda list | grep "pyimagej"
- Delete the ImagePy folder. We don't need it any more and we want to avoid accidentally launching ImagePy from here.
cd .. rm -r imagepy/
Depending on which parts you want to use of this code, make sure you meet the requirements and that you successfully install the dependencies.
The basic algorithms are contained in grain_segmentation.py and gala_light.py, found in the src/ directory. The methods in the GrainSegmentation class are given in an order that is expected in a usual workflow (e.g. filtering before segmentation). An actual example can be found in the test_gs.py script.
Image segmentation algorithms do not give perfect results in our case. A fully automatic workflow is not possible. You need manual corrections to split large regions (result of undersegmentation) or merge tiny ones (result of oversegmentation). This is done by comparing the segmented image with the original one. ImagePy is a good choice for this purpose.
If you choose to use pyimagej, check if the environment variable JAVA_HOME is found on your path
printenv | grep JAVA_HOME
If you get no result, set JAVA_HOME to /usr/lib/jvm/java-8-openjdk-amd64/
(or something similar). To do so, edit the environment variable
- from the shell (or put it into
.bashrc
to make it permanent):export JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64/" export PATH=$PATH:$JAVA_HOME/bin
- from within you Python session:
import os os.environ['JAVA_HOME'] = '/usr/lib/jvm/java-8-openjdk-amd64/'
If
import imagej
ij = imagej.init()
throws no error, pyimagej work properly on your machine.
If you have other problems using these tools, open an issue on GitHub after reading the existing ones or discuss it on Gitter.
Contributions to this open source project are welcome, supposing you accept our philosophy.
- Send a pull request
- Discuss ideas on Gitter
- Suggestions for improved segmentation algorithms
This is the most important aspect. - Improve the documentation
Let me know about typos and inconsistencies in the documentation (this README file, comments in the source code). - Improve the ImagePy integration
As I am new to ImagePy, suggestions are definitely welcome. Those who are new to ImagePy, the best sources are the- official page
- detailed tutorial on how to write ImagePy plugins
- image.sc forum, where you can find tutorials and can ask questions
The philosophy behind this project:
- Open source
Being on the public domain is important for open science (reproducibility) and helps collaboration. - Free software
The project only uses components that are free. - Modularity
The GUI and the image segmentation algorithms are completely separated. We also strive for as few dependencies as possible. - Conforming to coding conventions
As code is read more often than written, we adhere to the PEP guidelines. Specifically, PEP 8 for code layout and naming conventions, and PEP 257 for documentation. - Well-documented
The documentation is written at the same time as the code. It not only ensures that the documentation does not lag behind the code but it also promotes better understanding of the algorithms.