recursive_mask_grid_surface_helpers: Weighted recursive mask-grid surface helpers

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 \(\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.

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

Value

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

numeric matrix with columns x, y, and z.

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

edges: the occupied-cell masked-grid edges,
n: number of vertices,
edge_weights: induced positive edge lengths,
coords_surface: the 3D surface embedding,
coords_param: the 2D parameter coordinates,
weight_scale: the normalization constant applied to the raw edge lengths,
family: always "recursive.mask.grid",
surface: the chosen surface name,
level: the recursion depth,
mask: the logical keep-mask,
mask_size: the side length of the mask,
side: the side length of the fully refined grid,
label: a human-readable family label.

Arguments

mask: Square logical or numeric keep-mask with at least one retained cell. Non-zero entries are kept at each recursive step.
level: Recursion depth. Must be at least 1.
surface: Surface family used for the lift. One of "saddle", "paraboloid", or "ripple".
amplitude: Finite numeric amplitude controlling the non-flat displacement.
freq_u: Positive ripple frequency in the horizontal parameter direction. Used only when surface = "ripple".
freq_v: Positive ripple frequency in the vertical parameter direction. Used only when surface = "ripple".
x_scale: Positive horizontal scaling of the parameter domain.
y_scale: Positive vertical scaling of the parameter domain.
normalize: Normalization applied to the induced edge lengths. One of "median", "mean", or "none".

Details

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