Skip to main content

​
Overview

The Sphere class creates 3D spherical shapes with customizable radius and segment resolution. Spheres are generated using UV parameterization with configurable width and height segments for controlling geometry smoothness.

​
Constructor

const sphere = new Sphere(options?: ISphereOptions);

​
ISphereOptions

​
ogid
string
Unique identifier for the sphere. Auto-generated if not provided.
​
center
Vector3
required
Center point of the sphere in 3D space.
center: new Vector3(0, 0, 0)
​
radius
number
required
Radius of the sphere.
radius: 5  // Units in scene space
​
widthSegments
number
required
Number of horizontal segments (longitude). Higher values create smoother spheres.
widthSegments: 24  // Default value
​
heightSegments
number
required
Number of vertical segments (latitude). Higher values create smoother spheres.
heightSegments: 16  // Default value
​
color
number
required
Hexadecimal color value for the sphere.
color: 0x00ff00  // Green

​
Methods

​
setConfig()

Updates the sphere configuration and regenerates geometry. 
sphere.setConfig(options: ISphereOptions): void
Example: 
sphere.setConfig({
  center: new Vector3(0, 5, 0),
  radius: 8,
  widthSegments: 32,
  heightSegments: 24,
  color: 0x3498db
});

​
getBrep()

Returns the B-Rep (Boundary Representation) data as a parsed JSON object. 
sphere.getBrep(): object
Example: 
const brepData = sphere.getBrep();
console.log('Vertices:', brepData.vertices.length);
console.log('Edges:', brepData.edges.length);
console.log('Faces:', brepData.faces.length);

​
generateGeometry()

Regenerates the THREE.js geometry from the current configuration. Called automatically after setConfig(). 
sphere.generateGeometry(): void

​
discardGeometry()

Disposes of the current geometry to free memory. 
sphere.discardGeometry(): void

​
Properties

​
ogid
string
Unique identifier for the sphere instance.
​
options
ISphereOptions
Current sphere configuration.
const currentRadius = sphere.options.radius;
const currentSegments = sphere.options.widthSegments;
​
radius
number
Get or set the sphere radius. Setting triggers geometry regeneration.
sphere.radius = 10;  // Update radius and regenerate
​
color
number
Get or set the sphere color.
sphere.color = 0xff0000;  // Change to red
​
outline
boolean
Enable or disable outline rendering showing the sphere’s wireframe edges.
sphere.outline = true;   // Show wireframe
sphere.outline = false;  // Hide wireframe
​
outlineMesh
THREE.LineSegments | null
Reference to the outline mesh if outline is enabled.

​
Usage Examples

​
Basic Sphere

import { Sphere, Vector3 } from 'opengeometry';

const sphere = new Sphere({
  center: new Vector3(0, 0, 0),
  radius: 5,
  widthSegments: 24,
  heightSegments: 16,
  color: 0x2ecc71
});

// Add to scene
scene.add(sphere);

​
High-Resolution Sphere

import { Sphere, Vector3 } from 'opengeometry';

// Smooth sphere for close-up viewing
const smoothSphere = new Sphere({
  center: new Vector3(0, 0, 0),
  radius: 8,
  widthSegments: 48,  // High horizontal resolution
  heightSegments: 32,  // High vertical resolution
  color: 0x3498db
});

smoothSphere.outline = true;

​
Low-Poly Sphere

import { Sphere, Vector3 } from 'opengeometry';

// Faceted appearance for stylized visuals
const lowPolySphere = new Sphere({
  center: new Vector3(0, 0, 0),
  radius: 6,
  widthSegments: 8,   // Low segment count
  heightSegments: 6,
  color: 0xe74c3c
});

​
Animated Sphere

import { Sphere, Vector3 } from 'opengeometry';

const sphere = new Sphere({
  center: new Vector3(0, 0, 0),
  radius: 5,
  widthSegments: 32,
  heightSegments: 24,
  color: 0x9b59b6
});

// Pulsating animation
function animate() {
  const time = Date.now() * 0.001;
  sphere.radius = 5 + Math.sin(time * 2) * 1.5;
  requestAnimationFrame(animate);
}
animate();

​
Planet with Outline

import { Sphere, Vector3 } from 'opengeometry';

const planet = new Sphere({
  center: new Vector3(0, 0, 0),
  radius: 10,
  widthSegments: 40,
  heightSegments: 30,
  color: 0x1e8bc3
});

planet.outline = true;

​
Implementation Details

​
UV Sphere Generation

Spheres are generated using parametric equations with UV coordinates: Rust Implementation: /workspace/source/main/opengeometry/src/primitives/sphere.rs:76-106 
for iy in 0..=height {
    let v = iy as f64 / height as f64;
    let theta = v * std::f64::consts::PI;
    let sin_theta = theta.sin();
    let cos_theta = theta.cos();

    for ix in 0..=width {
        let u = ix as f64 / width as f64;
        let phi = u * std::f64::consts::PI * 2.0;
        let sin_phi = phi.sin();
        let cos_phi = phi.cos();

        let x = self.center.x + self.radius * sin_theta * cos_phi;
        let y = self.center.y + self.radius * cos_theta;
        let z = self.center.z + self.radius * sin_theta * sin_phi;
    }
}

​
Material Configuration

Spheres use MeshStandardMaterial with transparency: Source: /workspace/source/main/opengeometry/src/shapes/sphere.ts:113-117 
const material = new THREE.MeshStandardMaterial({
  color: this.options.color,
  transparent: true,
  opacity: 0.6,
});

​
Outline from B-Rep Edges

Unlike other shapes, sphere outlines are generated from the B-Rep edge data to properly represent the geometry: Source: /workspace/source/main/opengeometry/src/shapes/sphere.ts:150-176 
const brep = this.getBrep();
const lineBuffer: number[] = [];

for (const edge of brep.edges ?? []) {
  const start = brep.vertices?.[edge.v1]?.position;
  const end = brep.vertices?.[edge.v2]?.position;
  if (!start || !end) continue;
  
  lineBuffer.push(
    start.x, start.y, start.z,
    end.x, end.y, end.z
  );
}

​
Face Generation

The sphere is composed of triangular faces, with special handling for the poles to avoid degenerate triangles: Source: /workspace/source/main/opengeometry/src/primitives/sphere.rs:111-136

​
Best Practices

Segment Optimization: Use widthSegments: 24 and heightSegments: 16 for general purposes. Increase for close-ups (32/24 or 48/32), decrease for distant objects (12/8) to improve performance.
Minimum Segments: The Rust implementation enforces minimum values: widthSegments >= 3 and heightSegments >= 2. Lower values will be automatically clamped.
Aspect Ratio: For most realistic spheres, maintain a widthSegments:heightSegments ratio of approximately 3:2 (e.g., 24:16, 30:20, 48:32).

​
Performance Considerations

​
Vertex Count

The total number of vertices generated is (widthSegments + 1) × (heightSegments + 1):
  • 24×16 segments = 425 vertices
  • 32×24 segments = 825 vertices
  • 48×32 segments = 1,617 vertices

​
Face Count

Approximate number of triangular faces: widthSegments × heightSegments × 2

​
Live Demo

Sphere Demo

Try the Sphere shape in the browser

​
See Also

Cylinder

Cylindrical shapes

Cuboid

Rectangular boxes

Sweep

Custom revolution shapes
Last modified on March 14, 2026