\HeaderA{stackObjects}{Generate a stack of images for detected objects, one object per image}{stackObjects}
\aliasA{stackObjects,IndexedImage,Image,character-method}{stackObjects}{stackObjects,IndexedImage,Image,character.Rdash.method}
\aliasA{stackObjects,IndexedImage,Image,list-method}{stackObjects}{stackObjects,IndexedImage,Image,list.Rdash.method}
\aliasA{stackObjects,IndexedImage,Image,missing-method}{stackObjects}{stackObjects,IndexedImage,Image,missing.Rdash.method}
\aliasA{stackObjects,IndexedImage,Image,numeric-method}{stackObjects}{stackObjects,IndexedImage,Image,numeric.Rdash.method}
\keyword{manip}{stackObjects}
\begin{Description}\relax
From an indexed image the functions generates an image stack with one image
per object placing each object in the middle of the image. Objects can be
automatically rotated to align them along the horizontal axis.
\end{Description}
\begin{Usage}
\begin{verbatim}
  ## S4 methods for signatures 'x=IndexedImage,ref=Image,index=character'
  ## and 'x=IndexedImage,ref=Image,index=list' and
  ## S4 method for signature 'IndexedImage, Image,
  ##   numeric':
  stackObjects(x, ref, index, ...)

  ## S4 method for signature 'IndexedImage, Image,
  ##   missing':
  stackObjects(x, ref, index, combine, rotate, bg.col, ext, centerby, rotateby, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An object of \code{\LinkA{IndexedImage}{IndexedImage.Rdash.class}}.
Images must be Grayscale and carry object indexing information, like those
returned by \code{\LinkA{watershed}{watershed}} or \code{\LinkA{propagate}{propagate}}. 
\item[\code{ref}] A reference image containing images of the objects to be
stacked using \code{x} both as index and the mask. Can be in any
color mode. 
\item[\code{index}] Indexes of objects to stack. See details for supported
types. 
\item[\code{combine}] Called on a stack if images, specifies if the resulting
list of image stacks with individual objects should be combined into a single
image stack. Defaults to \code{FALSE}. 
\item[\code{rotate}] Specifies if the objects should be aligned rotationally.
Defaults to \code{TRUE}. 
\item[\code{bg.col}] Color for pixels outside the mask defined by \code{x}.
Defaults to \code{TRUE}. 
\item[\code{ext}] Extension of the target bounding box. See details. If not
given, \code{ext} is calculated from data. 
\item[\code{centerby,rotateby}] If \code{ref} is a TrueColor image, these character 
values specify which channel should be used to center and rotate objects. 
By default the image is converted by \code{\LinkA{channel}{channel}(ref,"gray")}. 
Other possible values are \code{"red", "green"} or \code{"blue"}. 
\item[\code{...}] Reserved. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The bounding box is set to be a square, which centre coinsides with the geometric
center of the object. The \code{ext} argument can be used to specified its size,
where edge length will be given by \code{2*ext+1}. If \code{ext} is not specified,
it is calculated from the data by taking the 95\% quantile of the vector of
\code{h.s2major} descriptor of \code{\LinkA{hullFeatures}{hullFeatures}} taken over all,
objects in the image. This descriptor specifies the extension of the object
along its major axis starting from its center.

The size of the bounding box is fixed for all frames to enable combining
the resulting frames into a single multiframe image.

\code{index} must be coersable to numeric to specify object indexes that
are taken into the resulting stack. It can be specified as \code{numeric}
directly only for images with 1 frame. For images with multiple frames it can
be either a \code{list} or a \code{character}. If specified as a \code{list},
it can be a named list of numeric indexes where names are converted to
\code{character} frame indexes in an arbitrary order, or it can be an unnamed
list of the same length as the number of frames. If specifies as \code{character},
each element must contain two numbers separated by a dot where the first number
is the index of the frame and the second one is the index of the object within
the frame, e.g. \code{"2.035"} will specify frame 2 and object 35.
\end{Details}
\begin{Value}
An image stack or a list of image stacks if \code{x} was itself a stack
(contained more than one image).
\end{Value}
\begin{Author}\relax
Oleg Sklyar, \email{osklyar@ebi.ac.uk}, 2006-2007
\end{Author}
\begin{SeeAlso}\relax
\code{
  \LinkA{tile}{tile}, \LinkA{tile}{tile}, \LinkA{tile}{tile}
}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

  ## load images
  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)

  ## stack individual objects
  s = stackObjects(io, ii, combine=FALSE)
  ## display stack of objects of from the first image
  if (interactive()) display(s[[1]])
  ## combine stacks of objects into a single stack
  s = combine(s)
  ## tile the stack into one frame
  t = tile(s)
  if (interactive()) display(t)
  
\end{ExampleCode}
\end{Examples}

