panel_coastline: Add coastline to the image panel.

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

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)

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.

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.

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.

License

Coastal data (land polygons) is distributed under ODbL.

Note

In the versions <=3.7-19 package ursa contained land polygons based on union of "GSHHS_l_L1.shp" and "GSHHS_l_L5.shp" data from Self-consistent Hierarchical High-resolution Geography Database (GSHHG), Version 2.3.3 (01 November 2014), distributed under the Lesser GNU Public License, Version 3 (29 June 2007).

Author(s)

Nikita Platonov [e-mail]

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

ursa documentation built on Oct. 17, 2023, 5:11 p.m.