\HeaderA{frameDist}{Calculate pairwise distances between image frames or frames of two images}{frameDist}
\aliasA{frameDist,Image,Image-method}{frameDist}{frameDist,Image,Image.Rdash.method}
\aliasA{frameDist,Image,missing-method}{frameDist}{frameDist,Image,missing.Rdash.method}
\keyword{manip}{frameDist}
\begin{Description}\relax
Given two images with multiple frames, \code{frameDist} calculates a matrix of
distances between frames (the more similar are the images, the smaller are
the distances). Prerequisite: images should be centered and rotationally and
scale aligned. The function is recommended with \code{\LinkA{stackObjects}{stackObjects}} with
arguments \code{rotate=combine=TRUE}.
\end{Description}
\begin{Usage}
\begin{verbatim}
  ## S4 method for signature 'Image, Image':
  frameDist(x, y, r, g, b, blur=TRUE, 
      method="dist", verbose, ...)
  ## S4 method for signature 'Image, missing':
  frameDist(x, y, r, g, b, blur=TRUE, 
      method="dist", verbose, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x,y}] A image stacks. 
\item[\code{r,b,g}] If \code{x} and \code{y} are in TrueColor mode, these values
specify weights of red, green and blue channels in the resulting distance. 
\item[\code{blur}] A logical indicating whether frames ought to be blurred before
comparison (\code{TRUE} recommended). 
\item[\code{method}] Method to use: \code{dist} - Euclidian distance, \code{dot} -
dot product. 
\item[\code{verbose}] Provides additional output as the function can be lengthy. 
\item[\code{...}] Reserved. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
For Grayscale images, the distance of each pair of frames, \code{xf} and 
\code{yf}, is calculated as \code{mean(abs(xf-yf))}, where \code{mean} is 
taken over the pixels with at least \code{xf} or \code{yf} being non-zero. 
For TrueColor images, the distance is calculated as 
\code{mean(sqrt(r*rc\textasciicircum{}2+g*gc\textasciicircum{}2+b*bc\textasciicircum{}2))}, where \code{rc,gc,bc} are \code{[0,1]}
ranged values of red, green and blue channels and \code{r,g,b} are the weights.
Again, the mean is taken only over non-zero pixels.
\end{Details}
\begin{Value}
A matrix of distances. If \code{y} is missing - a square symmetric matrix for
the distances between frames in the same image with diagonal elements set at
\code{Inf}.
\end{Value}
\begin{Author}\relax
Oleg Sklyar, \email{osklyar@ebi.ac.uk}, 2007
\end{Author}
\begin{SeeAlso}\relax
\code{
  \LinkA{stackObjects}{stackObjects}
}
\end{SeeAlso}

