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

recursive.mask.grid.surface.graph(
  mask,
  level = 2,
  surface = c("saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{mask}{Square logical or numeric keep-mask with at least one retained
cell. Non-zero entries are kept at each recursive step.}

\item{level}{Recursion depth. Must be at least \code{1}.}

\item{surface}{Surface family used for the lift. One of \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{x_scale}{Positive horizontal scaling of the parameter domain.}

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

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

\code{recursive.mask.grid.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the occupied-cell masked-grid 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 2D parameter coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"recursive.mask.grid"},
  \item \code{surface}: the chosen surface name,
  \item \code{level}: the recursion depth,
  \item \code{mask}: the logical keep-mask,
  \item \code{mask_size}: the side length of the mask,
  \item \code{side}: the side length of the fully refined grid,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that recursively subdivide a square grid according to a
square keep-mask, retain the occupied cells, and then lift those cells into
\eqn{\mathbb{R}^3}. The induced Euclidean edge lengths become positive graph
weights. This provides a generic mesh-derived family that includes the
Sierpinski carpet and related masked-grid fractals such as Vicsek-style
cross families.
}
\details{
The \code{mask} is interpreted in standard matrix display orientation: rows
run from top to bottom and columns run from left to right. Non-zero entries
are retained at each recursive subdivision step.

`recursive.mask.grid.surface.embedding()` returns the 3D coordinates of the
occupied cells in the same vertex order as \code{edges.recursive.mask.grid()}.
`recursive.mask.grid.surface.graph()` returns a reusable weighted-graph
bundle containing the masked-grid edges, induced edge weights, the 3D
surface coordinates, and the 2D parameter coordinates of the occupied cells.
}
