panel_graticule: Add latitude/longitude or metric grid to the image panel.

In ursa: Non-Interactive Spatial Tools for Raster Processing and Visualization

Add latitude/longitude or metric grid to the image panel.

Description

panel_graticule puts a grid on the panel with raster image. If CRS is georeferenced then grid is generated from longitudes and latitudes.

Usage

panel_graticule(...)

compose_graticule(...)

# non-public
.compose_graticule(panel = 0L, col = "grey70", border = "grey70", lon = NA, lat = NA,
                lwd = 0.5, lty = 2, marginalia = rep(FALSE, 4), trim = FALSE,
                language = NA_character_, cex = 0.75, verbose = FALSE)

# non-public
.panel_graticule(obj, marginalia = rep(TRUE, 4), verbose = FALSE)

Arguments

...	Set of arguments, which are recognized via their names (using regular expressions) and classes: Matched pattern Used argument Description (graticule|grid(line)*) Logical. Responsible for should grid lines be displayed or not. If TRUE then grid lines are plotted. If FALSE then grid lines are not displayed. Default is TRUE. ^(graticule|grid(line)*)$ panel See below. (graticule|grid(line)\.)*col col See below. Default value in compose_graticule depends on panel background color, "#0000002F" for ligth panel background, and "#FFFFFF4F" for dark panel background. (graticule|grid(line)\.)*border border See below. Default value in compose_graticule depends on figure background color, "#0000002F" for ligth figure background, and "#FFFFFF4F" for dark figure background. (graticule|grid(line)\.)*lon lon See below. (graticule|grid(line)\.)*lat lat See below. (graticule|grid(line)\.)*lwd lwd See below. (graticule|grid(line)\.)*lty lty See below. (decor|margin(alia)*) marginalia See below. .compose_graticule and .panel_graticule don't validate correctness of this parameter. ((graticule|grid(line)\.)*trim trim See below. (graticule|grid(line)\.)*language language See below. (graticule|grid(line)\.)*verb(ose)* verbose See below.
obj	Objects of the class ursaGridLine. It is internal structure, which is returned by function .compose_graticule.
panel	Integer vector. Panel for which coastline will be displayed. 0L means that coastline will bw displayed for all panels. Default is 0L.
col	Character. Color code/name for grid lines. Default is ⁠"grey70"⁠.
border	Character. Color code/name for marginal labels and ticks. Default is ⁠"grey70"⁠.
lon	Numeric vector. Set of longitudes for grid. If NA then set of logitudes is formed internally. Default is NA.
lat	Numeric vector. Set of latitudes for grid. If NA then set of latidudes is formed internally. Default is NA.
lwd	Positive numeric. Width of grid line. Default is 0.5. See lwd in par.
lty	Positive integer. Type (pattern) of grid line. Default is 2 (dashed). See lty in par.
marginalia	Logical or integer vectors. Responsible for whether longitudes and latitudes (or metric coordinates) be labelled on the frame of panel with raster image. If logical and TRUE, then labels will be displatyed on each open side of panel. If logical and FALSE then labels will not be displayed. If logical of length 4, then labels will be displayed on specific side, where side index is c(bottom, left, top, right) (see description for marginal parameters in par). If argument is a vector of positive integers, then labels for grid lines are plotted only for the specified panels, which sequence is defined in compose_design function and returned from getOption("ursaPngLayout")$layout. Default is c(TRUE,TRUE,TRUE,TRUE).
language	Character. Language for longitude and latitude captions. If "ru" then captions are in Russian else in English. Default is NA.
trim	Logical. If grid lines are labelled then trim=TRUE prevents crossing the labels on neighbor perpendicular sides.
cex	Positive numeric. The relative font size for grid lines' labels. Make sence in the case of labels plotting. Default is 0.75.
verbose	Logical. Value TRUE may provide some additional information on console. Default is FALSE.

Details

If not language="ru" but environmental variable LANGUAGE=ru then labels are in Russian (cyrillics).

Argument gridline (or, grid) is introduced for unconditional calling of panel_graticule inside of high-level functions.

Grid lines can be controlled in high-level plot functions (e.g., display, compose_plot, display_stack, display_brick, display_rgb, etc.). To prevent displaying grid lines, use argument gridline=FALSE (or grid=FALSE). To display grid lines, use argument gridline=TRUE (or grid=TRUE) and prefix grid(line)* (gridline.* or grid.*) for grid lines' parameters, e.g., gridline.verb=TRUE, grid.col="black". If prefix is omitted then arguments with the same names affect in other functions in the part of high-level function.

If grid lines are formed internally, then desirable number of lines for each direction is 3. The design of line density is based on intuition, providing pretty labelling.

If CRS is georeferenced then grid lines are corresponded to longitudes and latitudes. Integer minutes are used to illustate fractional values of degrees. If precision of minutes is insufficient, then integer values of seconds are introduced. The fractional values of seconds are not used.

Labels are located at the points, where grid lines cross plot margin. Labels are not overlapped along the same side. To prevent overlapping along the same side, labels are shifted or omitted. Argument trim=TRUE prevents overlapping labels from neighbor sides via hidding.

Value

Function returns NULL value.

Author(s)

Nikita Platonov [e-mail]

Examples

session_grid(NULL)
 ## Changing of environmental variables is out of CRAN Policy 
## Not run: Sys.setenv(LANGUAGE="ru")


# example no.1
cl <- compose_design(layout=c(2,2),legend=NULL)
session_grid(regrid(lim=3.2*1e6*c(-1,-1,1,1)))
compose_open(cl)
for (i in 1:4) {
   panel_new()
   panel_coastline()
   panel_graticule(decor=TRUE,trim=i %in% c(2:4))
   panel_annotation(text=as.character(i))
   panel_scalebar(scalebar=i==3)
}
compose_close()

# example no.2
session_grid(regrid(lim=1e6*c(-0.5,0.5,1.5,2.5)))
compose_open(layout=c(2,2),legend=NULL,skip=4)
for (i in seq(getOption("ursaPngLayout")$image)) {
   panel_new()
   panel_coastline()
   if (i==1)
      panel_graticule()
   else if (i==2)
      panel_graticule(decor=TRUE,lon=seq(0,360,by=40)[-1],lat=seq(-90,90,by=10))
   else if (i==3)
      panel_graticule(decor=TRUE,lon=seq(0,360,by=20)[-1],lat=seq(-90,90,by=5)
                     ,trim=TRUE)
   else if (i==4)
      panel_graticule(gridline=FALSE)
   panel_scalebar(scalebar=1)
   panel_annotation(text=as.character(i))
}
compose_close()

# example no.3 -- indirect usage
session_grid(NULL)
display(pixelsize(),decor=TRUE,grid.col="green3",coast.col="darkgreen",side=2)

 ## Changing of environmental variables is out of CRAN Policy 
## Not run: Sys.setenv(LANGUAGE="") # reset environmental variable

ursa documentation built on Sept. 30, 2024, 9:35 a.m.