R: Compute geometric measurements

geos_measures {sf} | R Documentation

## Compute geometric measurements

### Description

Compute Euclidian or great circle distance between pairs of geometries; compute, the area or the length of a set of geometries.

### Usage

    st_area(x, ...)

    ## S3 method for class 'sfc'
    st_area(x, ...)

    st_length(x, ...)

    st_distance(
      x,
      y,
      ...,
      dist_fun,
      by_element = FALSE,
      which = ifelse(isTRUE(st_is_longlat(x)), "Great Circle", "Euclidean"),
      par = 0,
      tolerance = 0
    )

### Arguments

`x` | object of class `sf`, `sfc` or `sfg`
`...` | passed on to s2_distance or s2_distance_matrix
`y` | object of class `sf`, `sfc` or `sfg`, defaults to `x`
`dist_fun` | deprecated
`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.
`which` | character; for Cartesian coordinates only: one of `Euclidean`, `Hausdorff` or `Frechet`; for geodetic coordinates, great circle distances are computed; see details
`par` | for `which` equal to `Hausdorff` or `Frechet`, optionally use a value between 0 and 1 to densify the geometry
`tolerance` | ignored if `st_is_longlat(x)` is `FALSE`; otherwise, if set to a positive value, the first distance smaller than `tolerance` will be returned, and true distance may be smaller; this may speed up computation. In meters, or a `units` object convertible to meters.

### Details

great circle distance calculations use by default spherical distances (s2_distance or s2_distance_matrix); if `sf_use_s2()` is `FALSE`, ellipsoidal distances are computed using st_geod_distance which uses function `geod_inverse` from GeographicLib (part of PROJ); see Karney, Charles FF, 2013, Algorithms for geodesics, Journal of Geodesy 87(1), 43–55

### Value

If the coordinate reference system of `x` was set, these functions return values with unit of measurement; see set_units.

st_area returns the area of a geometry, in the coordinate reference system used; in case `x` is in degrees longitude/latitude, st_geod_area is used for area calculation.

st_length returns the length of a `LINESTRING` or `MULTILINESTRING` geometry, using the coordinate reference system. `POINT`, `MULTIPOINT`, `POLYGON` or `MULTIPOLYGON` geometries return zero.

If `by_element` is `FALSE` `st_distance` returns a dense numeric matrix of dimension length(x) by length(y); otherwise it returns a numeric vector of length `x` or `y`, the shorter one being recycled. Distances involving empty geometries are `NA`.

### See Also

st_dimension, st_cast to convert geometry types

### Examples

    b0 = st_polygon(list(rbind(c(-1,-1), c(1,-1), c(1,1), c(-1,1), c(-1,-1))))
    b1 = b0 + 2
    b2 = b0 + c(-0.2, 2)
    x = st_sfc(b0, b1, b2)
    st_area(x)
    line = st_sfc(st_linestring(rbind(c(30,30), c(40,40))), crs = 4326)
    st_length(line)

    outer = matrix(c(0,0,10,0,10,10,0,10,0,0),ncol=2, byrow=TRUE)
    hole1 = matrix(c(1,1,1,2,2,2,2,1,1,1),ncol=2, byrow=TRUE)
    hole2 = matrix(c(5,5,5,6,6,6,6,5,5,5),ncol=2, byrow=TRUE)

    poly = st_polygon(list(outer, hole1, hole2))
    mpoly = st_multipolygon(list(
    	list(outer, hole1, hole2),
    	list(outer + 12, hole1 + 12)
    ))

    st_length(st_sfc(poly, mpoly))
    p = st_sfc(st_point(c(0,0)), st_point(c(0,1)), st_point(c(0,2)))
    st_distance(p, p)
    st_distance(p, p, by_element = TRUE)

[Package sf version 1.0-7 Index]