@combeenation/3d-viewer 16.0.0-alpha1 → 16.0.0-beta1

package/src/helper/decals-helper.ts

@@ -1,16 +1,43 @@
 import { IAssetContainer, Material, Mesh, MeshBuilder, Tuple, Vector3, ViewerError, ViewerErrorIds } from '..';
 
+export const DEFAULT_DECAL_CONFIG = {
+  normal: [0, 0, 1],
+  angle: 0,
+  offset: 0.001,
+  scaling: [1, 1, 1],
+  captureUVS: false,
+  cullBackFaces: true,
+  localMode: true,
+  sideOrientation: Material.ClockWiseSideOrientation,
+};
+
 export type DecalConfiguration = {
   // basic settings for decal creation
   name: string;
   sourceMeshName: string;
   position: Tuple<number, 3>;
-  normal: Tuple<number, 3>;
   size: Tuple<number, 3>;
-  angle: number;
 
-  /** Shifts decals away from source mesh in direction of "normal" vector */
-  offset: number;
+  /** Default `[0, 0, 1]` (forward direction) */
+  normal?: Tuple<number, 3>;
+
+  /** Default `0` */
+  angle?: number;
+
+  /**
+   * Shifts decals away from source mesh in direction of "normal" vector
+   *
+   * Default `0.001` (1mm)
+   */
+  offset?: number;
+
+  /**
+   * Can be used for shifting the decal away from the source mesh as alternative to `offset`.\
+   * Use this setting when the offset should be applied in radial direction (e.g. cylinders)
+   *
+   * Default `[1, 1, 1]` (no offset through scaling)
+   */
+  scaling?: Tuple<number, 3>;
 
   /**
    * `true`: Use UV mapping from source mesh\
@@ -60,19 +87,19 @@ export function createDecalMesh(config: DecalConfiguration, assetContainer: IAss
   }
 
   const position = Vector3.FromArray(config.position);
-  const normal = Vector3.FromArray(config.normal).normalizeToNew();
+  const normal = Vector3.FromArray(config.normal ?? DEFAULT_DECAL_CONFIG.normal).normalizeToNew();
 
-  const localMode = config.localMode ?? true;
+  const localMode = config.localMode ?? DEFAULT_DECAL_CONFIG.localMode;
   const worldNormal = localMode ? Vector3.TransformNormal(normal, sourceMesh.getWorldMatrix()) : normal;
 
   const decalMesh = MeshBuilder.CreateDecal(config.name, sourceMesh, {
     position: position,
     normal: normal,
     size: Vector3.FromArray(config.size),
-    angle: config.angle,
-    captureUVS: config.captureUVS ?? false,
-    cullBackFaces: config.cullBackFaces ?? true,
-    localMode: config.localMode ?? true,
+    angle: config.angle ?? DEFAULT_DECAL_CONFIG.angle,
+    captureUVS: config.captureUVS ?? DEFAULT_DECAL_CONFIG.captureUVS,
+    cullBackFaces: config.cullBackFaces ?? DEFAULT_DECAL_CONFIG.cullBackFaces,
+    localMode: config.localMode ?? DEFAULT_DECAL_CONFIG.localMode,
   });
 
   if (!addToScene) {
@@ -84,12 +111,15 @@ export function createDecalMesh(config: DecalConfiguration, assetContainer: IAss
   decalMesh._parentContainer = assetContainer;
   assetContainer.meshes.push(decalMesh);
 
-  decalMesh.sideOrientation = config.sideOrientation ?? Material.ClockWiseSideOrientation;
+  decalMesh.sideOrientation = config.sideOrientation ?? DEFAULT_DECAL_CONFIG.sideOrientation;
 
   // move decal away from mesh to avoid clipping
   // NOTE: zOffset of material can't be used, since it's not supported in glTF and therefore not usable in AR
-  const offsetVector = worldNormal.scale(config.offset);
+  const offsetVector = worldNormal.scale(config.offset ?? DEFAULT_DECAL_CONFIG.offset);
   decalMesh.position.addInPlace(offsetVector);
 
+  // apply scaling, this is an alternative approach for creating an offset, which is preferred for round surfaces
+  decalMesh.scaling = Vector3.FromArray(config.scaling ?? DEFAULT_DECAL_CONFIG.scaling);
+
   return decalMesh;
 }

package/src/internal/cbn-custom-babylon-loader-plugin.ts

@@ -1,8 +1,9 @@
 import {
   AssetContainer,
-  DecalConfiguration,
+  ExtendedAssetContainer,
   ISceneLoaderPlugin,
   InstancedMesh,
+  ParsedDecalConfiguration,
   SceneLoader,
   ViewerError,
   ViewerErrorIds,
@@ -10,20 +11,7 @@ import {
 } from '../index';
 import { setInternalMetadataValue } from './metadata-helper';
 import { deleteAllTags, getTags, setTagsAsString } from './tags-helper';
-import { isArray, isNumber, isString } from 'lodash-es';
-
-/**
- * Contains cbn custom data, like decals.
- * This is just a temporary type, as the `loadAssetContainer` function only returns an asset container, which can be
- * altered by our file loader plugin.
- * After loading the model, `cbnData` is cropped and a pure asset container is available for further processing.
- */
-export class ExtendedAssetContainer extends AssetContainer {
-  cbnData?: CbnBabylonFileData;
-}
-
-export type CbnBabylonFileData = { decals?: ParsedDecalConfiguration[] };
-export type ParsedDecalConfiguration = DecalConfiguration & { materialId?: string };
+import { isArray, isString } from 'lodash-es';
 
 type DataWithMeshes = { meshes: unknown[] };
 type DataWithDecalConfigurations = { cbnData: { decals: unknown[] } };
@@ -39,6 +27,8 @@ type InstanceData = {
   tags?: string;
 };
 
+let customLoader: ISceneLoaderPlugin;
+
 /**
  * Create and return a custom loader plugin to be registered with SceneLoader, that allows
  * us to run our own code against the input data before using the standard procedure to
@@ -51,12 +41,18 @@ type InstanceData = {
  *   editor area
  */
 export function registerCustomCbnBabylonLoaderPlugin(): void {
+  if (customLoader) {
+    // create the custom loader only once, otherwise receiving the current .babylon plugin would return the custom
+    // loader, resulting in multiple calls of the plugin (e.g. decals will be created multiple times)
+    return;
+  }
+
   // get original plugin for babylon files
   // we only want to manipulate Combeenation 3d assets, which are represented as babylon files
   // the plugin is not used for GLB files, "local" babylon are also not really affected by this plugin
   const previousLoaderPlugin = SceneLoader.GetPluginForExtension('.babylon') as ISceneLoaderPlugin;
 
-  const customLoader: ISceneLoaderPlugin = {
+  customLoader = {
     name: 'cbnCustomBabylonLoader',
     extensions: '.babylon',
     importMesh: previousLoaderPlugin.importMesh,
@@ -104,13 +100,7 @@ function _isMeshInstanceData(data: any): data is InstanceData {
 
 function _isDecalConfiguration(data: any): data is ParsedDecalConfiguration {
   const hasValidProps =
-    isString(data.name) &&
-    isString(data.sourceMeshName) &&
-    isArray(data.position) &&
-    isArray(data.normal) &&
-    isArray(data.size) &&
-    isNumber(data.angle) &&
-    isNumber(data.offset);
+    isString(data.name) && isString(data.sourceMeshName) && isArray(data.position) && isArray(data.size);
 
   if (!hasValidProps) {
     throw new ViewerError({
@@ -200,13 +190,17 @@ function _createDecals(dataParsed: unknown, container: AssetContainer): void {
   const validatedDecals = dataParsed.cbnData.decals.filter(_isDecalConfiguration);
 
   validatedDecals.forEach(decalConfig => {
-    const { materialId, ...decalMeshConfig } = decalConfig;
+    const { materialId, tags, ...decalMeshConfig } = decalConfig;
     const decalMesh = createDecalMesh(decalMeshConfig, container, false);
 
-    // optionally set material directly
+    // optionally set material and tags directly
     if (materialId) {
       window.Cbn?.Assets.assertMaterialExists(materialId);
       setInternalMetadataValue(decalMesh, 'deferredMaterial', materialId);
     }
+
+    if (tags) {
+      setTagsAsString(decalMesh, tags);
+    }
   });
 }

package/src/manager/material-manager.ts

@@ -47,7 +47,7 @@ export class MaterialManager {
 
     // there may have been later "setMaterialOnMesh" calls with faster material creation
     // make sure to assign the latest material!
-    if (getInternalMetadataValue(mesh, 'materialToBeSet') === materialId) {
+    if (material && getInternalMetadataValue(mesh, 'materialToBeSet') === materialId) {
       mesh.material = material;
       clearInternalMetadataValue(mesh, 'materialToBeSet');
       clearInternalMetadataValue(mesh, 'deferredMaterial');
@@ -65,7 +65,7 @@ export class MaterialManager {
    * @param mesh Required for shader compilation check, can be omitted if this check should not be done.\
    * Use {@link setMaterialOnMesh} instead if the material should be applied on the mesh immediately.
    */
-  public async getOrCreateMaterial(materialId: string, mesh?: AbstractMesh): Promise<Material> {
+  public async getOrCreateMaterial(materialId: string, mesh?: AbstractMesh): Promise<Material | null> {
     let chosenMaterial: Material | null = this.viewer.scene.materials.find(mat => mat.id === materialId) ?? null;
 
     if (!chosenMaterial) {
@@ -78,7 +78,7 @@ export class MaterialManager {
         this.viewer.eventManager.fireEvent(ViewerEvent.MaterialCreationStart, materialId);
 
         // request not pending, call the dedicated function
-        const newCreationProm = this._createMaterial(materialId, mesh);
+        const newCreationProm = this._createFromMaterialAsset(materialId, mesh);
         // store the promise in a global map, so that subsequent requests can reference it
         this._createMaterialPromises[materialId] = newCreationProm;
         chosenMaterial = await newCreationProm;
@@ -93,7 +93,7 @@ export class MaterialManager {
       }
     }
 
-    return chosenMaterial as Material;
+    return chosenMaterial;
   }
 
   /**
@@ -105,7 +105,7 @@ export class MaterialManager {
     materialId: string,
     newMaterialId: string,
     options?: MaterialCloneOptions
-  ): Promise<Material> {
+  ): Promise<Material | null> {
     const existingMaterial = this._clonedMaterials[newMaterialId];
     if (existingMaterial) {
       throw new ViewerError({
@@ -115,6 +115,10 @@ export class MaterialManager {
     }
 
     const sourceMaterial = await this.getOrCreateMaterial(materialId);
+    if (!sourceMaterial) {
+      return null;
+    }
+
     const clonedMaterial = CloningHelper.cloneMaterial(sourceMaterial, newMaterialId, options?.tagNamingStrategy);
 
     await this.viewer.parameterManager.applyParameterValuesToMaterial(clonedMaterial);
@@ -151,7 +155,7 @@ export class MaterialManager {
     Object.keys(this._clonedMaterials).forEach(materialId => this.deleteClonedMaterial(materialId));
   }
 
-  protected async _createMaterial(materialId: string, mesh?: AbstractMesh): Promise<Material> {
+  protected async _createFromMaterialAsset(materialId: string, mesh?: AbstractMesh): Promise<Material | null> {
     if (materialId === MaterialManager.CBN_FALLBACK_MATERIAL_NAME) {
       const fallbackMaterial = new StandardMaterial(MaterialManager.CBN_FALLBACK_MATERIAL_NAME, this.viewer.scene);
       fallbackMaterial.disableLighting = true;
@@ -159,17 +163,29 @@ export class MaterialManager {
       return fallbackMaterial;
     }
 
-    const materialDefinition = await window.Cbn?.Assets.getMaterial(materialId);
+    if (!window.Cbn) {
+      return null;
+    }
+
+    const materialDefinition = await window.Cbn.Assets.getMaterial(materialId);
+
+    if (!materialDefinition) {
+      console.warn(
+        `Trying to create material "${materialId}" from Combeenation asset but according asset does not exist or is not connected to the configurator.`
+      );
+      return null;
+    }
+
     // The generic `Material.Parse` actually returns a more specific material like `BABYLON.StandardMaterial`,
     // `BABYLON.PBRMaterial` or stuff like `BABYLON.PBRMetallicRoughnessMaterial` etc. based on the given `customType`
     // within the material JSON definition
-    const material = materialDefinition && Material.Parse(materialDefinition, this.viewer.scene, '');
+    const material = Material.Parse(materialDefinition, this.viewer.scene, '');
 
     if (!material) {
-      throw new ViewerError({
-        id: ViewerErrorIds.MaterialCouldNotBeParsed,
-        message: `Material with id "${materialId}" could not be parsed`,
-      });
+      console.warn(
+        `Failed to create material "${materialId}" from Combeenation asset. Seems like the material could not be parsed.`
+      );
+      return null;
     }
 
     await this.viewer.parameterManager.applyParameterValuesToMaterial(material);

package/src/manager/model-manager.ts

@@ -11,15 +11,25 @@ import {
   ViewerError,
   ViewerErrorIds,
 } from '../index';
-import {
-  CbnBabylonFileData,
-  ExtendedAssetContainer,
-  ParsedDecalConfiguration,
-} from '../internal/cbn-custom-babylon-loader-plugin';
 import { cloneModelAssetContainer } from '../internal/cloning-helper';
 import { getInternalMetadataValue } from '../internal/metadata-helper';
 import { isArray } from 'lodash-es';
 
+/**
+ * Contains cbn custom data, like decals.
+ * This is just a temporary type, as the `loadAssetContainer` function only returns an asset container, which can be
+ * altered by our file loader plugin.
+ * After loading the model, `cbnData` is cropped and a pure asset container is available for further processing.
+ *
+ * @internal
+ */
+export class ExtendedAssetContainer extends AssetContainer {
+  cbnData?: CbnBabylonFileData;
+}
+
+type CbnBabylonFileData = { decals?: ParsedDecalConfiguration[] };
+export type ParsedDecalConfiguration = DecalConfiguration & { materialId?: string; tags?: string };
+
 export type ModelAssetDefinition = {
   name: string;
   url: string;
@@ -372,7 +382,7 @@ export class ModelManager {
    * Decals are already converted to "normal" meshes when loading a model, still the original decals configuration can
    * be useful e.g. for alterning decals.
    */
-  public async getDecalsConfigurationOfModel(name: string): Promise<DecalConfiguration[]> {
+  public async getDecalsConfigurationOfModel(name: string): Promise<ParsedDecalConfiguration[]> {
     const model = this._getModel(name);
     if (!model) {
       throw new ViewerError({
@@ -391,16 +401,7 @@ export class ModelManager {
       await this._prepareModelForScene(model);
     }
 
-    // crop materialId as this is not part of `DecalConfiguration`
-    const decals = ((model.cbnBabylonFileData?.decals ?? []) as ParsedDecalConfiguration[]).map<DecalConfiguration>(
-      parsedDecal => {
-        const croppedDecal = parsedDecal;
-        delete croppedDecal.materialId;
-        return croppedDecal;
-      }
-    );
-
-    return decals;
+    return model.cbnBabylonFileData?.decals ?? [];
   }
 
   /**

package/src/manager/parameter-manager.ts

@@ -377,6 +377,13 @@ export class ParameterManager {
     const materialParamEntries = this._getEntriesOfSubject({ materialName: material.id });
     parameterEntriesToApply.push(...materialParamEntries);
 
+    // also get parameter entries that have this material set as value, this is the case for node <=> material
+    // assignment parameter (`BuiltInParameter.Material`)
+    const materialAssignmentParamEntries = this._parameterEntries.filter(
+      entry => entry.parameterName === BuiltInParameter.Material && entry.value === material.id
+    );
+    parameterEntriesToApply.push(...materialAssignmentParamEntries);
+
     await this._applyParameterValues(parameterEntriesToApply);
   }
 

package/src/viewer-error.ts

@@ -25,7 +25,6 @@ export const ViewerErrorIds = {
   ModelAlreadyExists: 'ModelAlreadyExists',
   ModelIsNotAClone: 'ModelIsNotAClone',
   AssetLoadingFailed: 'AssetLoadingFailed',
-  MaterialCouldNotBeParsed: 'MaterialCouldNotBeParsed',
   TextureCouldNotBeParsed: 'TextureCouldNotBeParsed',
   MaterialAlreadyExists: 'MaterialAlreadyExists',
   NotAClonedMaterial: 'NotAClonedMaterial',