% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{sampled_rectangle_surface_helpers}
\alias{sampled_rectangle_surface_helpers}
\alias{sampled.rectangle.param.coords}
\alias{sampled.rectangle.surface.embedding}
\alias{sampled.rectangle.surface.graph}
\alias{sampled.rectangle.surface.graphs}
\title{Sampled rectangle surface helpers}
\usage{
sampled.rectangle.param.coords(
  n,
  xmin = -1,
  xmax = 1,
  ymin = -1,
  ymax = 1,
  seed = NULL
)

sampled.rectangle.surface.embedding(
  n,
  xmin = -1,
  xmax = 1,
  ymin = -1,
  ymax = 1,
  seed = NULL,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1
)

sampled.rectangle.surface.graph(
  n,
  k,
  xmin = -1,
  xmax = 1,
  ymin = -1,
  ymax = 1,
  seed = NULL,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  graph_space = c("surface", "param"),
  max.path.edge.ratio.deviation.thld = 0.1,
  path.edge.ratio.percentile = 0.5,
  threshold.percentile = 0,
  normalize = c("median", "mean", "none")
)

sampled.rectangle.surface.graphs(
  n,
  k,
  xmin = -1,
  xmax = 1,
  ymin = -1,
  ymax = 1,
  seed = NULL,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  graph_space = c("surface", "param"),
  max.path.edge.ratio.deviation.thld = 0.1,
  path.edge.ratio.percentile = 0.5,
  threshold.percentile = 0,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{n}{Number of sampled points.}

\item{xmin}{Left rectangle boundary.}

\item{xmax}{Right rectangle boundary. Must satisfy \code{xmax > xmin}.}

\item{ymin}{Bottom rectangle boundary.}

\item{ymax}{Top rectangle boundary. Must satisfy \code{ymax > ymin}.}

\item{seed}{Optional integer seed used only for the rectangle sampling.}

\item{surface}{Geometry family used for the 3D lift. One of \code{"flat"},
\code{"saddle"}, \code{"paraboloid"}, \code{"ripple"}, or
\code{"folded"}.}

\item{amplitude}{Finite deformation amplitude.}

\item{freq_u}{Positive ripple frequency in the horizontal rectangle
direction. Used only when \code{surface = "ripple"}.}

\item{freq_v}{Positive ripple frequency in the vertical rectangle direction.
Used only when \code{surface = "ripple"}.}

\item{k}{Integer iKNN neighborhood size (single graph) or vector of
neighborhood sizes (graph sequence).}

\item{graph_space}{Coordinate system used to build the iKNN graph and its raw
edge weights. \code{"surface"} uses the 3D embedding and
\code{"param"} uses the sampled planar coordinates.}

\item{max.path.edge.ratio.deviation.thld}{Geometric-pruning deviation
threshold in \code{[0, 0.2)}.}

\item{path.edge.ratio.percentile}{Edge-length percentile in \code{[0, 1]}
used to select candidates for geometric pruning.}

\item{threshold.percentile}{Optional long-edge pruning percentile in
\code{[0, 0.5]}. A value of \code{0} disables this stage.}

\item{normalize}{Normalization applied to the final positive edge weights.
One of \code{"median"}, \code{"mean"}, or \code{"none"}.}
}
\value{
\code{sampled.rectangle.param.coords()} returns an \code{n x 2} numeric
matrix with columns \code{u} and \code{v}.

\code{sampled.rectangle.surface.embedding()} returns an \code{n x 3} numeric
matrix with columns \code{x}, \code{y}, and \code{z}.

\code{sampled.rectangle.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the undirected iKNN edges,
  \item \code{n}: number of vertices,
  \item \code{edge_weights}: normalized positive 3D chord lengths on the
    retained iKNN edges,
  \item \code{raw_edge_weights}: the unnormalized 3D chord lengths before
    \code{normalize},
  \item \code{iknn_witness_edge_weights}: raw iKNN witness weights based on
    common-neighbor distances, retained for diagnostics,
  \item \code{coords_surface}: the sampled 3D embedding,
  \item \code{coords_param}: the sampled planar rectangle coordinates,
  \item \code{coords_param_unit}: the centered unit-rectangle coordinates
    used for the surface lift,
  \item \code{weight_scale}: normalization constant applied to the raw edge
    weights,
  \item \code{family}: always \code{"sampled.rectangle"},
  \item \code{surface}: the chosen surface name,
  \item \code{graph_space}: the coordinate system used for iKNN graph
    construction,
  \item \code{k}: the iKNN neighborhood size,
  \item \code{label}: a human-readable family label.
}

\code{sampled.rectangle.surface.graphs()} returns a list with components:
\itemize{
  \item \code{graphs}: named list of single-\code{k} graph bundles,
  \item \code{k}: integer vector of retained \code{k} values,
  \item \code{k_statistics}: per-\code{k} edge-count summary,
  \item \code{coords_surface}: the shared sampled 3D embedding,
  \item \code{coords_param}: the shared sampled planar coordinates,
  \item \code{coords_param_unit}: the centered unit-rectangle coordinates
    used for the surface lift,
  \item \code{family}: always \code{"sampled.rectangle"},
  \item \code{surface}: the chosen surface name,
  \item \code{graph_space}: the coordinate system used for iKNN graph
    construction,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that sample points uniformly from a user-specified
rectangle, lift the sampled planar coordinates into \eqn{\mathbb{R}^3}, and
then build exact intersection-kNN graphs on either the planar or embedded
coordinates. The lifted surface uses normalized rectangle coordinates for the
non-flat \eqn{z}-displacement while preserving the original rectangle in the
returned \eqn{x} and \eqn{y} coordinates.
}
\details{
For the graph constructors, the iKNN relation determines which edges are
present, while the returned edge lengths are taken from the 3D endpoint
distances in the lifted embedding so that the graph metric reflects the
chosen surface geometry.

`sampled.rectangle.param.coords()` returns the sampled planar coordinates.
`sampled.rectangle.surface.embedding()` returns the corresponding 3D
embedding. `sampled.rectangle.surface.graph()` returns a single weighted
iKNN graph for one \code{k} value, while
`sampled.rectangle.surface.graphs()` reuses the same sample and embedding
across a sequence of \code{k} values.
}
