glance {ursa}

Command line utility for spatial view of raster or vector GIS file.

Description

glance is a parser of command line arguments for non-public function .glance, which creates multi-panel plots for each attribute of vector file or for each band of raster file.

Usage

glance(...)

# non-public
.glance(dsn, layer = ".*", grid = NULL, field = ".+", size = NA, expand = 1,
        border = 27, lat0 = NA, lon0 = NA, resetProj = FALSE, resetGrid = FALSE, 
        style = "auto", feature = c("auto", "field", "geometry"), alpha = NA,
        basemap.order = c("after", "before"), basemap.alpha = NA,
        engine = c("native", "sp", "sf"), geocode = "", place="",
        area = c("bounding", "point", "shape"), zoom = NA, gdal_rasterize = FALSE,
        silent = FALSE, verbose = FALSE, ...)

Arguments

dsn

Character or object of either ursaRaster, Spatial, or sf classes. If character, then data source name (interpretation varies by driver - for some drivers, dsn is a file name, but may also be a folder, or contain the name and access credentials of a database).

layer

Character or integer. If integer, then layer index. If character, then pattern (regular expressions) to recognize layer by name. Only one layer selection is allowed. If selected more then one layer, the error message contains indices and names of layers. Usually, datasets (e. g., "ESRI Shapefile") have only one layer. Default is ".*"; interpreted as all layers.

grid

Object of class ursaGrid or NULL. Reference CRS and boundary box for visualization. If NULL, then CRS and boundary box are zoomed to layer. Default is NULL.

field

Character. Pattern for field (attribute, column,...) selection by name using regular expressions. Multiple selection is allowed. Default is ".+"; all fields.

size

Integer of length 1 or 2 or character of length 1. Size of plotting panel in pixels. If character, then parsed to integer of length 1 or 2. Length 2 is used only for web cartography. If length 1, then size defines width of panel, and height is defined automatically. If integer, then width of panel for plotting in pixels. Default is NA; for web cartogrpaphy value of maximal size of static maps, and 640 for other cases.

expand

Numeric. Multiplier for plotting panel zoom in relation to extent of plotting geometry. Default is 1.0.

border

Integer. Value in pixels of fixed margins around plotting geometry. Default is 27L.

lat0

Numeric. Parallel os zero distortion. If NA, then parallel os zero distortion is determined from object geometry. Actual for "+proj=stere" projections. Default is NA.

lon0

Numeric. Central meridian, which have vertical direction on the plot. If NA, then central meridian is determined from object geometry. Default is NA.

resetProj

Logical. Value TRUE overwrites projection of vector file. Default is FALSE.

resetGrid

Logical. If TRUE, then session grid is ignored, and new session grid is assigned from input file. If FALSE, then input file is nested in the session grid.

style

Character. Either projection class or source of web-catrogrpaphy for basemap. Specified by a sentence of words separated by spaces.

• Projection class
  Valid values are "stere", "laea", "merc", "longlat". Default is keyword "auto"; use object projection, if this projection differs from projection class "+longlat", otherwise, projection ("stere" or "merc") is determined internally.

• Web cartography.

  • Static map
    Valid values are "google", "openstreetmap", "sputnikmap". Static maps have priority over tile services. however additional word "static" can be specified in the sentence, e.g., "openstreetmap static" or "static google". Additional parameters for request to web-script can be added in the sentence in the form "argument1=value1 [argument2=value2]", e.g., style="google static maptype=terrain language=ru-RU scale=2".

  • Tile service
    Supported tile services can be returned by calling of non-public function ursa:::.tileService() without arguments. Valid values are "mapnik", "cycle", "transport", "mapsurfer", "sputnik", "thunderforest", "carto", "kosmosnimki", etc.

  By default, if data has no data fields (e. g., geometry only), then basemap is drawn in color, else in grayscale. Adding word "color" (or "colour") to the sentence forces to use colored basemap. Adding word "gray" (or "grey", "greyscale", "grayscale") to the sentence forces to use colored basemap.

  The order of words in the sentence is any.

Keywords "google", "openstreetmap" force to use "Google Static Map" or "OpenStreetMap static map images" for basemap; the resulted projection has class "+proj=merc".

feature

Character. Appearance of visualization. If "field" then data of each field is plotted on separate panel (number of panels is equal to number of columns in attribute table). If "geometry" then each feature is plotted on separate panel (number of panels is equal to number of rows in attribute table). Default is "auto"; if intersects of features are found, then "geometry" is used, else "field".

basemap.order

Character. The order of basemap layer rendering in the case of web-cartography basemap.If "before", then basemap is plotted before object plot. If "after", then basemap is plotted over object.

basemap.alpha

Character. The saturation of basemap in the case of web-cartography basemap. Default is NA; basemap.alpha=0.5 for basemap.order="before" and basemap.alpha=0.35 for basemap.order="after".

alpha

Character. The opacity of plotted object. Default is NA; 0.75 for basemap.order="before" in web-cartogrpaphy style, 1.00 - in all other cases.

engine

Character keyword. Forcing to vector files processing by functions from package sp (engine="sp") or package sf (engine="sf", if sf is installed). Default is "native"; if dsn is Spatial object or if sf is not installed, then "sp" is used.

geocode

Character. Keyword for geocode service. Valid values are "google", "nominatim". If dsn is character and file dsn not found, then trying to interpret dsn as a request to geocode service. The output is only basemap of web cartogrpaphy. Default is ""; several services are considered in the case of failure. Is style is not specified, then "Google Static Map" is used for geocode="google", and "OpenStreetMap static map images" for geocode="nominatim".

place

Character. Type of geographical object (river, island) in the geocoding request. If geocode service is "nominatim", then place is searched among attributes "class" and "type". Default is ""; any object is acceptable.

area

Character. Keyword of spatial class of geocoded object. "bounding" is used for boundary box; "point" is used for point. Default value is extracted by match.arg(area).

zoom

Positive integer or character. Zooming if web-cartography is applied for basemap. If integer, then value of zoom for tile services and staticmap. If character, then "0" means zoom by default (defined internally), "+1" means increment on 1 of default zoom, "+2" means zoom increment on 2, "-1" means zoom decrement on 1, "-2" means zoom decrement on 2, etc. Default is NA; zoom is defined internally.

gdal_rasterize

Logical. If TRUE and GDAL utilities are in the system search path, then overlay for panels is formed via rastetization of vector file. GDAL utility "gdal_rasterize" is used. Note, that GDAL (system level) is optional for this package. Default is FALSE.

silent

Logical. Value TRUE cancels progress bar. Default is FALSE.

verbose

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

...

glance: Arguments, which are passed to .glance or to display.
.glance: Arguments, which are passed to static maps API, colorize, display, etc.

Details

Command line usage implies set of arguments using pair: argument ⁠name⁠ and argument ⁠value⁠. and values in the format "⁠[name1=]value1 [name2]=value2⁠". No spaces around ⁠=⁠ (equal symbol). Argument ⁠name⁠ can be omitted, symbol ⁠=⁠ is omitted too. If argument ⁠value⁠ has spaces, then argument value should be surrounded by double quotes (fname="my test.shp"). If argument ⁠value⁠ is matched to R function, then such value should be surrounded by single quotes (layer='density').

Command line usage example: Rscript -e ursa::glance() 'final_more_than_032.sqlite' attr="select" resetProj=TRUE expand=1.5

For OS Windows, bat-file can be created for raster and vector file association: Rscript -e ursa::glance() %*

Command line usage implies external software for PNG view session_pngviewer(TRUE).

Value

glance returns integer: 0L - successful, 10L - call without arguments.

Note

Package sf is 'Suggested' for package ursa.

Author(s)

Nikita Platonov [e-mail]

Examples

session_grid(NULL)
f <- system.file("shape/nc.shp",package="sf")
glance(f,style="merc",field="(NAME|AREA|COUNT)")
cmd <- paste("Rscript --vanilla -e ursa::glance()",paste0("\"",f,"\"")
            ,"style=\"merc\"","field=\"(lon|lat)\"")
cat(" --------- Try in command line: -----------\n")
message(cmd)
cat(" ----------- end of quoting ---------------\n")
 ## windows: figure will be opened using *.png file association 
try(system(cmd,wait=FALSE))


if (isSP <- require(sp)) {
   a <- data.frame(lat=c(70.734,71.657),lon=c(178.577,-177.38),place="Wrangel Island")
   coordinates(a) <- ~lon+lat
   proj4string(a) <- "EPSG:4326"
}

 ## internet connection is required
if (isSP)
   glance(a,style="google color maptype=terrain")

 ## internet connection is required
if (isSP)
   glance(a,style="Positron",border=0)

 ## internet connection is required
if (isSP)
   glance(a,style="mapnik color tile",border=0)

 ## internet connection is required
if (isSP)
   glance("Svalbard",resetGrid=TRUE)