Version: 1.0.0

Structure

This document describes the folder structure and main files of the 3D AR Viewer, focusing on core components for rendering and material management.

Overview

The project structure is organized in a modular way to separate responsibilities between rendering, material management, and user interface.

src/
├── components/
│   └── ModelViewer/
│       └── ThreeJSViewer/
│           ├── ARButton.js
│           ├── ARScene.js
│           ├── ErrorScreen.js
│           ├── LoadingScreen.js
│           ├── MaterialController.js
│           ├── Model.js
│           ├── Scene.js
│           └── ThreeJSViewer.js
├── pages/
│   ├── ARShades3dsViewer.js
│   ├── ARShades3dViewer.js
│   ├── ARShadesDemo/
│   ├── MaterialPresets.js
│   └── Renderer.js
└── services/
    └── api/
        └── materialPresetsApi.js

Quick Navigation:

Core Components: ThreeJSViewer.js | Scene.js | Model.js | MaterialController.js | ARScene.js | ARButton.js | LoadingScreen.js | ErrorScreen.js
Pages: ARShades3dsViewer.js | ARShades3dViewer.js | ARShadesDemo/ | MaterialPresets.js | Renderer.js
Services: materialPresetsApi.js

Core Components

`components/ModelViewer/ThreeJSViewer/`

This folder contains all the main components for Three.js-based 3D rendering:

ThreeJSViewer.js

Main orchestrator component that manages the entire 3D/AR viewing experience
Asynchronous model loading with browser cache support and loading progress tracking
Dual rendering modes: Standard 3D viewing and WebXR Augmented Reality
Post-processing pipeline with EffectComposer for high-quality rendering (bloom, gamma correction, SMAA antialiasing)
High-resolution screenshot rendering with customizable camera positions and FOV
Animation system for interactive model demonstrations (expand, apply clip-ons, change lenses)
Responsive design with mobile/desktop-specific FOV and layout adjustments
Validation mode for neutral scene settings vs. project-specific configurations
Material preset integration with Redux state management
WebGL capabilities detection and optimization for different devices

Scene.js

Scene orchestration with React Three Fiber Stage component using 'rembrandt' lighting preset
Responsive camera controls with OrbitControls (zoom limits, auto-rotate on mobile, pan disabled)
Advanced environment lighting supporting both HDRI files and preset environments ('apartment' fallback)
Dynamic shadow system with configurable intensity, smoothness, and contact shadow type
Optional reflective floor plane with physically-based MeshReflectorMaterial (blur, depth-based reflections, distortion)
Fog effects integrated with reflective surfaces for enhanced realism
Mobile-responsive FOV adjustments that automatically update camera projection on window resize
Performance monitoring integration (Perf component) for debugging and optimization

Model.js

Advanced GLTF/GLB model loading with comprehensive error handling and resource management
Sophisticated material system with original material preservation and dynamic preset application
Multi-layer material maps: Original, preset-applied, and runtime-adjusted material caching
Specialized material types: Transmissive lenses (non-PBR to PBR conversion), metallic frame adjustments, subsurface scattering shaders
Custom blending modes and shader management for realistic glass and metal rendering
Interactive animation system with forward/reverse playback, loop control, and frame-precise timing
Automatic feedback animation with gentle Y-axis rotation to encourage user interaction (disables on touch)
Bounding box calculation and model geometry analysis for camera positioning and lighting
Memory management system with comprehensive disposal of geometries, materials, textures, and skeletal data
Redux integration for global material state management and real-time material property updates
AR-specific optimizations: Shadow casting, frustum culling adjustments for skinned meshes
Debug mode integration with live material controllers and visual bounding box helpers

MaterialController.js

Live debugging interface using Leva controls for real-time material property adjustment
Multi-material type support: Standard materials, PBR physical materials, and custom subsurface scattering shaders
Comprehensive PBR controls: Transmission, thickness, IOR, clearcoat, dispersion, iridescence, anisotropy, attenuation, sheen properties
Advanced blending management: Complete Three.js blending modes (Normal, Additive, Subtractive, Multiply, Custom) with source/destination factors
Depth testing controls: All depth function options (Never, Always, Equal, Less, Greater, etc.) with depth test/write toggles
Geometry rendering options: Front/back/double-side rendering control
Color and emission controls: Real-time color picker integration with emissive intensity adjustment
Subsurface scattering debugging: Custom shader uniform controls (distortion, ambient, attenuation, power, scale, thickness color)
Redux state synchronization: Automatic updates to global material configuration state for persistence

ARScene.js

Complete WebXR AR implementation with session management, reference spaces, and hit testing
Advanced surface placement system using WebXR hit test API for real-world model positioning
Sophisticated multi-touch interaction system: Single finger dragging, dual finger scaling and rotation with dead zones
Intelligent scaling system with visual/haptic feedback, scale limits (0.5x-6x), tolerance zones, and temporary freeze mechanism
Dynamic lighting setup for AR environments with ambient light and directional shadow casting
Visual feedback system: Interactive reticle with color changes (red for limits, green for perfect scale), haptic vibration
Shadow plane management that dynamically follows model position for realistic ground shadows
UI interaction prevention to avoid conflicts between AR gestures and interface elements
State management system for model visibility, placement status, dragging, scaling freeze, and interaction states
Comprehensive cleanup handling for AR session lifecycle management and resource disposal
Real-time raycasting for precise model positioning on detected surfaces
Gesture recognition system with angle and distance calculations for natural rotation and scaling

ARButton.js

Cross-platform AR launcher with intelligent platform detection (Android, iOS, desktop, WebView)
Multi-AR system support: WebXR for compatible browsers, Scene Viewer for Android, Quick Look for iOS (.usdz)
Adaptive UI system: Different button layouts and behaviors for mobile/desktop, WebView detection, and iOS-specific handling
QR code modal integration for desktop users to transfer AR experience to mobile devices
Comprehensive fallback system: Graceful degradation from WebXR to native AR platforms with error handling
Session lifecycle management with proper cleanup, state tracking, and event handling for AR session start/end
Redux-driven customization: Dynamic AR icon, QR code colors, and layout positioning based on project configuration
Intent-based Android integration with Scene Viewer deep linking and browser fallback URL support
iOS Quick Look integration using rel="ar" anchor tags for native .usdz model viewing
WebView compatibility layer with specialized UI and functionality for in-app browser environments

LoadingScreen.js

Progress-aware loading overlay that displays during model download and initialization
Dual spinner design combining custom CSS animation with Ant Design Spin component
Smart visibility control that automatically hides when loading reaches 100% or completion
Non-blocking UI that overlays the canvas while maintaining responsive design
Simple and clean UX focused on providing visual feedback without cluttering the interface

ErrorScreen.js

Centered error overlay that displays when model loading or rendering fails
Dynamic error messaging showing specific error details for debugging and user feedback
Inline styled component with red error coloring and responsive center positioning
User-friendly error presentation with clear typography and adequate padding for readability
Absolute positioning system that overlays the main canvas without disrupting layout

Services

services/api/materialPresetsApi.js

Comprehensive Firebase/Firestore CRUD service for material preset management with full async/await support
Batch preset loading using Promise.all for efficient parallel fetching of multiple material presets
Intelligent upsert operations with name-based duplicate detection and merge functionality for preset updates
Robust error handling with comprehensive try-catch blocks, warning logs, and graceful degradation for missing presets
Map-based data transformation converting Firestore documents to JavaScript Maps for optimized material-to-preset lookups
Variant-specific preset management linking material presets to specific model variants with bidirectional synchronization
Efficient querying system using Firestore compound queries and filtering to minimize data transfer
Null safety and validation with filtering of invalid presets and comprehensive data existence checks
Performance optimized operations designed for real-time material editing workflows with minimal latency

Material Management

The material management system is a sophisticated multi-layer architecture designed to handle complex 3D material workflows:

Multi-Layer Material Architecture

Original Materials Map: Preserves untouched base materials for restoration and comparison
Adjusted Materials Map: Runtime modifications for metallic emission reduction and transmissive blending optimization
Preset Materials Map: Applied configurations from Firebase-stored presets with custom properties
Live Configuration State: Real-time Redux-managed material properties for debugging and editing

Material Optimizations According to the Type

Metallic Materials (MT_): Materials with emission intensity normalization and reflective properties
Transmissive Materials (TR_): Advanced transparency with custom blending modes and dual-layer opacity
Lens Materials (LN_): Automatic PBR conversion from non-PBR with IOR, transmission, and thickness properties
Subsurface Scattering Materials (_SSS): Custom shader materials with thickness maps and scattering parameters

Advanced Material Features

Custom Blending Systems: Support for CustomBlending, OneFactor, SrcAlphaFactor configurations
PBR Property Management: Transmission, thickness, IOR, clearcoat, dispersion, iridescence, anisotropy
Sheen Color Scaling: Production-ready normalization for GLB export with accurate color representation
Material Nomenclature Handling: Automatic mapping between MDV/3DV/VTO naming conventions for different model versions

Preset and Export System

Firebase Integration: Cloud-based preset storage with name-based duplicate detection and merge operations
Live Debugging Interface: Leva-powered real-time material editing with immediate visual feedback
Production Export Pipeline: Deep cloning with animation preservation and material normalization for GLB export
Batch Processing: Efficient parallel loading and application of multiple material presets

AR Support

The AR system provides enterprise-grade Augmented Reality capabilities with sophisticated interaction and cross-platform compatibility:

WebXR Implementation

Complete WebXR Session Management: Full lifecycle handling with reference spaces, hit testing, and session cleanup
Advanced Hit Testing: Real-time surface detection using WebXR hit test API for precise model placement
DOM Overlay Integration: UI elements overlay support for seamless AR/UI interaction without session interruption
Session State Management: Comprehensive handling of session start, end, and error states with automatic recovery

Multi-Touch Interaction System

Single Finger Dragging: Raycasting-based model positioning on detected horizontal planes
Dual Finger Scaling: Advanced pinch-to-scale with dead zones, tolerance checking, and scale limits (0.5x-6x)
Rotation Gestures: Natural two-finger rotation on horizontal plane with angle calculation and smooth interpolation
Gesture Recognition: Smart detection between dragging, scaling, and rotation with conflict prevention

Visual and Haptic Feedback

Interactive Reticle System: Dynamic placement indicator with color feedback (red for limits, green for perfect scale)
Haptic Vibration: Native device vibration for scale limit feedback and interaction confirmation
Real-time Scale Display: Live percentage display during scaling gestures with automatic hide/show
Visual State Indicators: Model visibility management and placement status feedback

Cross-Platform Architecture

WebXR Primary: Modern browser support with full feature set for compatible devices
Android Scene Viewer: Intent-based fallback with GLB model support and browser fallback URLs
iOS Quick Look: Native .usdz integration using rel="ar" anchor tags for seamless iOS experience
Intelligent Platform Detection: Automatic device and browser capability detection with graceful degradation

Advanced AR Features

Dynamic Shadow Plane: Real-time shadow casting that follows model position for realistic ground shadows
Camera Choreography: Synchronized lighting adjustments with directional light positioning for optimal model illumination
Gesture State Management: Sophisticated state tracking preventing UI conflicts and gesture overlap
Memory and Performance Optimization: Efficient model placement, interaction handling, and resource cleanup

Session Lifecycle Management

Automatic Session Recovery: Error handling and session restoration for interrupted AR experiences
UI Interaction Prevention: Smart detection to avoid AR gesture conflicts with interface elements
State Persistence: Model position, scale, and rotation preservation across AR session lifecycle
Performance Monitoring: Frame rate optimization and interaction responsiveness management

Overview​

Core Components​

components/ModelViewer/ThreeJSViewer/​

ThreeJSViewer.js​

Scene.js​

Model.js​

MaterialController.js​

ARScene.js​

ARButton.js​

LoadingScreen.js​

ErrorScreen.js​

Pages​

ARShades3dsViewer.js​

ARShades3dViewer.js​

ARShadesDemo.js​

MaterialPresets.js​

Renderer.js​

Services​

services/api/materialPresetsApi.js​

Material Management​

Multi-Layer Material Architecture​

Material Optimizations According to the Type​

Advanced Material Features​

Preset and Export System​

AR Support​

WebXR Implementation​

Multi-Touch Interaction System​

Visual and Haptic Feedback​

Cross-Platform Architecture​

Advanced AR Features​

Session Lifecycle Management​