@combeenation/3d-viewer 7.0.0-beta1 → 7.0.0-beta3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/3d-viewer",
-  "version": "7.0.0-beta1",
+  "version": "7.0.0-beta3",
   "description": "Combeenation 3D Viewer",
   "homepage": "https://github.com/Combeenation/3d-viewer#readme",
   "bugs": {

package/src/api/classes/viewer.ts

@@ -58,8 +58,7 @@ export class Viewer extends EventBroadcaster {
 
   protected _variantInstances: VariantInstanceManager | null = null;
 
-  // default value is `false` ATM for compatibility reasons
-  // in the future material cloning should be the edge case
+  // defaults to `false` as material cloning should be the edge case
   protected _cloneMaterialsOnMutation: boolean = false;
 
   protected _isRenderLoopPaused: boolean = false;
@@ -71,7 +70,7 @@ export class Viewer extends EventBroadcaster {
   static version = buildInfo.version;
 
   // these are constants for calculating the camera settings, depending on the bounding box size of the meshes to zoom
-  // the algorithms and constant values are directly taken from the BabylonJS repository
+  // the algorithms and constant values are directly taken from the Babylon.js repository
   private static readonly _autofocusConstants = {
     minZ: 100,
     wheelPrecision: 100,
@@ -80,15 +79,15 @@ export class Viewer extends EventBroadcaster {
   };
 
   /**
-   * Help function for automatically creating a valid Spec from a list of variant names and dedicated GLB/Babylon URLs.
+   * Help function for automatically creating a valid Spec from a list of variant names and dedicated GLB/babylon URLs.
    * This data is most likely coming from babylon assets from the Combeenation system but other sources are also valid.
    */
-  public static generateSpec(genData: SpecGenerationData[]): StructureJson {
+  public static generateSpec(genData: SpecGenerationData[]): AutoSpecStructureJson {
     // dots in the variant name indicate inheritance, but this should not be the case for an auto-generated spec
     // therefore dots are exchanged with slashes
     const safeGenData: SpecGenerationData[] = genData.map(data => ({ ...data, name: replaceDots(data.name) }));
 
-    const spec: StructureJson = {
+    const spec: AutoSpecStructureJson = {
       // common scene settings as suggested in the viewer docs
       scene: {
         engine: {
@@ -118,7 +117,7 @@ export class Viewer extends EventBroadcaster {
       },
       // variants definition is also mapped to the input array, using the name as key and url as glTF source
       // no elements are created here, since this should be done automatically from the system
-      // => create one element which contains all root nodes of the imported 3d file (GLB or Babylon)
+      // => create one element which contains all root nodes of the imported 3d file (GLB or babylon)
       variants: safeGenData.reduce((accVariants, curVariant) => {
         accVariants[curVariant.name] = {
           glTF: curVariant.url,
@@ -157,7 +156,7 @@ export class Viewer extends EventBroadcaster {
   }
 
   /**
-   * Gets the BabylonJS Scene that is attached to the instance.
+   * Gets the Babylon.js Scene that is attached to the instance.
    *
    * @throws Error if the `scene` has not been initialized.
    */
@@ -193,7 +192,7 @@ export class Viewer extends EventBroadcaster {
   }
 
   /**
-   * Gets the BabylonJS Engine that is attached to the viewer.
+   * Gets the Babylon.js Engine that is attached to the viewer.
    */
   get engine(): Engine {
     return this.scene.getEngine();
@@ -248,7 +247,9 @@ export class Viewer extends EventBroadcaster {
   }
 
   /**
-   * Sets the strategy handler for naming cloned nodes.
+   * Sets the strategy handler for naming cloned nodes.\
+   * Check the docs of the tag managers [renaming](https://3dviewer.docs.combeenation.com/pages/documentation/Tag-Manager.html#uniqueness-of-node-and-tag-names)
+   * chapter for further details.
    */
   set nodeNamingStrategyHandler(value: NodeNamingStrategyHandler) {
     if (!value || typeof value !== 'function') {
@@ -321,7 +322,7 @@ export class Viewer extends EventBroadcaster {
   }
 
   /**
-   * Enables the BabylonJS [Inspector](https://doc.babylonjs.com/toolsAndResources/tools/inspector).\
+   * Enables the Babylon.js [Inspector](https://doc.babylonjs.com/toolsAndResources/tools/inspector).\
    * Due to the additional size of the inspector, the CDN version is used instead of shipping the required code with
    * the viewer.\
    * This means that the code will be downloaded only when needed and calling `enableDebugLayer` can take a little while
@@ -329,7 +330,7 @@ export class Viewer extends EventBroadcaster {
    */
   public async enableDebugLayer(options?: IInspectorOptions) {
     if (!this._inspectorLoaded) {
-      // CDN version of inspector requires the BabylonJS core to be available as CDN module as well
+      // CDN version of inspector requires the Babylon.js core to be available as CDN module as well
       await loadJavascript('https://cdn.jsdelivr.net/npm/babylonjs@5.6.0/babylon.min.js');
 
       DebugLayer.InspectorURL =
@@ -532,7 +533,7 @@ export class Viewer extends EventBroadcaster {
     activeCamera.lowerRadiusLimit = radius;
 
     // additional settings
-    // constants for division are taken directly from BabylonJS repository
+    // constants for division are taken directly from Babylon.js repository
     activeCamera.minZ = Math.min(radius / Viewer._autofocusConstants.minZ, 1);
     if (settings?.adjustWheelPrecision !== false) {
       activeCamera.wheelPrecision = Viewer._autofocusConstants.wheelPrecision / radius;
@@ -552,7 +553,7 @@ export class Viewer extends EventBroadcaster {
       alpha: alpha,
       beta: beta,
       // this calculation is a bit "simplified", as it doesn't consider the viewport ratio or the frustum angle
-      // but it's also done this way in the BabylonJs repository, so it should be fine for us
+      // but it's also done this way in the Babylon.js repository, so it should be fine for us
       radius: diameter * radiusFactor,
       target: center,
     };

package/src/api/classes/viewerLight.ts

@@ -22,7 +22,7 @@ import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_lights_punctual';
 import { get, isEmpty, isString, set } from 'lodash-es';
 
 /**
- * A {@link ViewerLight} of a {@link Variant}. Acts as a container for BabylonJS lights. Lives only in the context of a
+ * A {@link ViewerLight} of a {@link Variant}. Acts as a container for Babylon.js lights. Lives only in the context of a
  * {@link Variant}.
  */
 export class ViewerLight extends VariantParameterizable {

package/src/api/manager/animationManager.ts

@@ -19,7 +19,7 @@ export class AnimationManager {
   protected constructor(protected scene: BabylonScene) {}
 
   /**
-   * Creates an {@link AnimationManager} based on given BabylonJS scene.
+   * Creates an {@link AnimationManager} based on given Babylon.js scene.
    */
   public static async create(scene: BabylonScene): Promise<AnimationManager> {
     return new AnimationManager(scene);

package/src/api/manager/sceneManager.ts

@@ -24,7 +24,7 @@ export class SceneManager extends ParameterObservable {
   }
 
   /**
-   * Creates a {@link SceneManager} based on given BabylonJS scene.
+   * Creates a {@link SceneManager} based on given Babylon.js scene.
    */
   public static async create(scene: BabylonScene): Promise<SceneManager> {
     const sceneManager = new SceneManager(scene);

package/src/api/manager/tagManager.ts

@@ -210,7 +210,7 @@ export class TagManager {
   }
 
   /**
-   * Gets all nodes for given {@link TagManagerSubject} on the Babylon scene.
+   * Gets all nodes for given {@link TagManagerSubject} on the Babylon.js scene.
    */
   public getNodesBySubject(subject: TagManagerSubject, predicate?: (node: TransformNode) => boolean): TransformNode[] {
     let nodes: TransformNode[] = [];
@@ -232,7 +232,7 @@ export class TagManager {
   }
 
   /**
-   * Registers observers that are called on every new node added to the Babylon scene. The observers ensure that each
+   * Registers observers that are called on every new node added to the Babylon.js scene. The observers ensure that each
    * new node gets the state of the {@link TagManager}'s {@link parameters} applied.
    */
   public registerNewTransformNodeObservers(scene: Scene) {

package/src/api/manager/variantInstanceManager.ts

@@ -202,6 +202,11 @@ export class VariantInstanceManager extends EventBroadcaster {
   /**
    * Clones and registers a new {@link VariantInstance} with a new, unique name.
    *
+   * @param tagMapping Object for renaming tags on the clone, whereas the "key" is the tag name of orignal variant
+   * instance and the "value" is the new tag name that should be created from it.\
+   * Check the docs of the tag managers [renaming](https://3dviewer.docs.combeenation.com/pages/documentation/Tag-Manager.html#uniqueness-of-node-and-tag-names)
+   * chapter for further details.
+   *
    * @emits {@link Event.VARIANT_INSTANCE_CLONED}
    */
   public async clone(

package/src/api/util/babylonHelper.ts

@@ -110,6 +110,11 @@ const cloneTransformNode = function (
     if (node.constructor.name === 'InstancedMesh') {
       clone.setEnabled(node.isEnabled(false));
     }
+    // copying tags is a temporary workaround, as it doesn't work for TransformNodes ATM
+    // see https://forum.babylonjs.com/t/transformnode-clone-doesnt-contain-original-tags/38429/1
+    if (Tags?.HasTags(node)) {
+      Tags.AddTagsTo(clone, Tags.GetTags(node, true));
+    }
   }
   if (deep) {
     const children = node.getChildTransformNodes(true);

package/src/api/util/globalTypes.ts

@@ -109,7 +109,7 @@ type EnvironmentDefinition = {
 
 type StructureJson = {
   /**
-   * `scene` describes the visualisation of the Babylon `scene` such as the incidence of light and camera position. If a
+   * `scene` describes the visualisation of the babylon `scene` such as the incidence of light and camera position. If a
    * string is given, the {@link Viewer} will resolve the URL or path and pass the parsed JSON to this property.
    */
   scene?: string | SceneJson;
@@ -131,7 +131,7 @@ type StructureJson = {
   /**
    * `variants` is a declarative description of 3D-model variations in the configurator. Each variant itself is a
    * {@link StructureJson} which must at least define a `name` in the key of the list and the properties `glTF` and
-   * `elements` in the value. FYI: BabylonJS's sandbox can show you the path of the 3D-model to properly define the
+   * `elements` in the value. FYI: Babylon.js's sandbox can show you the path of the 3D-model to properly define the
    * `paths`.
    *
    * Example Code
@@ -159,6 +159,12 @@ type StructureJson = {
   };
 };
 
+type AutoSpecStructureJson = StructureJson & {
+  scene: SceneJson;
+  setup: SetupJson;
+  variants: { [id: string]: StructureJson };
+};
+
 type SceneJson = {
   parameterDeclaration?: ParameterDeclarations;
   parameters?: ParameterBag;
@@ -174,7 +180,8 @@ type SceneJson = {
   animations?: AnimationDefinitions;
   placements?: PlacementDefinitions;
   /**
-   * Information about [material cloning](pages/Release%20Notes/releases/4-3-0.html#material-cloning-on-mutation)
+   * Information about [material cloning](pages/Release%20Notes/releases/4-3-0.html#material-cloning-on-mutation).
+   * Default value is `false`.
    */
   cloneMaterialsOnMutation?: boolean;
 };
@@ -228,7 +235,7 @@ type SceneGlobals = {
 };
 
 /**
- * {@link Viewer.screenshot} internally uses Babylons [ScreenshotTools.CreateScreenshotUsingRenderTarget](https://doc.babylonjs.com/typedoc/classes/babylon.screenshottools#createscreenshotusingrendertarget). \
+ * {@link Viewer.screenshot} internally uses Babylon.js [ScreenshotTools.CreateScreenshotUsingRenderTarget](https://doc.babylonjs.com/typedoc/classes/babylon.screenshottools#createscreenshotusingrendertarget). \
  * See this link for additional info about the properties.
  */
 type ScreenshotSettings = {
@@ -432,7 +439,7 @@ type AnimationDefinitions = {
 type AnimationDefinition = GSAPTweenVars & { shortestWay?: boolean };
 
 /**
- * Extends Babylon JSs {@link IExportOptions} by some viewer specific settings
+ * Extends Babylon.js's {@link IExportOptions} by some viewer specific settings
  */
 interface IExportOptionsExtended extends IExportOptions {
   /**

package/src/api/util/resourceHelper.ts

@@ -39,7 +39,7 @@ const loadText = async function (path: string): Promise<string> {
 
 /**
  * Loads a Javascript ressource.\
- * Usefull for including packages via CDN (eg: BabylonJS Inspector)
+ * Usefull for including packages via CDN (eg: Babylon.js Inspector)
  */
 const loadJavascript = (url: string): Promise<void> =>
   new Promise(resolve => {

package/src/api/util/sceneLoaderHelper.ts

@@ -156,8 +156,8 @@ export const removeMissingMaterialObserver = function (node: BjsNode) {
 /**
  * Look up the provided materials (see library import) and create and return one if found.
  *
- * @param materialId BabylonJs material-id. E.g. 'concrete".
- * @param scene BabylonJs scene
+ * @param materialId Babylon.js material-id. E.g. 'concrete".
+ * @param scene Babylon.js scene
  * @returns PBRMaterial | null
  */
 export const createMaterialFromCbnAssets = function (materialId: string, scene: Scene): Material | null {