Version: 1.0.0

Structure

Author: Gabriele Gilio Creation Date: 19/08/2025
Last Reviewer: Gabriele Gilio Last Updated: 26/09/2025

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/
│   ├── LocalRenderer/
│   │   ├── Steps/
│   │   │   ├── ConfigurationStep.js
│   │   │   ├── OutputStep.js
│   │   │   └── ProcessingStep.js
│   │   └── LocalRenderStepper.js
│   ├── ModelViewer/
│   │   └── ThreeJSViewer/
│   │       ├── ARButton.js
│   │       ├── ARScene.js
│   │       ├── ErrorScreen.js
│   │       ├── LoadingScreen.js
│   │       ├── MaterialController.js
│   │       ├── Model.js
│   │       ├── Scene.js
│   │       └── ThreeJSViewer.js
│   └── ThumbnailGenerator/
│       ├── ThumbnailGenerationModal.js
│       └── ThumbnailGenerator.js
├── pages/
│   ├── ARShades3dsViewer.js
│   ├── ARShades3dViewer.js
│   ├── ARShadesDemo.js
│   ├── MaterialPresets.js
│   └── Renderer.js
└── services/
    └── api/
        ├── localRenderApi.js
        ├── materialPresetsApi.js
        └── variantDetails.js

Quick Navigation:

Core Components: ThreeJSViewer.js | Scene.js | Model.js | MaterialController.js | ARScene.js | ARButton.js | LoadingScreen.js | ErrorScreen.js | LocalRenderStepper.js | ConfigurationStep.js | ProcessingStep.js | OutputStep.js | ThumbnailGenerator.js | ThumbnailGenerationModal.js
Pages: ARShades3dsViewer.js | ARShades3dViewer.js | ARShadesDemo.js | MaterialPresets.js | Renderer.js
Services: localRenderApi.js | variantDetails.js | 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
Imperative API exposing onRender, getScene, and getCameraSettings for external control and capture
Adaptive quality pipeline: Supersampling Anti-Aliasing (SSAA) with auto downscale on very large images; Multisample Anti-Aliasing (MSAA) when WebGL2 is available with Subpixel Morphological Anti-Aliasing (SMAA) fallback
Per-render scene overrides with safe restore: reflect, noShadows, lightExposition, background/backgroundColor
Animation system for interactive model demonstrations (expand, apply clip-ons, change lenses, and other animations)
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
AR UX refinements: conditional AR button, in-AR exit control, and live scale percentage overlay
Scene readiness flag toggled via window.isSceneReady during render preparation

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
Renderer-aware controls enabling pan and extended zoom range when running in renderer mode
Conditional background sets solid color via R3F color when no background image is present
Environment intensity driven by scene light exposition (with safety offset) and HDR preset rotation
Ground planes: shadow plane always under model plus optional reflector positioned using modelMinY; visibility toggled by reflect

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

`components/ThumbnailGenerator/`

ThumbnailGenerator.js

Headless thumbnail generator that uses ThreeJSViewer off-screen to create thumbnails
Readiness gate waits for model load (cache or network) before generating
Programmatic API exposes generateThumbnails and isReady via ref; reports progress upstream
Optimized hidden canvas minimizes layout/paint cost while rendering at fixed size

ThumbnailGenerationModal.js

Progress modal showing current step out of total with spinner and title
Non-dismissible flow while processing (no close, keyboard or mask close) to avoid interruptions
Visual progress bar with percentage and optional current view/template name

`components/LocalRenderer/`

This folder contains the multi-step UI and logic for local, template-driven screenshot rendering.

LocalRenderStepper.js

Modal stepper orchestrator that manages Configuration → Processing → Output for local renders
Rendering session management in Firebase/Firestore via createRenderingSession, getRenderingSession, and updateRenderingSession
Redux integration reading modelGlasses by variantId to determine mainVariantRef and catalogProductRef
Viewer integration with ThreeJSViewer through viewerRef; actual rendering is delegated to ProcessingStep
Bandwidth estimation calculated once per model by fetching urlGlobalComplete (cached with a default fallback)
Success callback: triggers onSuccess after at least one successful render to let parents refresh UI
UI built with Ant Design Steps, Button, and a custom StepperModal
Related files: Steps/ConfigurationStep.js, Steps/ProcessingStep.js, Steps/OutputStep.js, Components/Modals/StepperModal.js, services/api/localRenderApi.js, data/utils.js

Steps/ConfigurationStep.js

Render setup step providing two modes: preconfigured Templates loading from Firebase or Manual Positioning via ThreeJSViewer
Template workflow: fetches templates by userEmail, supports multi-select, and builds configuration payload
Manual workflow: lets users compose a custom camera template (FOV, position, lighting, background); can be stored to Firebase
Output settings: centralizes image quality/format to compute width/height and warns about templates requiring square format
State handoff: emits a compact configuration object to the stepper for subsequent processing

Steps/ProcessingStep.js

Render execution step that drives per-template rendering via ThreeJSViewer.onRender
Filename generation with timestamp and UUID for consistent asset naming
Per-template scene options: camera pose/FOV, reflect/shadows, light exposition, background/color
Square override for specific templates (e.g., R01/R04/R05) to enforce visibility-friendly aspect
Automatic persistence: uploads successful renders to Firebase with saveRenderToFirebase and aggregates stats
User feedback: progress UI and success/warning/error messages; returns summarized results to the stepper

Steps/OutputStep.js

Results display summarizing successful and failed renders with previews
Download actions for single images and a simple bulk download flow (per-file; zip for future implementation)
Status reporting showing totals and cloud save statistics from the processing step
Retry flow allowing users to start a new render session via reset

Services

services/api/localRenderApi.js

Local render templates and sessions service for Firebase Firestore and Storage
Template operations: loadTemplates (filters custom by userEmail), fetchTemplate, saveCustomTemplateToFirebase
Render persistence: saveRenderToFirebase uploads PNG to Storage (catalogue vs. library path by isFrameValidation), updates variant thumbnails and fills template imgUrl if missing
Batch thumbnails: saveThumbnailsBatch uploads in parallel and updates Firestore in a single transaction
Sessions: createRenderingSession, updateRenderingSession, getRenderingSession on Session_Renderings
Helper: dataURLtoBlob for client-side image conversion

services/api/variantDetails.js

Thumbnail generation utilities for local and remote workflows
Local flow: generateThumbnailsLocal renders a curated set of templates sequentially via ThreeJSViewer.onRender, then performs a single batch upload with saveThumbnailsBatch
Template sourcing: pulls per-template configuration with fetchTemplate and applies scene params consistently
Naming standardization: shared filename pattern with timestamp and UUID for stable asset names
Remote flow: generateThumbnails posts to a server endpoint defined by REACT_APP_GENERATION_THUMBNAILS

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

Local Rendering

The local rendering system provides a template-driven and manual camera flow for high-quality screenshots and thumbnails.

Workflow

Stepper orchestration: Modal flow across Configuration → Processing → Output
Templates vs Manual: Load templates from Firebase (per-user custom included) or create a manual camera template via ThreeJSViewer
Dimensions and guidance: Output size derived from quality/format; square-format guidance for specific templates (R01, R04, R05)
Per-template rendering: Sequential capture with timestamp/UUID filenames and progress feedback

Rendering Pipeline

Imperative capture via ThreeJSViewer.onRender with per-render scene overrides (reflect, noShadows, background, backgroundColor, lightExposition) and safe state restore
Adaptive quality: SSAA with auto downscale for very large images; MSAA on WebGL2 with SMAA fallback
Reflector preparation: Pre-renders to stabilize reflections; scene readiness toggled with window.isSceneReady

Persistence and Analytics

Auto-save to Firebase: PNGs uploaded to Storage; Firestore updated (list_user_thumbnails or list_thumbnails as appropriate)
Session tracking: Session_Renderings documents with started/pending/completed/failed status and timestamps per render
Bandwidth estimation: One-time fetch-based size estimation per model for consumption metrics
Batch uploads: Thumbnails can be saved in bulk via a single transaction

UX and Limitations

User feedback: Processing spinners, result previews, per-file downloads, and success/error messaging
Bulk download: Zip packaging planned for future iterations

Overview​

Core Components​

components/ModelViewer/ThreeJSViewer/​

ThreeJSViewer.js​

Scene.js​

Model.js​

MaterialController.js​

ARScene.js​

ARButton.js​

LoadingScreen.js​

ErrorScreen.js​

components/ThumbnailGenerator/​

ThumbnailGenerator.js​

ThumbnailGenerationModal.js​

components/LocalRenderer/​

LocalRenderStepper.js​

Steps/ConfigurationStep.js​

Steps/ProcessingStep.js​

Steps/OutputStep.js​

Pages​

ARShades3dsViewer.js​

ARShades3dViewer.js​

ARShadesDemo.js​

MaterialPresets.js​

Renderer.js​

Services​

services/api/localRenderApi.js​

services/api/variantDetails.js​

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​

Local Rendering​

Workflow​

Rendering Pipeline​

Persistence and Analytics​

UX and Limitations​