% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{recursive_triangle_mask_surface_helpers}
\alias{recursive_triangle_mask_surface_helpers}
\alias{recursive.triangle.mask.surface.embedding}
\alias{recursive.triangle.mask.surface.graph}
\title{Weighted recursive triangle-mask surface helpers}
\usage{
recursive.triangle.mask.surface.embedding(
  mask = mask.triangle.classic(),
  level = 2,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1
)

recursive.triangle.mask.surface.graph(
  mask = mask.triangle.classic(),
  level = 2,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{mask}{Four-entry logical or numeric keep-mask. Non-zero entries are
retained at each recursive step.}

\item{level}{Recursion depth. May be \code{0} or larger.}

\item{surface}{Triangle surface family. 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 first canonical triangle
coordinate. Used only when \code{surface = "ripple"}.}

\item{freq_v}{Positive ripple frequency in the second canonical triangle
coordinate. Used only when \code{surface = "ripple"}.}

\item{x_scale}{Positive horizontal scaling applied to the canonical
triangle coordinates.}

\item{y_scale}{Positive vertical scaling applied to the canonical triangle
coordinates.}

\item{normalize}{Normalization applied to the induced edge lengths. One of
\code{"median"}, \code{"mean"}, or \code{"none"}.}
}
\value{
\code{recursive.triangle.mask.surface.embedding()} returns an \code{n x 3}
numeric matrix with columns \code{x}, \code{y}, and \code{z}.

\code{recursive.triangle.mask.surface.graph()} returns a list with
components:
\itemize{
  \item \code{edges}: the retained recursive triangle-mask 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 canonical 2D triangle coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"recursive.triangle.mask"},
  \item \code{surface}: the chosen surface name,
  \item \code{level}: the recursion depth,
  \item \code{mask}: the logical keep-mask,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that recursively subdivide an equilateral triangle into
three corner subtriangles plus one central inverted subtriangle according to
a four-slot keep-mask, retain the selected subtriangles at each recursion
step, and lift the resulting vertex graph into \eqn{\mathbb{R}^3}. This
provides a generic gasket-style triangular family that includes the classic
Sierpinski triangle together with bridge and asymmetric variants.
}
\details{
The \code{mask} entries are interpreted in the order
\code{left}, \code{right}, \code{top}, and \code{center}. Named masks are
reordered automatically to match that convention.
}
