Skip to contents

Weighted sphere surface helpers

Source: R/graph_helpers.R
sphere_surface_helpers.Rd

Convenience helpers that embed the sampled sphere graph into \(\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.

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

h

Number of latitude levels including the poles. Must be at least 3.

w

Wrapped longitude count. Defaults to h; must be at least 3.

surface

Sphere surface family. One of "standard", "ellipsoid", or "wavy".

radius

Positive baseline radius.

amplitude

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

freq_theta

Positive longitudinal frequency used only when surface = "wavy".

freq_lat

Positive latitudinal frequency used only when surface = "wavy".

twist

Finite longitude twist applied smoothly by latitude. The twist vanishes at the poles.

normalize

Normalization applied to the induced edge lengths. One of "median", "mean", or "none".

Value

sphere.surface.embedding() returns an n x 3 numeric matrix with columns x, y, and z, where n = 2 + (h - 2) * w.

sphere.surface.graph() returns a list with components:

  • edges: the undirected sphere-graph edges,

  • n: number of vertices,

  • edge_weights: induced positive edge lengths,

  • coords_surface: the 3D surface embedding,

  • coords_param: the 2D longitude-latitude parameter coordinates,

  • weight_scale: the normalization constant applied to the raw edge lengths,

  • family: always "sphere",

  • surface: the chosen surface name,

  • label: a human-readable family label.

Details

`sphere.surface.embedding()` returns the 3D coordinates of the sampled surface in the same vertex order as 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.