% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{triangulated_polyhedron_surface_helpers}
\alias{triangulated_polyhedron_surface_helpers}
\alias{triangulated.polyhedron.surface.embedding}
\alias{triangulated.polyhedron.surface.graph}
\title{Weighted triangulated polyhedron surface helpers}
\usage{
triangulated.polyhedron.surface.embedding(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1,
  surface = c("standard", "inflated", "twisted", "wavy"),
  amplitude = 0.25,
  freq = 2,
  twist = 0.6
)

triangulated.polyhedron.surface.graph(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1,
  surface = c("standard", "inflated", "twisted", "wavy"),
  amplitude = 0.25,
  freq = 2,
  twist = 0.6,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{base}{Base polyhedron. One of \code{"tetrahedron"},
\code{"octahedron"}, or \code{"icosahedron"}.}

\item{level}{Subdivision depth. \code{level = 0} returns the base
triangulation, \code{level = 1} splits each face into four, and so on.}

\item{surface}{Geometry family used for the 3D embedding. One of
\code{"standard"}, \code{"inflated"}, \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{normalize}{Normalization applied to the induced edge lengths. One of
\code{"median"}, \code{"mean"}, or \code{"none"}.}
}
\value{
\code{triangulated.polyhedron.surface.embedding()} returns an \code{n x 3}
numeric matrix with columns \code{x}, \code{y}, and \code{z}.

\code{triangulated.polyhedron.surface.graph()} returns a list with
components:
\itemize{
  \item \code{edges}: the triangulated-surface 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 piecewise-flat coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"triangulated.polyhedron"},
  \item \code{base}: the chosen base polyhedron,
  \item \code{surface}: the chosen surface name,
  \item \code{level}: the subdivision depth,
  \item \code{subdivision}: the linear face subdivision factor
    \code{2^level},
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that take a triangular-face polyhedron, repeatedly split
each face into four subtriangles, merge shared-edge vertices, and use the
resulting triangulated-surface graph as a reusable benchmark family. The
canonical geometry is a piecewise-flat triangulated surface, while the
weighted variants can inflate, twist, or radially modulate that surface in
\eqn{\mathbb{R}^3}.
}
\details{
The current supported bases are the regular tetrahedron, octahedron, and
icosahedron. These give closed triangulated surfaces with non-grid topology
and a small number of extraordinary vertices, making them useful complements
to the mesh-derived families already in the package.
}
