compose_open: Start displaying

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

Start displaying

Description

compose_open create plot layout and open PNG graphic device.

Usage

compose_open(...)

Arguments

...

Set of arguments, which are recognized via their names and classes: mosaic Layout matrix or reference object to produce layout matrix. It is permitted to do not use name for this argument. Multiple types of argument are allowed: 1) object of class ursaRaster, 2) list of ursaRaster objects (raster stack), 3) object of class ursaLayout from function compose_design, 4) character keyword or 5) missing. Default is NA. fileout Character. Name for created output file. Supported PNG (*.png), JPEG (*.jpg), WEBP (*.webp) and SVG (*.svg) extensions. Missed extension assumes PNG. If absent ("") then temporal file is created and removed in wait seconds after opening in the associated external viewer. Default is absent (""). dpi Positive integer. Dots (or pixels) per inch (DPI). The nominal resolution of created output (default PNG) file. Default is 96L. The same as res argument in the png function. pointsize Positive integer. The pointsize of plotted text as it is applied in the png function. Default is NA. If pointsize=NA then it is taken value 16L multiplied to relative DPI (dpi/96). In the case of unspecified scale and pointsize the size of text is defined internally. scale Positive numeric or character. The scale factor applied to dimensions of original raster. Default is NA. If scale is unspecified (scale=NA), then scale is defined internally for intuitively better fitting in HD, FHD displays (single-panelled layout 900x700). If scale is character (e.g., "8000000", "1:8000000") then dimensions of image panels are defined using "one centimeter of map is corresponded to 8000000 centimeres of site" rule. width Positive numeric or character. The desired width of each panel of multipanel layout. If width is numeric, then units are pixels. If width is character (e.g., "12.5", "12.5 cm", "12.5cm") then units are centimeters in agreement with dpi argument. Default is NA. If width is unspecified (width=NA) then value 900 is used for single panelled layout. height Positive numeric or character. The desired height of each panel of multipanel layout. If height is numeric, then units are pixels. If height is character (e.g., "9.6", "9.6 cm", "9.6cm") then units are centimeters in agreement with dpi argument. Default is NA. If height is unspecified (height=NA) then value 700 is used for single panelled layout. colorbar or colorbarwidth Positive numeric. Scale factor to increase (colorbar>1) or decrease (colorbar<1) width (the shortest dimension) of color bars (legends). Default value (NA) means 2.8% of image panel width. indent or space or offset. Positive numeric. Scale factor to increase (space>1) or decrease (space<1) the white space between image panels and between image and color bar panels. Default value (NA) means 0.8% of image panel width. box Logical. If TRUE then boundary box is plotted around image panels and color bar panels. It is a transparent rectangle with black border. Default is TRUE. delafter Logical. If TRUE then created PNG file will be deleted after viewing. Default is FALSE for specified file names and TRUE for unspecified (temporal) file names. It is implemented as file removing after opening in the external PNG viewer. wait Positive numeric. Seconds between PNG file opening in the associated program and file removing. It make sense only if delafter=TRUE. Default is 1.0 (one second). device or type Character keyword, either "cairo", "windows" or "CairoPNG" for OS Windows, and either "cairo", "cairo-png", "Xlib" or "quartz" for other OSes. Should be plotting be done using cairographics or Windows GDI? The same as type argument in the png function, excepting "CairoPNG", which is handed by Cairo package. Default is "cairo". antialias Character keyword, either "none" or "default". Defines the effect on fonts. The same as antialias argument in the png function. Default is "default". font or family A length-one character vector. Specifies the font family. The same as family argument in the png function. Default is "sans" for device="windows" and "Tahoma" for device="cairo". bg or background Character. The background color in PNG file. Passed as argument bg to png function. Default is "white" retina Positive numeric. Scale coefficent for retina displays. Default is taken from getOption("ursaRetina"); if it missed, then 1. dev Logical. If TRUE then this developer tool shows created layout without any the followed plot functions from this package are ignored. Default is FALSE verbose Logical. Shows additional output information in console. Default is FALSE. ... Arguments, which can be passed to compose_design function.

Details

Other usage of compose_open(...,dev=TRUE) is

   compose_open(...,dev=FALSE)
   compose_close()

The reason to use compose_design function before compose_open is to reduce number of arguments in the case of complicated layout matrix and non-standard settings.

compose_open passes arguments to png function.

If character values are specified for arguments width, height or scale, then layout development is oriented to produce PNG file, which will be used as a paper copy. Character values for width and height are in centimeters. Character value ⁠V⁠ or ⁠1:⁠⁠V⁠ of scale defines scale ⁠1/⁠⁠V⁠.

The Cairo device (device="cairo") is more quick on MS Windows computers. However Windows GDI may produce less depth of colors (even 8 BPP) in the case of no font antialiasing. Usage of Windows GDI (device="windows") is a way to produce illustations for scientific journals with strict requirements of mininal line width, font size, etc.

The PNG layout reserves extra margins for captions of color bars. These margins are filled by white spaces. The cropping of layout applies to created PNG file using read-write functions of package png. Only white ("white", "#FFFFFF") or transparent ("transparent") colors are regognized as white spaces. Therefore, specification of bg!="white" or bg!="transparent" breaks PNG image cropping.

It is noted that Cyrillics is supported on Windows GDI (device="windows") and is not supported on Cairo (device="cairo") types of PNG device on MS Windows platform.

Argument retina is ignored for leaflet-compatible tiling.

Value

Name of created PNG file.

If dev=TRUE then output on console is layout matrix.

The set of required parameters for plotting are kept until function compose_close call via options.

ursaPngAuto	For developers. Indicator of high-level functions for internal use (manual set; value is TRUE). Or, can be missed.
ursaPngBox	Argument box. If TRUE then box is called for each panel of layout at the end of plotting.
ursaPngDelafter	Argument delafter. Applied in the function compose_close.
ursaPngDevice	Argument device. Applied for effective plottting of rasters and checking the ability for final reducing color depth from 24 to 8 bpp.
ursaPngDpi	Argument dpi. Currently used for verbose only.
ursaPngFamily	Applied for text plotting in annotations and legends.
ursaPngFigure	Set 0L. Specifies number of current panel in layout matrix. Used to detect term for applying $ursaPngBox option.
ursaPngFileout	Name of created PNG file.
ursaPngLayout	Layout matrix, the object of class ursaLayout.
ursaPngPaperScale	Numeric. Used for scalebar representation on the paper-based maps. If value 0, then scalebar is display-based. If value is greater 0 then the scale is exact. If value is -1 then the resonable rounding is used for scale displaying.
ursaPngPlot	The opposite to argument dev. If $ursaPngPlot is FALSE then any plotting functions of this package are ignored.
ursaPngScale	The actual value of argument scale, specified during function call or stated internally.
ursaPngShadow	Set "". Used for shadowing of the part of color bars in the case of semi-transparent land or ocean filling mask in the panel_coastline function.
ursaPngSkipLegend	Integer vector of non-negative length. Defines list of images panels, for which the color bars are not displayed.
ursaPngWaitBeforeRemove	Argument wait. Applied in the function compose_close for temporal PNG file.

Author(s)

Nikita Platonov [e-mail]

Examples

session_grid(NULL)
b <- ursa_dummy(nband=4,min=0,max=50,mul=1/4,elements=16)
p <- list(colorize(b[1:2],pal.rich=240,pal.rotate=0)
         ,colorize(sqrt(b[3:4]),pal.rich=-15,pal.rotate=0,stretch="equal"))
p
 
## exam #01
compose_open(width=950,dpi=150,pointsize=16,legend=NULL,dev=TRUE)

## exam #02
compose_open(pointsize=8,dpi=150,scale="1:130000000")
compose_plot(colorize(b[1]),scalebar=TRUE,coast=FALSE)
compose_close()

## exam #03
cl <- compose_design(layout=c(2,4)
                    ,legend=list(list("top","full"),list("bottom",1:3)))
compose_open(cl,dev=TRUE)

## exam #04
cl <- compose_design(p,layout=c(2,3),skip=c(2,4,6))
compose_open(cl,dev=TRUE)

## exam #05
cl <- compose_design(p,side=3)
compose_open(cl,dev=FALSE,bg="transparent")
compose_close()

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