AetherViz Master Documentation

AetherViz Master uses intelligent keyword detection to decide which rendering engine to use for a given topic. This ensures the most appropriate visualization method is applied:

• Pure Three.js 3D Mode: Triggered by keywords related to motion, particles, molecules, mechanics, or celestial bodies (e.g., 运动/粒子/分子/机械/天体). Best for physical simulations.
• SVG 2D Mode: Triggered by keywords related to functions, images, curves, or geometry (e.g., 函数/图像/曲线/几何). Best for mathematical graphs and diagrams.
• Hybrid Mode (Three.js + SVG): Triggered by keywords related to physics principles like Newton, waves, energy, or electromagnetism (e.g., 牛顿/波动/能量/电磁). This mode overlays 2D SVG charts (like wave patterns) onto 3D Three.js scenes.

Additionally, the system automatically detects the subject area (Physics, Chemistry, Biology, Math, Astronomy, or Programming) to apply appropriate color themes and language adaptations.

AetherViz Master uses a hybrid rendering architecture to combine 3D spatial depth with 2D data precision. The system automatically selects a mode based on the topic keywords.

Rendering Modes

Hybrid Architecture Implementation

1. Three.js Layer: The bottom layer containing the THREE.Scene and WebGLRenderer (with alpha: true).
2. SVG Overlay Layer: A top layer div with position: absolute, pointer-events: none, and a transparent background. This layer contains the SVG element.
3. Coordinate Synchronization: To align 2D SVG elements with 3D objects, use the project method to convert 3D vectors to 2D screen coordinates.

Responsive Synchronization

• Input Sync: Sliders must update both Three.js object properties and SVG path/attribute values simultaneously.
• Camera Sync: As the 3D camera moves, SVG annotations must follow using projectVector logic.
• Resize Sync: Window resizing must trigger updates to both the SVG viewBox and the Three.js renderer size.

// 1. Three.js 3D scene (Bottom layer)
const scene = new THREE.Scene();
const renderer = new THREE.WebGLRenderer({ alpha: true });

// 2. SVG Overlay (Top layer, transparent)
const svgContainer = document.createElement('div');
svgContainer.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;';
document.getElementById('canvas-container').appendChild(svgContainer);

const svg = d3.select(svgContainer).append('svg')
    .attr('width', '100%')
    .attr('height', '100%');

// 3. Coordinate synchronization
function syncSVGto3D() {
    const vector = new THREE.Vector3(x, y, z);
    vector.project(camera);

    const sx = (vector.x * 0.5 + 0.5) * width;
    const sy = (-(vector.y * 0.5) + 0.5) * height;

    return { x: sx, y: sy };
}

To run AetherViz Master on your local machine, follow these steps:

1. Clone the repository:

   git clone https://github.com/andyhuo520/aetherviz-master.git
   cd aetherviz-master

2. Start a local web server. Since the project generates interactive HTML content, you must serve it via a web server rather than opening files directly from the file system. You can use any of the following commands:

   • Using Python:

     python -m http.server 8080

   • Using npm (npx):

     npx serve .

   • Using PHP:

     php -S localhost:8080

3. Access the application by navigating to http://localhost:8080 in a modern web browser (Chrome, Edge, Firefox, or Safari) that supports WebGL.

# 1. 克隆仓库
git clone https://github.com/andyhuo520/aetherviz-master.git
cd aetherviz-master

# 2. 启动本地服务器（任选一种）
python -m http.server 8080
# 或
npx serve .
# 或
php -S localhost:8080

# 3. 访问 http://localhost:8080

To ensure compatibility and performance, AetherViz Master projects must adhere to the following technical stack. All dependencies must be loaded via CDN to maintain a zero-dependency, single-file HTML structure.

Required Libraries

• Three.js r134: The core 3D engine.
  • URL: https://cdnjs.cloudflare.com/ajax/libs/three.js/r134/three.min.js
• OrbitControls: Must be included as an inline, simplified version supporting enableDamping, touch operations, and zoom limits.
• Tailwind CSS v3.4+: For UI styling.
  • URL: https://cdn.tailwindcss.com
• KaTeX: For mathematical formula rendering.
  • CSS: https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css
  • JS: https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js
  • Auto-render: https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js
• D3.js (Optional): Used for data-driven SVG elements.
  • URL: https://d3js.org/d3.v7.min.js

Typography

• Use Inter and system sans-serif fonts.

AetherViz Master uses a specific CSS variable system to maintain a consistent 'Cyber-Education' aesthetic. Use these variables for UI components and theme switching.

Core Color Palette

• Primary Gradient: linear-gradient(135deg, #14B8A6 0%, #06B6D4 50%, #22D3EE 100%)
• Background: Deep sea tech feel using --bg-gradient (#0F172A to #164E63).
• Glassmorphism: Use --glass-bg (rgba(255, 255, 255, 0.08)) and --glass-border for panels.

Subject-Specific Themes

The UI should automatically switch to these gradients based on the detected subject:

• Physics: Blue (#3B82F6 to #0EA5E9)
• Chemistry: Orange-Red (#F59E0B to #EF4444)
• Biology: Emerald-Cyan (#10B981 to #22D3EE)
• Math: Golden (#F59E0B to #EAB308)
• Astronomy: Deep Blue (#1E40AF to #3B82F6)
• Programming: Code Cyan (#22C55E to #14B8A6)

/* Core Gradient Example */
--primary-gradient: linear-gradient(135deg, #14B8A6 0%, #06B6D4 50%, #22D3EE 100%);

/* Glassmorphism Example */
--glass-bg: rgba(255, 255, 255, 0.08);
--glass-border: rgba(255, 255, 255, 0.15);
--glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);

When building 3D educational scenes, follow these technical requirements for high-quality visualization:

Scene Setup

• Camera: Use PerspectiveCamera with fov: 60, near: 0.1, and far: 1000.
• Renderer: Use WebGLRenderer with antialias: true and shadowMap.enabled: true.
• Lighting: Combine HemisphereLight (ambient) and DirectionalLight (main light with castShadow=true).

Visual Elements

• Materials: Use MeshStandardMaterial or MeshPhongMaterial. For biological/chemical models, use transparent materials with particle effects.
• Vector Visualization: Use THREE.ArrowHelper for forces. Use specific colors:
  • Force: Red (#EF4444)
  • Velocity: Blue (#3B82F6)
  • Acceleration: Green (#22C55E)
• Particles: Use THREE.Points with BufferGeometry and PointsMaterial for real-time updates.
• Trajectories: Use THREE.Line with BufferAttribute. Implement a fixed-length buffer that shifts and pushes new points every frame.
• Interaction: Use THREE.Raycaster to detect clicks on 3D objects for highlighting or triggering sidebar formula derivations.