% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom.R
\name{g_factory}
\alias{g_factory}
\alias{g_create}
\alias{g_add_geom}
\alias{g_get_geom}
\alias{g_build_collection}
\alias{g_build_polygon_from_edges}
\title{Geometry factory functions}
\usage{
g_create(
  geom_type,
  pts = NULL,
  as_wkb = TRUE,
  as_iso = FALSE,
  byte_order = "LSB"
)

g_add_geom(
  sub_geom,
  container,
  as_wkb = TRUE,
  as_iso = FALSE,
  byte_order = "LSB"
)

g_get_geom(
  container,
  sub_geom_idx,
  as_wkb = TRUE,
  as_iso = FALSE,
  byte_order = "LSB"
)

g_build_collection(
  geoms,
  coll_type = "GEOMETRYCOLLECTION",
  as_wkb = TRUE,
  as_iso = FALSE,
  byte_order = "LSB"
)

g_build_polygon_from_edges(
  lines,
  auto_close = TRUE,
  tolerance = 0,
  as_wkb = TRUE,
  as_iso = FALSE,
  byte_order = "LSB"
)
}
\arguments{
\item{geom_type}{Character string (case-insensitive), one of \code{"POINT"},
\code{"MULTIPOINT"}, \code{"LINESTRING"}, \code{"POLYGON"} (see Note) or
\code{"GEOMETRYCOLLECTION"}.}

\item{pts}{Numeric matrix of points (x, y, z, m), or \code{NULL} to create an
empty geometry. The points can be given as (x, y), (x, y, z) or
(x, y, z, m), so the input must have two, three or four columns.
Data frame input will be coerced to numeric matrix. Rings for polygon
geometries should be closed.}

\item{as_wkb}{Logical value, \code{TRUE} to return the output geometry in WKB
format (the default), or \code{FALSE} to return a WKT string.}

\item{as_iso}{Logical value, \code{TRUE} to export as ISO WKB/WKT (ISO 13249
SQL/MM Part 3), or \code{FALSE} (the default) to export as "Extended WKB/WKT".}

\item{byte_order}{Character string specifying the byte order when output is
WKB. One of \code{"LSB"} (the default) or \code{"MSB"} (uncommon).}

\item{sub_geom}{Either a raw vector of WKB or a character string of WKT.}

\item{container}{Either a raw vector of WKB or a character string of WKT for
a container geometry type.}

\item{sub_geom_idx}{An integer value giving the 1-based index of a
sub-geometry (numeric values will be coerced to integer by truncation).}

\item{geoms}{Either a list of WKB raw vectors or character vector of WKT
strings.}

\item{coll_type}{A character string specifying a geometry collection type,
e.g., \code{"GEOMETRYCOLLECTION"} (the default), \code{"MULTIPOINT"},
\code{"MULTILINESTRING"}, \verb{"MULTIPOLYGON".}}

\item{lines}{Either a raw vector of WKB or a character string of WKT
specifying a \code{GeometryCollection} or \code{MultiLineString}, or a list of WKB raw
vectors for \code{LineString}s, or a character vector of WKT strings.}

\item{auto_close}{A logical value, \code{TRUE} (the default) if the polygon should
be closed when first and last points of the ring are the same.}

\item{tolerance}{A numeric value giving the tolerance into which two arcs are
considered close enough to be joined.}
}
\value{
A geometry as WKB raw vector by default, or a WKT string if
\code{as_wkb = FALSE}. In the case of multiple input points for creating \verb{Point`` geometry type, a list of WKB raw vectors or character vector of WKT strings will be returned. }NULL` is returned with a warning if the an error occurs
in the geometry operation.
}
\description{
These functions create WKB/WKT geometries from input vertices or arcs, and
build container geometry types from sub-geometries.
}
\details{
These functions use the GEOS library via GDAL headers.

\code{g_create()} creates a geometry object from the given point(s) and returns
a raw vector of WKB (the default) or a character string of WKT. Currently
supports creating \code{Point}, \code{MultiPoint}, \code{LineString}, and \code{Polygon}
(including \verb{25D}, \code{Z}, \code{M}, \code{ZM} variants).
If multiple input points are given for creating \code{Point}, then multiple
geometries will be returned as a list of WKB raw vectors, or character
vector of WKT strings if \code{as_wkb = FALSE}. Otherwise, a single geometry
is created from the input points. Only an empty \code{GeometryCollection} /
\code{MultiLineString} / \code{MultiPolygon} can be created with this function (for
subsequent use with \code{g_add_geom()}).

\code{g_add_geom()} adds a geometry to a geometry container, e.g.,
\code{Polygon} to \code{Polygon} (to add an interior ring), \code{Point} to \code{MultiPoint},
\code{LineString} to \code{MultiLineString}, \code{Polygon} to \code{MultiPolygon}, or mixed
geometry types to a \code{GeometryCollection}. Returns a new geometry, i.e,
the container geometry is not modified.

\code{g_get_geom()} fetches a geometry from a geometry container (1-based
indexing). For a polygon, requesting the first sub-geometry returns the
exterior ring (\code{sub_geom_idx = 1}), and the interior rings are returned for
\code{sub_geom_idx > 1}.

\code{g_build_collection()} builds a collection / container type geometry, e.g.,
\code{GeometryCollection}, \code{MultiPoint}, \code{MultiLineString}, \code{MultiPolygon}, from
a set of input geometries given as a list of WKB raw vectors or a character
vector of WKT strings.

\code{g_build_polygon_from_edges()} builds a polygon from a set of arcs given
in a \code{GeometryCollection}, \code{MultiLineString}, list of WKB raw vectors, or
character vector of WKT strings.
}
\note{
A \code{POLYGON} can be created for a single ring which will be the
exterior ring. Additional \code{POLYGON}s can be created and added to an
existing \code{POLYGON} with \code{g_add_geom()}. These will become interior rings.
Alternatively, an empty polygon can be created with \code{g_create("POLYGON")},
followed by creation and addition of \code{POLYGON}s as sub-geometries. In that
case, the first added \code{POLYGON} will be the exterior ring. The next ones will
be the interior rings.

Only an empty \code{GeometryCollection} can be created with \code{g_create()}, which
can then be used as a container with \code{g_add_geom()}. If given, input points
will be ignored by \code{g_create()} if \code{geom_type = "GEOMETRYCOLLECTION"}.
}
\examples{
# raw vector of WKB by default
g_create("POINT", c(1, 2))

# as WKT
g_create("POINT", c(1, 2), as_wkb = FALSE)

# or convert in either direction
g_create("POINT", c(1, 2)) |> g_wk2wk()
g_create("POINT", c(1, 2), as_wkb = FALSE) |> g_wk2wk()

# create MultiPoint from a matrix of xyz points
x <- c(9, 1)
y <- c(1, 9)
z <- c(0, 10)
pts <- cbind(x, y, z)
mp <- g_create("MULTIPOINT", pts)
g_wk2wk(mp)
g_wk2wk(mp, as_iso = TRUE)

# create an empty container and add sub-geometries
mp2 <- g_create("MULTIPOINT")
mp2 <- g_create("POINT", c(11, 2)) |> g_add_geom(mp2)
mp2 <- g_create("POINT", c(12, 3)) |> g_add_geom(mp2)
g_wk2wk(mp2)

# or build a container/collection type geometry from WKB list or WKT vector
lines <- c("LINESTRING (0 0,3 0)",
           "LINESTRING (3 0,3 4)",
           "LINESTRING (3 4,0 0)")
(multi_line <- g_build_collection(lines, "MULTILINESTRING", as_wkb = FALSE))

# get sub-geometry from container
g_get_geom(multi_line, 2, as_wkb = FALSE)

# build a polygon from a set of arcs
(poly <- g_build_polygon_from_edges(lines, as_wkb = FALSE))

# plot a vector of WKT strings or list of WKB raw vectors
plot_geom(poly)
}
