% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{irregular_rectangle_surface_helpers}
\alias{irregular_rectangle_surface_helpers}
\alias{irregular.rectangle.param.coords}
\alias{irregular.rectangle.surface.embedding}
\alias{irregular.rectangle.surface.graph}
\title{Irregular rectangle surface helpers}
\usage{
irregular.rectangle.param.coords(
  h,
  w = h,
  x_scale = 1,
  y_scale = 1,
  row_irregularity = 0.2,
  col_irregularity = 0.2,
  row_phase = 0.35,
  col_phase = 0.65,
  interior_warp = 0.08,
  shear = 0,
  min_step_ratio = 0.3
)

irregular.rectangle.surface.embedding(
  h,
  w = h,
  surface = c("flat", "saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1,
  row_irregularity = 0.2,
  col_irregularity = 0.2,
  row_phase = 0.35,
  col_phase = 0.65,
  interior_warp = 0.08,
  shear = 0,
  min_step_ratio = 0.3
)

irregular.rectangle.surface.graph(
  h,
  w = h,
  surface = c("flat", "saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1,
  row_irregularity = 0.2,
  col_irregularity = 0.2,
  row_phase = 0.35,
  col_phase = 0.65,
  interior_warp = 0.08,
  shear = 0,
  min_step_ratio = 0.3,
  connectivity = c("orthogonal", "diagonal"),
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{h}{Number of rows.}

\item{w}{Number of columns. Defaults to \code{h}.}

\item{x_scale}{Positive horizontal scaling of the parameter domain.}

\item{y_scale}{Positive vertical scaling of the parameter domain.}

\item{row_irregularity}{Irregularity level for the row spacing. Must lie in
\code{[0, 1]}.}

\item{col_irregularity}{Irregularity level for the column spacing. Must lie
in \code{[0, 1]}.}

\item{row_phase}{Finite phase shift for the deterministic row-spacing
perturbation.}

\item{col_phase}{Finite phase shift for the deterministic column-spacing
perturbation.}

\item{interior_warp}{Non-negative interior warp strength. Must lie in
\code{[0, 1]}. The warp vanishes on the boundary.}

\item{shear}{Finite affine shear applied after the boundary-vanishing warp.
Larger values can force a validation error if the mesh cells invert.}

\item{min_step_ratio}{Positive lower bound for the perturbed row and column
interval lengths, expressed relative to the unperturbed interval scale.
Must lie in \code{(0, 1]}.}

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

\item{amplitude}{Finite numeric amplitude controlling the non-flat
displacement.}

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

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

\item{connectivity}{Mesh neighborhood rule passed to \code{edges.mesh()}.}

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

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

\code{irregular.rectangle.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the undirected rectangular-mesh edges,
  \item \code{n}: number of vertices,
  \item \code{edge_weights}: induced positive edge lengths,
  \item \code{coords_surface}: the 3D surface embedding,
  \item \code{coords_param}: the irregular 2D parameter coordinates,
  \item \code{coords_regular_param}: the underlying regular 2D parameter
    coordinates used to define the boundary-vanishing warp,
  \item \code{row_breaks}: per-row parameter coordinates in row order,
  \item \code{col_breaks}: per-column parameter coordinates in column order,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"irregular.rectangle"},
  \item \code{surface}: the chosen surface name,
  \item \code{connectivity}: the chosen mesh connectivity rule,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that keep ordinary rectangular-mesh adjacency but replace
the regular parameter grid by a deterministic irregular rectangle. The
resulting family stays simply connected and rectangular in topology while
breaking the strongest row/column symmetries of the lattice.
}
\details{
`irregular.rectangle.param.coords()` returns the irregular planar parameter
coordinates.
`irregular.rectangle.surface.embedding()` lifts those coordinates into
\eqn{\mathbb{R}^3}.
`irregular.rectangle.surface.graph()` returns a reusable weighted-graph
bundle with the induced Euclidean edge lengths.
}
