Skip to contents

Get measurements for simple feature objects

Source: R/get_measurements.R
get_measurements.Rd

Get measurements for simple feature objects

Usage

get_area(x, units = NULL, keep_all = TRUE, drop = FALSE, .id = "area")

get_length(x, units = NULL, keep_all = TRUE, drop = FALSE, .id = "length")

get_dist(
  x,
  to,
  by_element = TRUE,
  units = NULL,
  drop = FALSE,
  keep_all = TRUE,
  .id = "dist",
  ...
)

get_bearing(x, dir = FALSE, keep_all = TRUE, .id = "bearing")

Arguments

x

A sf or sfc object to measure.

units

Units to return for area, length, perimeter, or distance; Default: NULL

keep_all

If TRUE, return all columns from the original object, Default: TRUE

drop

If TRUE, drop units from the line lengths, Default: FALSE

.id

Column name to use for area, line length/perimeter, distance, or bearing.

to

A sf, sfc, or bbox object or a length 2 character vector. If "to" is an sf or sfc object, it must have either a single feature or the same number of features as x (if by_element is TRUE). If "to" is a character vector it must represent a valid xy pair using the following options: "xmin", "ymin", "xmax", "ymax", "xmid", "ymid".

by_element

logical; if TRUE, return a vector with distance between the first elements of x and y, the second, etc. if FALSE, return the dense matrix with all pairwise distances.

...

passed on to s2_distance or s2_distance_matrix

dir

Logical indicator whether to include direction in bearing; If FALSE, return the absolute (positive) bearing value. If TRUE, return negative and positive bearing values. Default: FALSE.

Details

Wrapper functions for sf::geos_measures:

  • get_area: Wraps on sf::st_area but MULTIPOINT or MULTILINESTRING geometry is converted to a polygon using sf::st_polygonize which is used to determine the coverage area.

  • get_length: Wraps to sf::st_length but POINT and MULTIPOINT geometry is converted to LINESTRING using as_lines. If x has POLYGON geometry, lwgeom::st_perimeter is used to return the perimeter instead of the length.

  • get_dist: Wraps sf::st_distance but x is converted to a POINT using st_center and "to" can be a POINT, a sf object that can be converted to a POINT, or a character vector indicating a point on the overall bounding box for x.

Additional measurement functions:

See also

Other dist: convert_dist_scale(), convert_dist_units(), is_dist_units(), sf_bbox_misc

Examples

nc <- read_sf_path(system.file("shape/nc.shp", package = "sf"))

# Get area for North Caroline counties
get_area(nc[1:2,])$area
#> Units: [m^2]
#> [1] 1137107793  610916077
get_area(nc[1:2,], units = "acres")$area
#> Units: [acres]
#> [1] 280984.3 150960.0
get_area(nc[1:2,], units = "acres", .id = "acreage")$acreage
#> Units: [acres]
#> [1] 280984.3 150960.0

# Get distances for North Caroline counties
get_dist(nc[1,], to = c("xmax", "ymax"), units = "mile")$dist
#> 18.03826 [mile]
get_dist(nc[1,], to = nc[30,], units = "km")$dist
#> 239.2365 [km]

# Create a line between two counties
nc_line <- as_line(c(as_point(nc[1,]), as_point(nc[30,])), crs = nc)

# Get length and bearing of the line
get_length(nc_line)
#> Simple feature collection with 1 feature and 1 field
#> Geometry type: LINESTRING
#> Dimension:     XY
#> Bounding box:  xmin: -81.49823 ymin: 36.02862 xmax: -78.87809 ymax: 36.4314
#> Geodetic CRS:  NAD27
#>         length                       geometry
#> 1 239236.5 [m] LINESTRING (-81.49823 36.43...
get_bearing(nc_line)
#> Linking to GEOS 3.9.1, GDAL 3.4.2, PROJ 8.2.1; sf_use_s2() is TRUE
#> Simple feature collection with 1 feature and 1 field
#> Geometry type: LINESTRING
#> Dimension:     XY
#> Bounding box:  xmin: -81.49823 ymin: 36.02862 xmax: -78.87809 ymax: 36.4314
#> Geodetic CRS:  NAD27
#>    bearing                       geometry
#> 1 99.96725 LINESTRING (-81.49823 36.43...