Skip to content

Home

Jump to bottom
nolannmoisis edited this page Jan 2, 2025 · 5 revisions

GitHub Wiki for Interactive 3D Keycube Visualization System

Table of Contents

  1. Overview
  2. Project Structure
  3. Variables
  4. Methods
  5. Camera Configuration
  6. Lighting Configuration
  7. Key Features
  8. Dependencies
  9. Credits

Overview

This GitHub Wiki serves as a detailed documentation for the 3D Keycube Visualization System. Each section provides an in-depth exploration of variables, methods, and configurations used in the project, enabling developers to extend and modify the system effectively.

Project Structure

Folder Structure:

|-- config.json
|-- main.js
|-- model_stl/
|   |-- keycap.stl
|   |-- switch.stl
|   |-- ...
|-- model_glb/
|   |-- keycap.glb
|   |-- switch.glb
|   |-- ...
|-- wood/
|   |-- wooddiff.jpg
|   |-- ...
|-- metal/
|   |-- hexdiff.jpg
|   |-- ...

Key Files:

  • config.json: Configuration file defining parameters for camera, models, lighting, and materials.
  • main.js: Core script implementing the 3D visualization logic.
  • model_stl/ and model_glb/: Directories containing STL and GLTF models.
  • wood/ and metal/: Contains texture files used for materials.

Variables

Global Variables

Variable Type Description Example/Default Line Number
currentCamera THREE.Camera Tracks the currently active camera. perspectiveCamera 38
lastInteractionTime Integer Timestamp of the last user interaction. Date.now() 40
idleTimeout Integer Duration in seconds before idle animations start. 5 46
isExploded Boolean Indicates whether the keyboard is exploded. false 92
targetPositions Map Maps objects to explosion target positions. Initialized dynamically. 95
keys Array Stores all key meshes for interaction. [] 127
color String Default emissive color for key materials. "#0000FF" 129
clickColor String Emissive color when a key is pressed. "#FFFFFF" 130

Methods

createKeysForPlates

  • Description: Populates the keyboard plates with keycap models and assigns interactive features.
  • Parameters: None
  • Steps:
    1. Iterates through scene objects to find keyboard plates.
    2. Divides each plate into a grid and places key models.
    3. Adds glow and switch effects for each key.
    4. Stores keys in the global keys array.
  • Detailed Explanation: This method utilizes the grid layout on plates to position keycap models. Glow effects are derived from the FakeGlowMaterial configured in config.json. Interaction properties are attached dynamically.
  • Location in Code: Lines 170–396
  • Example Usage: 
    createKeysForPlates();

explodeModel

  • Description: Toggles the "explosion" effect by scattering or regrouping keyboard parts.
  • Parameters: None
  • Steps:
    1. Iterates through scene objects.
    2. Calculates directional vectors from the center.
    3. Updates targetPositions map based on isExploded state.
    4. Animates objects to their respective positions.
  • Location in Code: Lines 97–125
  • Example Usage: 
    explodeModel();

textForKey

Parameter Type Description
keyIndex Integer Identifier for the key.
size Float The size of the text.
position Vector3 Position of the text in 3D space.
rotation Vector3 Orientation of the text.
name String Unique identifier for the text object.
  • Steps:
    1. Parses the helvetiker_regular font.
    2. Creates a TextGeometry object.
    3. Centers and positions the text based on parameters.
    4. Adds the text to the scene.
  • Location in Code: Lines 134–167
  • Example Usage: 
    textForKey(1, 0.2, new THREE.Vector3(0, 0, 0), new THREE.Vector3(0, 0, 0), "key_1_text");

animateIdleCamera

  • Description: Adds smooth, idle motion to the camera when no user interaction is detected.
  • Parameters: None
  • Steps:
    1. Checks for idle state based on lastInteractionTime.
    2. Applies incremental sinusoidal adjustments to camera position.
  • Location in Code: Lines 47–57
  • Example Usage: 
    animateIdleCamera();

Loaders

  • STLLoader

    • Description: Loads .stl models for visualization.
    • Steps:
      1. Use the STLLoader class from Three.js.
      2. Call the load() method with the path to the .stl file.
      3. The loader parses the model and creates a THREE.Mesh.
      4. Add the mesh to the scene and apply materials as required.
    • Location in Code: Lines 480–613
    • Example Usage: 
      loader.load('models/keycap.stl', function (geometry) {
  const material = new THREE.MeshStandardMaterial({ color: 0xff0000 });
  const mesh = new THREE.Mesh(geometry, material);
  scene.add(mesh);
});

  • GLTFLoader

    • Description: Loads .gltf models for visualization.
    • Steps:
      1. Use the GLTFLoader class from Three.js.
      2. Call the load() method with the path to the .gltf file.
      3. The loader parses the model and creates a THREE.Object3D.
      4. Add the object to the scene and apply any additional settings.
    • Location in Code: Lines 618–755
    • Example Usage: 
      gltfLoader.load('models/keycap.gltf', function (gltf) {
  const object = gltf.scene;
  scene.add(object);
});

Camera Configuration

Perspective Camera

Property Value
Field of View 75
Near Clip Plane 0.1
Far Clip Plane 1000
Position [5, 5, 10]

Orthographic Camera

Property Value
Size 10
Near Clip Plane 0.1
Far Clip Plane 1000
Position [5, 5, 10]

Lighting Configuration

Lighting in the system is configurable through parameters defined in config.json and instantiated in main.js.

Light Sources

Light Type Description Line Number
AmbientLight Provides general illumination. 757
DirectionalLight Simulates sunlight with directional shadows. 760
SpecularLight Creates highlights and reflections. 769

Configurable Parameters

Light Type Property Description Example Value
AmbientLight color Base color of ambient light. 16777215
intensity Intensity of the light. 0.3
DirectionalLight color Base color of directional light. 16777215
intensity Intensity of the light. 3
position Position in 3D space. [5, 5, 10]
SpecularLight color Color for specular highlights. 0xffeedd
intensity Intensity for reflections. 1.5

To adjust these settings, modify the corresponding values in the lighting object within config.json or update them dynamically in the main.js file.

Key Features

  1. Interactive Keyboard: ²:
    • Real-time key pressing with glowing and position animations.
  2. Explosion Effect: a:
    • Visual disassembly of keyboard components.
  3. ASCII Rendering: e:
    • Converts the 3D scene into ASCII art with configurable options.
  4. Idle Camera Animation: auto:
    • Activates smooth, cyclical motion after inactivity.

Dependencies

The following libraries and tools are required:

Libraries

Library Purpose Version
three Core library for 3D rendering and visualization. ^0.150.0
STLLoader Loads .stl models into the Three.js scene. Built-in
GLTFLoader Loads .gltf models, allowing textures and lighting. Built-in
AsciiEffect Applies ASCII rendering effects to the scene. Built-in
OrbitControls Enables mouse-based camera navigation. Built-in
FontLoader Loads font files for text rendering in the scene. Built-in

Note: To load .stl models, uncomment the STLLoader code block (Lines 480–613) and comment out the GLTFLoader code block (Lines 618–755). Reverse this process to use .gltf models.

Credits

  • Author: MOISIS Nolann
Clone this wiki locally