PPM_RC

PPM_RC: Distributed-Memory Parallel Image Segmentation

Here you can download the source code (at the time of publication) of the Parallel Discrete Region Competition algorithm implemented as a PPM client application. The algorithm is a particle-based discrete multi-region segmentation method that runs on distributed image data over computer clusters. No computer needs to be able to store the whole image, and the computers communicate over the network in order to collectively solve the global segmentation task. This code has originally been developed and implemented by Yaser Afshar during his Ph.D. project in the MOSAIC Group. It is described in the following publication:

Y. Afshar and I. F. Sbalzarini. A parallel distributed-memory particle method enables acquisition-rate segmentation of large fluorescence microscopy images. PLoS ONE, 11(4):e0152528, 2016. (PDF)


Distributed Parallel Segmentation
Four processors jointly segmenting a piecewise smooth image consisting of two shaded objects on a shaded background. The image is decomposed into four blocks, each stored on a different computer. The initial segmentation (left) evolves to the final result (right) by communication among the computers. The software is currently maintained by Yaser Afshar at the MOSAIC Group.

The source code and tutorial are also available on github under https://github.com/yafshar/PPM_RC.

While the github version is under constant development, the file provided for download here is an archive snapshot of the software at the time of publication of the above paper. It is this version that has been used to produce all figures and results reported in the above publication, but will not be further updated or maintained. It is provided here for transparency and reproducibility only.


PPM_RC is a parallel distributed-memory implementation of Discrete Region Competition, a general-purpose image segmentation method that has originally been described here:

J. Cardinale, G. Paul, and I. F. Sbalzarini. Discrete region competition for unknown numbers of connected regions. IEEE Trans. Image Process., 21(8):3531–3545, 2012. (PDF)

and which has also been implemented as a sequential ITK filter in C++, available from here.

In order to ensure financial support for our project and allow further development of this software, please cite above publications in all your documents and manuscripts that made use of this software. Thanks a lot!

Requirements for building PPM_RC

You will need the following software installed on your system in order to build and use PPM_RC:

  • Fortran compiler with Fortran 2003 support
  • C compiler
  • C++ compiler
  • METIS 5: You may download the latest release of METIS 5 from http://glaros.dtc.umn.edu/gkhome/metis/metis/download.
  • An MPI distribution (recommended): Either get OpenMPI, mpich2, or any other MPI-3 compliant MPI library. If you are compiling PPM_RC on a cluster, most likely your sysadmin will have already an MPI installed on the system.
  • PPML & PPM core: PPM_RC is based on PPML and PPM core 1.2.2 (object-oriented Fortran 2003) and can only be linked against this version. Please get and install PPM and PPML first from the PPM Download Page. Compile PPM core 1.2.2 latest development version before attempting to compiling this package. Make sure that all requirements are compiled with the same compiler that you will be using to build PPM core.
  • TIFF Library: For handling huge images, or very large collections of images, breaking the 4 gigabytes boundary, you need a TIFF Library which supports BigTIFF.
  • BOOST C++ Library: For more information Please refer to: http://www.boost.org

Building PPM_RC

PPM_RC is built in 3 simple steps:

  1. Step 1: Configuring PPM_RC - Run the `configure` script to allow the build system to determine the correct options to compile PPM_RC. It is very important to give `configure` the correct settings to make sure PPM_RC is compiled correctly. To find out which settings are supported type

    `./configure --help`

    This is what will be returned:

    `configure` configures PPM_RC to adapt to many kinds of systems.
    Usage: `./configure [OPTION]... [VAR=VALUE]...`

    To assign environment variables (e.g., `CC, CFLAGS...`), specify them as `VAR=VALUE`. See below for descriptions of some of the useful variables. Defaults for the options are specified in brackets.

    ~~~~~~~~~~
    Configuration:
    -h, --help display this help and exit
    -V, --version display version information and exit
    ~~~~~~~~~~

    By default, `make` will create an executable file in `$ppm_rc_root/run`. For better control, use the options below.
    Optional Features:
    ~~~~~~~~~~
    --enable-mpi use MPI (default is no), If the MPI implementation of your choice provides compile wrappers that are in PATH, I can set them myself, choose: guess (I will choose the first implementation I can find). Else, set CC, CXX and FC to the appropriate compiler wrappers (safest)
    --enable-debug enable debug data generation (default is no)
    --enable-linux compile for linux (default is no)
    ~~~~~~~~~~

    Optional Packages:
    ~~~~~~~~~~
    --with-ppm=path set the path to the ppm core library - THIS FLAG IS MANDATORY
    --with-metis=path user defined path to METIS library
    --with-boost=path Specify the root directory for boost library
    --with-tiff=path user defined path to TIFF library
    ~~~~~~~~~~

    Some influential environment variables:
    ~~~~~~~~~~
    FC Fortran compiler command
    FCFLAGS Fortran compiler flags
    LDFLAGS linker flags, e.g. -L<lib dir> if you have libraries in a nonstandard directory <lib dir>
    LIBS libraries to pass to the linker, e.g. -l<library>
    CC C compiler command
    CFLAGS C compiler flags
    CPPFLAGS (Objective) C/C++ preprocessor flags, e.g. -I<include dir> if you have headers in a nonstandard directory <include dir>
    CXX C++ compiler command
    CXXFLAGS C++ compiler flags
    CPP C preprocessor
    CLIBS libraries to pass to the linker for C compiler, e.g. -l<library>
    ~~~~~~~~~~

    Use these variables to override the choices made by `configure' or to help it to find libraries and programs with nonstandard names/locations.
    Report bugs to the package provider.

    Following options are especially important:
    • `--enable-mpi`: If you will be running PPM_RC on a parallel environment (a cluster) using MPI. If your system is properly configured then this should be enough information for PPM_RC build system to find the MPI libraries and compiler wrappers needed. If this goes wrong, you may ommit this option and set compiler wrapper and libraries in `FC` and `LDFLAGS` respectively.
    • `--enable-linux`: Set this if you're compiling/running on a Linux system
    • `--prefix`: If you like to install PPM_RC and the target directory is not the system's standard directory (`/usr/`) then you have to define this directory here. You must provide the full path. It is not necessary to install PPM_RC. Building it and leaving it in the compilation directory is sufficient. If you provide a directory here it must already exist - it will not be created by the build system.
    • `FC` etc.: If you wish to not use MPI or you have to specify exactly which compiler executable should be used, then you can use this flag to set your compiler.
    • `LDFLAGS`: If metis was not installed in one of the system's standard library directories (e.g. `/usr/lib`) you must specify the directory to the libmetis.a file here.

    Here two examples on how you could run the configure command
    `.configure` on Linux cluster using OpenMPI (and intel compilers, wrapped)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ./configure CPP=cpp --enable-mpi --enable-linux --with-ppm=/home/usr/ppmcore
    --with-metis=/home/usr/metis --with-boost=/home/usr/boost_1_58_2 --with-tiff=/home/usr/tiff4
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~

    `./configure` on Mac OS X workstation with HomeBrew compilers
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ./configure CPP=cpp-5 --enable-mpi --with-ppm=/home/usr/ppmcore
    --with-metis=/home/usr/metis --with-boost=/home/usr/boost_1_58_2 --with-tiff=/home/usr/tiff4
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~

    `./configure` on a computer with OpenMPI installed in a non-standard location
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ./configure --enable-mpi FC=/opt/openmpi/1.10.2/bin/mpif90 CC=/opt/openmpi/1.10.2/bin/mpicc CXX=/opt/openmpi/1.10.2/bin/mpic++
    --with-ppm=/home/usr/ppmcore --with-metis=/home/usr/metis --with-boost=/home/usr/boost_1_58_2 --with-tiff=/home/usr/tiff4
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~

  2. Step 2: Compiling PPM_RC - If the configure process finished successfully you should see on your screen a message that the Makefile has been generated (and you can now find this Makefile in this directory). Now you can simply run make to compile PPM_RC:

    `make`

    If you encounter problems in the compilation process (compile errors) please, first check if you have set everything correctly in your environment. If the error persists, please send us a bug-report detailing the previous steps you have performed. Also, please include the `config.log` file and the output of `export`. Finally, if yu are using MPI, please include which MPI library you are using.

  3. Step 3: Installing PPM_RC (optional) - If you wish to install PPM_RC you can now use the `make install` command to do so:

    `make install`

    If the target directory is part of the system, you will most probably get a message that you have insufficient rights. If you have a root account you can use in this case the sudo command to override this security setting.

    `sudo make install`

    Your PPM_RC is installed.
Enjoy the PPM_RC experience!

IN NO EVENT SHALL THE MOSAIC GROUP BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE MOSAIC GROUP HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE MOSAIC GROUP SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE MOSAIC GROUP HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.