README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# s2

<!-- badges: start -->
[![R-CMD-check](https://github.com/r-spatial/s2/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-spatial/s2/actions/workflows/R-CMD-check.yaml)
[![codecov](https://codecov.io/gh/r-spatial/s2/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-spatial/s2)
[![CRAN](http://www.r-pkg.org/badges/version/s2)](https://cran.r-project.org/package=s2)
[![Downloads](http://cranlogs.r-pkg.org/badges/s2?color=brightgreen)](https://www.r-pkg.org/pkg/s2)
<!-- badges: end -->

The s2 R package provides bindings to Google's [S2Geometry](http://s2geometry.io) library. The package exposes an API similar to Google's [BigQuery Geography API](https://cloud.google.com/bigquery/docs/reference/standard-sql/geography_functions), whose functions also operate on spherical geometries. Package [sf](https://cran.r-project.org/package=sf) uses this package by default for nearly all its geometrical operations on objects with ellipsoidal (unprojected) coordinates; in cases where it doesn't, such as `st_relate()`, it emits a warning.

This package is a complete rewrite of an earlier CRAN package s2 with versions up
to 0.4-2, for which the sources are found [here](https://github.com/spatstat/s2/).

## Installation

You can install the released version of s2 from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("s2")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("r-spatial/s2")
```

The S2 package requires [Abseil]() and OpenSSL. You can install these using a system package manager on most platforms:

- Windows: Both OpenSSL and Abseil are available from RTools since R 4.3
- MacOS: `brew install openssl abseil`
- Debian/Ubuntu: `apt-get install libssl-dev libabsl-dev`
- Fedora: `dnf install openssl-devel abseil-cpp-devel`
- Alpine: `apk add abseil-cpp`

## Example

The s2 package provides geometry transformers and predicates similar to those found in [GEOS](https://trac.osgeo.org/geos/), except instead of assuming a planar geometry, s2's functions work in latitude and longitude and assume a spherical geometry:

```{r example}
library(s2)

s2_contains(
  # polygon containing much  of the northern hemisphere
  "POLYGON ((-63.5 44.6, -149.75 61.20, 116.4 40.2, 13.5 52.51, -63.5 44.6))",
  # ...should contain the north pole
  "POINT (0 90)"
)
```

The [sf package](https://r-spatial.github.io/sf/) uses s2 for geographic coordinates with `sf::sf_use_s2(TRUE)`, and will become the default after sf version 1.0.0. The sf package also supports creating s2 vectors using `as_s2_geography()`:

```{r, warning=FALSE, message = FALSE}
library(dplyr)
library(sf)

nc_s2 <- read_sf(system.file("shape/nc.shp", package = "sf")) %>%
  mutate(geometry = as_s2_geography(geometry)) %>%
  as_tibble() %>%
  select(NAME, geometry)

nc_s2
```

Use accessors to extract information about geometries:

```{r}
nc_s2 %>%
  mutate(
    area = s2_area(geometry),
    perimeter = s2_perimeter(geometry)
  )
```

Use predicates to subset vectors:

```{r}
nc_s2 %>%
  filter(s2_contains(geometry, "POINT (-80.9313 35.6196)"))
```

Use transformers to create new geometries:

```{r}
nc_s2 %>%
  mutate(geometry = s2_boundary(geometry))
```

Finally, use the WKB or WKT exporters to export to sf or some other package:

```{r}
nc_s2 %>%
  mutate(geometry = st_as_sfc(s2_as_binary(geometry))) %>%
  st_as_sf()
```

## Acknowledgment

This project gratefully acknowledges financial [support](https://www.r-consortium.org/) from the

<a href="https://www.r-consortium.org/">
<img src="man/figures/rc300.png" width="300" />
</a>