plot.im
Plot a Pixel Image
Plot a pixel image.
Usage
## S3 method for class 'im':
plot(x, \dots,
main,
add=FALSE, clipwin=NULL,
col=NULL, valuesAreColours=NULL, log=FALSE,
ribbon=show.all, show.all=!add,
ribside=c("right", "left", "bottom", "top"),
ribsep=0.15, ribwid=0.05, ribn=1024,
ribscale=1, ribargs=list(), colargs=list(),
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. - 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
andaxis
to control the display of the ribbon and its scale axis. These - colargs
- List of additional arguments passed to
col
if it is a function. - 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.
By default, the ribbon is placed at the right of the main image.
This can be changed using the argument ribside
.
Arguments ribsep, ribwid, ribn
control the appearance of the
ribbon.
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 ribn
different numerical values, evenly spaced between the minimum and
maximum pixel values in the image x
, rendered according to
the chosen colour map.
Arguments ribscale, ribargs
control the annotation of the
colour ribbon. To plot the colour ribbon without the axis and
tick-marks, use ribargs=list(axes=FALSE)
.
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.[object Object],[object Object],[object Object] - a
function
in theRlanguage with an argument namedrange
orinputs
. Ifcol
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 should be a character vector containing colour values. Ifcol
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.
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", "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.
useRaster=TRUE
in image.default
.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 willnotbe 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 willnotbe interpreted as colour values. Otherwise, if all the pixel values are strings that represent colours, then they will be interpreted and displayed as colours.
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 colour image (including the ribbon if present).
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 Rendering Errors and Problems
The help for image.default
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.
An error 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 X
, type
X <- as.im(X)
.
See Also
im.object
,
colourmap
,
contour.im
,
persp.im
,
image.default
,
spatstat.options
Examples
# an image
Z <- setcov(owin())
plot(Z)
plot(Z, ribside="bottom")
# stretchable colour map
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))
# log scale
V <- eval.im(exp(exp(Z+2))/1e4)
plot(V, log=TRUE, main="Log scale")