Merge pull request #17 from KBLLR/JSDocumentation

Jules PR

Author: KBLLR

README.md

@@ -1,6 +1,75 @@
 # 3D Model Splats Stager
 
-A modern, high-performance 3D object stager specializing in Gaussian Splatting models, built with Three.js and Vite. This application enables advanced visualization of 3D models with sophisticated post-processing effects and real-time parameter adjustment.
+A modern, high-performance 3D object stager specializing in Gaussian Splatting models, built with Three.js and Vite. This application enables advanced visualization of 3D models with sophisticated post-processing effects and real-time parameter adjustment, serving as a powerful tool for artists, designers, and developers to test and showcase their 3D assets in a feature-rich environment.
+
+## Getting Started
+
+These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
+
+### Prerequisites
+
+You need to have Node.js and npm installed on your system. You can download them from [nodejs.org](https://nodejs.org/).
+
+### Installation
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/your-username/3d-model-splats-stager.git
+    cd 3d-model-splats-stager
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+
+## Usage
+
+### Running the Development Server
+
+To start the development server with hot module replacement, run the following command:
+
+```bash
+npm run dev
+```
+
+This will open the application in your default browser, typically at `http://localhost:5173`.
+
+### Running Tests
+
+The project includes a suite of browser-based tests. To run them, use the following command:
+
+```bash
+npm run test
+```
+
+This will start a Vite server to serve the tests from the `src/tests` directory. Open the provided URL in your browser to see the test results.
+
+### Building for Production
+
+To build the application for production, run:
+
+```bash
+npm run build
+```
+
+This command will create a `dist` directory with the optimized and minified assets, ready for deployment.
+
+## Project Structure
+
+The project's source code is located in the `src` directory and is organized as follows:
+
+-   **`src/assets`**: Contains static assets like environment maps and icons.
+-   **`src/core`**: The core application logic, divided into subdirectories:
+    -   **`components`**: Reusable Three.js components (cameras, lights, materials, etc.).
+    -   **`generators`**: Classes that generate complex objects like scenes and stages.
+    -   **`managers`**: Classes that manage different aspects of the application (scenes, cameras, loaders, etc.).
+    -   **`renderers`**: Custom Three.js renderer classes with specific configurations.
+    -   **`scenes`**: Definitions for different scenes within the application.
+    -   **`utils`**: Core utility functions.
+-   **`src/presets`**: Contains preset configurations for cameras, fog, scenes, and models.
+-   **`src/tests`**: Contains the browser-based test suite.
+-   **`src/utils`**: General utility functions for the application.
 
 ## Key Features
 - Advanced rendering pipeline using Three.js r157
@@ -27,4 +96,4 @@ A modern, high-performance 3D object stager specializing in Gaussian Splatting m
 - Automatic compression for production builds
 - Environment variable handling
 - ESLint and Prettier configuration
-- Type support for Three.js
+- Type support for Three.js

main.js

@@ -1,3 +1,10 @@
+/**
+ * @file This is the main entry point for the 3D Model Splats Stager application.
+ * It sets up the Three.js scene, renderer, camera, and controls.
+ * It also initializes the UI for controlling fog and camera movement.
+ *
+ * @module main
+ */
 import "./style.css";
 import * as THREE from "three";
 import { Pane } from "tweakpane";
@@ -9,10 +16,16 @@ import { HDRIEnvironment } from "@components/environments/HDRIEnvironment";
 import { FOG_PRESETS } from "@presets/fogPresets"; // Ensure path is correct
 import { CAMERA_MOVEMENT_PRESETS } from "@presets/cameraPresets"; // Adjust the path if necessary
 
-// Initialize Tweakpane
+/**
+ * @description Initialize Tweakpane for UI controls.
+ * @type {Pane}
+ */
 const pane = new Pane();
 
-// Fog parameters with initial description
+/**
+ * @description Fog parameters with initial description.
+ * @type {{enabled: boolean, preset: string, color: number, density: number, description: string}}
+ */
 const fogParams = {
   enabled: true,
   preset: "SOFT_BLUE",
@@ -21,10 +34,16 @@ const fogParams = {
   description: FOG_PRESETS.SOFT_BLUE.description, // Initial description
 };
 
-// Fog controls within a folder
+/**
+ * @description Fog controls within a Tweakpane folder.
+ * @type {import("tweakpane").FolderApi}
+ */
 const fogFolder = pane.addFolder({ title: "Fog Controls" });
 
-// Dropdown options for fog presets
+/**
+ * @description Dropdown options for fog presets.
+ * @type {Object.<string, string>}
+ */
 const options = Object.fromEntries(
   Object.keys(FOG_PRESETS).map((key) => [key, key]),
 );
@@ -63,7 +82,10 @@ fogFolder.addBinding(fogParams, "description", {
   readonly: true,
 });
 
-// Camera movement parameters with `shake` properties initially set to null
+/**
+ * @description Camera movement parameters with `shake` properties initially set to null.
+ * @type {{preset: string, description: string, movement: number, stabilization: number, shake: {intensity: number|null, frequency: number|null}}}
+ */
 const movementParams = {
   preset: "STATIC",
   description: CAMERA_MOVEMENT_PRESETS.STATIC.name,
@@ -72,8 +94,16 @@ const movementParams = {
   shake: { intensity: null, frequency: null }, // Initialize shake properties
 };
 
+/**
+ * @description Camera movement controls within a Tweakpane folder.
+ * @type {import("tweakpane").FolderApi}
+ */
 const movementFolder = pane.addFolder({ title: "Camera Movement" });
 
+/**
+ * @description Dropdown options for camera movement presets.
+ * @type {Object.<string, string>}
+ */
 const movementOptions = Object.fromEntries(
   Object.keys(CAMERA_MOVEMENT_PRESETS).map((key) => [
     key,
@@ -149,7 +179,10 @@ movementFolder.addBinding(movementParams, "stabilization", {
   label: "Stabilization",
 });
 
-// Initialize Scene and Renderer
+/**
+ * @description Initialize Scene and Renderer.
+ * @type {THREE.Scene}
+ */
 const scene = new THREE.Scene();
 const canvas = document.querySelector("#webgl");
 const renderer = new CinematicRenderer({
@@ -166,7 +199,10 @@ renderer.toneMappingExposure = 1.0;
 renderer.shadowMap.enabled = true;
 renderer.shadowMap.type = THREE.PCFSoftShadowMap;
 
-// Camera
+/**
+ * @description The main camera for the scene.
+ * @type {CinematicCamera}
+ */
 const camera = new CinematicCamera({
   fov: 75,
   aspect: window.innerWidth / window.innerHeight,
@@ -176,12 +212,18 @@ const camera = new CinematicCamera({
 });
 scene.add(camera);
 
-// Orbit Controls
+/**
+ * @description Orbit controls for camera manipulation.
+ * @type {OrbitControls}
+ */
 const controls = new OrbitControls(camera, canvas);
 controls.enableDamping = true;
 controls.enablePanning = true;
 
-// Infinite Ground
+/**
+ * @description An infinite ground plane.
+ * @type {THREE.Mesh}
+ */
 const groundGeometry = new THREE.PlaneGeometry(1000, 1000);
 const groundMaterial = new THREE.MeshStandardMaterial({
   color: 0x999999,
@@ -193,7 +235,10 @@ ground.rotation.x = -Math.PI / 2;
 ground.receiveShadow = true;
 scene.add(ground);
 
-// Environment
+/**
+ * @description The HDRI environment for the scene.
+ * @type {HDRIEnvironment}
+ */
 const environment = new HDRIEnvironment({
   path: "/src/assets/environmentMaps/hdr/placeholder.hdr",
   intensity: 1.0,
@@ -203,16 +248,22 @@ environment.load(renderer).then((envMap) => {
   scene.background = envMap;
 });
 
-// Fog Setup with Default Preset
-// Set initial fog
+/**
+ * @description Fog setup with a default preset.
+ */
 scene.fog = new THREE.FogExp2(fogParams.color, fogParams.density);
 
-// Stats
+/**
+ * @description Performance statistics panel.
+ * @type {Stats}
+ */
 const stats = new Stats();
 stats.showPanel(0);
 document.body.appendChild(stats.dom);
 
-// Animation loop
+/**
+ * @description The main animation loop.
+ */
 function animate() {
   requestAnimationFrame(animate);
   stats.begin();
@@ -225,7 +276,9 @@ function animate() {
 
 animate();
 
-// Handle resize
+/**
+ * @description Handles window resize events.
+ */
 window.addEventListener("resize", () => {
   camera.aspect = window.innerWidth / window.innerHeight;
   camera.updateProjectionMatrix();

src/core/components/cameras/CinematicCamera.js

@@ -1,6 +1,31 @@
+/**
+ * @file Extends the Three.js CinematicCamera with additional features and a simplified constructor.
+ * @module CinematicCamera
+ */
+
 import { CinematicCamera as ThreeCinematicCamera } from 'three/examples/jsm/cameras/CinematicCamera';
 
+/**
+ * @class CinematicCamera
+ * @description A custom cinematic camera that extends Three.js's CinematicCamera to provide
+ * simplified setup for position, target, and depth of field.
+ * @extends {ThreeCinematicCamera}
+ */
 export class CinematicCamera extends ThreeCinematicCamera {
+    /**
+     * @constructor
+     * @param {object} [params={}] - The parameters for the camera.
+     * @param {number} [params.fov=75] - The camera's field of view.
+     * @param {number} [params.aspect=window.innerWidth / window.innerHeight] - The camera's aspect ratio.
+     * @param {number} [params.near=0.1] - The near clipping plane.
+     * @param {number} [params.far=1000] - The far clipping plane.
+     * @param {object} [params.position={x: 0, y: 2, z: 10}] - The camera's position.
+     * @param {object} [params.target={x: 0, y: 0, z: 0}] - The point the camera is looking at.
+     * @param {object} [params.dof] - The depth of field parameters.
+     * @param {string|number} [params.dof.focus='center'] - The focus distance. 'center' sets focus to the camera's distance from origin.
+     * @param {number} [params.dof.aperture=0.1] - The camera's aperture size.
+     * @param {boolean} [params.dof.required=true] - Indicates if DOF is required.
+     */
     constructor(params = {}) {
         const {
             fov = 75,
@@ -35,6 +60,9 @@ export class CinematicCamera extends ThreeCinematicCamera {
             dof.focus;
         this.postprocessing.bokeh.aperture = dof.aperture;
 
+        /**
+         * @property {object} debugObject - An object holding the camera's parameters for debugging purposes.
+         */
         this.debugObject = {
             position,
             target,
@@ -45,6 +73,11 @@ export class CinematicCamera extends ThreeCinematicCamera {
         };
     }
 
+    /**
+     * @method updateFromDebug
+     * @description Updates the camera's properties from the `debugObject`. This is useful for
+     * dynamically updating the camera from a GUI or other debug tools.
+     */
     updateFromDebug() {
         // Update position
         this.position.set(

src/core/components/encoders/basis/BasisConfig.js

@@ -1,3 +1,13 @@
+/**
+ * @file This file contains the configuration for the Basis Universal texture encoder.
+ * It includes default settings, quality presets, and a validation function.
+ * @module BasisConfig
+ */
+
+/**
+ * @description Configuration object for the Basis Universal texture encoder.
+ * Contains default settings, quality presets, and a validation function.
+ */
 export const BasisConfig = {
     defaults: {
         transcoderPath: '/basis/',
@@ -42,6 +52,14 @@ export const BasisConfig = {
         }
     },
 
+    /**
+     * Validates the given configuration object, ensuring values are within valid ranges.
+     *
+     * @param {object} config - The configuration object to validate.
+     * @param {number} config.quality - The quality level to validate.
+     * @param {string} config.format - The format to validate.
+     * @returns {{quality: number, format: string}} A new object with the validated properties.
+     */
     validate(config) {
         return {
             quality: Math.max(1, Math.min(255, config.quality)),

src/core/components/encoders/basis/BasisEncoder.js

@@ -1,21 +1,59 @@
+/**
+ * @file Defines the BasisEncoder class for handling Basis Universal texture encoding settings.
+ * @module BasisEncoder
+ */
+
+/**
+ * @class BasisEncoder
+ * @description Manages settings for Basis Universal texture encoding.
+ */
 export class BasisEncoder {
+  /**
+   * @constructor
+   * @description Initializes the BasisEncoder with default settings.
+   */
   constructor() {
+    /**
+     * @property {string} type - The type of the encoder.
+     */
     this.type = "basis";
+    /**
+     * @property {boolean} isCustomEncoder - Flag indicating this is a custom encoder.
+     */
     this.isCustomEncoder = true;
+    /**
+     * @property {string} transcoderPath - The path to the Basis transcoder files.
+     */
     this.transcoderPath = "/basis/";
 
+    /**
+     * @property {object} debugObject - An object holding the encoder's settings for debugging.
+     * @property {string} debugObject.transcoderPath - The path to the transcoder.
+     * @property {string} debugObject.format - The texture format.
+     * @property {number} debugObject.quality - The encoding quality.
+     */
     this.debugObject = {
       transcoderPath: this.transcoderPath,
       format: "auto",
       quality: 128,
     };
   }
 
+  /**
+   * @method setTranscoderPath
+   * @description Sets the path to the Basis transcoder files.
+   * @param {string} path - The new path to the transcoder.
+   */
   setTranscoderPath(path) {
     this.transcoderPath = path;
     this.debugObject.transcoderPath = path;
   }
 
+  /**
+   * @method updateSettings
+   * @description Updates the encoder's settings from a given object.
+   * @param {object} settings - An object containing settings to update.
+   */
   updateSettings(settings) {
     Object.assign(this.debugObject, settings);
   }