PBSmapping (version 2.74.1)

addPolys: Add Polygon PolySet to Existing Plot

Description

Add a PolySet to an existing plot, where each unique (PID, SID) describes a polygon.

Usage

addPolys(polys, xlim = NULL, ylim = NULL, polyProps = NULL,
         border = NULL, lty = NULL, col = NULL, colHoles = NULL,
         density = NA, angle = NULL, ...)
.insertNAs(polys, idx)
.preparePolyProps(polysPID, polysSID, polyProps)
.rollupPolys(polys, rollupMode, exteriorCCW, closedPolys, addRetrace)

Value

PolyData consisting of the PolyProps used to create the plot.

Arguments

polys

data.frame -- PolySet to add (required)

xlim

numeric -- range of X-coordinates.

ylim

numeric -- range of Y-coordinates.

polyProps

data.frame -- PolyData specifying which polygons to plot and their properties. par parameters passed as direct arguments supersede these data.

border

character|numeric -- vector describing edge colours (cycled by PID).

lty

character|numeric -- vector describing line types (cycled by PID).

col

character|numeric -- vector describing fill colours (cycled by PID).

colHoles

character|numeric -- vector describing hole colours (cycled by PID). The default, NULL, should be used in most cases as it renders holes transparent. colHoles is designed solely to eliminate retrace lines when images are converted to PDF format. If colHoles is specified, underlying information (i.e., previously plotted shapes) will be obliterated. If NA is specified, only outer polygons are drawn, consequently filling holes.

density

numeric -- vector describing shading line densities (lines per inch, cycled by PID).

angle

numeric -- vector describing shading line angles (degrees, cycled by PID).

...

dots -- additional par parameters for the polygon function.

idx

character|numeric -- index of PIDs used to extract select polygons/polylines from a PolySet

polysPID

numeric -- vector of primary polygon identification numbers (PIDs)

polysSID

numeric -- vector of secondary polygon identification numbers (SIDs)

rollupMode

numeric -- method for rolling up a PolySet; essentially controls when to introduce a new PID (or PID,SID). Options:
1 = roll-up to the PID level (only PIDs in the result)
2 = roll-up to the outer contour level (only outer contours in the result)
3 = do not roll-up

exteriorCCW

numeric -- modify orientation of vertices (clockwise or counter-clockwise):
-1 = do not modify
0 = exterior should be clockwise
+1 = exterior should be counter-clockwise

closedPolys

numeric -- whether the last and first vertices should be the same:
-1 = do not modify
0 = ensure polygons do not close
+1 = close the polygons

addRetrace

numeric -- determines whether to add retrace lines to the first vertex of the parent after outputting a child:
0 = do not add
1 = add

Author

Nicholas M. Boers, Software Engineer, Jobber, Edmonton AB

Maintainer: Rowan Haigh, Program Head -- Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Remote office, Vancouver BC
Last modified Rd: 2024-09-03

Details

The plotting routine connects the last vertex of each discrete polygon to the first vertex of that polygon. It supports both borders (border, lty) and fills (col, density, angle). It clips polys to xlim and ylim before plotting.

For additional help on the arguments border, lty, col, density, and angle, please see polygon and par.

See Also

In package PBSmapping:
addLabels, addLines (also uses '.preparePolyProps' and '.insertNAs'), addPoints, addStipples
'.rollupPolys' is also called by:
calcArea, calcCentroid, calcLength, calcSummary, fixPOS

Examples

local(envir=.PBSmapEnv,expr={
  oldpar = par(no.readonly=TRUE)
  #--- create a PolySet to plot
  polys <- data.frame(PID=rep(1,4),POS=1:4,X=c(0,1,1,0),Y=c(0,0,1,1))
  polys <- as.PolySet(polys, projection=1)
  #--- plot the PolySet
  plotPolys(polys,xlim=c(-.5,1.5),ylim=c(-.5,1.5),density=0,projection=1)
  #--- add the PolySet to the plot (in a different style)
  addPolys(polys,col="green",border="blue",lwd=3)
  par(oldpar)
})