3d viewer control with custom JS

If you need more functionality than the 3d viewer control provides out of the box in the configurator editor, you can use custom JS to extend it by adding custom parameter observers, adjusting the auto generated spec and much more.

Basic setup & usage

• Set the 3d viewer control's viewer version property to Injected
• Install the viewer in your custom JS code with npm i @combeenation/3d-viewer
• Use the viewer control's injectViewer method to pass the viewer to the control:

  import { Viewer } from '@combeenation/3d-viewer';
  // ...
  CfgrUtils.onCfgrReady(() => {
    // ...
    CtrlUtils.getViewerCtrl('viewer3d').injectViewer(Viewer);
    // ...
  });
  

• Use the viewer control's getViewer to get access to the viewer instance, the Babylon.js scene etc.:

  const viewerCtrl = CtrlUtils.getViewerCtrl('viewer3d');
  const viewer = await viewerCtrl.getViewer();
  
  // E.g. create custom skybox from JPGs
  const scene = viewer.scene;
  const customReflection = new CubeTexture('', scene, null, null, files);
  const customSkybox = scene.createDefaultSkybox(customReflection, true, 10000);
  

Common use cases

When extending the viewer control's capabilities in custom JS, there are almost no limits in what you can do. If you want to, you can have direct access to the underlying Combeenation 3d viewer & Babylon.js core which power the viewer control.

Please refer to the Viewer & Babylon.js docs for details on what is possible and how to achieve it.

In the following chapters we'll explore some common use cases and explain how to best deal with them.

Add custom parameter observer

The viewer comes with some built in parameters which you can use with the control's set parameter values slot but you can also add your own, custom parameters using custom JS.

These observers should be added before the viewer is bootstrapped which makes the callback of the viewer control's onBeforeBootstrap function the perfect place to do so.

This example shows, how to add a custom parameter named ShowBoundingBox with which you can show or hide a meshs bounding box:

CtrlUtils.getViewerCtrl('viewer3d').onBeforeBootstrap((viewer, initialParams) => {
  viewer.tagManager.setParameterObserver('ShowBoundingBox', async ({ nodes, newValue }) => {
    nodes
      .filter(node => node instanceof AbstractMesh)
      .forEach(node => node.showBoundingBox = newValue)
    
    return true;
  });
});

You can set & change the value of all custom parameters with the control's set parameter values slot like with all built in parameters.

See the tag managers section about custom parameters to get more information about how to define them in custom JS.

Adjust the auto generated spec

The viewer control automatically creates a viewer instance with an auto generated spec which comes with a set of default values. You can customize this spec before the viewer instance is created in the callback of the viewer control's onAfterSpecCreated function.

The following example shows how to adjust some default engine options & add a named placement which can be used as a target for camera movements etc.:

CtrlUtils.getViewerCtrl('viewer3d').onAfterSpecCreated(spec => {
  spec.scene.engine.options.useHighPrecisionMatrix = true;
  spec.scene.placements = {
    insideCar: {
      position: '(a, b, c)',
      target: '(x, y, z)',
    }
  }
});