% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{cylinder_surface_helpers}
\alias{cylinder_surface_helpers}
\alias{cylinder.surface.embedding}
\alias{cylinder.surface.graph}
\title{Weighted cylinder surface helpers}
\usage{
cylinder.surface.embedding(
  h,
  w = h,
  surface = c("barrel", "hourglass", "wavy"),
  radius = 1,
  height = 2,
  amplitude = 0.3,
  freq_theta = 2,
  freq_z = 1,
  twist = 0.25
)

cylinder.surface.graph(
  h,
  w = h,
  surface = c("barrel", "hourglass", "wavy"),
  radius = 1,
  height = 2,
  amplitude = 0.3,
  freq_theta = 2,
  freq_z = 1,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{h}{Number of rows.}

\item{w}{Number of columns. Defaults to \code{h}.}

\item{surface}{Cylinder surface family. One of \code{"barrel"},
\code{"hourglass"}, or \code{"wavy"}.}

\item{radius}{Positive baseline cylinder radius.}

\item{height}{Positive cylinder height.}

\item{amplitude}{Finite numeric deformation amplitude. The resulting radius
profile must stay positive everywhere.}

\item{freq_theta}{Positive angular frequency used only when
\code{surface = "wavy"}.}

\item{freq_z}{Positive vertical frequency used only when
\code{surface = "wavy"}.}

\item{twist}{Finite angular twist applied linearly with height.}

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

\code{cylinder.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the undirected cylindrical-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 unwrapped parameter coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"cylinder"},
  \item \code{surface}: the chosen surface name,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that embed a cylindrical grid graph into
\eqn{\mathbb{R}^3} and use the induced Euclidean edge lengths as positive
graph weights. These helpers are intended for benchmark families where the
graph topology is cylindrical but the intended metric comes from a curved or
spatially varying 3D realization.
}
\details{
`cylinder.surface.embedding()` returns the 3D coordinates of the embedded
cylindrical grid. `cylinder.surface.graph()` returns a reusable weighted-graph
bundle containing the cylinder edges, induced edge weights, the 3D surface
coordinates, and a 2D unwrapped parameterization.
}
