lib-3d-scene-viewer

lib-3d-scene-viewer is a package based on Babylon.js. It provides preset configurations for quickly setting up a 3D scene viewer, which offers a 3D environment similar to the "View in 3D" CX on Amazon Product Detail Pages.

Table of Contents

• Getting Started
  • Installation
  • Usage
  • Resource
  • Config
• Sandbox
• Documentation
• Development
• Contributing
• License

Getting Started

Installation

The package can be installed from npm:

npm install @amazon/lib-3d-scene-viewer
Copy

Usage

Take a look at an example

import { Config } from '@amazon/lib-3d-scene-viewer/config/config';
import { Model } from '@amazon/lib-3d-scene-viewer/model/model';
import { Scene } from '@babylonjs/core/scene';
import { V3D_CONFIG } from '@amazon/lib-3d-scene-viewer/config/preset/v3dConfig';
import { V3DScene } from '@amazon/lib-3d-scene-viewer/scene/v3dScene';

(async function () {
    /////////////////////////////////////////
    // Step 0: create a canvas DOM element //
    /////////////////////////////////////////
    
    const canvas = document.createElement('canvas');
    document.body.appendChild(canvas);

    ////////////////////////////////////////////
    // Step 1: create an instance of V3DScene //
    ////////////////////////////////////////////
    
    // V3D_CONFIG is a preset config
    const v3dScene = new V3DScene(canvas, V3D_CONFIG, {
        // Override file paths if needed
        lightingConfig: {
            DirectionalBlur: {
                type: 'env',
                filePath: 'public/ibl/Directional_colorVariationOnTopBlur100_512.env',
            },
        },
        basisTranscoder: {
            urlConfig: {
                jsModuleUrl: 'public/js/basis/basis_transcoder.js',
                wasmModuleUrl: 'public/js/basis/basis_transcoder.wasm',
            },
        },
        ktx2Decoder: {
            urlConfig: {
                jsDecoderModule: 'public/js/ktx2/babylon.ktx2Decoder.js',
                jsMSCTranscoder: 'public/js/ktx2/msc_basis_transcoder.js',
                wasmMSCTranscoder: 'public/js/ktx2/msc_basis_transcoder.wasm',
                wasmUASTCToASTC: 'public/js/ktx2/uastc_astc.wasm',
                wasmUASTCToBC7: 'public/js/ktx2/uastc_bc7.wasm',
                wasmUASTCToR8_UNORM: null,
                wasmUASTCToRG8_UNORM: null,
                wasmUASTCToRGBA_SRGB: 'public/js/ktx2/uastc_rgba8_srgb_v2.wasm',
                wasmUASTCToRGBA_UNORM: 'public/js/ktx2/uastc_rgba8_unorm_v2.wasm',
                wasmZSTDDecoder: 'public/js/ktx2/zstddec.wasm',
            },
        },
        dracoCompression: {
            decoders: {
                wasmBinaryUrl: 'public/js/draco/draco_decoder_gltf.wasm',
                wasmUrl: 'public/js/draco/draco_decoder_gltf_nodejs.js',
                fallbackUrl: 'public/js/draco/draco_decoder_gltf.js',
            },
        },
        meshoptCompression: {
            decoder: {
                url: 'public/js/meshopt/meshopt_decoder.js',
            },
        },
        enableDragAndDrop: true,
    });

    /////////////////////////////////////////////////////////////////////
    // Step 2: register any observers using V3DScene.observableManager //
    /////////////////////////////////////////////////////////////////////
    
    v3dScene.observableManager.onConfigChangedObservable.add((config: Config) => {
        console.log('Updated config:', config);
    });

    v3dScene.observableManager.onModelLoadedObservable.add((model) => {
        model.showShadowOnGroundDepthMap();
        model.moveCenterToTargetCoordinate();

        const radius = 2 * Math.max(...model.getOverallBoundingBoxDimensions().asArray());
        v3dScene.updateConfig({
            cameraConfig: {
                ArcRotateCamera: {
                    type: 'arcRotateCamera',
                    radius: radius,
                    lowerRadiusLimit: radius * 0.05,
                    upperRadiusLimit: radius * 5,
                    minZ: radius * 0.02,
                    maxZ: radius * 40,
                },
            },
        });
    });
    
    //////////////////////////////////
    // Step 3: call init() function //
    //////////////////////////////////
    
    await v3dScene.init();

    /////////////////////////////////
    // Step 4: load glTF/glb model //
    /////////////////////////////////
    
    const model: Model = await v3dScene.loadGltf('public/model/mannequin.glb', true);
    console.log('Bounding box dimensions:', model.getOverallBoundingBoxDimensions());

    //////////////////////////////////////////////////////////////////////////////////////////////////
    // Step 5 (Optional): call updateConfig() to update scene setup and/or handle user interactions //
    //////////////////////////////////////////////////////////////////////////////////////////////////
    
    await v3dScene.updateConfig({
        sceneConfig: {
            useLoadingUI: true,
        },
    });

    // Access BabylonJS scene object
    const babylonScene: Scene = v3dScene.scene;
    console.log('Active Cameras:', babylonScene.activeCameras);

    // Toggle BabylonJS debug layer
    document.addEventListener('keydown', async (event) => {
        const key = event.key;
        // Pressing '?' should show/hide the debug layer
        if (key === '?') {
            // Needed for BabylonJS debug layer
            import('@babylonjs/inspector').then(() => {
                v3dScene.toggleDebugMode();
            });
        }
    });
})();
Copy

Resource

This package provides a few resources including IBL files, decoder/transcoder files, and 3D models. These resources can be found in public folder or @amazon/lib-3d-scene-viewer/public via npm.

Config

This packages uses Config to set up engine, scene, camera, lighting, decoder files, etc.

The full config parameters and default values can be found in Config.

It also provides preset config files in preset folder or @amazon/lib-3d-scene-viewer/config/preset.

Sandbox

Try loading GLB/GLTF models into the Sandbox.

Documentation

• API Docs

Development

When developing the project, first install git, Node.js and npm.

Then, follow the steps to set up the development environment:

git clone git@github.com:amzn/lib-3d-scene-viewer.git
cd lib-3d-scene-viewer
npm install
Copy

The following scripts are available:

Command	Description
npm install	Install dependencies
npm run build	Run the build step for all sub-projects
npm run clean	Remove all built artifacts
npm run docs	Create API documentation
npm run lint	Run ESLint
npm run pack:dist	Build the project and create an npm tarball under dist folder
npm run publish:dist	Publish the npm tarball
npm run server	Run a web server and open a new browser tab pointed to src/dev/index.ts
npm run test	Run tests
npm run update-bjs-ver	Update BabylonJS dependencies to a specific version
npm run webpack	Generate static web resources for sandbox and API docs

Contributing

For more information take a look at CONTRIBUTING.md.

License

This library is licensed under the Apache 2.0 License.