% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{occupied_mesh_surface_helpers}
\alias{occupied_mesh_surface_helpers}
\alias{occupied.mesh.surface.embedding}
\alias{occupied.mesh.surface.graph}
\title{Occupied-mesh and perforated-grid helpers}
\usage{
occupied.mesh.surface.embedding(
  keep,
  surface = c("saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1
)

occupied.mesh.surface.graph(
  keep,
  surface = c("saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq_u = 1,
  freq_v = 1,
  x_scale = 1,
  y_scale = 1,
  connectivity = c("orthogonal", "diagonal"),
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{keep}{Logical or numeric occupancy matrix. Non-zero entries are kept.}

\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{connectivity}{Mesh neighborhood rule passed to \code{edges.mesh()}.}

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

\code{occupied.mesh.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the occupied-cell mesh 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{"occupied.mesh"},
  \item \code{surface}: the chosen surface name,
  \item \code{connectivity}: the chosen occupied-mesh connectivity rule,
  \item \code{keep}: the logical occupancy matrix,
  \item \code{label}: a human-readable family label.
}
}
\description{
\code{edges.occupied.mesh()} builds a finite occupied-grid graph on the
retained cells of a rectangular occupancy matrix. The corresponding surface
helpers lift those occupied cells into \eqn{\mathbb{R}^3} using the same
\code{"saddle"}, \code{"paraboloid"}, and \code{"ripple"} families used
for regular meshes.
}
