ursa (version 3.9.4)

panel_scalebar: Add scale bar to the image panel

Description

panel_scalebar puts a scale bar ('box' style) on the panel with raster image.

Usage

panel_scalebar(...)
# non-public
.panel_scalebar(position = "bottomleft", w = NA, cex = 0.85,
                col = "#0000002F", bg = "transparent", fill = "#FFFFFF2F",
                language=NA, verbose = FALSE)

Arguments

…

Set of arguments, which are recognized via their names (using regular expressions) and classes. Passed to non-public .panel_scalebar, excepting argument scalebar:

Pattern (panel_scalebar)	Argument (.panel_scalebar)	Description
(scalebar|ruler|decor)		Logical or integer. Responsible for should scale bar be displayed or not. If logical and TRUE then scale bars are plotted on all panel of layout. If logical and FALSE then scale bars are not displayed. If argument is a vector of positive integers, then scale bars are plotted only in the specified panels, which sequence is defined in compose_design function and returned from getOption("ursaPngLayout")$layout. Default is TRUE.
(scalebar\\.)*pos(ition)*	position	See below.
(scalebar\\.)*w	w	See below.
(scalebar\\.)*cex	cex	See below.
(scalebar\\.)*col	col	See below.
(scalebar\\.)*fill	fill	See below.
(scalebar\\.)*bg	bg	See below.
(scalebar\\.)*language	language	See below.

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 "bottomleft".

w

Positive numeric. The length in km of scalebar's right segment. If w=NA then length of segment is defined automatically. Default is NA.

cex

Positive numeric. The relative font size for scalebar's labels. Default is 0.85.

col

Character. Primary fill color for scalebar box and scalebar labels. Default is "#0000002F".

fill

Character. Secondary fill color for scalebar box. Default is "#FFFFFF2F".

bg

Character. Background color for the area of scalebar box and labels. Default is "transparent".

language

Character. Language for longitude and latitude captions. If "ru" then captions are in Russian else in English. Default is NA.

verbose

Logical. Value TRUE may provide some additional information on console. Default is FALSE.

Value

This function returns NULL value.

Details

The scalebar has 2 left segments and 2 right segments. Left and right segments are separated by 0. The length of left segments is a half of length of right segments.

Argument scalebar (or, synonym, ruler) is introduced for unconditional calling of panel_scalebar inside of high-level functions.

Default x=0 and y=0 define the "bottomleft" position of scale bar.

If argument scale in the function compose_open is character, then the length of one segment is exactly 1 cm, and the total length of scalebar is 3 cm.

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

The length distortions is taken into account for transverse Mercator ("+proj=tmerc") projection regarding to location of scalebar.

Scalebar (single occurence) can be controlled in high-level plot functions (e.g., display, compose_plot, display_stack, display_brick, display_rgb, etc.).

To plot scalebar, use argument scalebar=TRUE and prefix (ruler|scalebar) (scalebar.* or ruler.*) for scalebar's parameters, e.g., scalebar.pos="bottomright", scalebar.cex=0.9.

Scalebar is not displayed for longlat projection ("+proj=longlat"), where units are degrees.

Examples

# NOT RUN {
session_grid(NULL)
# example no.1 -- direct usage
   a <- colorize(pixelsize())
   compose_open(a)
   panel_new()
   panel_raster(a)
   panel_scalebar()
   compose_close()

# example no.2 -- indirect usage
   display_rgb(ursa_dummy(nband=3,min=0,max=255)
              ,scalebar=TRUE,scalebar.col="white",scalebar.fill="black")

# example no.3 -- for paper copy
   a <- colorize(pixelsize(),breakvalue=seq(400,650,by=50),palname="Greys",inv=FALSE)
   compose_open(scale="1:95000000",dpi=150,device="cairo",family="Times")
   compose_plot(a,gridline=FALSE,scalebar=TRUE,scalebar.x=1,units=expression(km^2))
   compose_close(bpp=8)

# example no.4 -- length distortion in the Transverse Mercator projection
   a1 <- regrid(setbound=c(10,65,71,83),dim=c(100,100),crs=4326)
   a2 <- polygonize(ursa_bbox(a1))
   a3 <- spatial_transform(a2,3857)
   a4 <- regrid(setbound=spatial_bbox(a3),res=20000,crs=spatial_crs(a3))
   compose_open(legend=NULL)
   panel_new("white")
   panel_coastline(fill="#00000010")
  # panel_graticule()
   for (p in c("bottom","center","top"))
      panel_scalebar(pos=p,w=200)
   compose_close()
# }