PBSmapping (version 2.73.2)

PolySet: PolySet Objects

Description

A PolySet object comprises a data frame that defines a collection of polygonal contours (i.e., line segments joined at vertices). These contours can be open-ended (polylines) or closed (polygons).

PBSmapping functions that expect PolySet's will accept properly formatted data frames in their place (see 'Details').

as.PolySet attempts to coerce a data frame to an object with class PolySet.

is.PolySet returns TRUE if its argument is of class PolySet.

Usage

as.PolySet(x, projection = NULL, zone = NULL)
is.PolySet(x, fullValidation = TRUE)

Value

The as.PolySet method returns an object with classes

"PolySet" and "data.frame", in that order.

Arguments

x

data frame to be coerced or tested.

projection

optional projection attribute to add to the PolySet, possibly overwriting an existing attribute.

zone

optional zone attribute to add to the PolySet, possibly overwriting an existing attribute.

fullValidation

Boolean value; if TRUE, fully test x.

Author

Nicholas M. Boers, Associate Professor -- Computer Science
MacEwan University, Edmonton AB
Last modified Rd: 2022-09-06

Details

In our software, a PolySet data frame defines a collection of polygonal contours (i.e., line segments joined at vertices), based on four or five numerical fields:

  • PID - the primary identification number for a contour;

  • SID - optional, the secondary identification number for a contour;

  • POS - the position number associated with a vertex;

  • X - the horizontal coordinate at a vertex;

  • Y - the vertical coordinate at a vertex.

The simplest PolySet lacks an SID column, and each PID corresponds to a different contour. By analogy with a child's “follow the dots” game, the POS field enumerates the vertices to be connected by straight lines. Coordinates (X, Y) specify the location of each vertex. Thus, in familiar mathematical notation, a contour consists of \(n\) points (\(x_{i}, y_{i}\)) with \(i = 1, ..., n\), where \(i\) corresponds to the POS index. A PolySet has two potential interpretations. The first associates a line segment with each successive pair of points from 1 to \(n\), giving a polyline (in GIS terminology) composed of the sequential segments. The second includes a final line segment joining points \(n\) and 1, thus giving a polygon.

The secondary ID field allows us to define regions as composites of polygons. From this point of view, each primary ID identifies a collection of polygons distinguished by secondary IDs. For example, a single management area (PID) might consist of two fishing areas, each defined by a unique SID. A secondary polygon can also correspond to an inner boundary, like the hole in a doughnut. We adopt the convention that POS goes from 1 to \(n\) along an outer boundary, but from \(n\) to 1 along an inner boundary, regardless of rotational direction. This contrasts with other GIS software, such as ArcView (ESRI 1996), in which outer and inner boundaries correspond to clockwise and counter-clockwise directions, respectively.

The SID field in a PolySet with secondary IDs must have integer values that appear in ascending order for a given PID. Furthermore, inner boundaries must follow the outer boundary that encloses them. The POS field for each contour (PID, SID) must similarly appear as integers in strictly increasing or decreasing order, for outer and inner boundaries respectively. If the POS field erroneously contains floating-point numbers, fixPOS can renumber them as sequential integers, thus simplifying the insertion of a new point, such as point 3.5 between points 3 and 4.

A PolySet can have a projection attribute, which may be missing, that specifies a map projection. In the current version of PBS Mapping, projection can have character values "LL" or "UTM", referring to “Longitude-Latitude” and “Universal Transverse Mercator”. We explain these projections more completely below. If projection is numeric, it specifies the aspect ratio \(r\), the number of \(x\) units per \(y\) unit. Thus, \(r\) units of \(x\) on the graph occupy the same distance as one unit of \(y\). Another optional attribute zone specifies the UTM zone (if projection="UTM") or the preferred zone for conversion from Longitude-Latitude (if projection="LL").

A data frame's class attribute by default contains the string "data.frame". Inserting the string "PolySet" as the class vector's first element alters the behaviour of some functions. For example, the summary function will print details specific to a PolySet. Also, when PBSprint is TRUE, the print function will display a PolySet's summary rather than the contents of the data frame.

References

Environmental Systems Research Institute (ESRI). (1996) ArcView GIS: The Geographic Information System for Everyone. ESRI Press, Redlands, California. 340 pp.

See Also

PolyData, EventData, LocationSet