panel_annotation {ursa}

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")