addPolys function

Add Polygon PolySet to Existing Plot

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

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)

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

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.

Note

Auxiliary dot function '.insertNAs' facilitates (hastens) the plotting of polygons and polylines. It also reduces the incidence of retrace lines.

Auxiliary dot function '.preparePolyProps' performs at least one of the following tasks:

1. creates 'polyProps' if it equals NULL;

2. adds 'SID' column to 'polyProps' if one exists in 'polys';

3. removes from 'polyProps' any PIDs that do not exist in 'polys'.

Returns a polyProps object.

Auxiliary dot function '.rollupPolys' does not validate a PolySet; returns a rolled-up PolySet or NULL.

Returns

PolyData consisting of the PolyProps used to create the plot.

Author(s)

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

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