magimage {magicaxis}

Magically pretty images

Description

magimage is a level replacement for base image with hooks into magaxis for the tick marks and magmap for the image scaling. The default behavious is a bit different to base (e.g. x/y scales are automatically the number of pixels in the image matrix). magimageRGB is similar, but is for the creation colour images where the user can provide R G B input matrix chanels (or similar).

Usage

magimage(x, y, z, zlim, xlim, ylim, col = grey((0:1000)/1000), add = FALSE,
  useRaster = TRUE, asp = 1, magmap = TRUE, locut = 0.4, hicut = 0.995, flip = FALSE,
  range = c(0, 1), type = "quan", stretch = "asinh", stretchscale = 'auto', bad = NA,
  clip = "", axes = TRUE, frame.plot = TRUE, sparse = 'auto', qdiff = FALSE,
  rem_med = FALSE, doplot = TRUE, ...)

magimageRGB(x, y, R, G, B, saturation = 1, zlim, xlim, ylim, add = FALSE,
  useRaster = TRUE, asp = 1, magmap = TRUE, locut = 0.4, hicut = 0.995, flip = FALSE,
  range = c(0, 1), type = "quan", stretch = "asinh", stretchscale = "auto",
  bad = range[1], clip = "", axes = TRUE, frame.plot = TRUE, sparse = 'auto', ...) 

Arguments

x, y

Locations of grid lines at which the values in z are measured. These must be finite and non-missing (order may be reversed). By default, equally spaced values from 0 to dim(z)[1] are used. If x is a list, its components x$x and x$y are used for x and y, respectively. If the list has component z/R/G/B this is used for z/R/G/B.

z

A numeric or logical matrix containing the values to be plotted (NAs are allowed). Note that x can be used instead of z for convenience.

R

A numeric or logical matrix containing the red colour values to be plotted (NAs are allowed). Note that x can be a 3D array or list (containing elements R/G/B) instead of R for convenience, where R=x[,,1].

G

A numeric or logical matrix containing the green colour values to be plotted (NAs are allowed). Note that x can be a 3D array or list (containing elements R/G/B) instead of G for convenience, where G=x[,,2].

B

A numeric or logical matrix containing the blue colour values to be plotted (NAs are allowed). Note that x can be a 3D array or list (containing elements R/G/B) instead of B for convenience, where B=x[,,3].

saturation

The visual saturation of the colours, a bit like the dial on a TV. 1 is native, 0 is black and white, 2 is very intense nigh-on trippy.

zlim

The z limit with respect to the output of magmap$map. If magmap=FALSE (default) zlim should be with respect to the provided z matrix (like base image). If magmap=TRUE zlim should be with respect to the range output of magmap. By default the magmap function scales between 0 and 1, so to only show the brighter pixels zlim could be set to c(0.5,1).

xlim, ylim

Ranges for the plotted x and y values, defaulting to the ranges of x and y.

col

A list of colours for the magmap re-mapping of z to be parsed into (e.g. rainbow, heat.colors, topo.colors, terrain.colors or similar).

add

If true add the new image to the current plot.

useRaster

If TRUE a bitmap raster is used to plot the image instead of polygons. The grid must be regular in that case, otherwise an error is raised. Raster is much faster, so use when pixels are equal sized.

asp

The y/x aspect ratio

magmap

If TRUE then magmap scaling is applied to the z dimension (default), if FALSE then it is not.

locut

The low limit to clip the z data at (what this means varies depending on the 'type' option). For magimageRGB this can be a single value (used for R, G and B) or a vector of length 3 (used for R, G and B respectively). See magmap for more information.

hicut

The high limit to clip the z data at (what this means varies depending on the 'type' option). For magimageRGB this can be a single value (used for R, G and B) or a vector of length 3 (used for R, G and B respectively). See magmap for more information.

flip

Should the z scaling be flipped. This allows numbers from 0 to 10 to be mapped from 1 to 0 (so ordered back to front with respect to the input). See magmap for more information.

range

The numerical range of the output z mapping which should be a vector of length two specifying c(low,high). See magmap for more information.

type

The type of z mapping attempted. Options are 'quan' (default), 'num', 'sig' and 'rank'. See magmap for more information.

stretch

stretch='lin' gives linear mapping. stretch='log' gives logarithmic mapping. stretch='atan' gives atan mapping. stretch='asinh' gives asinh mapping. stretch='sqrt' gives sqrt mapping. See magmap for more information.

stretchscale

A number to multiply the z data by before applying the stretch. This only has a user impact for stretch='atan' and stretch='asinh' since it controls what parts of the data is in the linear or logarithmic regime of the stretch procedure. If set to 'auto' (the default) it uses 1/median(abs(data)) to find a useful scale.See magmap for more information. For magimageRGB this can be a single value (used for R, G and B) or a vector of length 3 (used for R, G and B respectively). See magmap for more information.

bad

Sets the value that NA, NaN and infinite input z data should be set to in the final map output. This should be thought of in the context of the range argument, i.e. if bad=range[1] then bad values will be the low range value and if bad=range[2] bad values will be the high range value. See magmap for more information. For magimageRGB bad is set to range[1] by default since this removes RGB conversion errors that would be experiences with NA values (i.e. negative values when stretch='log').

clip

By default clipped z values inherit the nearest lo/hi value (depending on which side they are clipped). Setting clip='NA' will set values outside the 'lo' and 'hi' values to be NA (currently this is the only other clip option). See magmap for more information.

axes

Specify if any axes be drawn on the image. If FALSE then only the pixels (with appropriate magmap scaling) are shown.

frame.plot

Specify if a box be drawn around the image frame. Only happens if add=TRUE and axes=TRUE.

sparse

Determines whether the image pixels are sparse sampled to speed up plotting. If set to 2 it will only determine every 2nd pixel, and if 3 every 3rd etc. The default 'auto' means it will scale to produce a maximum number of 1,000 pixels on any side (on most monitors this is a fairly useful maximum, and ensures quick displaying of even very large images).

qdiff

Logical; if the z axis being plotted, this will set all the various parameters that make for a visually useful difference plot, where -ve difference values become blue, 0 difference values are yellow, and +ve difference values are red.

rem_med

Logical; should the median of the image be subtracted or not? This is often useful in conjunction with qdiff = TRUE.

doplot

Logical; if TRUE then gnerates the image. If FALSE then just return the output below (with z scaled as request).

...

Arguments to be parsed to image and magaxis as relevant (this is checked for internally by argument name). See image and magaxis for details.

Details

See image, magmap and magaxis for more details.

Value

Outputs the final image list containing x,y and z (magimage) or R/G/B (magimageRGB). z is the scaled output (not the native input). Generally run for the side effect of producing rapid and well-scaled image plots.

Author(s)

Aaron Robotham

See Also

image, magcutout, magmap, magaxis

Examples

#Basic
magimage(matrix(1:9,3))

#Mid pixel versus pixel edge:
magimage(3:0,1:3,matrix(1:9,3))

#Standard scaling is not very useful in this instance:
magimage(matrix(10^(1:9),3))
#Linear scaling is not very useful in this instance, though it does now map from [0,1]:
magimage(matrix(10^(1:9),3),magmap=TRUE,zlim=c(0,0.5))
#Log scaling with magmap makes it much clearer:
magimage(matrix(10^(1:9),3),magmap=TRUE,stretch='log')
#And it's easy just to show the lowest half now:
magimage(matrix(10^(1:9),3),magmap=TRUE,stretch='log',zlim=c(0,0.5))

## Not run: 
#Some astro data:
library(Rfits)
image = Rfits_read_image(system.file("extdata", 'image.fits', package = "Rfits"))

#A monotone image:
magimage(image$imDat)
#A faked colour image (this won't look great):
magimageRGB(R=image$imDat^3, G=image$imDat^1.5, B=image$imDat^2)

## End(Not run)