Plot a pixel image.
# S3 method for im
plot(x, ...,
main,
add=FALSE, clipwin=NULL,
col=NULL, reverse.col=FALSE,
valuesAreColours=NULL, log=FALSE,
ncolours=256, gamma=1,
ribbon=show.all, show.all=!add,
drop.ribbon=FALSE,
ribside=c("right", "left", "bottom", "top"),
ribsep=0.15, ribwid=0.05, ribn=1024,
ribscale=1, ribargs=list(), riblab=NULL, colargs=list(),
useRaster=NULL, workaround=FALSE, zap=1,
do.plot=TRUE,
addcontour=FALSE, contourargs=list(),
background=NULL, clip.background=FALSE) # S3 method for im
image(x, ...,
main,
add=FALSE, clipwin=NULL,
col=NULL, reverse.col=FALSE,
valuesAreColours=NULL, log=FALSE,
ncolours=256, gamma=1,
ribbon=show.all, show.all=!add,
drop.ribbon=FALSE,
ribside=c("right", "left", "bottom", "top"),
ribsep=0.15, ribwid=0.05, ribn=1024,
ribscale=1, ribargs=list(), riblab=NULL, colargs=list(),
useRaster=NULL, workaround=FALSE, zap=1,
do.plot=TRUE,
addcontour=FALSE, contourargs=list(),
background=NULL, clip.background=FALSE)
The colour map used. An object of class "colourmap".
Also has an attribute "bbox" giving a bounding box
for the plot (containing the main colour image, the
colour ribbon if plotted, and the background if given).
If a ribbon was plotted, there is also an attribute
"bbox.legend" giving a bounding box for the ribbon image.
Text annotation occurs outside these bounding boxes.
Also has an attribute "at" giving the axis positions
of the tick marks next to the colour ribbon.
This is the plot method for the class "im".
[It is also the image method for "im".]
The pixel image x is displayed on the current plot device,
using equal scales on the x and y axes.
If ribbon=TRUE, a legend will be plotted.
The legend consists of a colour ribbon and an axis with tick-marks,
showing the correspondence between the pixel values and the colour map.
Arguments ribside, ribsep, ribwid control the placement
of the colour ribbon.
By default, the ribbon is placed at the right of the main image.
This can be changed using the argument ribside.
The width of the ribbon is ribwid times the size of the pixel
image, where `size' means the larger of the width and the height.
The distance separating the ribbon and the image is ribsep times
the size of the pixel image.
The ribbon contains the colours representing ribn
different numerical values, evenly spaced between the minimum and
maximum pixel values in the image x, rendered according to
the chosen colour map.
The argument ribargs controls the annotation of the
colour ribbon. It is a list of arguments to be passed to
image.default,
axis and
axisTicks.
To plot the colour ribbon without the axis and
tick-marks, use ribargs=list(axes=FALSE).
To ensure that the numerals or symbols printed next to the colour map
are oriented horizontally, use ribargs=list(las=1).
To double the size of the numerals or symbols,
use ribargs=list(cex.axis=2).
To control the number of tick-marks, use ribargs=list(nint=N)
where N is the desired number of intervals (so there will
be N+1 tickmarks, subject to the vagaries of R internal code).
The argument riblab contains text that should be displayed
in the margin next to the ribbon. Alternatively riblab may be a
list of arguments to be passed to
mtext; in that case riblab$text should
specify the text to be displayed, while other arguments
can specify a different
location for the text (e.g. riblab$side = 1 for text at the
bottom of the ribbon) and a different font and colour if desired.
The argument ribscale is used
to rescale the numerical values printed next to the colour map,
for convenience.
For example if the pixel values in x range between 1000 and
4000, it would be sensible to use ribscale=1/1000 so that the
colour map tickmarks would be labelled 1 to 4.
Normally the pixel values are displayed using the colours given in the
argument col. This may be either
an explicit colour map (an object of class
"colourmap", created by the command colourmap).
This is the best way to ensure
that when we plot different images, the colour maps are consistent.
a character vector or integer vector
that specifies a set of colours.
The colour mapping will be stretched to match the range of
pixel values in the image x. The mapping of pixel values
to colours is determined as follows.
the values FALSE and
TRUE are mapped to the colours col[1] and
col[2] respectively.
The vector col should have length 2.
the factor levels levels(x)
are mapped to the entries of col in order. The vector
col should have the same length as levels(x).
By default, the range of pixel values in x
is divided into n = length(col)
equal subintervals, which are mapped to the colours in col.
(If col was not specified, it defaults to a vector of 255
colours.)
Alternatively if the argument zlim is given, it should be
a vector of length 2 specifying an interval of real numbers.
This interval will be used instead of the range of pixel
values. The interval from zlim[1] to zlim[2] will be
mapped to the colours in col. This facility enables the user to
plot several images using a consistent colour map.
Alternatively if the argument breaks is given,
then this specifies
the endpoints of the subintervals that are mapped to each colour.
This is incompatible with zlim.
The arguments col and zlim or breaks
are then passed to the function image.default.
For examples of the use of these arguments,
see image.default.
a function in the R language
with an argument named range
or inputs. If col is a function with an argument named range,
and if the pixel values of x are numeric values,
then the colour values will be determined by evaluating
col(range=range(x)). The result of this evaluation
should be a character vector containing colour values, or
a "colourmap" object. Examples of such functions
are beachcolours and beachcolourmap. If col is a function with an argument named inputs,
and if the pixel values of x are discrete values (integer,
logical, factor or character),
then the colour values will be determined by evaluating
col(inputs=p) where p is the set of possible pixel
values. The result should be a character vector
containing colour values, or a "colourmap" object.
a function in the R language with first argument
named n.
The colour values will be determined by evaluating
col(n) where n is the
number of distinct pixel values, up to a maximum of 128.
The result of this evaluation
should be a character vector containing color values.
Examples of such functions are
heat.colors,
terrain.colors,
topo.colors and
cm.colors.
If col is missing or col=NULL, the default colour values
are the linear, perceptually uniform colour sequence given by
Kovesi[[29,"values"]].
If spatstat.options("monochrome") has been set to TRUE
then all colours will be converted to grey scale values.
If reverse.col=TRUE, the sequence of colour values specified
by col will be reversed (unless valuesAreColours=TRUE).
Other graphical parameters controlling the display of both the pixel image
and the ribbon can be passed through the ... arguments
to the function image.default.
A parameter is handled only if it is one of the following:
a formal argument of image.default
that is operative when add=TRUE.
one of the parameters
"main", "asp", "sub", "axes", "xlab", "ylab"
described in plot.default.
one of the parameters
"ann", "cex", "font", "cex.axis", "cex.lab", "cex.main", "cex.sub",
"col.axis", "col.lab", "col.main", "col.sub",
"font.axis", "font.lab", "font.main", "font.sub"
described in par.
the argument box, a logical value specifying whether
a box should be drawn.
Images are plotted using a bitmap raster if useRaster=TRUE
or by drawing polygons if useRaster=FALSE.
Bitmap raster display (performed by rasterImage)
tends to produce better results, but is not supported on all graphics devices.
The default is to use bitmap raster display if it is
supported according to dev.capabilities.
Alternatively, the pixel values could be directly interpretable as colour values in R. That is, the pixel values could be character strings that represent colours, or values of a factor whose levels are character strings representing colours.
If valuesAreColours=TRUE, then the pixel values will
be interpreted as colour values and displayed using these colours.
If valuesAreColours=FALSE, then the pixel values will
not be interpreted as colour values, even if they could be.
If valuesAreColours=NULL, the algorithm will guess
what it should do. If the argument col is given,
the pixel values will not be interpreted as colour values. Otherwise,
if all the pixel values are strings that represent colours, then
they will be interpreted and displayed as colours.
If pixel values are interpreted as colours,
the arguments col and ribbon will be ignored,
and a ribbon will not be plotted.
Baddeley, A., Rubak, E. and Turner, R. (2015) Spatial Point Patterns: Methodology and Applications with R. Chapman and Hall/CRC Press.
im.object,
colourmap,
contour.im,
persp.im,
hist.im,
image.default,
spatstat.options,
default.image.colours
# an image
Z <- setcov(owin())
plot(Z)
plot(Z, ribside="bottom")
# stretchable colour map
plot(Z, col=rainbow)
plot(Z, col=terrain.colors(128), axes=FALSE)
# fixed colour map
tc <- colourmap(rainbow(128), breaks=seq(-1,2,length=129))
plot(Z, col=tc)
# colour map function, with argument 'range'
plot(Z, col=beachcolours, colargs=list(sealevel=0.5))
# tweaking the plot
plot(Z, main="La vie en bleu", col.main="blue", cex.main=1.5,
box=FALSE,
ribargs=list(col.axis="blue", col.ticks="blue", cex.axis=0.75),
riblab=list(text="couleur", side=1, col="blue", offset=1, font=2))
# add axes and axis labels
plot(Z, axes=TRUE, ann=TRUE, xlab="Easting", ylab="Northing")
# add contour lines
plot(Z, addcontour=TRUE, contourargs=list(col="white", drawlabels=FALSE))
# log scale
V <- eval.im(exp(exp(Z+2))/1e4)
plot(V, log=TRUE, main="Log scale")
# it's complex
Y <- exp(Z + V * 1i)
plot(Y)
Run the code above in your browser using DataLab