README.Rmd

---
output: github_document
---

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

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

<!-- badges: start -->
[![R build status](https://github.com/crazycapivara/h3-r/workflows/R-CMD-check/badge.svg)](https://github.com/crazycapivara/h3-r/actions)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![H3 Version](https://img.shields.io/badge/h3-v3.7.1-blue.svg)](https://github.com/uber/h3/releases/tag/v3.7.1)
[![CRAN status](https://www.r-pkg.org/badges/version/h3)](https://CRAN.R-project.org/package=h3)
<!-- badges: end -->

Provides R bindings for [H3](https://h3geo.org/), a hexagonal hierarchical spatial indexing system.

## Documentation

* [H3-R](https://crazycapivara.github.io/h3-r/)
* [H3](https://h3geo.org/docs/)

## Notes

Succesfully built on

* Linux
* macOS
* Windows

Since v3.7.1 {h3} comes with a bundled version of the H3 C library, so that you no longer have to build it yourself before installing the R package.

## Installation

Once on [CRAN](https://cran.r-project.org/) you can install {h3} with:

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

You can install the latest version of {h3} from github with:

```{r installation, eval = FALSE}
# install.packages("remotes")
remotes::install_github("crazycapivara/h3-r")
```

## Usage

Core functions:

```{r h3-core}
library(h3)

coords <- c(37.3615593, -122.0553238)
resolution <- 7

# Convert a lat/lng point to a hexagon index at resolution 7
(h3_index <- geo_to_h3(coords, resolution)) 

# Get the center of the hexagon
h3_to_geo_sf(h3_index)

# Get the vertices of the hexagon
h3_to_geo_boundary(h3_index)

# Get the polygon of the hexagon
h3_to_geo_boundary_sf(h3_index)
```

Useful algorithms:

```{r h3-algorithms}
# Get all neighbors within 1 step of the hexagon
radius <- 1
(neighbors <- k_ring(h3_index, radius))

h3_to_geo_boundary_sf(neighbors) %>%
  sf::st_geometry() %>% plot(col = "blue")

h3_set_to_multi_polygon(neighbors) %>%
  sf::st_geometry() %>% plot(col = "green")
```

## Run tests

```{r tests}
devtools::test(reporter = "minimal")
```