addPolys: Add Polygon PolySet to Existing Plot

In PBSmapping: Mapping Fisheries Data and Spatial Analysis Tools

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)

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.

Value

PolyData consisting of the PolyProps used to create the plot.

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.

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

PBSmapping documentation built on Sept. 30, 2024, 9:21 a.m.