% fields, Tools for spatial data
% Copyright 2004-2011, Institute for Mathematics Applied Geosciences
% University Corporation for Atmospheric Research
% Licensed under the GPL -- www.gpl.org/licenses/gpl.html

\name{add.image}
\alias{add.image}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{ Adds an image to an existing plot.}
\description{
Adds an image to an existing plot. Simple arguments control the 
location and size. 
}
\usage{
add.image(xpos, ypos, z, adj.x = 0.5, adj.y = 0.5, 
image.width = 0.15, image.height = NULL, col = tim.colors(256), ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{xpos}{X position of  image in user coordinates }
  \item{ypos}{ Y position of  image in user coordinates }
  \item{z}{ Matrix of intensities comprising the image. }
 \item{adj.x}{ Location of image relative to x coordinate. 
 Most
common values are .5 (centered), 0 (right side of image at x) and  1 
(left side  of
image at x). These are the same conventions that are used for \code{adj} 
in
positioning text.}
  \item{adj.y}{Location of image relative to y coordinate.
Same rules as \code{adj.x}
}
  \item{image.width}{ Width of image as a fraction of the 
plotting region in horizontal direction. }
  \item{image.height}{ Height of image as a fraction of the
plotting region in horizontal direction. If NULL height is scaled to 
make image pixels square.}
  \item{col}{ Color table for image. Default is tim.colors.}
  \item{\dots}{Any other plotting arguments that are passed to the image 
function  }
}
\seealso{ image.plot, colorbar.plot, image, tim.colors }
\examples{
plot( 1:10, 1:10, type="n")
data( lennon)

add.image( 5,4,lennon, col=grey( (0:256)/256))
# reference lines 
xline( 5, col=2)
yline( 4,col=2) 

#
# add lennon right in the corner beyond the plotting region
# 

par(new=TRUE, plt=c(0,1,0,1), mar=c(0,0,0,0), usr=c(0,1,0,1))
add.image( 0,0, lennon, adj.x=0, adj.y=0) 

}
\keyword{ hplot }% at least one, from doc/KEYWORDS