% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/h3_lonlat_to.R
\name{ddbh3_lonlat_to}
\alias{ddbh3_lonlat_to}
\alias{ddbh3_lonlat_to_h3}
\alias{ddbh3_lonlat_to_spatial}
\title{Convert longitude and latitude to H3 cell representations}
\usage{
ddbh3_lonlat_to_spatial(
  x,
  lon = "lon",
  lat = "lat",
  resolution = 8,
  conn = NULL,
  name = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbh3_lonlat_to_h3(
  x,
  lon = "lon",
  lat = "lat",
  resolution = 8,
  new_column = "h3string",
  h3_format = "string",
  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{lon}{The name of a column in \code{x} containing the longitude}

\item{lat}{The name of a column in \code{x} containing the latitude}

\item{resolution}{A number specifying the resolution level of the H3
string (between 0 and 15)}

\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{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{h3_format}{Character. The format of the H3 cell index: \code{string} or
\code{bigint}}
}
\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 geographic coordinates (longitude and latitude) into H3 cell
representations at a specified resolution, with different output formats
}
\details{
The three functions differ only in the output format of the H3 cell index:
\itemize{
\item \code{ddbh3_lonlat_to_h3()} returns H3 cell indexes as strings (e.g. \code{"8928308280fffff"})
or as unsigned 64-bit integers (\code{UBIGINT})
\item \code{ddbh3_lonlat_to_spatial()} returns H3 cells as spatial hexagon polygons
}
}
\examples{
\donttest{
## Load needed packages
library(duckdb)
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")
)

## Create a connection with spatial and h3 extensions
conn <- ddbh3_create_conn(threads = 1)

## TO H3 ------------

## Add h3 strings as a new column (res 5)
points_strings_5_tbl <- ddbh3_lonlat_to_h3(
  points_tbl,
  resolution = 5
)

## Add h3 UBIGINT as a new column (res 8 by default)
points_bigint_8_tbl <- ddbh3_lonlat_to_h3(
  points_tbl,
  new_column = "h3bigint",
  h3_format  = "bigint"
)

## If column names are different from lon/lat:
points_renamed <- rename(points_tbl, long = lon, lati = lat)

ddbh3_lonlat_to_h3(
  points_renamed,
  lon = "long",
  lat = "lati",
  resolution = 10
)


## Create a new table in the connection
ddbh3_lonlat_to_h3(
  points_tbl,
  conn = conn,
  name = "points_strings_8"
)

## Open the created table lazily
points_lazy <- dplyr::tbl(conn, "points_strings_8")

## Read it in memory
points_eager <- dbReadTable(conn, "points_strings_8")


## TO SPATIAL -----------

## Add h3 strings as a new column (res 5)
points_5_ddbs <- ddbh3_lonlat_to_spatial(
  points_tbl,
  resolution = 5
)

## Create a new table in the connection
ddbh3_lonlat_to_spatial(
  points_tbl,
  conn = conn,
  name = "points_strings_spatial"
)

## Open the created table lazily
as_duckspatial_df("points_strings_spatial", conn)

## Read it in memory as an sf object
ddbs_read_table(conn, "points_strings_spatial")
}
}
