Grain segmentation

Identification of individual grains in microscopic images

Contents

• Purpose
• Dependencies
• Installation
  • pyimagej
  • ImagePy
  • full installation
• Usage
• Troubleshooting
• Contributing
• Design considerations

Purpose

Dependencies

Depending on the features you want to use, the requirements are different:

1. Image segmentation algorithms The only requirements are Python 3 with the following packages:
   • scipy
   • numpy
   • scikit-image (a.k.a. skimage)
2. 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)
3. 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

Installation

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.

Installing pyimagej

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.

Installing ImagePy

1. For Windows, there is a standalone package (quite an old version)
2. You can install ImagePy with pip: pip install imagepy. To install it from your current Python environment, use python -m pip install imagepy.
3. If you want the latest version, download the source:

   git clone git://github.com/Image-Py/imagepy
   cd imagepy

   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

   python setup.py install

   If you want an isolated environment, use conda before installing:

   conda env create # creates the "imagepy" environment
   conda activate imagepy
   python setup.py install

4. To check whether ImagePy is recognized:

    conda list | grep "imagepy"

   When the installation is done, you can start ImagePy with python -m imagepy.

If you want to remove the environment you have just created, type

conda remove --name imagepy --all

Full installation

Since both ImagePy and ImageJ are needed for a good segmentation result, it is recommended to install both.

1. Install Conda and Python 3 (Anaconda already ships them)
2. Install Java
3. Activate the conda-forge channel

   conda config --add channels conda-forge
   conda config --set channel_priority strict

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

5. Activate the new environment, called combined. This is important so that ImagePy is installed there.

   conda activate combined
   

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

7. Download and install ImagePy

   git clone https://github.com/Image-Py/imagepy
   cd imagepy
   python setup.py install

8. The following commands must both give a non-empty output

   conda list | grep "imagepy"
   conda list | grep "pyimagej"

9. 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/

Usage

Depending on which parts you want to use of this code, make sure you meet the requirements and that you successfully install the dependencies.

Only Python without GUI

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.

Using the GUI

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.

Troubleshooting

imagej.init() throws an error

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.

Getting help

If you have other problems using these tools, open an issue on GitHub after reading the existing ones or discuss it on Gitter.

Contributing

Contributions to this open source project are welcome, supposing you accept our philosophy.

How can you contribute?

• Send a pull request
• Discuss ideas on Gitter

What can you help in?

• 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

Design considerations

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.