sampled_rectangle_surface_helpers: Sampled rectangle surface helpers

Description

Convenience helpers that sample points uniformly from a user-specified rectangle, lift the sampled planar coordinates into \(\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 \(z\)-displacement while preserving the original rectangle in the returned \(x\) and \(y\) coordinates.

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")
)

Value

sampled.rectangle.param.coords() returns an n x 2 numeric matrix with columns u and v.

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

sampled.rectangle.surface.graph() returns a list with components:

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

sampled.rectangle.surface.graphs() returns a list with components:

graphs: named list of single-k graph bundles,
k: integer vector of retained k values,
k_statistics: per-k edge-count summary,
coords_surface: the shared sampled 3D embedding,
coords_param: the shared sampled planar coordinates,
coords_param_unit: the centered unit-rectangle coordinates used for the surface lift,
family: always "sampled.rectangle",
surface: the chosen surface name,
graph_space: the coordinate system used for iKNN graph construction,
label: a human-readable family label.

Arguments

n: Number of sampled points.
xmin: Left rectangle boundary.
xmax: Right rectangle boundary. Must satisfy xmax > xmin.
ymin: Bottom rectangle boundary.
ymax: Top rectangle boundary. Must satisfy ymax > ymin.
seed: Optional integer seed used only for the rectangle sampling.
surface: Geometry family used for the 3D lift. One of "flat", "saddle", "paraboloid", "ripple", or "folded".
amplitude: Finite deformation amplitude.
freq_u: Positive ripple frequency in the horizontal rectangle direction. Used only when surface = "ripple".
freq_v: Positive ripple frequency in the vertical rectangle direction. Used only when surface = "ripple".
k: Integer iKNN neighborhood size (single graph) or vector of neighborhood sizes (graph sequence).
graph_space: Coordinate system used to build the iKNN graph and its raw edge weights. "surface" uses the 3D embedding and "param" uses the sampled planar coordinates.
max.path.edge.ratio.deviation.thld: Geometric-pruning deviation threshold in [0, 0.2).
path.edge.ratio.percentile: Edge-length percentile in [0, 1] used to select candidates for geometric pruning.
threshold.percentile: Optional long-edge pruning percentile in [0, 0.5]. A value of 0 disables this stage.
normalize: Normalization applied to the final positive edge weights. One of "median", "mean", or "none".

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 k value, while `sampled.rectangle.surface.graphs()` reuses the same sample and embedding across a sequence of k values.