Sphere

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

string

Unique identifier for the sphere. Auto-generated if not provided.

Vector3

required

Center point of the sphere in 3D space.

center: new Vector3(0, 0, 0)

number

required

Radius of the sphere.

radius: 5  // Units in scene space

number

required

Number of horizontal segments (longitude). Higher values create smoother spheres.

widthSegments: 24  // Default value

number

required

Number of vertical segments (latitude). Higher values create smoother spheres.

heightSegments: 16  // Default value

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

string

Unique identifier for the sphere instance.

ISphereOptions

Current sphere configuration.

const currentRadius = sphere.options.radius;
const currentSegments = sphere.options.widthSegments;

number

Get or set the sphere radius. Setting triggers geometry regeneration.

sphere.radius = 10;  // Update radius and regenerate

number

Get or set the sphere color.

sphere.color = 0xff0000;  // Change to red

boolean

Enable or disable outline rendering showing the sphere’s wireframe edges.

sphere.outline = true;   // Show wireframe
sphere.outline = false;  // Hide wireframe

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

Cylinder

Cylindrical shapes

Cuboid

Rectangular boxes

Sweep

Custom revolution shapes

2D Primitives

3D Shapes

Operations

Export (Experimental)

Overview

Constructor

ISphereOptions

Methods

setConfig()

getBrep()

generateGeometry()

discardGeometry()

Properties

Usage Examples

Basic Sphere

High-Resolution Sphere

Low-Poly Sphere

Animated Sphere

Planet with Outline

Implementation Details

UV Sphere Generation

Material Configuration

Outline from B-Rep Edges

Face Generation

Best Practices

Performance Considerations

Vertex Count

Face Count

Live Demo

Sphere Demo

See Also

Cylinder

Cuboid

Sweep

​Overview

​Constructor

​ISphereOptions

​Methods

​setConfig()

​getBrep()

​generateGeometry()

​discardGeometry()

​Properties

​Usage Examples

​Basic Sphere

​High-Resolution Sphere

​Low-Poly Sphere

​Animated Sphere

​Planet with Outline

​Implementation Details

​UV Sphere Generation

​Material Configuration

​Outline from B-Rep Edges

​Face Generation

​Best Practices

​Performance Considerations

​Vertex Count

​Face Count

​Live Demo

Sphere Demo

​See Also

Cylinder

Cuboid

Sweep

Overview

Constructor

ISphereOptions

Methods

setConfig()

getBrep()

generateGeometry()

discardGeometry()

Properties

Usage Examples

Basic Sphere

High-Resolution Sphere

Low-Poly Sphere

Animated Sphere

Planet with Outline

Implementation Details

UV Sphere Generation

Material Configuration

Outline from B-Rep Edges

Face Generation

Best Practices

Performance Considerations

Vertex Count

Face Count

Live Demo

See Also