\HeaderA{propagate}{Voronoi-based segmentation on image manifolds}{propagate}
\aliasA{propagate,Image,IndexedImage-method}{propagate}{propagate,Image,IndexedImage.Rdash.method}
\keyword{manip}{propagate}
\begin{Description}\relax
R implementation of the Voronoi-based image segmentation on image
manifolds [2].
\end{Description}
\begin{Usage}
\begin{verbatim}

  ## S4 method for signature 'Image, IndexedImage':
  propagate(x, seeds, mask=NULL, lambda=0.1, 
     ext=1, seed.centers=FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An object of \code{\LinkA{Image}{Image.Rdash.class}} to be segmented,
in the \code{\LinkA{Grayscale}{Grayscale}} mode. 
\item[\code{seeds}] An object of \code{\LinkA{IndexedImage}{IndexedImage.Rdash.class}} of the same
size as x in all three dimensions. This image provides seed points for object detection. 
\item[\code{mask}] An object of \code{\LinkA{Image}{Image.Rdash.class}} of the same
size as \code{x} in all three dimensions; in the \code{\LinkA{Grayscale}{Grayscale}} mode.
All zero regions will be excluded from object detection. 
\item[\code{lambda}] A numeric value. The regularisation parameter for the
distance calculations, determines the trade-off between the Euclidian distance in
the image plane and the contribution of the gradient of the values
in \code{x}. See details. 
\item[\code{ext}] Extension of the neighborhood to estimate image
gradient, in pixels in every direction from the central point, i.e.
ext=1 means a 3x3 neighborhood. 
\item[\code{seed.centers}] If \code{TRUE}, only centers of the seed points are left
in the seeds image supplied to the propagate algorithm. 
\item[\code{...}] Reserved. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The method operates by computing a discretized approximation of the
Voronoi regions for given seed points on a manifold with a metric
controlled by local image features.

The metric is a Riemannian metric defined in terms of the image I and
a regularization parameter lambda. With this metric the
distance between pixels used to let the given seeds grow outwards
(propagate) is

\begin{alltt}d\textasciicircum{}2 = (grad(I)\textasciicircum{}2 + lambda * (dx\textasciicircum{}2 + dy\textasciicircum{}2)) / (lambda + 1)\end{alltt}

The above formulation was proposed by Carpenter et al, however in the 
calculation we use a modified distance measture, in which sharp gradients
are downregulated and large distances additionally penalized. Effectively,
we use the following formula:

\begin{alltt}d = sqrt(grad(I)) + 1e-3*lambda * (dx\textasciicircum{}2+dy\textasciicircum{}2)\textasciicircum{}2\end{alltt}

The denominator is left out for speed reasons, so is the square root of the 
distance.

The gradient is calculated on a neighborhood of pixels (the width of which
is controlled by the argument \code{ext}) to avoid relying on single
(noisy) pixels. Lambda controls the weight of the Euclidian distance
term. In case of large
lambda, d turns into Euclidian distance in the \code{(x,y)}-plane.
For small lambda, the distance will be dominated by the intensity gradient.
\end{Details}
\begin{Value}
An image of \code{\LinkA{Image}{Image.Rdash.class}}, with the same object indexing as
\code{seeds}. No new objects are created, only those specified by
seeds are propagated. Use \code{\LinkA{getFeatures}{getFeatures}} to assign the
feature matrix.
\end{Value}
\begin{Section}{License}
The underlying \code{C++} code is based on code from CellProfiler
[1,3]. An LGPL license was granted by Thouis Jones to use this part
of CellProfiler's code for the \code{propagate} function.
\end{Section}
\begin{Author}\relax
Original CellProfiler code: Anne Carpenter <carpenter@wi.mit.edu>,
Thouis Jones <thouis@csail.mit.edu>, In Han Kang <inthek@mit.edu>.

Port for this package: Oleg Sklyar <osklyar@ebi.ac.uk> and Wolfgang Huber <huber@ebi.ac.uk>.
\end{Author}
\begin{References}\relax
\code{[1]} \emph{A. Carpenter, T.R. Jones, M.R. Lamprecht, C. Clarke, I.H. Kang,
O. Friman, D. Guertin, J.H. Chang, R.A. Lindquist, J. Moffat,
P. Golland and D.M. Sabatini}, "CellProfiler: image analysis software
for identifying and quantifying cell phenotypes", Genome Biology 2006, 7:R100

\code{[2]} \emph{T. Jones, A. Carpenter and P. Golland},
"Voronoi-Based Segmentation of Cells on Image Manifolds",
CVBIA05 (535-543), 2005

\code{[3]} CellProfiler: http://www.cellprofiler.org
\end{References}
\begin{SeeAlso}\relax
\code{
    \LinkA{IndexedImage}{IndexedImage.Rdash.class}, \LinkA{IndexedImage}{IndexedImage.Rdash.class}, \LinkA{IndexedImage}{IndexedImage.Rdash.class}, \LinkA{IndexedImage}{IndexedImage.Rdash.class}
}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  
  ## load images of nuclei (seed points later)
  f <- paste( system.file(package="EBImage"), "images/Gene1_G.tif", sep="/" )
  ii = readImage(f)
  ## normalize images
  ii = normalize(ii, separate=TRUE)
  ## segment
  mask = thresh(ii, 25, 25, 0.02)
  ## refine segmentation with morphology filters
  mk3 = morphKern(3)
  mk5 = morphKern(5)
  mask = dilate(erode(closing(mask, mk5), mk3), mk5)
  ## index objects with 'watershed'
  io = watershed( distmap(mask), 1.5, 1)
  if (interactive()) display(io)

  ## load images of cells (the ones to segment with propagate)
  f <- paste( system.file(package="EBImage"), "images/Gene1_R.tif", sep="/" )
  xi = readImage(f)
  ## normalize images
  xi = normalize(xi, separate=TRUE)
  ## segment
  mask = thresh(xi, 40, 40, 0.0)
  ## refine segmentation with morphology filters
  mk7 = morphKern(7)
  mask = dilate(erode(closing(mask, mk7), mk5), mk7)
  ## index objects of xi with 'propagate' using ii as seeds
  xo = propagate(xi, io, mask, 1e-2, 2)
  if (interactive()) display(xo)
  
\end{ExampleCode}
\end{Examples}

