InstancedSphereMeshDesc
The InstancedSphereMeshDesc class is a mesh descriptor that renders multiple sphere instances using GPU instancing. All spheres share a single geometry and material, rendered in one draw call for high performance. It extends InstancedMeshDesc.
In addition to the properties below, all common properties from the base class (position, rotation, scale, matrix, matrixWorld, pickable, visible) are available. See MeshDesc for details.
Shared Material Properties
Section titled “Shared Material Properties”Shared properties applied to all instances. These are specified in the spheres config object. Segment and arc parameters are baked into the shared geometry and cannot vary per instance.
widthSegments
Section titled “widthSegments”Type: number
Description: Specifies the number of horizontal segments of the shared sphere geometry.
Default: 32
heightSegments
Section titled “heightSegments”Type: number
Description: Specifies the number of vertical segments of the shared sphere geometry.
Default: 16
phiStart
Section titled “phiStart”Type: number
Description: Specifies the horizontal starting angle (radians).
Default: 0
phiLength
Section titled “phiLength”Type: number
Description: Specifies the horizontal sweep angle (radians).
Default: Math.PI * 2
thetaStart
Section titled “thetaStart”Type: number
Description: Specifies the vertical starting angle (radians).
Default: 0
thetaLength
Section titled “thetaLength”Type: number
Description: Specifies the vertical sweep angle (radians).
Default: Math.PI
Type: Color
Description: Specifies the base color for all instances using a Color instance.
Default: new Color().setStyle("#ffffff")
Example:
import { Color } from "@navaramap/three";
{ spheres: { color: new Color().setHex(0xff0000), }}emissiveColor
Section titled “emissiveColor”Type: Color
Description: Specifies the emissive (self-illuminating) color.
Default: new Color().setHex(0x000000)
emissiveIntensity
Section titled “emissiveIntensity”Type: number
Description: Specifies the emissive intensity.
Default: 0
opacity
Section titled “opacity”Type: number
Description: Specifies the opacity. Ranges from 0.0 (fully transparent) to 1.0 (fully opaque).
Default: 1
transparent
Section titled “transparent”Type: boolean
Description: Specifies whether to enable transparency.
Default: false
castShadow
Section titled “castShadow”Type: boolean
Description: Specifies whether the instances cast shadows.
Default: false
receiveShadow
Section titled “receiveShadow”Type: boolean
Description: Specifies whether the instances receive shadows.
Default: false
Per-Instance Properties (SphereChildConfig)
Section titled “Per-Instance Properties (SphereChildConfig)”Properties for each individual sphere instance, specified in the children array.
radius
Section titled “radius”Type: number
Description: Specifies the sphere radius. Encoded as uniform scale in the instance matrix. Multiplied with scale if specified.
Default: 1
Example:
{ spheres: { children: [ { radius: 100 }, ], }}Type: Color | undefined
Description: Specifies the per-instance color. Overrides the shared material color for this specific instance.
Default: undefined (uses shared material color)
position
Section titled “position”Type: { x: number, y: number, z: number } | undefined
Description: Specifies the local position relative to the parent group.
Default: { x: 0, y: 0, z: 0 }
rotation
Section titled “rotation”Type: { x: number, y: number, z: number } | undefined
Description: Specifies the local rotation (Euler angles in radians).
Default: undefined
Type: { x: number, y: number, z: number } | undefined
Description: Specifies the local scale. Multiplied with radius.
Default: { x: 1, y: 1, z: 1 }
matrix
Section titled “matrix”Type: Matrix4 | undefined
Description: Specifies a pre-computed transform matrix. When set, position, rotation, and scale are ignored.
Default: undefined
Config
Section titled “Config”effectIds
Section titled “effectIds”Type: string[] (optional)
Description: Specifies an array of selective effect descriptor IDs to apply to this mesh.
Example:
{ spheres: { effectIds: ["bloom-effect", "outline-effect"], }}pickable
Section titled “pickable”Type: boolean (optional)
Description: Enables picking for individual instances. When true, each instance can be picked by the picking system.
Default: false
Instance Management
Section titled “Instance Management”Methods inherited from InstancedMeshDesc for dynamic instance management:
handle.ref.add(config)
Section titled “handle.ref.add(config)”Adds a new instance. Returns the index of the added instance.
const index = handle.ref.add({ position: { x: 100, y: 0, z: 0 }, radius: 20, color: new Color().setHex(0xffff00),});handle.ref.removeAt(index)
Section titled “handle.ref.removeAt(index)”Removes an instance by index. Uses swap-with-last for O(1) removal. Instance order is not preserved.
handle.ref.removeAt(1);handle.ref.updateAt(index, config)
Section titled “handle.ref.updateAt(index, config)”Updates an instance at the given index with partial config.
handle.ref.updateAt(0, { color: new Color().setHex(0xff00ff), radius: 50,});handle.ref.clear()
Section titled “handle.ref.clear()”Removes all instances.
handle.ref.replaceAll(configs)
Section titled “handle.ref.replaceAll(configs)”Batch replaces all instances. More efficient than clear() + multiple add() calls as it emits a single update notification.
handle.ref.count
Section titled “handle.ref.count”Gets the number of active instances.
Usage Examples
Section titled “Usage Examples”Basic Usage
Section titled “Basic Usage”import ThreeView, { Color } from "@navaramap/three";import { InstancedSphereMeshDesc } from "@navaramap/three_default_descs";
const view = new ThreeView();view.registerMesh("spheres", InstancedSphereMeshDesc);await view.init();
const handle = view.addMesh<InstancedSphereMeshDesc>({ spheres: { color: new Color().setHex(0xffffff), castShadow: true, children: [ { position: { x: 0, y: 0, z: 0 }, radius: 10, color: new Color().setHex(0xff0000) }, { position: { x: 30, y: 0, z: 0 }, radius: 15, color: new Color().setHex(0x00ff00) }, { position: { x: 60, y: 0, z: 0 }, radius: 5, color: new Color().setHex(0x0000ff) }, ], }, position: { x: 0, y: 0, z: 6378137 },});Updating Shared Material
Section titled “Updating Shared Material”handle.update({ spheres: { color: new Color().setHex(0x333333), emissiveColor: new Color().setHex(0xff0000), emissiveIntensity: 0.5, opacity: 0.8, transparent: true, },});