\HeaderA{moments}{Image moments and moment invariants}{moments}
\aliasA{cmoments}{moments}{cmoments}
\aliasA{rmoments}{moments}{rmoments}
\aliasA{smoments}{moments}{smoments}
\begin{Description}\relax
Computes moments and invariant moments from image objects.
\end{Description}
\begin{Usage}
\begin{verbatim}
  moments(x, ref)
  cmoments(x, ref)
  rmoments(x, ref)
  smoments(x, ref, pw=3, what="scale")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An \code{Image} object or an array containing object masks.
Object masks are sets of pixels with the same unique integer value.
\item[\code{ref}] An \code{Image} object or an array, containing the
intensity values of the objects.
\item[\code{pw}] A numeric value specifying the maximum moment order to
compute. Default is 3.
\item[\code{what}] A character string partially matching \code{central} or
\code{scale}, specifiying what kind of moments to compute. Default
is \code{scale}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{moments} returns the features returned by \code{cmoments}, 
\code{rmoments} and the features \code{m.n20}, \code{m.n11},
\code{m.n02}, \code{m.theta}, \code{m.l1}, \code{m.l2} and
\code{m.ecc} for each objet. See \code{Definitions} for details
on features.

\code{cmoments} returns the features \code{m.pxs}, \code{m.int}, \code{m.x}
and \code{m.y} for each objet. 

\code{rmoments} returns Hu's translation/rotation/scale 7 invariant
moments \code{m.Ik} for each object, where k spans from 1 to 7.

\code{smoments} returns for each object the central moments \eqn{mu_pq}{}
if \code{what}=\code{central} or the scale invariant moments \eqn{nu_pq}{} if
\code{what}=\code{scale}. The variables (p, q) span the range [0, pw].
\end{Details}
\begin{Value}
\code{moments}, \code{cmoments} and \code{rmoments} returns a matrix
(or a list of matrices if \code{x} contains multiple frames) of
features computed of the objects present in \code{x} and using the
intensity values of \code{ref}.

\code{smoments} returns a 3-dimensional array of size (\code{pw+1},
\code{pw+1}, \code{n}) where \code{n} is the maximal value of
\code{x}, or a list of such arrays if \code{x} contains multiple frames.
\end{Value}
\begin{Section}{Definitions}
Image moments \eqn{m_pq}{} are defined for the k-th object in \code{x} by:
\eqn{m_pq = sum_{i,j st. x_ij = k} i^p * j^q * ref_ij}{}.

Central moments \eqn{mu_pq}{} are defined for the k-th object in \code{x} by:
\eqn{mu_{pq} = sum_{i,j st. x_ij = k} (i - m_10/m_00)^p * (j -
m_01/m_00)^q * ref_{ij}}{}. Central moments are invariant by translation.

Scale moments \eqn{nu_pq}{} are defined for the k-th object in \code{x} by:
\eqn{nu_{pq} = mu_pq / mu_00^(1+ (p+q)/2)}{}. Scale moments are
invariant by translation and scaling.

Features returned by \code{moments}, \code{cmoments} and
\code{rmoments} are defined by:
\Itemize{
\item \code{m.pxs} = \eqn{sum_{i,j st. x_ij = k} 1 }{}
\item \code{m.int} = \eqn{m_00}{}
\item \code{m.x} = \eqn{m_10 / m_00}{}
\item \code{m.y} = \eqn{m_01 / m_00}{}
\item \code{m.n20} = \eqn{nu_20}{}
\item \code{m.n11} = \eqn{nu_11}{}
\item \code{m.n02} = \eqn{nu_02}{}
\item \code{m.theta} = \eqn{0.5 * atan(2*mu_11/(mu_20-mu_02))}{}
\item \code{m.l1} = largest eigenvalue of the covariance matrix [\eqn{mu_20}{}, \eqn{mu_11}{} ;
\eqn{mu_11}{}, \eqn{mu_02}{}]/\eqn{m_00}{}
\item \code{m.l2} = smallest eigenvalue of the covariance matrix
\item \code{m.ecc} = \eqn{sqrt(1-m.l2/m.l1)}{}
\item \code{m.Ik} = k-th Hu's moment, see References.
}

Properties:
\Itemize{
\item \code{m.pxs} is the surface of the objects, in pixels.
\item \code{m.int} is the mass of the object.
\item (\code{m.x}, \code{m.y}) is the center of gravity of the object.
\item \code{m.n20}, \code{m.n11} and \code{m.n02} are translation/scale
invariant moments.
\item \code{m.theta} characterizes the orientation of an object in radians.
\item 2*sqrt(\code{m.l1}) and 2*sqrt(\code{m.l2}) are the semi-major
and semi-minor axes of the object and have the dimension of a length.
\item \code{m.Ik} is the translation/scale/rotation invariant k-th Hu's moment.
}
\end{Section}
\begin{Author}\relax
Oleg Sklyar, \email{osklyar@ebi.ac.uk}, 2007
\end{Author}
\begin{References}\relax
M. K. Hu, \emph{Visual Pattern Recognition by Moment Invariants}, IRE Trans.
Info. Theory, vol. IT-8, pp.179-187, 1962

\emph{Image moments}: \url{http://en.wikipedia.org/wiki/Image_moments}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{getFeatures}{getFeatures}}, \code{\LinkA{bwlabel}{bwlabel}}, \code{\LinkA{watershed}{watershed}}, \code{\LinkA{propagate}{propagate}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## load cell nucleus images
  x = readImage(system.file('images', 'nuclei.tif', package='EBImage'))
  if (interactive()) display(x)

  ## computes object mask
  y = thresh(x, 10, 10, 0.05)
  y = opening(y, makeBrush(5, shape='disc'))
  mask = fillHull(bwlabel(y))
  if (interactive()) display(mask, title='Cell nuclei')

  ## moments
  m = moments(mask, x)
  mc = do.call(rbind, m)
  print(mc[1:5,])
  cat('Mean nucleus size is', mean(mc[,'m.pxs']), '\n')
  cat('Mean nucleus eccentricity is', mean(mc[,'m.ecc']), '\n')

  ## paint nuclei with an eccentricity higher than 0.85
  maskb = mask
  for (i in 1:dim(mask)[3]) {
    id = which(m[[i]][,'m.ecc']<0.85)
    z = maskb[,,i]
    z[!is.na(match(z, id))] = 0
    maskb[,,i] = z
  } 
  img = paintObjects(maskb, channel(x, 'rgb'), col=c(NA, 'red'), opac=c(0,0.7))
  if (interactive()) display(img, title='Nuclei with high eccentricity')
\end{ExampleCode}
\end{Examples}

