\HeaderA{haralickMatrix}{Co-occurrence matrices (GLCM) and Haralick texture features}{haralickMatrix}
\aliasA{haralickFeatures}{haralickMatrix}{haralickFeatures}
\aliasA{haralickFeatures,IndexedImage,Image-method}{haralickMatrix}{haralickFeatures,IndexedImage,Image.Rdash.method}
\aliasA{haralickMatrix,IndexedImage,Image-method}{haralickMatrix}{haralickMatrix,IndexedImage,Image.Rdash.method}
\keyword{manip}{haralickMatrix}
\begin{Description}\relax
A set of functions to compute the co-occurrence matrix (GLCM - gray level 
co-occurrence matrix) and haralick texture features of objects in an indexed image.
\end{Description}
\begin{Usage}
\begin{verbatim}

  ## S4 method for signature 'IndexedImage, Image':
  haralickMatrix(x, ref, nc = 32, ...)
  ## S4 method for signature 'IndexedImage, Image':
  haralickFeatures(x, ref, nc = 32, ...)

\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An object of \code{\LinkA{IndexedImage}{IndexedImage.Rdash.class}} used as a mask.
\item[\code{ref}] A \code{\LinkA{Grayscale}{Grayscale}} object of \code{\LinkA{Image-class}{Image.Rdash.class}}.
The texture is calculated from the data in this image.
\item[\code{nc}] A numeric value. Specifies the number of gray levels to separate
\code{ref} into when calculating the co-occurrence matrix. Defaults to 32
\item[\code{...}] Reserved. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{haralickMatrix} computes a co-occurrence matrix of dimension \code{nc * nc} 
for each object in an image.  The co-occurrence matrix is constructed
by assigning to element \code{[i,j]} the number of times a pixel of value
\code{i} is adjacent to a pixel of value \code{j}.

In order to achieve rotational invariance the co-occurrence matrix is
computed using four passes through each object.  Thus each pixel is
compared to four neighbours: right, below, diagonally down left and
diagonally down right.  In order to achieve symmetry in the
co-occurrence matrix the reciprocal of each of these scores is also
added.  Thus for each pixel we have have a score for comparison with each of the
surrounding pixels.

Finally the entire matrix is divided by the total
number of comparisons, giving a probability for each of the possible combinations.

\code{haralickFeatures} computes for each object in an image 12 Haralick 
texture features, calculated from the co-occurrence matrix. The feature names 
carry a \code{t.} prefix (t for texture). The features and their calculations are:

\describe{
\item[\code{asm}] Angular second moment: \code{sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc]p(i,j)\textasciicircum{}2}.
\item[\code{con}] Contrast: \code{sum[\_i=2\textasciicircum{}(2*nc)] n\textasciicircum{}2 *
    sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc] p(i,j), for all i,j s.t ABS(i - j) = n}.
\item[\code{cor}] Correlation of GLCM: \code{sum[\_i=1\textasciicircum{}nc]
    sum[\_j=1\textasciicircum{}nc]((i * j) * p(i,j) - mu\_x * mu\_y) / sigma\_x * sigma\_y}.
\item[\code{var}] Variance: \code{sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc](i - mu)\textasciicircum{}2.
    * p(i,j)}.
\item[\code{idm}] Inverse difference moment: \code{sum[\_i=1\textasciicircum{}nc]
    sum[\_j=1\textasciicircum{}nc] p(i,j) / (1 + (i - j)\textasciicircum{}2) }.
\item[\code{sav}] Sum average: \code{sum[\_i=2\textasciicircum{}(2*nc)] i * Px+y(i)}.
\item[\code{sva}] Sum variance: \code{sum[\_i=2\textasciicircum{}(2*nc)] (i - sen)\textasciicircum{}2 * Px+y(i)}.
\item[\code{sen}] Sum entropy: \code{-sum[\_i=2\textasciicircum{}(2*nc)] Px+y(i) * log(
    p(i,j) )}.
\item[\code{ent}] Entropy: \code{-sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc] p(i,j) *
    log( p(i,j) )}.
\item[\code{dva}] Difference variance: \code{sum[\_i=0\textasciicircum{}(nc-1)] (i\textasciicircum{}2) * Px-y(i)}.
\item[\code{den}] Difference entropy: \code{sum[\_i=0\textasciicircum{}(nc-1)] Px-y(i)
      * log( Px-y(i,j) )}.
\item[\code{f12}] Measure of correlation: \code{ABS(ent - HXY1) / HX}.
\item[\code{f13}] Measure of correlation: \code{sqrt( 1 - exp( -2
    *(HXY2 - ent) ) )}.
}

Where:
\describe{
\item[\code{p(i,j)}] The value in row i, column j of the co-occurrence
matrix.
\item[\code{Px(i)}] Partial probability density function.  Defined
by \code{sum[\_j=1\textasciicircum{}nc] p(i,j) }.
\item[\code{Py(j)}] Partial probability density function.  Defined
by \code{sum[\_i=1\textasciicircum{}nc] p(i,j) }.
\item[\code{mu\_x, mu\_y}] Are the means of \code{Px} and \code{Px}, the partial
probability density functions.
\item[\code{sigma\_x, sigma\_y}] Are the standard deviations of
\code{Px} and \code{Py}.
\item[\code{Px+y}] Is the probability of the co-occurrence matrix
co-ordinates summing to \code{x+y}.  It is defined as \code{Px+y(k) =
        sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc] p(i,j), i + j = k and k = 2,3,...,2*nc}.
\item[\code{Px-y}] Is the probability of the absolute value of the
difference between co-occurrence matrix
co-ordinates being equal to \code{x-y}.  It is defined as \code{Px-y(k) =
        sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc] p(i,j), ABS(i - j) = k and k =
        2,3,...,2*nc}.
\item[\code{HXY1}] \code{-sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc] p(i,j) * log(
        Px(i),Py(j) ) }.
\item[\code{HXY2}] \code{-sum[\_i=1\textasciicircum{}nc] sum[\_j=1\textasciicircum{}nc] Px(i)*Py(j) * log(
        Px(i),Py(j) ) }.
}
\end{Details}
\begin{Value}
For a single frame in \code{x} the result of \code{haralickMatrix} is an array of 
dimensions \code{nc} * \code{nc} * "the number of objects in the frame". 

\code{haralickFeatures} returns a matrix of dimensions "number of objects in 
the frame" * 12. 

For multiple frames a list of each of the above will be returned.
\end{Value}
\begin{Author}\relax
Mike Smith, \email{msmith@ebi.ac.uk}; Oleg Sklyar, \email{osklyar@ebi.ac.uk}, 2007
\end{Author}
\begin{References}\relax
R. M. Haralick, K Shanmugam and Its'Hak Deinstein (1979). \emph{Textural Features for Image 
Classification}. IEEE Transactions on Systems, Man and Cybernetics.
\end{References}
\begin{SeeAlso}\relax
\code{
  \LinkA{IndexedImage}{IndexedImage.Rdash.class}, \LinkA{IndexedImage}{IndexedImage.Rdash.class}, \LinkA{IndexedImage}{IndexedImage.Rdash.class}
}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## see example(getFeatures)
\end{ExampleCode}
\end{Examples}

