oce (version 1.8-1)

mapImage: Add an Image to a Map

Description

Plot an image on an existing map that was created with mapPlot().

Usage

mapImage(
  longitude,
  latitude,
  z,
  zlim,
  zclip = FALSE,
  breaks,
  col,
  colormap,
  border = NA,
  lwd = par("lwd"),
  lty = par("lty"),
  missingColor = NA,
  filledContour = FALSE,
  gridder = "binMean2D",
  debug = getOption("oceDebug")
)

Arguments

longitude

numeric vector of longitudes corresponding to z matrix.

latitude

numeric vector of latitudes corresponding to z matrix.

z

numeric matrix to be represented as an image.

zlim

limit for z (color).

zclip

A logical value, TRUE indicating that out-of-range z values should be painted with missingColor and FALSE indicating that these values should be painted with the nearest in-range color. If zlim is given then its min and max set the range. If zlim is not given but breaks is given, then the min and max of breaks sets the range used for z. If neither zlim nor breaks is given, clipping is not done, i.e. the action is as if zclip were FALSE.

breaks

The z values for breaks in the color scheme. If this is of length 1, the value indicates the desired number of breaks, which is supplied to pretty(), in determining clean break points.

col

Either a vector of colors corresponding to the breaks, of length 1 plus the number of breaks, or a function specifying colors, e.g. oce.colorsViridis() for the Viridis scheme.

colormap

optional colormap, as created by colormap(). If a colormap is provided, then its properties takes precedence over breaks, col, missingColor, and zclip specified to mapImage.

border

Color used for borders of patches (passed to polygon()); the default NA means no border.

lwd

line width, used if borders are drawn.

lty

line type, used if borders are drawn.

missingColor

a color to be used to indicate missing data, or NA to skip the drawing of such regions (which will retain whatever material has already been drawn at the regions).

filledContour

either a logical value indicating whether to use filled contours to plot the image, or a numerical value indicating the resampling rate to be used in interpolating from lon-lat coordinates to x-y coordinates. See “Details” for how this interacts with gridder.

gridder

character value specifying the gridding function to be used if filledContour is TRUE. This can be either "binMean2D" to select binMean2D() or "interp" to select interp::interp(). The former produces cruder results, but the latter can be slow for large datasets. Note that "akima" is taken as a synonym for "interp" (see “Historical Notes”).

debug

A flag that turns on debugging. Set to 1 to get a moderate amount of debugging information, or to 2 to get more.

Historical Notes

Until oce 1.7.4, the gridder argument could be set to "akima", which used the akima package. However, that package is not released with a FOSS license, so CRAN requested a change to interp. Note that drawImage() intercepts the errors that sometimes get reported by interp::interp().

Author

Dan Kelley

Details

Image data are on a regular grid in lon-lat space, but not in the projected x-y space. This means that image() cannot be used. Instead, there are two approaches, depending on the value of filledContour.

If filledContour is FALSE, the image "pixels" are drawn with polygon(). This can be prohibitively slow for fine grids. However, if filledContour is TRUE or a numerical value, then the "pixels" are remapped into a regular grid and then displayed with .filled.contour(). The remapping starts by converting the regular lon-lat grid to an irregular x-y grid using lonlat2map(). This irregular grid is then interpolated onto a regular x-y grid with either binMean2D() or interp::interp(), as determined by the value of the gridder parameter. If filledContour is TRUE, the dimensions of the regular x-y grid is the same as that of the original lon-lat grid; otherwise, the number of rows and columns are multiplied by the numerical value of filledContour, e.g. the value 2 means to make the grid twice as fine.

Filling contours can produce aesthetically-pleasing results, but the method involves interpolation, so the data are not represented exactly and analysts are advised to compare the results from the two methods (and perhaps various grid refinement values) to guard against misinterpretation.

If a png() device is to be used, it is advised to supply arguments type="cairo" and antialias="none" (see reference 1).

References

1. https://codedocean.wordpress.com/2014/02/03/anti-aliasing-and-image-plots/

See Also

A map must first have been created with mapPlot().

Other functions related to maps: formatPosition(), lonlat2map(), lonlat2utm(), map2lonlat(), mapArrows(), mapAxis(), mapContour(), mapCoordinateSystem(), mapDirectionField(), mapGrid(), mapLines(), mapLocator(), mapLongitudeLatitudeXY(), mapPlot(), mapPoints(), mapPolygon(), mapScalebar(), mapText(), mapTissot(), oceCRS(), shiftLongitude(), usrLonLat(), utm2lonlat()

Examples

if (FALSE) {
library(oce)
data(coastlineWorld)
data(topoWorld)

# Northern polar region, with color-coded bathymetry
par(mfrow=c(1,1), mar=c(2,2,1,1))
cm <- colormap(zlim=c(-5000, 0), col=oceColorsGebco)
drawPalette(colormap=cm)
mapPlot(coastlineWorld, projection="+proj=stere +lat_0=90",
        longitudelim=c(-180,180), latitudelim=c(70,110))
mapImage(topoWorld, colormap=cm)
mapGrid(15, 15, polarCircle=1, col=gray(0.2))
mapPolygon(coastlineWorld[['longitude']], coastlineWorld[['latitude']], col="tan")
}