sl.plot.init: Initialise spheRlab Plot

In helgegoessling/spheRlab: Spherical Geometry, Analysis, and Plotting of Geoscientific Data on Arbitrary Grids

Initialise spheRlab Plot

Description

Initialise a standard spheRlab plot. Returns a plot specifics list that needs to be provided to any spheRlab plotting functions called afterwards, ended by a call of sl.plot.end.

Usage

sl.plot.init(projection = "lonlat", lonrange = c(-180,180), latrange = c(-89,89), lonlatrot = NULL, polar.latbound = 0, regpoly.N = 3, regpoly.lat0 = 60, regpoly.rotfrac = 0, col.background = NULL, precision = 1, main = "", xshift = 0, yshift = 0, device = "pdf", do.init = TRUE, file.name = NULL, width = 12, transform.function = NULL, mar = rep(0,4), lonlat.lonrange = c(-180,180), lonlat.latrange = c(-85,85), lonlat.lonlatrot = NULL, polar.lonlatrot = c(0,90,0), regpoly.lonlatrot = c(0,90,0))

Arguments

projection	a character specifing the plot projection type. Currently possible projections are "polar" (orthographic), "lonlat", "mollweide", and "regpoly" (gnomonic).
lonrange	a vector of length 2 specifying the plot longitude range in ascending order. Only used if projection is "lonlat" or "mollweide".
latrange	a vector of length 2 specifying the plot latitude range in ascending order. Absolute values above 89 degrees are forbidden. Only used if projection is "lonlat" or "mollweide".
lonlatrot	NULL (default) or a vector of length 3 specifying the projection North Pole and rotation. For polar-type projections, use this argument to change the plot centre, e.g., lonlatrot=c(0,-90,0) for the South Pole. See the documentation of sl.lonlatrot2abg for details.
polar.latbound	a scalar in the range [0,90) specifying the latitude (post-rotation) at which the plot shall be truncated. Default is polar.latbound=0, in which case the whole hemisphere is plotted. Only used if projection="polar".
regpoly.N	an integer specifying the number of vertices of the regular polygon.
regpoly.lat0	a scalar in the range (0,90) specifying the latitude (post-rotation) at which the vertices of the regular polygon shall be placed. Default is regpoly.latbound=60 (which does not correspond to a platonian body). Only used if projection="regpoly".
regpoly.rotfrac	a scalar in the range [0,1) specifying at which longitude (post-rotation) the 'first' vertex of the regular polygon shall be placed. The argument is not the longitude itself, but the fraction by which the vertex shall be rotated from 0 degrees to 360/regpoly.N degrees. Default is regpoly.rotfrac=0.
col.background	a background colour. Default is col.background=NULL, meaning that no background is drawn. Note that this parameter determines only the backgound colour of the map. To set the background colour of the whole plot, use par(bg=...) before calling sl.plot.init.
precision	a scalar specifying for projections with curved boundaries the precision (in degrees) at which the backgound polygon boundary is broken into straight line segments. Used only if col.background != NULL.
main	a character specifying the main plot title.
xshift	a scalar specifying how far the plot region shall be shifted in x-direction. Default is xshift=0. Needed for multi-panel plots as generated by sl.plot.platon.init and sl.plot.3D.init.
yshift	a scalar specifying how far the plot region shall be shifted in y-direction. Default is yshift=0. Needed for multi-panel plots as generated by sl.plot.platon.init and sl.plot.3D.init.
device	a character specifying which graphics device to use. Default is device='pdf'. Ignored if file.name=NULL.
do.init	a logical value indicating whether or not an initial call of plot shall be executed. Default is do.init=TRUE. When called by sl.plot.platon.init or sl.plot.3D.init, this argument is set FALSE as only one initial call of plot is wanted.
file.name	a character specifying the output file. Default is file.name=NULL, in which case the plot is using the current standard graphics device.
width	a scalar giving the width of the resulting figure. The height will be derived according to the chosen projection and other relevant plotting parameters. Only used if do.init.device=TRUE. Default is width=12. Note that for device %in% c("bmp","jpeg","png","tiff"), width is multiplied by 100 to ensure a reasonable default size.
transform.function	a function that transforms longitudes and latitudes (as two input arguments 'lon' and 'lat') into 'transformed' longitudes and latitudes. Can be used for fancy adjustments, e.g., to zoom into a region. Default is NULL, in which case no transformation is applied.
mar	a numerical vector of the form c(bottom, left, top, right) which gives the relative width of margin to be added to the four sides of the plot. This can be used to make space for a colourbar, for example. The default is rep(0,4).
lonlat.lonrange	deprecated, use lonrange instead! (stills works only for backward compatibility.)
lonlat.latrange	deprecated, use latrange instead! (stills works only for backward compatibility.)
lonlat.lonlatrot	deprecated, use lonlatrot instead! (stills works only for backward compatibility.)
polar.lonlatrot	deprecated, use lonlatrot instead! (stills works only for backward compatibility.)
regpoly.lonlatrot	deprecated, use lonlatrot instead! (stills works only for backward compatibility.)

Details

For a standard single-panel spheRlab plot, this function needs to be called explicitly to initialise the plot, and to generate a plot specifics list that needs to be provided to any spheRlab plotting functions called afterwards to transfer information of the projection, rotation, plot range, and so forth. For a multi-panel plot as generated by sl.plot.platon.init or sl.plot.3D.init, this function is called internally once for every panel.

Value

A (single-panel) spheRlab plot specifics list.

Elements that are always returned are:

projection	a character specifying the projection.
lonlatrot	see the corresponding argument.
alpha	a scalar specifying the alpha parameter derived from lonlatrot, or NULL if the latter is NULL.
beta	a scalar specifying the beta parameter derived from lonlatrot, or NULL if the latter is NULL.
gamma	a scalar specifying the gamma parameter derived from lonlatrot, or NULL if the latter is NULL.
xlim	a vector of length 2 specifying the projected x-range (used also as argument xlim when calling plot.
ylim	a vector of length 2 specifying the projected y-range (used also as argument ylim when calling plot.
xshift	see the corresponding argument.
yshift	see the corresponding argument.
transform.function	see the corresponding argument.

Additional list elements depend on the projection. For projection one of "lonlat" and "mollweide":

lonrange	see the corresponding argument.
latrange	see the corresponding argument.

For projection="polar":

polar.latbound

see the corresponding argument.

For projection="regpoly":

regpoly.N	see the corresponding argument.
regpoly.lat0	see the corresponding argument.
regpoly.z0	a scalar specifying the z-coordinate (post-rotation) of the regular polygon vertices (on a unit sphere).
regpoly.rotfrac	see the corresponding argument.
regpoly.cornerlons0	a vector of length regpoly.N specifying the longitudes (post-rotation) of the regular polygon vertices.
regpoly.lat0i	a scalar specifying the maximum latitude (post-rotation) of the regular polygon edges (located at the great-circle edge midpoints).
regpoly.cornerlons	a vector of length regpoly.N specifying the longitudes (pre-rotation, that is, in original coordinates) of the regular polygon vertices.
regpoly.cornerlats	a vector of length regpoly.N specifying the latitudes (pre-rotation, that is, in original coordinates) of the regular polygon vertices.

Note

Projections to be added include: "robinson" and "mercator".

The projection "regpoly" corresponds to a polar orthographic projection, truncated along a regular polygon, which allows composing the whole spherical surface with precisely connecting polygons, forming a platonian-type body (e.g. cube or icosahedron). sl.plot.platon.init calls this function multiple times to plot onto platonian-type bodies.

Typical multi-panel plotting (beyond the rather special functions sl.plot.platon.init or sl.plot.3D.init) shall be implemented at some point, too, making use of this function in a similar way as sl.plot.platon.init and sl.plot.3D.init, but with explicit calls inbetween where the current panel to be plotted into will need to be specified.

Author(s)

Helge Goessling

See Also

sl.plot.end, sl.plot.platon.init, sl.plot.3D.init

Examples

pir = sl.plot.init(projection="mollweide",latrange=c(-89,89))
sl.plot.naturalearth(pir, resolution="coarse")
sl.plot.lonlatgrid(pir, col="grey", labels=TRUE, labels.cex=0.7, labels.col="orange")
sl.plot.end(pir)

helgegoessling/spheRlab documentation built on April 8, 2024, 8:34 a.m.