% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ddbs_ops_binary.R
\name{ddbs_binary_funs}
\alias{ddbs_binary_funs}
\alias{ddbs_intersection}
\alias{ddbs_difference}
\alias{ddbs_sym_difference}
\alias{ddbs_crop}
\alias{ddbs_shortest_line}
\title{Geometry binary operations}
\usage{
ddbs_intersection(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_difference(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_sym_difference(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_crop(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

ddbs_shortest_line(
  x,
  y,
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)
}
\arguments{
\item{x}{Input spatial data. Can be:
\itemize{
\item A \code{duckspatial_df} object (lazy spatial data frame via dbplyr)
\item An \code{sf} object
\item A \code{tbl_lazy} from dbplyr
\item A character string naming a table/view in \code{conn}
}
Data is returned from this object.}

\item{y}{Input spatial data. Can be:
\itemize{
\item A \code{duckspatial_df} object (lazy spatial data frame via dbplyr)
\item An \code{sf} object
\item A \code{tbl_lazy} from dbplyr
\item A character string naming a table/view in \code{conn}
}}

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

\item{conn_x}{A \code{DBIConnection} object to a DuckDB database for the input \code{x}.
If \code{NULL} (default), it is resolved from \code{conn} or extracted from \code{x}.}

\item{conn_y}{A \code{DBIConnection} object to a DuckDB database for the input \code{y}.
If \code{NULL} (default), it is resolved from \code{conn} or extracted from \code{y}.}

\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{mode}{Character. Controls the return type. Options:
\itemize{
\item \code{"duckspatial"} (default): Lazy spatial data frame backed by dbplyr/DuckDB
\item \code{"sf"}: Eagerly collected sf object (uses memory)
}
Can be set globally via \code{\link{ddbs_options}(mode = "...")} or
per-function via this argument. Per-function overrides global setting.}

\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}.}
}
\value{
Depends on the \code{mode} argument (or global preference set by \code{\link{ddbs_options}}):
\itemize{
\item \code{duckspatial} (default): A \code{duckspatial_df} (lazy spatial data frame) backed by dbplyr/DuckDB.
\item \code{sf}: An eagerly collected object in R memory, that will return the same data type as the
\code{sf} equivalent (e.g. \code{sf} or \code{units} vector).
}
When \code{name} is provided, the result is also written as a table or view in DuckDB and the function returns \code{TRUE} (invisibly).
}
\description{
Perform geometric set operations between two sets of geometries.
}
\details{
These functions perform different geometric set operations:
\describe{
\item{\code{ddbs_intersection}}{Returns the geometric intersection of two sets
of geometries, producing the area, line, or point shared by both.}
\item{\code{ddbs_crop}}{Returns the geometric intersection of two sets of
geometries, using the bounding box of \code{y}, rather than its original geometry}
\item{\code{ddbs_difference}}{Returns the portion of the first geometry that
does not overlap with the second geometry.}
\item{\code{ddbs_sym_difference}}{Returns the portions of both geometries
that do not overlap with each other. Equivalent to
\verb{(A - B) UNION (B - A)}.}
\item{\code{ddbs_shortest_line}}{Returns a LINESTRING connecting the closest
points between each pair of geometries from \code{x} and \code{y}. Performs
a cross join (all combinations), so the output contains columns from both
\code{x} and \code{y} (excluding \code{y}'s geometry column). For each pair
the line has the same length as \code{ST_Distance}.}
}
}
\examples{
\dontrun{
library(duckspatial)
library(sf)

# Create two overlapping polygons for testing
poly1 <- st_polygon(list(matrix(c(
  0, 0,
  4, 0,
  4, 4,
  0, 4,
  0, 0
), ncol = 2, byrow = TRUE)))

poly2 <- st_polygon(list(matrix(c(
  2, 2,
  6, 2,
  6, 6,
  2, 6,
  2, 2
), ncol = 2, byrow = TRUE)))

x <- st_sf(id = 1, geometry = st_sfc(poly1), crs = 4326)
y <- st_sf(id = 2, geometry = st_sfc(poly2), crs = 4326)

# Visualize the input polygons
plot(st_geometry(x), col = "lightblue", main = "Input Polygons")
plot(st_geometry(y), col = "lightcoral", add = TRUE, alpha = 0.5)

# Intersection: only the overlapping area (2,2 to 4,4)
result_intersect <- ddbs_intersection(x, y)
plot(st_geometry(result_intersect), col = "purple", 
     main = "Intersection")

# Difference: part of x not in y (L-shaped area)
result_diff <- ddbs_difference(x, y)
plot(st_geometry(result_diff), col = "lightblue", 
     main = "Difference (x - y)")

# Symmetric Difference: parts of both that don't overlap
result_symdiff <- ddbs_sym_difference(x, y)
plot(st_geometry(result_symdiff), col = "orange", 
     main = "Symmetric Difference")

# Using with database connection
conn <- ddbs_create_conn(dbdir = "memory")

ddbs_write_vector(conn, x, "poly_x")
ddbs_write_vector(conn, y, "poly_y")

# Perform operations with connection
ddbs_intersection("poly_x", "poly_y", conn)
ddbs_difference("poly_x", "poly_y", conn)
ddbs_sym_difference("poly_x", "poly_y", conn)

# Save results to database table
ddbs_difference("poly_x", "poly_y", conn, name = "diff_result")
}

\dontrun{
library(duckspatial)
library(sf)

# Two separate point clouds in a projected CRS
origins <- st_as_sf(
  data.frame(id = 1:3, x = c(0, 5, 10), y = c(0, 0, 0)),
  coords = c("x", "y"), crs = "EPSG:3857"
)
targets <- st_as_sf(
  data.frame(id = 1:3, x = c(0, 5, 10), y = c(3, 4, 5)),
  coords = c("x", "y"), crs = "EPSG:3857"
)

# Returns LINESTRING geometries connecting the closest points
ddbs_shortest_line(origins, targets)
ddbs_shortest_line(origins, targets, mode = "sf")

# Works with any geometry type
ddbs_shortest_line(origins, argentina_ddbs)
}
}
