sgo_points: Object containing 2D or 3D point coordinates

Description

2D or 3D coordinates (and other attributes) of a point or collection of points

Usage

sgo_points(x, coords = NULL, epsg = NULL)
# S3 method for sgo_points
print(x, ..., n = 6L)
# S3 method for sgo_points
as.data.frame(x, row.names = NULL, optional = FALSE, ...)
# S3 method for sgo_points
as.list(x, ...)

Value

An object of class sgo_points. This object is a actually a list with class sgo_points and at least 5 elements (or 6 elements if it is 3D):

x: A numeric vector containing easting or longitude coordinates.
y: A numeric vector with northing or latitude coordintes.
z: A numeric vector with height values when the object is 3D.
epsg: A scalar value with the EPSG code of the current Geographic Coordinate System (GCS).
datum: A string describing the geodetic datum that defines the GCS of the object. Currently can take the values "OSGB36", "WGS84" or "ETRS89"
dimension: A string describing whether the object is 2D or 3D. It can take the values "XY" or "XYZ".

Arguments

x

A matrix, list or dataframe with at least 2 columns of either easting/northing or longitude/latitude coordinates per row. A column with height values is optional. Please note that the order is important when x has only 2 or 3 columns and coords is not informed: lat/lon or northing/easting (and height) will produce wrong results.

coords

A vector with the names of the two or three columns containing the X (easting or longitude), Y (northing or latitude) and optionally Z (ellipsoid or orthometric height) coordinates.

epsg

Specifies the EPSG code of coordinates to store. It can take any of the following values:

when working with (2D/3D) ETRS89 Datum: 4258, 4937, 4936, 3035
when working with (2D/3D) WGS84 Datum:4326, 4979, 4978
when working with (2D/3D) OSGB36 Datum:4277, 27700, 7405
WGS84/Pseudo-Mercator (Google Maps, OpenStreetMap, etc.): 3857

...

Further arguments passed to or from other methods, see print, as.data.frame or as.list .

n

Maximum number of features to print.

row.names

NULL or a character vector giving the row names for the data frame. Missing values are not allowed.

optional

Logical. See as.data.frame

Details

This object stores 2D or 3D point coordinates and any other column-list of attributes related to each point. Note that additional column-lists will be expanded with NA values if they contain less elements than coordinates. Currently it only supports the following epsgs:

4258: ETRS89, geodetic coordinate system. The columns in x must be defined as Longitude and Latitude (sgo also accepts a third column for ellipsoid heights). The defined datum for this set of coordinates is ETRS89 (https://epsg.io/4258).
4937: ETRS89, geodetic coordinate system. The columns in x must be defined as Longitude, Latitude and Ellipsoid Heights respectively. The defined datum for this set of coordinates is ETRS89 (https://epsg.io/4937).
4936: ETRS89, geodetic coordinate system. The columns in x must be defined as cartesian coordinates x, y and z. The defined datum for this set of coordinates is ETRS89 (https://epsg.io/4936).
3035: ETRS-LAEA, projected coordinate system. The columns in x must be defined as Easting and Northing. The defined datum for this set of coordinates is ETRS89 (https://epsg.io/3035)
4326: WGS84, geodetic coordinate system. The columns in x must be defined as Longitude and Latitude (sgo also accepts a third column for ellipsoid heights). The defined datum for this set of coordinates is WGS84 (https://epsg.io/4326).
4979: WGS84, geodetic coordinate system. The columns in x must be defined as Longitude, Latitude and Ellipsoid Height respectively. The defined datum for this set of coordinates is WGS84 (https://epsg.io/4979)
4978: WGS84, geodetic coordinate system. The columns in x must be defined as cartesian coordinates x, y and z. The defined datum for this set of coordinates is WGS84 (https://epsg.io/4978)
4277: OSGB36, geodetic coordinate system. The 2 columns in x must be defined as Longitude and Latitude values respectively. The defined datum for this set of coordinates is OSGB 1936 (https://epsg.io/4277). Coordinates defined like this should only be used for historical reasons and to convert only to or from BNG coordinates. Height values will be discarded when working with this coordinate system.
27700: British National Grid, projected coordinate system. The columns in x must be defined as Easting and Northing (sgo also accepts a third column for orthometric heights). The defined datum for this set of coordinates is OSGB 1936 (https://epsg.io/27700).
7405: British National Grid, projected coordinate system. The columns in x must be defined as Easting, Northing and ODN Orthometric height respectively (sgo accepts heights from other datums like Orkney, Lerwick, Stornoway, Douglas, St.Marys and 'Newlyn offshore'). The defined datum for this set of coordinates is OSGB 1936 (https://epsg.io/7405).
3857: WGS 84 / Pseudo-Mercator, projected coordinate system. The columns in x must be defined as Easting and Northing. The defined datum for this set of coordinates is WGS84 (https://epsg.io/3857)

Examples

Run this code

# lists:
p1 <- sgo_points(list(-3.9369, 56.1165), epsg=4326)
lon <- c(-4.25181,-3.18827)
lat <- c(55.86424, 55.95325)
p2 <- sgo_points(list(longitude=lon, latitude=lat), epsg=4326)
#p3 will fill up the list 'desc' with NA's to have the same number of
#elements as coordinates in the list:
p3 <- sgo_points(list(longitude=lon, latitude=lat, desc="c1"),
                 coords=c("longitude", "latitude"), epsg=4326)
# dataframe:
ln <- c(-4.22472, -2.09908)
lt <- c(57.47777, 57.14965)
n <- c("Inverness", "Aberdeen")
df <- data.frame(n, ln, lt, stringsAsFactors = FALSE)
p4 <- sgo_points(df, coords=c("ln", "lt"), epsg=4326)

# plotting on a map:
if (require(maps)) {
  map('world', regions=('uk'), xlim=c(-9, 0), ylim=c(54.5, 60.9))
  points(x=p1$x, y=p1$y, pch=0, col="green") #Stirling
  points(p4, pch=0, col="red")
  text(p4, labels=p4$n, pos=1, cex=0.9)
}