plot.im
Plot a Pixel Image
Plot a pixel image.
Usage
# S3 method for im
plot(x, …,
main,
add=FALSE, clipwin=NULL,
col=NULL, valuesAreColours=NULL, log=FALSE,
ncolours=256, gamma=1,
ribbon=show.all, show.all=!add,
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) # S3 method for im
image(x, …,
main,
add=FALSE, clipwin=NULL,
col=NULL, valuesAreColours=NULL, log=FALSE,
ncolours=256, gamma=1,
ribbon=show.all, show.all=!add,
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)
Arguments
- x
The pixel image to be plotted. An object of class
"im"
(seeim.object
).- …
Extra arguments passed to
image.default
to control the plot. See Details.- main
Main title for the plot.
- add
Logical value indicating whether to superimpose the image on the existing plot (
add=TRUE
) or to initialise a new plot (add=FALSE
, the default).- clipwin
Optional. A window (object of class
"owin"
). Only this subset of the image will be displayed.- col
Colours for displaying the pixel values. Either a character vector of colour values, an object of class
colourmap
, or afunction
as described under Details.- valuesAreColours
Logical value. If
TRUE
, the pixel values ofx
are to be interpreted as colour values.- log
Logical value. If
TRUE
, the colour map will be evenly-spaced on a logarithmic scale.- ncolours
Integer. The default number of colours in the colour map for a real-valued image.
- gamma
Exponent for the gamma correction of the colours. A single positive number.
- ribbon
Logical flag indicating whether to display a ribbon showing the colour map. Default is
TRUE
for new plots andFALSE
for added plots.- show.all
Logical value indicating whether to display all plot elements including the main title and colour ribbon. Default is
TRUE
for new plots andFALSE
for added plots.- ribside
Character string indicating where to display the ribbon relative to the main image.
- ribsep
Factor controlling the space between the ribbon and the image.
- ribwid
Factor controlling the width of the ribbon.
- ribn
Number of different values to display in the ribbon.
- ribscale
Rescaling factor for tick marks. The values on the numerical scale printed beside the ribbon will be multiplied by this rescaling factor.
- ribargs
List of additional arguments passed to
image.default
,axis
andaxisTicks
to control the display of the ribbon and its scale axis. These may override the…
arguments.- riblab
Text to be plotted in the margin near the ribbon. A character string or expression to be interpreted as text, or a list of arguments to be passed to
mtext
.- colargs
List of additional arguments passed to
col
if it is a function.- useRaster
Logical value, passed to
image.default
. Images are plotted using a bitmap raster ifuseRaster=TRUE
or by drawing polygons ifuseRaster=FALSE
. Bitmap raster display 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.- workaround
Logical value, specifying whether to use a workaround to avoid a bug which occurs with some device drivers in R, in which the image has the wrong spatial orientation. See the section on Image is Displayed in Wrong Spatial Orientation below.
- zap
Noise threshold factor. A numerical value greater than or equal to 1. If the range of pixel values is less than
zap * .Machine$double.eps
, the image will be treated as constant. This avoids displaying images which should be constant but contain small numerical errors.- do.plot
Logical value indicating whether to actually plot the image and colour ribbon. Setting
do.plot=FALSE
will simply return the colour map and the bounding box that were chosen for the plot.
Details
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 will be displayed
in the margin next to the ribbon.
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 commandcolourmap
). 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.- logical-valued images:
the values
FALSE
andTRUE
are mapped to the colourscol[1]
andcol[2]
respectively. The vectorcol
should have length 2.- factor-valued images:
the factor levels
levels(x)
are mapped to the entries ofcol
in order. The vectorcol
should have the same length aslevels(x)
.- numeric-valued images:
By default, the range of pixel values in
x
is divided inton = length(col)
equal subintervals, which are mapped to the colours incol
. (Ifcol
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 fromzlim[1]
tozlim[2]
will be mapped to the colours incol
. 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 withzlim
.The arguments
col
andzlim
orbreaks
are then passed to the functionimage.default
. For examples of the use of these arguments, seeimage.default
.
a
function
in the R language with an argument namedrange
orinputs
.If
col
is a function with an argument namedrange
, and if the pixel values ofx
are numeric values, then the colour values will be determined by evaluatingcol(range=range(x))
. The result of this evaluation should be a character vector containing colour values, or a"colourmap"
object. Examples of such functions arebeachcolours
andbeachcolourmap
.If
col
is a function with an argument namedinputs
, and if the pixel values ofx
are discrete values (integer, logical, factor or character), then the colour values will be determined by evaluatingcol(inputs=p)
wherep
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 namedn
. The colour values will be determined by evaluatingcol(n)
wheren
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 areheat.colors
,terrain.colors
,topo.colors
andcm.colors
.
If spatstat.options("monochrome")
has been set to TRUE
then all colours will be converted to grey scale values.
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 whenadd=TRUE
.one of the parameters
"main", "asp", "sub", "axes", "xlab", "ylab"
described inplot.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 inpar
.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 argumentcol
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.
Value
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 and the
colour ribbon if plotted).
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.
Complex-valued images
If the pixel values in x
are complex numbers,
they will be converted into four images containing the real and
imaginary parts and the modulus and argument,
and plotted side-by-side using plot.imlist
.
Monochrome colours
If spatstat.options("monochrome")
has been set to TRUE
,
then the image will be plotted in greyscale.
The colours are converted to grey scale values using
to.grey
.
The choice of colour map still has an effect, since it determines
the final grey scale values.
Monochrome display can also be achieved by
setting the graphics device parameter colormodel="grey"
when starting a new graphics device, or in a call to
ps.options
or pdf.options
.
Image Looks Like Noise
An image plot which looks like digital noise
can be produced when the pixel values are almost exactly equal
but include a tiny amount of numerical error.
To check this, look at the numerals plotted next to the colour ribbon,
or compute diff(range(x))
, to determine whether the range
of pixel values is almost zero. The behaviour can be suppressed
by picking a larger value of the argument zap
.
Image Rendering Errors and Problems
The help for image.default
and rasterImage
explains that
errors may occur, or images may be rendered incorrectly, on some
devices, depending on the availability of colours and other
device-specific constraints.
If the image is not displayed at all,
try setting useRaster=FALSE
in the call to plot.im
.
If the ribbon colours are not displayed, set
ribargs=list(useRaster=FALSE)
.
Errors may occur on some graphics devices if the image is very
large. If this happens, try setting useRaster=FALSE
in the
call to plot.im
.
The error message
useRaster=TRUE can only be used with a regular grid
means that the \(x\) and \(y\) coordinates of the pixels in the
image are not perfectly equally spaced, due to numerical rounding.
This occurs with some images created by earlier versions of spatstat.
To repair the coordinates in an image X
, type
X <- as.im(X)
.
Image is Displayed in Wrong Spatial Orientation
If the image is displayed in the wrong spatial orientation, and you created the image data directly, please check that you understand the spatstat convention for the spatial orientation of pixel images. The row index of the matrix of pixel values corresponds to the increasing \(y\) coordinate; the column index of the matrix corresponds to the increasing \(x\) coordinate (Baddeley, Rubak and Turner, 2015, section 3.6.3, pages 66--67).
Images can be displayed in the wrong spatial orientation
on some devices, due to a bug in the device driver. This occurs only
when the plot coordinates are reversed, that is, when
the plot was initialised with coordinate limits xlim, ylim
such that xlim[1] > xlim[2]
or ylim[1] > ylim[2]
or
both. This bug is reported to occur only when useRaster=TRUE
.
To fix this, try setting workaround=TRUE
, or if that is
unsuccessful, useRaster=FALSE
.
References
Baddeley, A., Rubak, E. and Turner, R. (2015) Spatial Point Patterns: Methodology and Applications with R. Chapman and Hall/CRC Press.
See Also
im.object
,
colourmap
,
contour.im
,
persp.im
,
hist.im
,
image.default
,
spatstat.options
Examples
# NOT RUN {
# 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))
# add axes and axis labels
plot(Z, axes=TRUE, ann=TRUE, xlab="Easting", ylab="Northing")
# 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)
# }