panel_scalebar: Add scale bar to the image panel

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

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. (scalebar\\.)*verb(ose)* verbose 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.

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.

Value

This function returns NULL value.

Author(s)

Nikita Platonov [e-mail]

Examples

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

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

# example no.3 -- for paper copy
   a <- colorize(pixelsize(),breakvalue=seq(400,650,by=50),pal=c("gray90","gray30"))
   compose_open(scale="1:95000000",dpi=150,device="cairo",family="Times")
   compose_plot(a,graticule=TRUE,coastline=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",detail="l")
  # panel_graticule()
   for (p in c("bottom","center","top"))
      panel_scalebar(pos=p,w=200)
   compose_close()

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