recursive_cube_mask_surface_helpers: Weighted recursive cube-mask surface helpers

Description

Convenience helpers that recursively subdivide a cube into a regular \(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 \(\mathbb{R}^3\). This provides a generic cubical 3D family that includes Menger-sponge-style cell adjacency as a named special case.

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

Value

recursive.cube.mask.surface.embedding() returns an n x 3

numeric matrix with columns x, y, and z.

recursive.cube.mask.surface.graph() returns a list with components:

edges: the retained recursive cube-mask face-adjacency edges,
n: number of vertices,
edge_weights: induced positive edge lengths,
coords_surface: the 3D embedding,
coords_param: the canonical 3D voxel-center coordinates,
weight_scale: the normalization constant applied to the raw edge lengths,
family: always "recursive.cube.mask",
surface: the chosen surface name,
level: the recursion depth,
mask: the logical keep-array,
mask_side: side length of the base keep-mask,
side: side length of the fully refined cube grid,
label: a human-readable family label.

Arguments

mask: Cubic logical or numeric keep-array. Non-zero entries are retained at each recursive step.
level: Recursion depth. Must be at least 1.
surface: Cube-mask geometry family. One of "standard", "bulged", "twisted", or "wavy".
amplitude: Finite deformation amplitude.
freq: Positive modulation frequency used only when surface = "wavy".
twist: Finite twist strength used only when surface = "twisted".
x_scale: Positive horizontal scaling applied to the canonical cube coordinates.
y_scale: Positive vertical scaling applied to the canonical cube coordinates.
z_scale: Positive depth scaling applied to the canonical cube coordinates.
normalize: Normalization applied to the induced edge lengths. One of "median", "mean", or "none".

Details

The 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.