panel_annotation: Add label or annotation to the image panel.

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

Add label or annotation to the image panel.

Description

panel_annotation puts an annotation (text label) on the panel with raster image without anchors to any layer. Can be used as captions to image panels.

Usage

panel_annotation(...)

# non-public
.panel_annotation(label = expression(), position = "bottomright",
                  lon = NA, lat = NA, x = NA, y = NA, cex = 1.0, adjust = 0.5,
                  fg = "#000000", bg = "#FFFFFF1F", buffer = 1, fill = "#FFFFFF7F",
                  font = par("family"), vertical = FALSE, alpha = 1,
                  interpolate = FALSE, resample = FALSE, verbose = FALSE, ...)

Arguments

...	Set of arguments, which are recognized via their names (using regular expressions) and classes: Matched pattern (panel_annotation) Argument (.panel_annotation) Description ((caption|ann(otation)*) Logical or integer. Responsible for should annotation be displayed or not. If logical and TRUE then annotations are plotted on all panel of layout. If logical and FALSE then annotation is not displayed. If argument is a vector of positive integers, then annotations are plotted only in the specified panels, which sequence is defined in compose_design function and returned from getOption("ursaPngLayout")$layout. Default is TRUE. (label|text) label See below. pos(ition)* pos See below. lon(gitude)* lon See below. lat(itude)* lat See below. x$ x See below. y$ y See below. cex cex See below. adj(ust)* adjust See below. fg fg See below. bg bg See below. buf(fer)* buffer See below. fill fill See below. font font See below. vert(ical)* vertical See below. (alpha|transp(aren(cy)*)*) alpha See below. interp(olate)* interpolate See below. resample resample See below. verb(ose)* verbose See below.
label	Character, expression, or objects of classes array or matrix. Text, symbols or logo for displaying on image panel. Multi-row characters are allowed with delimiter "\n". Default is expression().
position	Character keyword or numeric of length 2 in the interval [0,1]. Defines the location of scale bar. If character, then one of the "bottomleft", "bottomright", "topleft", "topright", "left", "right", "bottom", "top", or "center". If numeric then relative position on panel is defined using shift on horizontal and vertical axes from origin in the bottom-left corner. Default is "bottomright".
lon	Numeric. Longitude for center of annotation's position. Default is NA.
lat	Numeric. Latitude for center of annotation's position. Default is NA.
x	Numeric. The horizontal coordinate of the annotation's position in the units of image grid. Default is NA.
y	Numeric. The vertical coordinate of the annotation's position in the units of image grid. Default is NA.
cex	Positive numeric. The relative font size for annotation's label. Default is 1. See description of argument cex in text function.
adjust	One or two values in [0, 1]. Specifies the horizontal (and optionally vertical) adjustment of the labels. See description of argument adj in text function.
fg	Character. Color name or code for label (texts and symbols). Default is "#000000" (black).
bg	Character. Color name or code for thin buffer around label's elements. Default is NA, which is interpreted as "transparent" for captions and as "#FFFFFF1F" for annotations.
buffer	Numeric. The relative width of buffer around label's elements. Default is 1.
fill	Character. Color name or code for circumscribed rectangle around labels. Default is NA, which is interpreted as "#FFFFFF7F" for captions and as "transparent" for annotations.
font	Character. Font family. Default is getOption("ursaPngFamily"), which is specified by argument font (or family) in compose_open().
vertical	Logical or numeric. Vertical or inclined orientation of label. If FALSE, then horizontal labeling. If numeric then vertical defines text direction in degrees. Limitation: value 1 is interpreted as TRUE. Default is FALSE, which means horizontal text direction.
interpolate	Logical. Passed as argument interpolate to function rasterImage for logo annotation.
resample	Logical or numeric. Passed as argument resample to function regrid for logo annotation. Default is FALSE. If TRUE , then resized logo is drawn smoothly.
alpha	Numeric or character. Level of transparency for logos. If numeric, the either ⁠0 <= alpha <= 1⁠ or 0 <= alpha <= 255. If character, then one byte of hexadecimal value ⁠"00" <= alpha <= "FF"⁠. Default is 1.
verbose	Logical. Value TRUE may provide some additional information on console. Default is FALSE.

Details

This function is based on function text with adding some decoration elements. For low-level plotting use layout.text function, which is equal to function text with additional control of image panels.

Since the most of character keywords of position have relation to the boundary of image panel, such annotation is assigned as a caption for image panel. Default decoration is shadowed background rectangle, which is implemented by function rect.

If location is defined by two-dimensional vector (either relative position inside of image boundaries (pos is numeric of length two), or pair lon, lat, or pair x, y), then such labeling is assigned as an annotation. Default decoration is thin buffer around symbols. The implementaion is via application of function function text for small diplacements around original position.

The priority of arguments (from higher to lower): 1) pair lon, lat, 2) pair x, y, 3) two-dimensional numeric of pos, 4) character keyword of pos. However, the default annotation is interpreted as a caption.

Value

This function returns NULL value.

Author(s)

Nikita Platonov [e-mail]

Examples

session_grid(NULL)
## exam no.1 -- direct use
compose_open(layout=c(2,3),legend=NULL,device="cairo")
for (i in seq(6)) {
   panel_new()
   panel_annotation(label=LETTERS,cex=1.5)
   panel_annotation(pos=c(0.7,0.2)
                    ,label=paste("panel",paste("no.",i),sep="\n"))
   if (i==1)
      panel_annotation(pos="center")
}
compose_close()

## exam no.2 -- indirect use
display(pixelsize(),scale=2
       ,ann.label="FJL",ann.lon=52,ann.lat=80,ann.buffer=1
       ,ann.bg="#8F6FFF2F",ann.fill="#FFFF7F9F",ann.font="courier")

nplatonov/ursa documentation built on May 8, 2024, 6:02 p.m.