ursa (version 3.11.1)

panel_coastline: Add coastline to the image panel.

Description

panel_coastline puts a coastline to the active panel of layout with optional land shadowing. The package provides data for coastline.

Usage

compose_coastline(...)
panel_coastline(...)
update_coastline(merge = TRUE)
# not public
.compose_coastline(obj = NULL, panel = 0, col = NA, fill = "transparent",
                    detail = NA, density = NA, angle = NA, land = FALSE,
                    lwd = 0.5, lty = 1, fail180 = NA, verbose = FALSE)
# not public
.panel_coastline(obj, verbose = FALSE)

Value

panel_coastline returns NULL

compose_coastline returns of object of class ursaCoastLine. It is a list:

coast_xy

Two-column matix of coordinates in the sessional projection. The polygons are separated by c(NA,NA) rows.

panel

Integer. Panel for coastline displaying. If 0L, then coastline is displayed on each panel.

col

See description of argument col.

fill

See description of argument fill.

shadow

If filling is semi-transparent, then it is "alpha" of filling color (argument fill).

land

See description of argument land.

density

See description of argument density.

angle

See description of argument angle.

lwd

See description of argument lwd.

lty

See description of argument lty.

Arguments

...

Set of arguments, which are recognized via their names (using regular expressions) and classes:

Matched pattern	Used name	Description
coast(line)*		Logical or integer. Responsible for should coastline be displayed or not. If integer, the indicates panel index for coastline displaying. If TRUE then coastline is plotted. If FALSE then coastline is not displayed. Default is TRUE.
(obj)*	obj	See below.
panel	panel	See below.
fill	fill	See below.
detail	detail	See below.
density	density	See below.
angle	angle	See below.
land	land	See below.
lwd	lwd	See below.
lty	lty	See below.
fail180	fail180	See below.
verb(ose)*	verbose	See below.

obj

Objects of the one of the classes Spatial, sfc, ursaCoastLine. The last one is internal structure, which is returned by function .compose_coastline.

panel

Integer vector. Panel for which coastline will be displayed. 0L means that coastline will bw displayed for all panels. Default is 0L.

col

Character. Color code/name for coastline. Default is "grey60".

fill

Character. Color code/name for land masking/shadowing. Default is "transapent".

detail

Character keyword. The categorical spatial resolution for coastline. Valid values are "l" (low), "m" (medium), "h" (high), "f" (full). If value is NA, then coasline resolution is selected internally. Default is NA.

density

Numeric. The density of shading lines for land masking/shadowing. If NA then no shading lines are drawn. Default is NA. See density in polygon.

angle

Numeric. The slope of shading lines, given as an angle in degrees (counter-clockwise). If NA then no shading lines are drawn. Default is NA. See angle in polygon.

land

Logical. If TRUE then map's accent is to land, and ocean is masked/shadowed. If FALSE then map's accent is to ocean, and land is masked/shadowed. Default is FALSE.

lwd

Positive numeric. Width of coastline. Default is 1. See lwd in par.

lty

Positive integer. Type (pattern) of coastline. Default is 1L (solid). See lty in par.

fail180

Logical. Patch for correct plotof polygons crossing 180 degree longitude. NA means than decision is taken intuitively. TRUE forces to implement crossing og 180 degree longitude. FALSE forces to not implement crossing og 180 degree longitude. Default is NA.

verbose

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

merge

Logical. Ingored.

Author

Nikita Platonov

License

Coastal data (land polygons) is distributed under ODbL.

Details

compose_coastline forms an obect of class ursaCoastLine. panel_coastline displays object of class ursaCoastLine. It is expected higher performance for multi-panel plotting.

If obj is NULL, then internal data is used. This data is based on simplified polygons of OpenStreetMap-derived data. Source data is licensed under the Open Data Commons Open Database License (ODbL). The crossing longitude 180 degrees polygons are merged. Removing of small polygons and simplifying of polygons geometry is applied for three levels of details ("l" - low, "i" - interim, "h" - high). For the full ("f") level of details data simplification is not applied.

Coastline data are taken from directory, which is specified by getOption("ursaRequisite") with default value system.file("requisite",package="ursa"). Package contains data of "l" (low) details level in the file system.file("requisite/coast-l.rds",package="ursa"). Data of higher levels can be added using update_coastline() function. It is required to specify user's requisite path using options(ursaRequisite=path/to/user/files) before loading ursa, e.g. in the user's ~/.Rprofile file. Otherwise, there is a chance that data can not be updated due to 'permission deny' of the system directories. Package sf and some it's suggestions are required for data update.

If detail=NA then the spatial resolution is selected using CRS boundary and resolution using intuitive approach. If package's database cannot supply required details, then lower resolution is used.

Source coastline data in EPSG:4326 are transformed to CRS projection, extracted using session_grid function. Coastlines with optional filling of either land or ocean area is interpreted as polygons. If filling is solid (there is no transparency or shading lines (numerical values of arguments density and angle), then coastline plotting is imlemented via polypath function, otherwise polygon function.

Examples

session_grid(NULL)
a <- pixelsize()
p1 <- colorize(a[a>500],ramp=FALSE,interval=TRUE)
p2 <- colorize(a,ramp=FALSE,pal=colorRampPalette(c("grey40","grey100"))
              ,verbose=!TRUE,interval=TRUE)
compose_open(layout=c(2,2),legend=list(list(1,"right"),list(2,"left")))
for (i in 1:4) {
   panel_new(col=ifelse(i==2,"white",NA))
   if (i %in% c(3,4))
      panel_raster(p1)
   else if (i %in% 2)
      panel_raster(p2)
   if (i==1)
      panel_coastline()
   panel_coastline(coast=4,col="#007F00",fill="lightgreen",land=TRUE)
   panel_coastline(coast=3,col="#0000003F",fill="#0000003F")
   panel_coastline(coast=2,col="black",fill="black",density=20
                   ,angle=c(-45,45),lwd=0.25,detail="l")
  # panel_graticule(decor=4)
   panel_annotation(text=as.character(i))
   if (i==1)
      panel_annotation(pos=c(1,1),text="default")
   else if (i==2)
      panel_annotation(pos=c(0,1),text="greyscale")
   else if (i==3)
      panel_annotation(pos=c(1,1),text="land is shadowed")
   else if (i==4)
      panel_annotation(pos=c(0,1),text="ocean is masked")
}
compose_legend(p2,p1)
compose_close()