R/labelStack.R

In ornelles/EBImageExtra: Helper Functions for EBImage

#' Label Frames of an Image Stack
#' 
#' Add labels to a plotted image stack
#' 
#' @param x A recently plotted \code{Image} object or \code{array} of such
#'   objects
#' @param labels Either a \code{logical} value (default of \code{TRUE})
#'   to number each frame \emph{or} a vector of labels to be applied to
#'   each frame.
#' @param nx The number of frames in the x-direction of the image stack.
#'   If missing, a square tile of images will be assumed.
#' @param col Color of the label to be added.
#' @param offset A numeric vector of length 1 or 2 specifying the position
#'   of the label in each frame with default values of \code{c(0.95, 0.05)} to
#'   place the label at the top \emph{right} corner. Note that this default
#'   differs from that in \code{\link{plotStack}}.
#' @param adj One or two values in [0, 1] which specify the \code{x} (and
#'   optionally \code{y}) adjustment or "justification" of the label
#'   where 0 indicates left/bottom, 1 indicates right/top, and 0.5 centered.
#'   Note that this default differs from that in \code{\link{plotStack}}.
#'   See the \code{\link{text}} function for details.
#' @param ... Additional values passed to \code{\link{text}} for labeling/
#' 
#' @details
#' This code is called after having plotted an \code{Image} object, typically
#' by \code{\link{plotStack}} or \code{plot(img, all = TRUE)}. If \code{labels}
#' is \code{TRUE}, each frame of the image will be labeled by frame number.
#' If \code{FALSE}, no labeling will occur. Otherwise, labels generated by 
#' \code{as.graphicsAnnot} will be placed in the top right corner of each frame
#' by default or according to \code{offset} and \code{adj}.
#' 
#' @seealso
#' \code{\link{plotStack}}, which allows for automatically labeling the plotted
#' image and \code{\link{locatorStack}}, which provides an interface for
#' selecting frames from the stack.
#' 
#' @return
#' The image \code{x} is invisibly returned to permit passing the argument through
#' a pipe. This function primarily called to label a plotted image.
#' 
#' @examples
#' lighthouse <- readImage(system.file("extdata", "lighthouse.jpg", package="EBImageExtra"))
#' x <- EBImage::untile(lighthouse, c(4, 3), lwd = 0)
#' idx <- sample(1:12)
#' plotStack(x[,,,idx], label = TRUE)
#' labelStack(x, labels = paste("Original:", idx), offset = 0.5, adj = 0.5, col = "yellow")
#' 
#' @import EBImage
#' 
#' @export
#' 
labelStack <- function(x, labels = TRUE, nx, col = "white",
		offset = c(0.95, 0.05), adj = c(1, 1), ...)
{
	if(!is(x, "Image")) stop("'x' must be an Image object")
	if (length(offset) == 1) offset <- rep(offset, 2)
	if (length(adj) == 1) adj <- rep(adj, 2)
	nf <- numberOfFrames(x, type = "render")
	if (missing(nx)) nx <- ceiling(sqrt(nf))
	ss <- seq_len(nf)
	if (identical(labels, NULL) | identical(labels, TRUE))
		labels <- as.character(ss)
	else if (identical(labels, FALSE))
		labels <- ""
	else
		labels <- as.graphicsAnnot(labels)
	ix <- (ss - 1)%%nx
	iy <- (ss - 1)%/%nx
	dm <- dim(x)
	xx <- dm[1]*(ix + offset[1])
	yy <- dm[2]*(iy + offset[2])
	text(xx, yy, labels, adj = adj[1:2], col = col, ...)
	invisible(x)
}