PBSmapping: rotatePolys – R documentation

Pricing

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

Get Started for Free

Documentation

PBSmapping

rotatePolys

Rotate Polygons and Events

Description

Rotate a PolySet (or an EventData set) clockwise by a specified angle around a fixed point.

Usage

rotatePolys(polys, angle=40, centroid=c(500,5700),
   proj.out, zone, xlim=c(-135,-121.5), ylim=c(47,56),
   plot=FALSE, keep.extra=FALSE, ...)

rotateEvents(data, angle=40, centroid=c(500,5700),
   proj.out, zone, plot=FALSE, keep.extra=FALSE, ...)

Arguments

`polys`	`PolySet` – data frame with fields `'PID'`, `'SID'`, `'POS'`, `'X'`, `'Y'`, and attribute `'projection'` set to either `"LL"` or `"UTM"`.
`data`	`EventData` – data frame with fields `'EID'`, `'POS'`, `'X'`, `'Y'`, and attribute `'projection'` set to either `"LL"` or `"UTM"`.
`angle`	`numeric` – angle between 0 and 360 degrees for map rotation in a clockwise direction.
`centroid`	`numeric` – fixed UTM point, specified in km, around which the map will be rotated. Rotation is performed in UTM space regardless of the input and output projections. If user specifies `'NULL'` or `'NA'`, the centroid of the map will be used.
`proj.out`	`character` – desired output projection, where choices are `'LL'` or `'UTM'`. If `'proj.out'` is not specified, the output projection will be the same as the projection of the input object.
`zone`	`numeric` – UTM zone used for rotation; if not supplied, the zone is set to 9.
`xlim`	`numeric` – two-element vector specifying the limits of X using units (degrees or km) that match the input projection.
`ylim`	`numeric` – two-element vector specifying the limits of Y using units (degrees or km) that match the input projection.
`plot`	`logical` – if `TRUE`, plot the results of the rotation.
`keep.extra`	`logical` – if `TRUE`, keep the coordinates of initial and intermediate steps in the rotation process in addition to the final rotated coordinates of the desired projection.
`...`	`dots` – additional arguments for `'plotMap'` (in `'rotatePolys'`) or `'plotPoints'` (in `'rotateEvents'`).

Details

Map rotation returns coordinates that are no longer meaningful with respect to the original coordinate system. When displaying rotated maps, the user might wish to turn off axis labels using xaxt="n" and yaxt="n".

Value

Rotated PolySet or EventData set where 'X' and 'Y' are the rotated coordinates in the projection specified by 'proj.out'. The returned object has an attribute list object named 'rotation' that contains:

angle – angle of clockwise rotation in degrees
radian – angle of rotation in radians: pi * (-angle)/180
centroid – fixed point in UTM coordinates (km) around which map is rotated in UTM projection
R – rotation matrix (2-dimensional)
xylim – list object to keep track of 'xlim', 'ylim' and a bounding box 'xybox'.
projection – projection of the rotated PolySet or EventData set
zone – zone of the rotated PolySet or EventData set

When keep.extra=TRUE, the returned object will contain additional fields calculated by the rotational algorithm:

(X0,Y0) – original coordinates of the input PolySet | EventData set
(uX0,uY0) – original coordinates converted to UTM (only if original projection is 'LL')
(aX,aY) – UTM coordinates adjusted by subtracting the UTM centroid
(tX,tY) – adjusted UTM coordinates transformed by multiplying the rotational matrix
(rX,rY) – rotated UTM coordinates re-centered by adding the UTM centroid

Note:
If proj.out="UTM", the coordinates c(rX, rY) are used as the final rotated coordinates. If proj.out="LL", the coordinates c(rX, rY) are transformed back into projection 'LL' as the final rotated coordinates.

Additionally, 'xylim' in the 'rotation' list attribute contains intermediary bounding box objects. For instance, if the input PolySet | EventData object has projection 'LL', the 'xylim' object contains:

LL – original (X,Y) limits ('xlim', 'ylim', 'xybox')
UTM – original (X,Y) limits transformed to UTM coordinates
rot – rotated UTM (X,Y) limits
out – final projection (X,Y) limits

Note

The map rotation algorithm is not heavily tested at this time. Report any issues to the package maintainer.

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

References

Academo – 2D Rotation about a point

Wikipedia – Rotation matrix