Voice Orb 3D Rendering
Relevant source files
The following files were used as context for generating this wiki page:
The Voice Orb 3D is a central semantic indicator within the J.A.R.V.I.S. desktop environment, providing visual feedback for various system states through an animated 3D sphere. It utilizes a custom Perlin-4D noise shader for organic deformation, responding dynamically to audio levels with effects like Fresnel glow and bloom post-processing.
Sources: voice-orb-export/orb-readme.md:1-5, instructions/design-backend-prompt.txt:127-130
Architecture and Components
The rendering system is built using React 18, Three.js, and @react-three/fiber. It follows a layered approach to ensure reliability and performance, employing a "Safe" wrapper to handle hardware limitations or crashes.
Rendering Hierarchy
This diagram illustrates the component hierarchy and the fallback mechanism used to prevent application crashes when WebGL is unavailable.
Sources: src/components/safe-voice-orb.tsx:23-44, src/components/VoiceOrb2D.tsx:9-11
Key Component Descriptions
| Component | Description |
|---|---|
SafeVoiceOrb | An Error Boundary wrapper that prevents WebGL/Three.js crashes from affecting the rest of the application. |
VoiceOrb3D | The primary 3D component using Perlin-4D Vertex/Fragment shaders for high-fidelity animation. |
VoiceOrb2D | A 2D-canvas fallback orb used when WebGL is unavailable, ensuring visual continuity on low-end hardware. |
SphereMesh | The internal component managing the Three.js mesh, geometry subdivisions (512x512), and shader uniforms. |
Sources: voice-orb-export/orb-readme.md:8-13, src/components/safe-voice-orb.tsx:16-20, src/components/VoiceOrb2D.tsx:11
Shader Logic and Animation
The visual identity of the orb is defined by a 4D Perlin noise implementation, which drives both vertex displacement and fragment coloring.
Vertex Shader Displacement
The vertex shader calculates a displacedPosition based on frequency and strength parameters. It also computes normals dynamically after displacement to ensure correct lighting and Fresnel effects.
vec3 getDisplacedPosition(vec3 _position) {
vec3 distortedPosition = _position;
distortedPosition += perlin4d(vec4(distortedPosition * uDistortionFrequency + uOffset, uTime)) * uDistortionStrength;
float perlinStrength = perlin4d(vec4(distortedPosition * uDisplacementFrequency + uOffset, uTime));
vec3 displacedPosition = _position;
displacedPosition += normalize(_position) * perlinStrength * uDisplacementStrength;
return displacedPosition;
}
Sources: src/components/voice-orb-3d.tsx:90-98
Uniform Mappings
The orb's appearance is controlled via uniforms that are updated every frame based on easing logic and input audio levels.
| Uniform | Type | Purpose |
|---|---|---|
uTime | float | Drives the noise animation progression. |
uOffset | vec3 | Provides a coordinate offset to create organic movement. |
uDistortionStrength | float | Controls the intensity of the surface distortion. |
uDisplacementStrength | float | Controls the overall volume/expansion of the orb. |
uFresnelMultiplier | float | Adjusts the intensity of the outer rim glow. |
Sources: src/components/voice-orb-3d.tsx:143-162
Audio Reactivity
The orb maps specific audio frequency bands (low, mid, high) to visual parameters. This mapping uses a variationsRef to store current and target values, applying easing to ensure smooth transitions between audio frames.
The sequence shows how raw audio levels are processed into smooth shader transitions.
Sources: src/components/voice-orb-3d.tsx:173-195, voice-orb-export/voice-orb-3d.tsx:179-204
Visual State Contract
While the orb reacts to audio, its base color and orbit speed are determined by the application's semantic state.
| State | Meaning | Visual Language |
|---|---|---|
idle | Core initialized | Muted cyan, slow orbit |
ready | Service healthy | Luminous cyan/blue, steady pulse |
listening | Voice intake active | Green/cyan receptive pulse |
thinking | Model inference | Violet/blue faster orbit |
responding | Output active | Bright cyan/green expansion |
error | Runtime fault | Red high-contrast warning |
disconnected | Service unreachable | Dim desaturated core |
Sources: instructions/design-backend-prompt.txt:132-141
Implementation Notes
- Performance: Sphere subdivision is set to 512x512 for high quality. If performance issues occur, these values in
sphereGeometryshould be reduced. - GPU Usage: The
pausedprop should be set totruewhen the orb is not visible to save GPU resources. - Imports: The
SafeVoiceOrbcomponent requires a specific import path adjustment insafe-voice-orb.tsxdepending on the project structure (e.g.,@/components/voice-orb-3d).
Sources: voice-orb-export/orb-readme.md:27-38, src/components/voice-orb-3d.tsx:210