• Version 1.2.0 Details
  • Update to latest Babylon.js version 4.2.0
    • Update path
  • Simplifications for type imports
    • Example code
    • Update path
  • Automatic conversion of colors to linear space
  • Spec driven camera positioning and animation API
    • Example code
    • How to define animations ease function

Version 1.2.0 Details

List of all changes

Update to latest Babylon.js version 4.2.0

The internally used version of the Babylon.js library has been updated from 4.1.0 to the latest stable version 4.2.0.

See Babylon.js release notes for detailed description of what this update changes under the hood.

Ensure to update all your project dependencies to this version to prevent bundling of different versions in your project output!

Update path

You can check & update the versions used by your project with the following steps:

• Open the file package.json within your project
• Look for dependencies with "babylon" in their name
• If you can't find any -> Nothing to do
• If you find such dependencies with version != 4.2.0 please update them:
  • Change the version of all Babylon.js dependencies from 4.1.0 to 4.2.0.
    Don't use any prefixes like ~, ^ etc. for the version number but only write 4.2.0.
    Your dependencies should look something like this: "@babylonjs/core": "4.2.0".
  • Open a command line and navigate to your project (where you usually run npm run watch)
  • Run npm i to update all dependencies to the new versions from your package.json

Simplifications for type imports

Type exports of the viewer have been adjusted for easier use which results in the following improvements for your code:

• All viewer types like Viewer, StructureJson etc. are exported by the viewers index file:
  👍 You can pull all types from 1 file instead of having multiple import statements with complex paths
• All viewer types are exported as "globals":
  👍 You don't have to import from complex paths when using types in JSDoc annotations
• The viewer exports many frequently used Babylon.js types from its own index file:
  👍 Most projects won't have to pull in Babylon.js as a dedicated dependency anymore

Example code

Before:

import { Viewer } from '@combeenation/3d-viewer';
import { VariantInstance } from '@combeenation/3d-viewer/api/classes/variantInstance';
import { Mesh } from '@babylonjs/core/Meshes/mesh';
import { Vector3 } from '@babylonjs/core/Maths/math.vector';
import { Color4 } from '@babylonjs/core/Maths/math.color';
import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';

/**
 * @return {import('@combeenation/3d-viewer/dist/lib-cjs/api/util/typeExports').StructureJson}
 */
export function createSpec() {
  /* ... */
}

Now:

import { ViewerVariantInstance, Mesh, Vector3, Color4, ArcRotateCamera } from '@combeenation/3d-viewer';

/**
 * @return {StructureJson}
 */
export function createSpec() {
  /* ... */
}

Update path

• Simplify imports of 3d viewer types:

  • Search for all occurrences of from '@combeenation/3d-viewer/
  • Simplify path to from '@combeenation/3d-viewer':

    // E.g. change
    import { VariantInstance } from '@combeenation/3d-viewer/api/classes/variantInstance';
    // to
    import { VariantInstance } from '@combeenation/3d-viewer';
    

  • Combine all imports from '@combeenation/3d-viewer' to 1 statement

• Simplify types in JSDoc annotations:

  • Search for all occurrences of import('@combeenation in JSDoc annotations
  • Remove the complete part with the import:

    // E.g. change
    @return {import('@combeenation/3d-viewer/dist/libcjs/api/util/typeExports').StructureJson}
    // to
    @return {StructureJson}
    

• Use Babylon.js type imports from viewer:

  • Search for all occurrences of from '@babylonjs
  • Change the import path to @combeenation/3d-viewer
  • Check if the build process from npm run watch gives you any errors
    • If not: ✅
    • If so: Go back to the Babylon.js import
  • You can find all Babylon.js types which are exported by the viewer on this page

• Remove obsolete Babylon.js dependencies:

  • Search for all occurrences of from '@babylonjs
  • If there are some left: Nothing to do
  • If there are none:
    • Remove all Babylon.js dependencies from your package.json
    • Run npm i
    • 🎉

• Remove obsolete type imports:

  • Search for all occurrences of no-unused-vars
  • Remove the no-unused-vars line
  • Remove the unused import
  • Check if the build process from npm run watch gives you any errors
    • If not: ✅
    • If so: Go back to import the thing and use the no-unused-vars statement

Automatic conversion of colors to linear space

Colors applied to PBR materials appeared "washed out" in earlier viewer versions. The color which appeared on the screen was often a lot lighter than one would have expected from its color code.

The new viewer fixes this by automatically converting colors given to its API (e.g. to commitParameters) from gamma to linear color space.

This changes how colors applied using the viewer API (e.g. by commitParameters) appear on the screen. Please check & adjust all your colors carefully after updating the viewer.

Spec driven camera positioning and animation API

Positions within the 3d scene can now be declared using PlacementDefinition inside the specs SceneJson.placements.

Those placements can be used to trigger animated camera movements using the new camera movement API and AnimationDefinition inside the specs SceneJson.animations.

Example code

/**
 * @return {StructureJson}
 */
export function createSpec() {
  return {
    scene: {
      // ...

      // Define placements & animations in spec:
      placements: {
        Height60: {
          position: '(-0.6073864925275645, 0.4765578799104585, -1.284793058907506)',
          target: '(-0.030564361711816836, 0.26223482532257786, -0.1034106283975893)',
        },
        Height100: {
          position: '(-0.5034608339970097, 0.9162828478182772, -1.4399870356436006)',
          target: '(0.11190323895696523, 0.47328146232722085, -0.016705972101674342)',
        },
      },

      animations: {
        DefaultCameraAnimation: {
          ease: 'Power3.easeInOut',
          duration: 0.8,
        },
      },

      // ...
    },
    // ...
  };
}

// ...

// Perform a simple animated camera movement:
const camPlacementName = isHeight100 ? 'Height100' : 'Height60';
viewer.moveActiveCameraTo(camPlacementName, 'DefaultCameraAnimation');

// Perform a series of animated camera movements:
await viewer.moveActiveCameraTo('Height60', 'DefaultCameraAnimation');
await viewer.moveActiveCameraTo('Height100', 'DefaultCameraAnimation');
await viewer.moveActiveCameraTo('Height60', 'DefaultCameraAnimation');

// ...

How to define animations ease function

You can use the GreenSock Ease Visualizer to create an animation of your liking and simply copy the ease function shown at the bottom of the visualizer into the ease property of your AnimationDefinition.