| Title: | Access Uber's H3 Library |
|---|---|
| Description: | Provides access to Uber's H3 library for geospatial indexing via its JavaScript transpile 'h3-js' <https://github.com/uber/h3-js> and 'V8' <https://github.com/jeroen/v8>. |
| Authors: | Lauren O'Brien [aut, cre] |
| Maintainer: | Lauren O'Brien <[email protected]> |
| License: | Apache License (>= 2) |
| Version: | 1.3.1 |
| Built: | 2024-10-06 03:03:57 UTC |
| Source: | https://github.com/obrl-soil/h3jsr |
This package uses package V8 to access the javascript bindings for Uber's H3 library
Maintainer: Lauren O'Brien [email protected] (ORCID)
Useful links:
This function checks whether two H3 cells share an edge.
are_neighbours(origin = NULL, destination = NULL, simple = TRUE)are_neighbours(origin = NULL, destination = NULL, simple = TRUE)
origin |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
destination |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
Logical; TRUE if neighbours.
The number of indexes supplied to origin and destination must be equal.
This function will always return false if the indexes are of different resolutions.
# Are the following cells neighbours? are_neighbours(origin = '86be8d12fffffff', destination = '86be8d127ffffff')# Are the following cells neighbours? are_neighbours(origin = '86be8d12fffffff', destination = '86be8d127ffffff')
This function calculates the exact area of an H3 cell.
cell_area(h3_address = NULL, units = c("m2", "km2", "rads2"), simple = TRUE)cell_area(h3_address = NULL, units = c("m2", "km2", "rads2"), simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
units |
Length unit to report in. Options are square meters, square kilometers, or steradians. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a numeric vector of length(h3_address).
cell_area(h3_address = '8abe8d12acaffff', 'm2')cell_area(h3_address = '8abe8d12acaffff', 'm2')
Get the position of the cell within an ordered list of all children of the cell's parent at the specified resolution.
cell_to_childpos(h3_address = NULL, parent_res = NULL, simple = TRUE)cell_to_childpos(h3_address = NULL, parent_res = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
parent_res |
numeric; resolution of reference parent cell. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
Numeric, Position of child within parent at 'parent_res'.
Function will return 0 if 'parent_res' is the same as the resolution of the supplied cell.
# example address has resolution 7 cell_to_childpos('872830b82ffffff', c(3,4,5,6), simple = FALSE)# example address has resolution 7 cell_to_childpos('872830b82ffffff', c(3,4,5,6), simple = FALSE)
Get the number of children for a cell at a given resolution.
cell_to_children_size(h3_address = NULL, child_res = NULL, simple = TRUE)cell_to_children_size(h3_address = NULL, child_res = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
child_res |
numeric; child resolution to report on. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
numeric; number of children at the requested resolution
# example address has resolution 7: cell_to_children_size('872830b82ffffff', c(8,9,10,11), simple = FALSE)# example address has resolution 7: cell_to_children_size('872830b82ffffff', c(8,9,10,11), simple = FALSE)
Return line geometry for a sequence of H3 cell indexes in WGS84 coordinates.
cell_to_line(input = NULL, simple = TRUE) ## S3 method for class 'data.frame' cell_to_line(input = NULL, simple = TRUE) ## S3 method for class 'list' cell_to_line(input = NULL, simple = TRUE) ## S3 method for class 'character' cell_to_line(input = NULL, simple = TRUE)cell_to_line(input = NULL, simple = TRUE) ## S3 method for class 'data.frame' cell_to_line(input = NULL, simple = TRUE) ## S3 method for class 'list' cell_to_line(input = NULL, simple = TRUE) ## S3 method for class 'character' cell_to_line(input = NULL, simple = TRUE)
input |
Character vector of 15-character indexes generated by H3, a
list of such, or a data frame where the last column is a list-column of H3
cell indexes (usually the output of
|
simple |
Logical; whether to return an |
An sfc_LINESTRING object containing a line for each vector of
H3 cell indexes supplied. If simple = FALSE, an sf object
including the input data.
This function can accept any arbitrary vector of cell indexes (including cells at multiple resolutions) but results may be unexpected. It is assumed that indexes are supplied in a pre-ordered fashion.
# What is the cell index over the Brisbane Town Hall at resolution 10? brisbane_hex_10 <- cell_to_polygon(input = '8abe8d12acaffff') # Give me a some nearby cells hex_sample <- get_disk_list('8abe8d12acaffff', 4)[[1]][[4]][seq(1,18,3)] hex_sample_polys <- cell_to_polygon(hex_sample) # find connecting paths paths <- grid_path(rep('8abe8d12acaffff', 6), hex_sample) # make lines lines <- cell_to_line(paths) ## Not run: plot(hex_sample_polys, reset = FALSE) plot(brisbane_hex_10, add = TRUE) plot(lines, col = 'red', add = TRUE) ## End(Not run)# What is the cell index over the Brisbane Town Hall at resolution 10? brisbane_hex_10 <- cell_to_polygon(input = '8abe8d12acaffff') # Give me a some nearby cells hex_sample <- get_disk_list('8abe8d12acaffff', 4)[[1]][[4]][seq(1,18,3)] hex_sample_polys <- cell_to_polygon(hex_sample) # find connecting paths paths <- grid_path(rep('8abe8d12acaffff', 6), hex_sample) # make lines lines <- cell_to_line(paths) ## Not run: plot(hex_sample_polys, reset = FALSE) plot(brisbane_hex_10, add = TRUE) plot(lines, col = 'red', add = TRUE) ## End(Not run)
This function takes a H3 cell index and returns its center coordinates in WGS84.
cell_to_point(h3_address = NULL, simple = TRUE)cell_to_point(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, an sfc_POINT object of length(h3_address).
EPSG:WGS84.
# Where is the center of the hexagon over the Brisbane Town Hall at resolution 10? brisbane_10 <- cell_to_point(h3_address = '8abe8d12acaffff')# Where is the center of the hexagon over the Brisbane Town Hall at resolution 10? brisbane_10 <- cell_to_point(h3_address = '8abe8d12acaffff')
This function takes an H3 cell index and returns its bounding shape (usually a hexagon) in WGS84.
cell_to_polygon(input = NULL, simple = TRUE)cell_to_polygon(input = NULL, simple = TRUE)
input |
Character; 15-character index generated by H3, or a vector or list of same, or a data frame where the first column contains H3 addresses. |
simple |
Logical; whether to return an |
By default, an sfc_POLYGON object of length(input). If an
appropriately formatted data frame is supplied, an sf data frame
containing input attributes and geometry.
# What is the hexagon over the Brisbane Town Hall at resolution 10? brisbane_hex_10 <- cell_to_polygon(input = '8abe8d12acaffff') # Give me some of the cells over Brisbane Town Hall as an sf object bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326) bth_addys <- unlist(point_to_cell(bth, res = seq(10, 15)), use.names = FALSE) bth_hexes <- cell_to_polygon(input = bth_addys) plot(bth_hexes, axes = TRUE)# What is the hexagon over the Brisbane Town Hall at resolution 10? brisbane_hex_10 <- cell_to_polygon(input = '8abe8d12acaffff') # Give me some of the cells over Brisbane Town Hall as an sf object bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326) bth_addys <- unlist(point_to_cell(bth, res = seq(10, 15)), use.names = FALSE) bth_hexes <- cell_to_polygon(input = bth_addys) plot(bth_hexes, axes = TRUE)
Convert an H3 cell (64-bit hexidecimal string) into a "split long" - a pair of 32-bit integers.
cell_to_splitlong(h3_address, simple = TRUE)cell_to_splitlong(h3_address, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
list of integer pairs, one for each address supplied.
cell_to_splitlong(h3_address = '8abe8d12acaffff')cell_to_splitlong(h3_address = '8abe8d12acaffff')
This function returns geometry associated with a set of H3 cells, as a
single sfc_MULTIPOLYGON.
cells_to_multipolygon(h3_addresses = NULL, simple = TRUE)cells_to_multipolygon(h3_addresses = NULL, simple = TRUE)
h3_addresses |
Character vector or list of 15-character cell indices generated by H3. |
simple |
Logical; whether to return an |
By default, object of type sfc_MULTIPOLYGON of length 1.
The geometry returned by this function will not be valid where the
addresses supplied overlap at the same resolution. The main use case for
this function appears to be visualising the outputs of
polygon_to_cells and
compact.
## Not run: # Give me the outline of the cells around Brisbane Town Hall at # resolution 10 (not run as slow-ish) bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326) bth_10 <- point_to_h3(bth, res = 10) bth_patch <- get_disk(h3_address = bth_10, ring_size = 2) bth_patch_sf <- cells_to_multipolygon(bth_patch) ## End(Not run)## Not run: # Give me the outline of the cells around Brisbane Town Hall at # resolution 10 (not run as slow-ish) bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326) bth_10 <- point_to_h3(bth, res = 10) bth_patch <- get_disk(h3_address = bth_10, ring_size = 2) bth_patch_sf <- cells_to_multipolygon(bth_patch) ## End(Not run)
Get the child cell at a given position within an ordered list of all children at the specified resolution.
childpos_to_cell( child_pos = NULL, h3_address = NULL, child_res = NULL, simple = TRUE )childpos_to_cell( child_pos = NULL, h3_address = NULL, child_res = NULL, simple = TRUE )
child_pos |
numeric; position of the child cell to get. |
h3_address |
Character; 15-character index generated by H3. |
child_res |
numeric; resolution of the child cell to return. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
Character, H3 address of child
'child_pos' is 0-indexed and capped at the maximum number of hexagons within the parent cell at the supplied resolution. This figure can be determined using cell_to_children_size.
# example address has resolution 7: childpos_to_cell(0, '872830b82ffffff', 9, simple = FALSE)# example address has resolution 7: childpos_to_cell(0, '872830b82ffffff', 9, simple = FALSE)
This function compacts a set of cells of the same resolution into a set of cells across multiple resolutions that represents the same area.
compact(h3_addresses = NULL, simple = TRUE)compact(h3_addresses = NULL, simple = TRUE)
h3_addresses |
Character vector or list of 15-character indices
generated by H3 at a single resolution, generally the output of
|
simple |
Logical; whether to return a vector of outputs or a list object containing both inputs and outputs. |
A list of H3 cells with multiple resolutions. The minimum resolution of the output list matches the resolution of the input list.
## Not run: # Give me a compacted representation of County Ashe, NC nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc1 <- nc[1, ] nc1 <- sf::st_cast(nc1, 'POLYGON') fillers <- polygon_to_cells(geometry = nc1, res = 6) compacted <- compact(fillers) ## End(Not run)## Not run: # Give me a compacted representation of County Ashe, NC nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc1 <- nc[1, ] nc1 <- sf::st_cast(nc1, 'POLYGON') fillers <- polygon_to_cells(geometry = nc1, res = 6) compacted <- compact(fillers) ## End(Not run)
Convert degrees to radians.
degs_to_rads(degree = NULL, lang = c("r", "h3"), simple = TRUE)degs_to_rads(degree = NULL, lang = c("r", "h3"), simple = TRUE)
degree |
Numeric, value in degrees |
lang |
Character; whether to perform the conversion using base R or the H3 library. Defaults to R for speed. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
Numeric, value in radians
degs_to_rads(120)degs_to_rads(120)
This function calculates the exact length of an H3 cell edge.
edge_length(h3_edge = NULL, units = c("m", "km", "rads"), simple = TRUE)edge_length(h3_edge = NULL, units = c("m", "km", "rads"), simple = TRUE)
h3_edge |
Character; address of unidirectional edge. |
units |
Length unit to report in. Options are meters, kilometers, or radians. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a numeric vector of length(h3_address).
edge_length(h3_edge = '166be8d12fffffff', 'm')edge_length(h3_edge = '166be8d12fffffff', 'm')
This function returns the number of the base (Level 1) cell for an H3 cell idnex.
get_base_cell(h3_address = NULL, simple = TRUE)get_base_cell(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, an integer vector of length(h3_address), ranging from
0 to 121.
# What is Brisbane Town Hall's base cell number? get_base_cell(h3_address = '8abe8d12acaffff')# What is Brisbane Town Hall's base cell number? get_base_cell(h3_address = '8abe8d12acaffff')
This function returns the vertex index for a supplied H3 cell and vertex number.
get_cell_vertex(h3_address = NULL, v_num = 0, simple = TRUE)get_cell_vertex(h3_address = NULL, v_num = 0, simple = TRUE)
h3_address |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
v_num |
Numeric; the vertex number required. Options are 0-5 inclusive. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address).
# Get vertex 3 for this cell get_cell_vertex(h3_address = '86be8d12fffffff', 3)# Get vertex 3 for this cell get_cell_vertex(h3_address = '86be8d12fffffff', 3)
This function returns all 6 vertex indices for a supplied H3 cell.
get_cell_vertexes(h3_address = NULL, simple = TRUE)get_cell_vertexes(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address).
# Get vertexes for this cell get_cell_vertexes(h3_address = '86be8d12fffffff')# Get vertexes for this cell get_cell_vertexes(h3_address = '86be8d12fffffff')
This function returns the central child of a particular H3 cell index at the requested resolution.
get_centerchild(h3_address = NULL, res = NULL, simple = TRUE)get_centerchild(h3_address = NULL, res = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address). Each list element contains
a vector of H3 cells.
# What is the central child of this resolution 6 index at resolution 8? get_centerchild(h3_address = '86be8d12fffffff', res = 8)# What is the central child of this resolution 6 index at resolution 8? get_centerchild(h3_address = '86be8d12fffffff', res = 8)
This function returns the children of a particular H3 cell at the requested resolution.
get_children(h3_address = NULL, res = NULL, simple = TRUE)get_children(h3_address = NULL, res = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address). Each list element contains
a vector of H3 cell indexes.
The number of cells returned for each request is 7 ^ (parent_res -
child_res), so jumping three levels will return 343 indexes per request.
This can cause memory issues with larger requests.
# What are the children of this resolution 6 cell index at resolution 8? get_children(h3_address = '86be8d12fffffff', res = 8)# What are the children of this resolution 6 cell index at resolution 8? get_children(h3_address = '86be8d12fffffff', res = 8)
This function returns all the H3 cell indices within a specified number of steps from the index supplied.
get_disk(h3_address = NULL, ring_size = 1, simple = TRUE)get_disk(h3_address = NULL, ring_size = 1, simple = TRUE)
h3_address |
Character; 15-character cell index generated by H3. |
ring_size |
Character; number of steps away from the central cell. Defaults to 1. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address). Each list element
contains a character vector of H3 cells.
The number of cells returned for each input index conforms to the
centered
hexagonal number sequence, so at ring_size = 5, 91 addresses are
returned. The first address returned is the input address, the rest follow
in a spiral anticlockwise order.
# What are all the neighbours of this cell within two steps? get_disk(h3_address = '86be8d12fffffff', ring_size = 2)# What are all the neighbours of this cell within two steps? get_disk(h3_address = '86be8d12fffffff', ring_size = 2)
This function returns all the H3 cell indexes within a specified number of steps from the address supplied, grouped by step.
get_disk_list(h3_address = NULL, ring_size = 1, simple = TRUE)get_disk_list(h3_address = NULL, ring_size = 1, simple = TRUE)
h3_address |
Character; 15-character cell index generated by H3. |
ring_size |
Character; number of steps away from the central cell. Defaults to 1. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address). Each list element
contains a list of length(ring_size + 1). Each of those lists
contains a character vector of H3 cell indices belonging to that step away
from the input cell.
In total, the number of indices returned for each input cell conforms
to the
centered
hexagonal number sequence, so at ring_size = 5, 91 cells are
returned. Cells are returned in separate lists, one for each step.
# What are the nested neighbours of this cell within two steps? get_disk_list(h3_address = '86be8d12fffffff', ring_size = 2)# What are the nested neighbours of this cell within two steps? get_disk_list(h3_address = '86be8d12fffffff', ring_size = 2)
This function returns the indices of all icosahedron faces intersected by a given H3 cell index.
get_faces(h3_address = NULL, simple = TRUE)get_faces(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, an integer vector of length(h3_address), ranging
from 1 to 20. If simple = FALSE, a data.frame with a column of H3
cell indexes and a list-column of faces.
# Which faces does this h3 cell index intersect? get_faces(h3_address = '8abe8d12acaffff')# Which faces does this h3 cell index intersect? get_faces(h3_address = '8abe8d12acaffff')
Get the great circle distance between WGS84 lat/long points
get_gcdist(pt1 = NULL, pt2 = NULL, units = c("m", "km", "rads"), simple = TRUE)get_gcdist(pt1 = NULL, pt2 = NULL, units = c("m", "km", "rads"), simple = TRUE)
pt1 |
'sf' object with point geometry, 'sfc_POINT' object, 'sfg' point, data frame or matrix. |
pt2 |
'sf' object with point geometry, 'sfc_POINT' object, 'sfg' point, data frame or matrix. |
units |
whether to return the great circle distance in meters, kilometers, or radians. |
simple |
whether to return a numeric vector of distances or a 'data.frame' containing start and end coordinates as well as distance. |
Numeric vector of point to point distances, or data frame of origin and destination coordinates accompanied by their distances.
This functionality also exists in R packages sp, sf,
geosphere and fields. H3's version appears to return slightly
shorter distances than most other implementations, but is included here
for completeness.
# distance between Brisbane and Melbourne bne <- c(153.028, -27.468) mlb <- c(144.963, -37.814) get_gcdist(bne, mlb, 'km')# distance between Brisbane and Melbourne bne <- c(153.028, -27.468) mlb <- c(144.963, -37.814) get_gcdist(bne, mlb, 'km')
This function returns H3 destination cells for local i, j coordinate pairs anchored by an H3 origin cell.
get_local_cell(origin = NULL, i = NULL, j = NULL, simple = TRUE)get_local_cell(origin = NULL, i = NULL, j = NULL, simple = TRUE)
origin |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
i |
a single i coordinate or vector of same, generated by
|
j |
a single j coordinate or vector of same, generated by
|
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
If simple = TRUE, a character vector of destination H3 cells.
If not, a data frame containing columns origin, i, j, destination.
The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.
Coordinates are only comparable if they come from the same origin cell.
Failure may occur if the destination is too far away from the origin or if the destination is on the other side of a pentagon.
This function is experimental, and its output is not guaranteed to be compatible across different versions of H3.
# Get local coordinates for a nearby cell local <- get_local_ij(origin = '86be8d12fffffff', destination = '86be8d127ffffff') # Convert back to destination cell get_local_cell(origin = '86be8d12fffffff', i = local[, 1], j = local[, 2])# Get local coordinates for a nearby cell local <- get_local_ij(origin = '86be8d12fffffff', destination = '86be8d127ffffff') # Convert back to destination cell get_local_cell(origin = '86be8d12fffffff', i = local[, 1], j = local[, 2])
This function defines local i, j coordinates for an H3 destination cell relative to an H3 origin cell.
get_local_ij(origin = NULL, destination = NULL, simple = TRUE)get_local_ij(origin = NULL, destination = NULL, simple = TRUE)
origin |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
destination |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
simple |
Logical; whether to include an unprojected sfc_POINT geometry column in the output object. |
If simple = TRUE, a matrix where each row contains the local
i, j coordinates for the supplied destination indexes. If not, an sf
object with origin and destination attributes, point geometry of the
destination cell centers, and an undefined coordinate reference system.
The number of indexes supplied to origin and destination must be equal.
The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.
Coordinates are only comparable if they come from the same origin index.
Failure may occur if the index is too far away from the origin or if the index is on the other side of a pentagon.
This function is experimental, and its output is not guaranteed to be compatible across different versions of H3.
# Get local coordinates for a nearby cell get_local_ij(origin = '86be8d12fffffff', destination = '86be8d127ffffff') # Get local coordinates for a donut of nearby cells destinations <- get_ring(h3_address = '86be8d12fffffff', ring_size = 2) local_coords <- get_local_ij(origin = rep('86be8d12fffffff', length(destinations[[1]])), destination = destinations[[1]], simple = FALSE) plot(local_coords['destination'], pch = 19) # note origin is (0,0)# Get local coordinates for a nearby cell get_local_ij(origin = '86be8d12fffffff', destination = '86be8d127ffffff') # Get local coordinates for a donut of nearby cells destinations <- get_ring(h3_address = '86be8d12fffffff', ring_size = 2) local_coords <- get_local_ij(origin = rep('86be8d12fffffff', length(destinations[[1]])), destination = destinations[[1]], simple = FALSE) plot(local_coords['destination'], pch = 19) # note origin is (0,0)
This function returns the parent of a particular H3 cell index at the requested resolution.
get_parent(h3_address = NULL, res = NULL, simple = TRUE)get_parent(h3_address = NULL, res = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a logical vector of length(h3_address).
# What is the parent of this cell at resolution 6? get_parent(h3_address = '8abe8d12acaffff', res = 6)# What is the parent of this cell at resolution 6? get_parent(h3_address = '8abe8d12acaffff', res = 6)
This function returns the indices of all pentagons occurring at a given H3 resolution.
get_pentagons(res = NULL, simple = TRUE)get_pentagons(res = NULL, simple = TRUE)
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return outputs as list of outputs (TRUE) or data frame with both inputs and outputs. |
By default, a list of length(h3_address). Each list element
contains a vector of twelve H3 addresses. If simple = FALSE, a data
frame with a column of input resolutions and a list-column of pentagon
indexes for each.
# Which indexes are pentagons at resolution 7? get_pentagons(res = 7)# Which indexes are pentagons at resolution 7? get_pentagons(res = 7)
This function returns an H3 cell index's resolution level.
get_res(h3_address = NULL, simple = TRUE)get_res(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, an integer vector of length(h3_address), ranging
from 1 to 15.
# What is the resolution of this H3 cell index? get_res(h3_address = '8abe8d12acaffff')# What is the resolution of this H3 cell index? get_res(h3_address = '8abe8d12acaffff')
Get all H3 cell indexes at resolution 0.
get_res0()get_res0()
length 122 character vector of top-level H3 cell indices.
As every index at every resolution > 0 is
the descendant of a res 0 index, this can be used with
get_children to iterate over H3 indexes at
any resolution.
res0 <- get_res0() cell_area(res0[1], 'km2')res0 <- get_res0() cell_area(res0[1], 'km2')
This function returns all the H3 cell indexes at the specified step from the address supplied.
get_ring(h3_address = NULL, ring_size = 1, simple = TRUE)get_ring(h3_address = NULL, ring_size = 1, simple = TRUE)
h3_address |
Character; 15-character cell index generated by H3. |
ring_size |
Character; number of steps away from the central cell. Defaults to 1. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a list of length(h3_address). Each list element
contains a character vector of H3 cells belonging to that step away from
the input address.
In total, the number of cells returned for each input index is
ring_size * 6. This function will throw an error if there is a
pentagon anywhere in the ring.
# What are the neighbours of this cell at step 2? get_ring(h3_address = '86be8d12fffffff', ring_size = 2)# What are the neighbours of this cell at step 2? get_ring(h3_address = '86be8d12fffffff', ring_size = 2)
Get an H3 index representing the destination of a directed edge.
get_uddest(h3_edge = NULL, simple = TRUE)get_uddest(h3_edge = NULL, simple = TRUE)
h3_edge |
Character; address of unidirectional edge. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, character vector of h3 cell indexes.
# Get the destination cell index of this directed edge index get_uddest(h3_edge = '166be8d12fffffff')# Get the destination cell index of this directed edge index get_uddest(h3_edge = '166be8d12fffffff')
Returns an H3 index representing a unidirectional edge for a given origin and destination cell pair.
get_udedge(origin = NULL, destination = NULL, simple = TRUE)get_udedge(origin = NULL, destination = NULL, simple = TRUE)
origin |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
destination |
Character; 15-character cell index generated by H3. A vector of indexes can also be supplied. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, character vector of unidirectional edge indexes.
The number of cell indexes supplied to origin and destination must be equal.
# Return the unidirectional edge representing the transition between these two cells: get_udedge(origin = '86be8d12fffffff', destination = '86be8d127ffffff')# Return the unidirectional edge representing the transition between these two cells: get_udedge(origin = '86be8d12fffffff', destination = '86be8d127ffffff')
Get all directed edge indexes for a given H3 cell index.
get_udedges(h3_address = NULL, simple = TRUE)get_udedges(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, list of length(h3_address). Each list contains a
character vector of H3 edge indexes.
# Get all the edge indexes for this cell get_udedges(h3_address = '86be8d12fffffff')# Get all the edge indexes for this cell get_udedges(h3_address = '86be8d12fffffff')
Get H3 cell indexes representing the origin and destination of a directed edge index.
get_udends(h3_edge = NULL, simple = TRUE)get_udends(h3_edge = NULL, simple = TRUE)
h3_edge |
Character; address of unidirectional edge. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, character matrix of h3 cell indexes.
# Get the origin and destination of this directed edge get_udends(h3_edge = '166be8d12fffffff')# Get the origin and destination of this directed edge get_udends(h3_edge = '166be8d12fffffff')
Get an H3 cell index representing the origin of a directed edge.
get_udorigin(h3_edge = NULL, simple = TRUE)get_udorigin(h3_edge = NULL, simple = TRUE)
h3_edge |
Character; address of unidirectional edge. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, character vector of H3 indexes.
# Get the origin cell of this directed edge get_udorigin(h3_edge = '166be8d12fffffff')# Get the origin cell of this directed edge get_udorigin(h3_edge = '166be8d12fffffff')
This function gets the grid distance between two H3 cell indices.
grid_distance(origin = NULL, destination = NULL, simple = TRUE)grid_distance(origin = NULL, destination = NULL, simple = TRUE)
origin |
Character vector or list of 15-character indices generated by H3. |
destination |
Character vector or list of 15-character indices generated by H3. |
simple |
Logical; whether to return a vector of outputs or a list object containing both inputs and outputs. |
The distance between two H3 cells, expressed as the minimum number of hexagon 'steps' required to get from the origin to the destination. Thus, a neighbour cell is one step away, and two cells with one hexagon between them are two steps apart.
Input H3 indices must be of the same resolution or results cannot be computed. This function may fail to find the distance between two indices if they are very far apart or on opposite sides of a pentagon.
## Not run: nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc_pts <- sf::st_centroid(nc[c(1, 2), ]) nc_6 <- point_to_cell(nc_pts, res = 6) # how far apart are these two addresses? grid_distance(nc_6[1], nc_6[2]) ## End(Not run)## Not run: nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc_pts <- sf::st_centroid(nc[c(1, 2), ]) nc_6 <- point_to_cell(nc_pts, res = 6) # how far apart are these two addresses? grid_distance(nc_6[1], nc_6[2]) ## End(Not run)
This function returns a path of H3 cells between a start and end cell (inclusive).
grid_path(origin = NULL, destination = NULL, simple = TRUE)grid_path(origin = NULL, destination = NULL, simple = TRUE)
origin |
Character vector or list of 15-character indices generated by H3. |
destination |
Character vector or list of 15-character indices generated by H3. |
simple |
Logical; whether to return a vector of outputs or a list object containing both inputs and outputs. |
A vector of h3 cells of form c(origin, c(path), destination).
Input H3 cells must be of the same resolution or results cannot be computed. This function may fail to find the distance between two indexes if they are very far apart or on opposite sides of a pentagon.
The specific output of this function should not be considered stable
across library versions. The only guarantees the library provides are that
the line length will be h3_distance(start, end) + 1 and that every
index in the line will be a neighbor of the preceding index.
Lines are drawn in grid space, and may not correspond exactly to either Cartesian lines or great arcs
## Not run: nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc_pts <- sf::st_centroid(nc[c(1, 2), ]) nc_6 <- point_to_cell(nc_pts, res = 6) # find a path between these two addresses: grid_path(nc_6[1], nc_6[2], simple = TRUE) ## End(Not run)## Not run: nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc_pts <- sf::st_centroid(nc[c(1, 2), ]) nc_6 <- point_to_cell(nc_pts, res = 6) # find a path between these two addresses: grid_path(nc_6[1], nc_6[2], simple = TRUE) ## End(Not run)
A dataset containing information about h3 cell indexes at each resolution, calculated using H3's built-in functions.
h3_info_tableh3_info_table
A data frame with 16 rows and 6 variables:
H3 resolution index number
Average area of an H3 cell index at the given resolution, in square meters.
Average area of an H3 cell index at the given resolution, in square kilometers.
Average edge length of an H3 cell index at the given resolution, in meters.
Average edge length of an H3 cell index at the given resolution, in kilometers.
Average distance between cell centers at the given resolution, in meters.
Average distance between cellcenters at the given resolution, in kilometers.
Total number of H3 cells at the given resolution.
See also https://h3geo.org/docs/core-library/restable/
This function checks whether a H3 cell index refers to one of the pentagons that occur at icosahedron corners.
is_pentagon(h3_address = NULL, simple = TRUE)is_pentagon(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a logical vector of length(h3_address).
# is the following cell index a pentagon? is_pentagon(h3_address = '8abe8d12acaffff')# is the following cell index a pentagon? is_pentagon(h3_address = '8abe8d12acaffff')
This function checks whether a H3 cell index is in a Class III resolution (rotated versus the icosahedron and subject to shape distortion adding extra points on icosahedron edges).
is_rc3(h3_address = NULL, simple = TRUE)is_rc3(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a logical vector of length(h3_address).
# is the following cell index Class III? is_rc3(h3_address = '8abe8d12acaffff')# is the following cell index Class III? is_rc3(h3_address = '8abe8d12acaffff')
This function checks whether an H3 cell index is valid.
is_valid(h3_address = NULL, simple = TRUE)is_valid(h3_address = NULL, simple = TRUE)
h3_address |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a logical vector of length(h3_address).
# is the following cell index valid? is_valid(h3_address = '8abe8d12acaffff')# is the following cell index valid? is_valid(h3_address = '8abe8d12acaffff')
This function checks whether an H3 unidirectional edge index is valid.
is_valid_edge(h3_edge = NULL, simple = TRUE)is_valid_edge(h3_edge = NULL, simple = TRUE)
h3_edge |
Character; address of unidirectional edge. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a logical vector of length(h3_edge).
# is the following unidirectional edge index valid? is_valid_edge(h3_edge = '166be8d12fffffff')# is the following unidirectional edge index valid? is_valid_edge(h3_edge = '166be8d12fffffff')
This function checks whether an H3 cell index is valid.
is_valid_vertex(h3_vertex = NULL, simple = TRUE)is_valid_vertex(h3_vertex = NULL, simple = TRUE)
h3_vertex |
Character; 15-character index generated by H3. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, a logical vector of length(h3_vertex).
# is the following cell index valid? is_valid_vertex(h3_vertex = '25abe8d12ac87fff')# is the following cell index valid? is_valid_vertex(h3_vertex = '25abe8d12ac87fff')
This function returns total number of H3 cells at a given resolution.
num_cells(res = NULL, fast = TRUE)num_cells(res = NULL, fast = TRUE)
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
fast |
Logical; whether to retrieve values from a locally stored table or recalculate from source. |
Numeric; H3 cell count.
Above resolution 8 the exact count cannot be represented in a JavaScript 32-bit number, so consumers should use caution when applying further operations to the output.
# Return cell count for resolution 8 num_cells(res = 8)# Return cell count for resolution 8 num_cells(res = 8)
This function takes point location data and returns a H3 cell index for each point at the chosen resolution(s).
point_to_cell(input = NULL, res = NULL, simple = TRUE)point_to_cell(input = NULL, res = NULL, simple = TRUE)
input |
|
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return outputs as character vector where possible. |
if simple = TRUE and one resolution is requested, a character vector
of H3 addresses.
if simple = TRUE and multiple resolutions are requested, a data
frame of H3 addresses.
if simple = FALSE and a matrix, sfc or sfg object is supplied, a
data frame of H3 addresses.
if simple = FALSE and a data frame or sf object with other
attributes is supplied, a data frame of non-spatial attributes with new
columns containing addresses for one or more H3 resolutions.
While multiple resolutions can be requested for multiple points, be aware of the memory demand on large datasets.
# where is the Brisbane Town Hall at resolution 15? bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326) bth_15 <- point_to_cell(bth, res = 15) # where is it at several resolutions? bth_many <- point_to_cell(bth, res = seq(10, 15), simple = FALSE)# where is the Brisbane Town Hall at resolution 15? bth <- sf::st_sfc(sf::st_point(c(153.023503, -27.468920)), crs = 4326) bth_15 <- point_to_cell(bth, res = 15) # where is it at several resolutions? bth_many <- point_to_cell(bth, res = seq(10, 15), simple = FALSE)
This function returns all the H3 cell indexes within the supplied polygon geometry.
polygon_to_cells(geometry = NULL, res = NULL, simple = TRUE)polygon_to_cells(geometry = NULL, res = NULL, simple = TRUE)
geometry |
|
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return a vector of outputs or an sf object containing both inputs and outputs. |
By default, a list of length(h3_address). Each list element
contains a character vector of H3 cell indices belonging to that geometry.
A result of NA indicates that no H3 cell indices of the chosen resolution
are centered over the geometry.
This function will be slow with a large number of polygons, and/or polygons that are large relative to the hexagon area at the chosen resolution. A message is printed to console where the total input area is (roughly) > 100000x the area of the chosen H3 resolution.
# Which level 5 H3 cell indices have centers inside County Ashe, NC? nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc1 <- nc[1, ] fillers <- polygon_to_cells(geometry = nc1, res = 5)# Which level 5 H3 cell indices have centers inside County Ashe, NC? nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc1 <- nc[1, ] fillers <- polygon_to_cells(geometry = nc1, res = 5)
Convert radians to degrees.
rads_to_degs(radian = NULL, lang = c("r", "h3"), simple = TRUE)rads_to_degs(radian = NULL, lang = c("r", "h3"), simple = TRUE)
radian |
Numeric, value in radians |
lang |
Character; whether to perform the conversion using base R or the H3 library. Defaults to R for speed. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
Numeric, value in degrees
rads_to_degs(1.5)rads_to_degs(1.5)
This function returns the average area of an H3 cell at a given resolution.
res_area(res = NULL, units = c("m2", "km2"), fast = TRUE)res_area(res = NULL, units = c("m2", "km2"), fast = TRUE)
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
units |
Areal unit to report in. Options are square meters or square kilometers. |
fast |
Logical; whether to retrieve values from a locally stored table or reclaculate from source. |
Numeric; average H3 cell area.
# Return average H3 cell area at each resolution in square meters res_area(res = seq(0, 15), units = 'm2')# Return average H3 cell area at each resolution in square meters res_area(res = seq(0, 15), units = 'm2')
This function returns the average distance between the center of H3 cells at a given resolution.
res_cendist(res = NULL, units = c("m", "km"), fast = TRUE)res_cendist(res = NULL, units = c("m", "km"), fast = TRUE)
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
units |
Length unit to report in, either meters or kilometers. |
fast |
Logical; whether to retrieve values from a locally stored table or recalculate from source. |
Numeric; H3 cell center separation distance.
This isn't in the core library but may be useful.
# Return average H3 cell separation distance at each resolution in kilometers res_cendist(res = seq(0, 15), units = 'km')# Return average H3 cell separation distance at each resolution in kilometers res_cendist(res = seq(0, 15), units = 'km')
This function returns the average edge length of an H3 cell edge at a given resolution.
res_length(res = NULL, units = c("m", "km"), fast = TRUE)res_length(res = NULL, units = c("m", "km"), fast = TRUE)
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
units |
Length unit to report in. Options are meters or kilometers. |
fast |
Logical; whether to retrieve values from a locally stored table or recalculate from source. |
Numeric; H3 cell edge length
This value is also the hexagon circumradius.
# Return average H3 cell edge length at each resolution in kilometers res_length(res = seq(0, 15), units = 'km')# Return average H3 cell edge length at each resolution in kilometers res_length(res = seq(0, 15), units = 'km')
Convert a "split long" - a pair of 32-bit integers - into an H3 cell index.
splitlong_to_cell(split_lower = NULL, split_upper = NULL, simple = TRUE)splitlong_to_cell(split_lower = NULL, split_upper = NULL, simple = TRUE)
split_lower |
Integer; Lower 32 bits of an H3 index. |
split_upper |
Integer; Upper 32 bits of an H3 index. |
simple |
Logical; whether to return a vector or a data frame containing both inputs and outputs. |
Vector of H3 addresses, one for each split long pair supplied.
x <- cell_to_splitlong(h3_address = '8abe8d12acaffff') splitlong_to_cell(split_lower = x[[1]][1], split_upper = x[[1]][2])x <- cell_to_splitlong(h3_address = '8abe8d12acaffff') splitlong_to_cell(split_lower = x[[1]][1], split_upper = x[[1]][2])
This function takes an H3 unidirectional edge address and returns the coordinates of its geometry in WGS84.
udedge_to_line(h3_edge = NULL, simple = TRUE)udedge_to_line(h3_edge = NULL, simple = TRUE)
h3_edge |
Character; address of unidirectional edge. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, an object of type 'sfc_LINESTRING'.
# get me the shape of this edge udedge_to_line(h3_edge = '166be8d12fffffff')# get me the shape of this edge udedge_to_line(h3_edge = '166be8d12fffffff')
This function uncompacts a compacted set of H3 cells to indices of the target resolution.
uncompact(h3_addresses = NULL, res = NULL, simple = TRUE)uncompact(h3_addresses = NULL, res = NULL, simple = TRUE)
h3_addresses |
Character vector or list of 15-character cell indices generated by H3. |
res |
Integer; Desired H3 resolution. See https://h3geo.org/docs/core-library/restable/ for allowable values and related dimensions. |
simple |
Logical; whether to return a vector of outputs or a list object containing both inputs and outputs. |
A list of H3 cell indices of the chosen resolution.
## Not run: # Give me a compacted representation of County Ashe, NC nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc1 <- nc[1, ] nc1 <- sf::st_cast(nc1, 'POLYGON') fillers <- polygon_to_cells(geometry = nc1, res = 6) compacted <- compact(fillers) # uncompact to resolution 7 uncompacted <- uncompact(compacted, res = 7) ## End(Not run)## Not run: # Give me a compacted representation of County Ashe, NC nc <- sf::st_read(system.file("shape/nc.shp", package="sf"), quiet = TRUE) nc1 <- nc[1, ] nc1 <- sf::st_cast(nc1, 'POLYGON') fillers <- polygon_to_cells(geometry = nc1, res = 6) compacted <- compact(fillers) # uncompact to resolution 7 uncompacted <- uncompact(compacted, res = 7) ## End(Not run)
This function takes a H3 cell vertex index and returns its coordinates in WGS84.
vertex_to_point(h3_vertex = NULL, simple = TRUE)vertex_to_point(h3_vertex = NULL, simple = TRUE)
h3_vertex |
Character; vertex address or addresses. |
simple |
Logical; whether to return a vector of outputs or a data frame containing both inputs and outputs. |
By default, an sfc_POINT object of length(h3_address).
EPSG:WGS84.
# Convert this vertex to a point vertex_to_point('246be8d127ffffff')# Convert this vertex to a point vertex_to_point('246be8d127ffffff')