% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/h3_vertex.R
\name{ddbh3_vertex}
\alias{ddbh3_vertex}
\alias{ddbh3_h3_to_vertex}
\alias{ddbh3_h3_to_vertexes}
\alias{ddbh3_vertex_to_spatial}
\alias{ddbh3_vertex_to_lon}
\alias{ddbh3_vertex_to_lat}
\title{Convert H3 cell indexes to vertex representations}
\usage{
ddbh3_h3_to_vertex(
  x,
  n = 0,
  h3 = "h3string",
  new_column = "h3vertex",
  conn = NULL,
  name = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbh3_vertex_to_lon(
  x,
  h3vertex = "h3vertex",
  new_column = "lon_vertex",
  conn = NULL,
  name = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbh3_vertex_to_lat(
  x,
  h3vertex = "h3vertex",
  new_column = "lat_vertex",
  conn = NULL,
  name = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbh3_h3_to_vertexes(
  x,
  h3 = "h3string",
  new_column = "h3vertex",
  conn = NULL,
  name = NULL,
  nested = FALSE,
  overwrite = FALSE,
  quiet = FALSE
)

ddbh3_vertex_to_spatial(
  x,
  h3vertex = "h3vertex",
  conn = NULL,
  name = NULL,
  overwrite = FALSE,
  quiet = FALSE
)
}
\arguments{
\item{x}{Input data. One of:
\describe{
\item{\code{duckspatial_df}}{A lazy spatial data frame via dbplyr.}
\item{\code{sf}}{A spatial data frame.}
\item{\code{tbl_lazy}}{A lazy data frame from dbplyr.}
\item{\code{data.frame}}{A standard R data frame.}
\item{character string}{A table or view name in \code{conn}.}
\item{character vector}{A vector of values to operate on in vectorized mode (requires \code{conn = NULL}).}
}}

\item{n}{Integer. Vertex number to retrieve. Must be in the range 0–5 for
hexagons and 0–4 for pentagons. Only used in \code{ddbh3_h3_to_vertex()}.}

\item{h3}{The name of a column in \code{x} containing the H3 strings or
H3 unsigned 64-bit integers (\code{UBIGINT})}

\item{new_column}{Name of the new column to create on the input data. If NULL,
the function will return a vector with the result}

\item{conn}{A connection object to a DuckDB database. If \code{NULL}, the function
runs on a temporary DuckDB database.}

\item{name}{A character string of length one specifying the name of the table,
or a character string of length two specifying the schema and table
names. If \code{NULL} (the default), the function returns the result as an
\code{sf} object}

\item{overwrite}{Boolean. whether to overwrite the existing table if it exists. Defaults
to \code{FALSE}. This argument is ignored when \code{name} is \code{NULL}.}

\item{quiet}{A logical value. If \code{TRUE}, suppresses any informational messages.
Defaults to \code{FALSE}.}

\item{h3vertex}{Name of the column containing H3 vertex strings. Defaults
to \code{"h3vertex"}}

\item{nested}{Logical. If \code{TRUE}, children are returned as a nested list
column (one row per parent cell). If \code{FALSE} (default), the result is
unnested so each child cell occupies its own row.}
}
\value{
One of the following, depending on the inputs:
\describe{
\item{\code{tbl_lazy}}{If \code{x} is not spatial.}
\item{\code{duckspatial_df}}{If \code{x} is spatial (e.g. an \code{sf} or \code{duckspatial_df} object).}
\item{\code{TRUE} (invisibly)}{If \code{name} is provided, a table is created in the connection
and \code{TRUE} is returned invisibly.}
\item{vector}{If \code{x} is a character vector and \code{conn = NULL}, the function operates
in vectorized mode, returning a vector of the same length as \code{x}.}
}
}
\description{
Convert H3 cell indexes stored as strings or unsigned 64-bit integers
(\code{UBIGINT}) to their vertex representations
}
\details{
The functions cover the full vertex workflow:
\itemize{
\item \code{ddbh3_h3_to_vertex()} returns a single vertex of an H3 cell, identified
by its vertex number \code{n} (0–5 for hexagons, 0–4 for pentagons), as an H3
vertex string
\item \code{ddbh3_h3_to_vertexes()} returns all vertices of an H3 cell as H3 vertex
strings — either nested (one row per cell) or unnested (one row per vertex)
depending on \code{nested}
\item \code{ddbh3_vertex_to_lat()} returns the latitude of an H3 vertex string
\item \code{ddbh3_vertex_to_lon()} returns the longitude of an H3 vertex string
\item \code{ddbh3_vertex_to_spatial()} converts H3 vertex strings to spatial point
geometries. If the input column is nested, vertices are automatically
unnested and aggregated into a \code{MULTIPOINT} geometry per cell
}
}
\examples{
## Load needed packages
library(duckh3)
library(duckspatial)
library(dplyr)

## Setup the default connection with h3 and spatial extensions
## This is a mandatory step to use duckh3 functions
ddbh3_default_conn(threads = 1)

## Load example data
points_tbl <- read.csv(
  system.file("extdata/example_pts.csv", package = "duckh3")
)

## Add h3 strings
points_tbl <- ddbh3_lonlat_to_h3(points_tbl, resolution = 8)

## TO VERTEX ---------------

## Add second vertex
vertex_2_tbl <- ddbh3_h3_to_vertex(points_tbl, n = 2)

## Add add vertexes (unnested)
vertexes_tbl <- ddbh3_h3_to_vertexes(points_tbl)

## Add add vertexes (nested)
vertexes_nested_tbl <- ddbh3_h3_to_vertexes(points_tbl, nested = TRUE)

## Add some vertexes with with mutate
points_tbl |> 
  mutate(
    v1 = ddbh3_h3_to_vertex(h3string, 1),
    v3 = ddbh3_h3_to_vertex(h3string, 3)
  )

## VERTEX TO LON/LAT ------

## Add coords
coords_vertex_tbl <- vertex_2_tbl |> 
  ddbh3_vertex_to_lon(new_column = "lon_v2") |> 
  ddbh3_vertex_to_lat(new_column = "lat_v2")

## Add coords in mutate
vertex_2_tbl |> 
  mutate(
    lon_v2 = ddbh3_vertex_to_lon(h3vertex),
    lat_v2 = ddbh3_vertex_to_lat(h3vertex)
  )

## VERTEX TO SPATIAL ------

## Convert unnested vertexes (returns POINTS)
ddbh3_h3_to_vertexes(points_tbl) |> 
  ddbh3_vertex_to_spatial()


## Convert nested vertexes (returns MULTIPOINTS)
ddbh3_h3_to_vertexes(points_tbl, nested = TRUE) |> 
  ddbh3_vertex_to_spatial()
}
