Laboratoire RDP » Biophysics Team » lsm3d

{{TOC}}

h1. lsm3d - Tools for segmenting 3D images of plant tissues at multiple scales using the level set method

One of the main technical challenges in the reconstruction of plant tissues from 3D confocal images remains the faithful segmentation at the cellular level. A typical issue with segmentation based on watershed methods is the weaker staining of some outer periclinal walls. This systematically causes segmentation errors as holes on the tissue surface.

We detect the outer surface of the tissue using level set method (lsm_contour). We enhance the signal of the outer periclinal walls by the detected outer surface. Also, we propose a new edge function, based on second order derivatives of the image, for a level set used to segment the tissue at cellular level (lsm_cells).

The "lsm3d" tools:

- *lsm_contour* --> detects the outer surface of the tissue

- *lsm_cells* --> used to cellular segmentation or nuclei detection

h2. Dependencies

The levelset tools make use of the CImg image processing C++ library, which in turn needs Xlib library. Furthermore, the lsm_cells tool is parallelized using OpenMP.

In particular, if you do not have Xlib on your computer, you may add it:

* on Ubuntu:

<pre>

sudo apt-get install libx11-dev

</pre>

* on Mac OS:

install xQuartz from www.xquartz.org

h2. Download

In a terminal go to the directory where you wish to download and install the tool

<pre>

cd Path_to_your_directory

</pre> and then download using svn

<pre>

svn --username $USER checkout http://forge.cbp.ens-lyon.fr/svn/levelsetmethod/lsm3D

</pre>

h2. Compile

<pre>

cd lsm3D

./lsm3D_compile.sh

</pre>

The binaries will be in the lsm3D/bin folder. Add this folder to your PATH by adding in your .bashrc file

<pre>

export PATH=$PATH:Path_to_your_directory/lsm3D/bin

</pre>

Troubleshooting if problems with compilation :

In the file lsm3d/lsm3D_compile.sh

- you might have to choose an appropriate compiler, which supports OpenMP.

- you might need to precise the location of the X11 library in the compilation options.

For more detailed information on the method and usage please see the [[Wiki]].

h2. Methods and usage

The main idea of the level set method in image segmentation is to evolve a contour until it fits a desired object in the image. A  level set function (LSF) is defined on the image (one value per pixel), and the contour is defined as it's zero crossing points. The function is positive inside the contour and negative outside of it. At each time step, the values of the LSF are updated in each pixel, and thus the zero crossing points change and the contour evolves. The LSF's evolution is such that an energy is minimized, which in turn is usually based on the image properties (gradient, intensity...) and the geometrical aspects of the contour (curvature, size...).

h3. lsm_contour --> detects the outer surface of the tissue 

!>lsm_contour_100.png!The LSF is initialized with a linear threshold, which roughly separates the background from the cells. The threshold is linear in order to adjust for the image intensity variation along the z-axis. The function takes +c0 values inside the initial contour and -c0 outside, the area in the contour being the background. The contour evolves attracted mainly by the maximum gradient, corresponding to the edge of the cell walls. There are also a curvature term, to obtain a smoother contour, and an accelerating area term to push the contour towards the boundaries. At each time step, the background growth is measured. The algorithm stops when the growth stays in a small interval near zero for ten consecutive iterations.

*Usage*

In order to check the syntax, just lounch the binary without any argument. It will give as output

<pre>

Usage : lsm_contour img t_up t_down a b smooth perUp perDown

Examples for parameter values:

------------------------------

img : grayscale image of cells, (.inr or .inr.gz)

Upper threshold : t_up = 20

Down threshold : t_down = 5

Area term : a = 0 (0.5, 1)

Curvature term : b = 0 (1)

Gaussian filter : smooth = 1 (0, if image already filtered)

Stop criteria : the contour evolution is in [perDown,perUp] for 10 consecutive iterations

     perUp = 0.002, perDown = -0.002

</pre>

In order to test it on an image file "sample-stack.inr.gz", lounch the binary with parameters :

<pre>

lsm_contour sample-stack.inr.gz 20 10 0 0 1 0.002 -0.002

</pre>

The detected contour is in the directory "sample-stack_LSMcont20-10a0b0s1".

h3. lsm_cells --> for cellular or nuclear segmentation

!>lsm_cells_100.png!The detection of cell-shapes is done in 3 steps :

- eroding the watershed segmentation and initialize a function for each cell

- evolve independently each cell's contour, attract by the maximal gradient (the inside edge of the cell walls)

- evolve simultaneously every cell's contour, attract by the maximal intensity (center of the cell walls)

In the last step, every cell evolves for one iteration and then possible overlap is checked. An overlap region is considered not segmented. A cell can't evolve in an other cell area : overlap can only happen in a same iteration. At each iteration, the growth of the segmented areas is measured, and the algorithm stops when this growth becomes null.

*Usage*

You can recall the syntax any time by lounching the binary without any argument:

<pre>

Usage : lsm_cells img img_wat img_contour erosion [a b smooth lsm_type]

----------------- 

img : grayscale image of cells, (.inr or .inr.gz)

img_wat : image of seeds, (.inr or .inr.gz)

img_contour : mask, where cells do not evolve, (.inr or .inr.gz)

              if 'None', then cells can evolve on the whole image

erosion : amount of erosion of seeds for initialisation (uint8) --> -2, 0, 2

              if 0, then no erosion or dilation

              if negative, then a dilation is performed

a : area term (float) --> 0 or 0.5 or 1 (the default is 0.5)

              if negative, the object retracts

              if positive, the object inflates

b : curvature term (float) --> 0 or 1 (the default is 0)

gamma : scale parameter (float>0) --> 0.5 or 1 (the default is 1)

smooth : gaussian blur to apply to the image (int) --> 0 or 1 (the default is 0)

lsm_type : image, gradient or hessien based evolution --> 'i', 'g' or 'h' (the default is g)

</pre>

Applying it to the image "sample-stack.inr.gz" as the level sets are initialised by the watershed segmentation of the same image

<pre>

lsm_cells sample-stack.inr.gz sample-stack-watershed.inr.gz 'None' 2 0.3 0 0.2 1 'h'

</pre>

you will get the new segmentation in the "sample-stack-watershed_cellLSM-d2-a0.3-b0-g0.2-s1-h" folder. Or if you would like to use a mask image as background, you can make the test with the previously detected contour as a mask, like

<pre>

lsm_cells sample-stack.inr.gz sample-stack-watershed.inr.gz sample-stack_LSMcont20-10a0b0s1/sample-stack_LSMcont20-10a0b0s1.inr.gz 2 0.3 0 0.2 1 'h'

</pre>