# Frontend Documentation (`threejs-frontend.js`)

## Overview

The `RFVisualization` component is a React component responsible for rendering 3D visualizations of RF data using Three.js. It handles scene setup, camera controls, rendering loops, post-processing effects, and user interactions.

## Component Props

*   `visualizationData` (Object): The core data object containing information to be visualized. The structure depends on the `type` field (e.g., 'nerf', 'gaussian', 'point_cloud', 'correspondence').
*   `width` (Number, optional): Width of the visualization canvas (defaults to window width).
*   `height` (Number, optional): Height of the visualization canvas (defaults to window height).
*   `autoRotate` (Boolean, optional): Whether the camera should automatically rotate (defaults to `true`).
*   `backgroundColor` (String, optional): Background color of the scene (defaults to `#000011`).
*   `neuronActive` (Boolean, optional): Flag to enable/disable neuron firing-like effects (defaults to `true`, currently used in NeRF shader).
*   `signalOpacity` (Number, optional): Base opacity for signals/points (defaults to `0.7`).
*   `showAxes` (Boolean, optional): Whether to display coordinate axes (defaults to `true`).
*   `colorScale` (String, optional): The color mapping to use for intensity/feature values (e.g., 'thermal', 'jet', 'rainbow', 'grayscale', defaults to 'thermal').
*   `onPointClicked` (Function, optional): Callback function triggered when a point/voxel is clicked, receiving point data as an argument.

## Core Functionality

1.  **Scene Setup (`useEffect` hook):**
    *   Initializes the Three.js scene, perspective camera, and WebGL renderer.
    *   Sets up OrbitControls for camera manipulation.
    *   Configures an EffectComposer with RenderPass and UnrealBloomPass for post-processing.
    *   Adds basic lighting (ambient and directional) and optional axes helpers.
    *   Handles cleanup on component unmount.
2.  **Data Loading (`useEffect` hook based on `visualizationData`):**
    *   Clears any previous visualization objects (points, volumes).
    *   Determines the visualization type based on `visualizationData.type`.
    *   Calls the appropriate visualization function (`visualizeNeRF`, `visualizeGaussianSplats`, `visualizeCorrespondenceField`, `visualizePointCloud`).
    *   Manages loading and error states.
3.  **Animation Loop (`useEffect` hook based on `isPaused`):**
    *   Uses `requestAnimationFrame` for smooth rendering.
    *   Updates OrbitControls if auto-rotate is enabled.
    *   Updates shader uniforms (like time for NeRF animation) or morph targets (for correspondence fields).
    *   Renders the scene using the EffectComposer.
4.  **Visualization Methods:**
    *   `visualizePointCloud`: Renders data as individual points using `THREE.Points`. Handles position, color (based on data or color scale), and size attributes.
    *   `visualizeNeRF`: Renders NeRF data using volumetric ray marching. Creates a 3D texture (`Data3DTexture`) and uses a custom `ShaderMaterial` with ray marching logic in the fragment shader.
    *   `visualizeGaussianSplats`: Renders data using Gaussian Splatting. Uses `InstancedBufferGeometry` and a custom `ShaderMaterial` to efficiently render many oriented Gaussians.
    *   `visualizeCorrespondenceField`: Renders point trajectories using morph targets for animation.
5.  **Interaction (`handlePointClick`):**
    *   Uses `Raycaster` to detect clicks on points (currently only implemented for `visualizePointCloud` and `visualizeCorrespondenceField`).
    *   Retrieves data associated with the clicked point.
    *   Updates the `selectedPoint` state and calls the `onPointClicked` prop.
6.  **UI Controls:**
    *   Provides buttons to pause/resume the animation and toggle camera auto-rotation.
    *   Displays loading and error states.
    *   Shows an information panel when a point is selected.

## Visualization Data Formats

Each visualization type expects specific data structures in the `visualizationData` object:

1. **Point Cloud (`type: 'point_cloud'`)**:
   * `positions` (Array): Float32Array or standard array of [x, y, z] positions (flattened to [x1, y1, z1, x2, y2, z2, ...])
   * `colors` (Array, optional): Float32Array or standard array of [r, g, b] colors (0-1 range, flattened)
   * `intensities` (Array, optional): Float32Array or standard array of signal intensities for color mapping 
   * `pointSize` (Number, optional): Size of each point (default: 0.05)
   * `metadata` (Object, optional): Additional point metadata for display when clicked

2. **NeRF Volume (`type: 'nerf'`)**:
   * `dimensions` (Array): Three-element array specifying grid dimensions [x, y, z]
   * `gridData` (Array): Float32Array or standard array of volume data 
   * `volumeSize` (Array): Three-element array [width, height, depth] of physical volume size
   * `transferFunction` (Object, optional): Color and opacity mapping parameters
   * `densityThreshold` (Number, optional): Minimum density threshold for visualization

3. **Gaussian Splats (`type: 'gaussian'`)**:
   * `positions` (Array): Float32Array or standard array of splat center positions (flattened)
   * `rotations` (Array): Float32Array or standard array of quaternions [x, y, z, w] for orientation
   * `scales` (Array): Float32Array or standard array of [sx, sy, sz] scale factors for each splat
   * `colors` (Array): Float32Array or standard array of [r, g, b] colors (0-1 range)
   * `opacities` (Array, optional): Float32Array or standard array of opacity values (0-1)

4. **Correspondence Field (`type: 'correspondence'`)**:
   * `positions` (Array): Base positions of points (flattened [x, y, z] coordinates)
   * `trajectories` (Array): Array of position arrays representing point positions over time
   * `colors` (Array, optional): Colors for each point
   * `times` (Array, optional): Timestamp for each trajectory frame
   * `velocities` (Array, optional): Velocity vectors for points (used for coloring if colors not provided)

## Shaders

*   **NeRF Volume Shader:** Implements a basic volumetric ray marching algorithm in the fragment shader. Samples the 3D texture along rays cast from the camera and composites color and opacity. Includes a simple time-based pulsing effect.
*   **Gaussian Splat Shader:** Uses instancing attributes (position, rotation, scale, color, opacity) in the vertex shader to position and orient individual quads. The fragment shader calculates the Gaussian falloff based on UV coordinates to render the splat appearance.

## Dependencies

*   React (`react`)
*   Three.js (`three`)