PBSmapping: placeHoles – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

placeHoles

Place Holes Under Solids

Description

Place secondary polygons identified as holes (inner contours) under primary polygons identified as solids (outer contours) if the vertices of the holes lie completely within the vertices of the solids. This operation is performed for each primary polygon until all holes have been assigned.

Usage

placeHoles(polyset, minVerts=3, 
   orient=FALSE, show.progress=FALSE, unique.pid=FALSE)

Arguments

`polyset`	a valid PBSmapping PolySet.
`minVerts`	`numeric` – minimum number of vertices required for a polygon representing a hole to be retained (does not affect solids).
`orient`	`logical` – if `TRUE`, use each polygon's rotation to determine its nature: clockwise = solid (outer contour), counter-clockwise = hole (inner contour).
`show.progress`	`logical` – if `TRUE`, display on the command console the progress of placing holes under solids.
`unique.pid`	`logical` – if `TRUE`, ignore the input PIDs and redefine them from 1 to the number of solids; this inherently destroys the previous organisation that a creator may have intended for the PolySet.

Details

The algorithm identifies outer contours (solids) and inner contours (holes) using either the default PBSmapping method (solids = increasing "POS", holes = decreasing "POS") or the rotational direction of the polygons (solids = clockwise, holes = counter-clockwise).

It then systematically starts matching holes with solids based on their vertices being completely within the boundaries of the solid. If a hole happens to match a current solid completley (all vertices on the boundary), then the hole is not matched to this solid because it is a hole in another solid that creates space for the current solid.

To facilitate computation, the algorithm assumes that once a hole is located in a solid, it will not occur in any other solid. This means that for each successive solid, the number of candidate holes will either decrease or stay the same.

This function makes use of the PBSmapping hidden function ".is.in" which uses the C code "findPolys". The latter only returns events found in a polygon (or on the boundary) but .is.in evaluates all events and returns a list containing:
"e.in" – events within the polygon,
"e.out" – events outside the polygon,
"all.in" – logical value of whether all events are in the polygon,
"all.out" – logical value of whether all events are outside the polygon,
"all.bdry" – logical value of whether all events occur on the boundary of the polygon

Value

Returns the input PolySet where holes have been arranged beneath appropriate solids for each PID (original or redefined).

Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
locus opus: Institute of Ocean Sciences (IOS), Sidney BC
Last modified Rd: 2019-03-14