https://github.com/paleolimbot/geovctrs
Common Classes and Data Structures for Geometry Vectors
https://github.com/paleolimbot/geovctrs
Last synced: 5 months ago
JSON representation
Common Classes and Data Structures for Geometry Vectors
- Host: GitHub
- URL: https://github.com/paleolimbot/geovctrs
- Owner: paleolimbot
- License: other
- Created: 2020-03-29T13:59:38.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-07-24T18:59:22.000Z (over 5 years ago)
- Last Synced: 2025-04-15T21:52:57.787Z (7 months ago)
- Language: R
- Homepage: https://paleolimbot.github.io/geovctrs
- Size: 2.41 MB
- Stars: 25
- Watchers: 6
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
- Awesome-Geospatial - geovctrs - Common Classes and Data Structures for Geometry Vectors. (R)
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
dpi = 300,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# geovctrs
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://codecov.io/gh/paleolimbot/geovctrs?branch=master)
The goal of geovctrs is to provide a common set of classes and data structures to ensure that processing functions in the rapidly expanding R geospatial ecosystem are interchangeable.
## Installation
You can install the development version from [GitHub](https://github.com/) with:
``` r
# install.packages("remotes")
remotes::install_github("paleolimbot/geovctrs")
```
If you can load the package, you're good to go!
```{r example}
library(geovctrs)
```
## Geometry vectors
This package provides [vctrs](https://vctrs.r-lib.org/) class definitions several simple geometries that can be efficiently stored using column vectors (`geo_xy()`, `geo_xyz()`, `geo_segment()`, and `geo_rect()`). Well-known geometry (well-known binary and well-known text) vectors from the [wk](https://paleolimbot.github.io/wk) package are used for generic geometries. These classes are designed to work with [dplyr](https://dplyr.tidyverse.org/), [tidyr](https://tidyr.tidyverse.org/), and other [tidyverse](https://tidyverse.org/) packages that use vctrs. In addition to providing default implementations of [generics](#generics), they have print, plot, and coercion methods so that they "just work" when you need them to.
```{r}
head(geo_example_wkt)
head(as_wkb(geo_example_wkt))
```
## Constructing and destructing geometries
The geovctrs package provides functions to construct geometries from coordinates, and destruct geometries to extract their coordinates.
```{r}
# construct linestrings
linestrings <- c(
geo_linestring(geo_xy(c(1, 2, 5), c(0, 1, 2))),
geo_linestring(geo_xy(c(10, 20, 50), c(0, 10, 20)))
)
linestrings
# destruct to get coordinates
geo_coordinates(linestrings)
```
You can use `separate_xy()` get the actual x and y values (and `unite_xy()` to create a `geo_xy()` column).
```{r}
separate_xy(geo_coordinates(linestrings), "xy")
```
In the [newest version of dplyr](https://www.tidyverse.org/blog/2020/03/dplyr-1-0-0-summarise/), this is useful in conjunction with `group_by()` and `summarise()`.
```{r, message=FALSE, warning=FALSE}
library(dplyr)
geo_coordinates(linestrings) %>%
group_by(feature) %>%
summarise(geometry = geo_linestring(xy))
```
## Generics
There are several concepts that show up on repeat in geometry packages. The geovctrs package provides these as generics with reasonable implementations for the bundled [geometry vector classes](#geometry-vectors). Notably, `geo_bbox()`/`geo_envelope()` (return a `geo_rect()`), `geo_srid()`, and `geo_z()`. These generics work on anything that can be interpreted as a geometry vector, including character vectors (interpreted as well-known text), data frames with exactly one geometry column (interpreted as the geometry column), and anything that implements `as_geovctr()` (e.g., [sf](https://r-spatial.github.io/sf) objects).
```{r ex-plot}
geo_bbox(geo_nc)
geo_srid(head(geo_nc))
```
The geovctrs package also provides a framework for transformers, or functions that accept a vector of geometries and return a vector of geometries. These always return the same type as the input, as dictated by the implementations of `as_geovctr()` and `restore_geovctr()`. This enables transforming functions to work on a wide variety of input types, including sf objects:
```{r}
library(sf)
sf_nc <- read_sf(system.file("shape/nc.shp", package = "sf"))
geo_envelope(sf_nc)
```
See `vignette("extending-geovctrs", package = "geovctrs")` for instructions on how to create a class that works with the geovctrs framework.