% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{recursive_cube_mask_surface_helpers}
\alias{recursive_cube_mask_surface_helpers}
\alias{recursive.cube.mask.surface.embedding}
\alias{recursive.cube.mask.surface.graph}
\title{Weighted recursive cube-mask surface helpers}
\usage{
recursive.cube.mask.surface.embedding(
  mask,
  level = 2,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x_scale = 1,
  y_scale = 1,
  z_scale = 1
)

recursive.cube.mask.surface.graph(
  mask,
  level = 2,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x_scale = 1,
  y_scale = 1,
  z_scale = 1,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{mask}{Cubic logical or numeric keep-array. Non-zero entries are
retained at each recursive step.}

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

\item{surface}{Cube-mask geometry family. One of \code{"standard"},
\code{"bulged"}, \code{"twisted"}, or \code{"wavy"}.}

\item{amplitude}{Finite deformation amplitude.}

\item{freq}{Positive modulation frequency used only when
\code{surface = "wavy"}.}

\item{twist}{Finite twist strength used only when
\code{surface = "twisted"}.}

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

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

\item{z_scale}{Positive depth scaling applied to the canonical cube
coordinates.}

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

\code{recursive.cube.mask.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the retained recursive cube-mask face-adjacency edges,
  \item \code{n}: number of vertices,
  \item \code{edge_weights}: induced positive edge lengths,
  \item \code{coords_surface}: the 3D embedding,
  \item \code{coords_param}: the canonical 3D voxel-center coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"recursive.cube.mask"},
  \item \code{surface}: the chosen surface name,
  \item \code{level}: the recursion depth,
  \item \code{mask}: the logical keep-array,
  \item \code{mask_side}: side length of the base keep-mask,
  \item \code{side}: side length of the fully refined cube grid,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that recursively subdivide a cube into a regular
\eqn{k \times k \times k} array of subcubes according to a cubic keep-mask,
retain the selected cells at each recursion step, and deform the resulting
face-adjacency graph inside \eqn{\mathbb{R}^3}. This provides a generic
cubical 3D family that includes Menger-sponge-style cell adjacency as a
named special case.
}
\details{
The \code{mask} is interpreted as a cubic array whose first dimension runs
from top to bottom, second from left to right, and third from front to back.
Non-zero entries are retained at each recursive step.
}
