compose_open: Start displaying

Description

compose_open create plot layout and open PNG graphic device.

Usage

compose_open(...)

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.

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.

Author

Nikita Platonov platonov@sevin.ru

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.

Examples

Run this code

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

Run the code above in your browser using DataLab