% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_helpers.R
\name{sphere_surface_helpers}
\alias{sphere_surface_helpers}
\alias{sphere.surface.embedding}
\alias{sphere.surface.graph}
\title{Weighted sphere surface helpers}
\usage{
sphere.surface.embedding(
  h,
  w = h,
  surface = c("standard", "ellipsoid", "wavy"),
  radius = 1,
  amplitude = 0.2,
  freq_theta = 3,
  freq_lat = 2,
  twist = 0.25
)

sphere.surface.graph(
  h,
  w = h,
  surface = c("standard", "ellipsoid", "wavy"),
  radius = 1,
  amplitude = 0.2,
  freq_theta = 3,
  freq_lat = 2,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)
}
\arguments{
\item{h}{Number of latitude levels including the poles. Must be at least
\code{3}.}

\item{w}{Wrapped longitude count. Defaults to \code{h}; must be at least
\code{3}.}

\item{surface}{Sphere surface family. One of \code{"standard"},
\code{"ellipsoid"}, or \code{"wavy"}.}

\item{radius}{Positive baseline radius.}

\item{amplitude}{Finite deformation amplitude. For \code{"ellipsoid"},
positive values make the shape oblate and negative values make it prolate,
while keeping all axis lengths positive. For \code{"wavy"}, the local
radius must remain positive everywhere.}

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

\item{freq_lat}{Positive latitudinal frequency used only when
\code{surface = "wavy"}.}

\item{twist}{Finite longitude twist applied smoothly by latitude. The twist
vanishes at the poles.}

\item{normalize}{Normalization applied to the induced edge lengths. One of
\code{"median"}, \code{"mean"}, or \code{"none"}.}
}
\value{
\code{sphere.surface.embedding()} returns an \code{n x 3} numeric matrix
with columns \code{x}, \code{y}, and \code{z}, where
\code{n = 2 + (h - 2) * w}.

\code{sphere.surface.graph()} returns a list with components:
\itemize{
  \item \code{edges}: the undirected sphere-graph 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 longitude-latitude parameter coordinates,
  \item \code{weight_scale}: the normalization constant applied to the raw
    edge lengths,
  \item \code{family}: always \code{"sphere"},
  \item \code{surface}: the chosen surface name,
  \item \code{label}: a human-readable family label.
}
}
\description{
Convenience helpers that embed the sampled sphere 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 follows the current pole-plus-latitude-rings sphere graph but
the intended metric comes from a curved or spatially varying 3D realization.
}
\details{
`sphere.surface.embedding()` returns the 3D coordinates of the sampled
surface in the same vertex order as \code{edges.sphere()}: north pole first,
then latitude rings from north to south, then the south pole.
`sphere.surface.graph()` returns a reusable weighted-graph bundle containing
the sphere edges, induced edge weights, the 3D surface coordinates, and a 2D
longitude-latitude parameterization.
}
