@combeenation/3d-viewer 15.1.0 → 16.0.0-alpha2

package/src/helper/decals-helper.ts

@@ -0,0 +1,125 @@
+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>;
+  size: Tuple<number, 3>;
+
+  /** 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\
+   * `false`: Use default box mapping from the decal
+   *
+   * Default `false`
+   */
+  captureUVS?: boolean;
+
+  /**
+   * Create decal only on front side if set to `true`
+   *
+   * Default `true`
+   */
+  cullBackFaces?: boolean;
+
+  /** `true`: Sets created decal as child of source mesh
+   *
+   * Default `true`
+   */
+  localMode?: boolean;
+
+  /**
+   * The Babylon.js default for mesh side orientation value is `Material.CounterClockWiseSideOrientation`.\
+   * However if the mesh (in this case the created decal mesh) is located under a glTF root node, it has to be flipped,
+   * using `Material.ClockWiseSideOrientation`.
+   *
+   * Default `Material.ClockWiseSideOrientation`
+   */
+  sideOrientation?: number;
+};
+
+/**
+ * Creates mesh from a decal configuration.\
+ * This is basically calling `MeshBuilder.CreateDecal`, with some extra steps:
+ * - add created decal mesh to source mesh asset container
+ * - overwrite decal mesh side orientation (important for glTF models)
+ * - move decal along the "normal" to avoid clipping
+ */
+export function createDecalMesh(config: DecalConfiguration, assetContainer: IAssetContainer, addToScene = true): Mesh {
+  const sourceMesh = assetContainer.meshes.find(mesh => mesh.name === config.sourceMeshName);
+  if (!sourceMesh) {
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidDecalConfiguration,
+      message: `Source mesh for decal "${config.name}" couldn't be found`,
+    });
+  }
+
+  const position = Vector3.FromArray(config.position);
+  const normal = Vector3.FromArray(config.normal ?? DEFAULT_DECAL_CONFIG.normal).normalizeToNew();
+
+  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 ?? 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) {
+    const scene = sourceMesh.getScene();
+    scene.removeMesh(decalMesh);
+  }
+
+  // make sure that the decal is part of the source mesh asset container
+  decalMesh._parentContainer = assetContainer;
+  assetContainer.meshes.push(decalMesh);
+
+  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 ?? 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/index.ts

@@ -69,3 +69,4 @@ export * from './manager/model-manager';
 export * from './manager/parameter-manager';
 export * from './manager/scene-manager';
 export * from './manager/texture-manager';
+export * from './helper/decals-helper';

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

@@ -1,58 +1,88 @@
-import { AssetContainer, ISceneLoaderPlugin, InstancedMesh, SceneLoader } from '../index';
+import {
+  AssetContainer,
+  ExtendedAssetContainer,
+  ISceneLoaderPlugin,
+  InstancedMesh,
+  ParsedDecalConfiguration,
+  SceneLoader,
+  ViewerError,
+  ViewerErrorIds,
+  createDecalMesh,
+} from '../index';
 import { setInternalMetadataValue } from './metadata-helper';
 import { deleteAllTags, getTags, setTagsAsString } from './tags-helper';
 import { isArray, isString } from 'lodash-es';
 
+type DataWithMeshes = { meshes: unknown[] };
+type DataWithDecalConfigurations = { cbnData: { decals: unknown[] } };
+
+type MeshData = {
+  name: string;
+  materialId?: string;
+  instances?: unknown[];
+};
+
+type InstanceData = {
+  name: string;
+  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
  * import.
- * The main use case is to mark missing material in meshes, which will get loaded on demand at the first time the
- * dedicated mesh gets visible.
- * This is the case if the babylon file is a Combeenation "3d asset" which comes without materials, as the materials
- * are defined as "material assets".
+ * The main use cases are:
+ * - Marking missing material in meshes, which will get loaded on demand at the first time the dedicated mesh gets
+ *   visible. This is the case if the babylon file is a Combeenation "3d asset" which comes without materials, as the
+ *   materials are defined as "material assets".
+ * - Interpreting custom cbn data that have been injected in the babylon file, e.g. by the "decals editor" in the asset
+ *   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,
     load: previousLoaderPlugin.load,
-    loadAssetContainer: function (scene, data, rootUrl, onError) {
+    loadAssetContainer: (scene, data, rootUrl, onError): ExtendedAssetContainer => {
       const dataParsed = JSON.parse(data as string);
       const importedContainer = previousLoaderPlugin.loadAssetContainer(scene, data, rootUrl);
 
       _addMissingMaterialMetadata(dataParsed, importedContainer);
       _reconstructTagsForInstancedMeshes(dataParsed, importedContainer);
+      _createDecals(dataParsed, importedContainer);
+
+      // add `cbnData` to output asset container, so that this information can be store as metadata for the model
+      const extendedContainer = importedContainer as ExtendedAssetContainer;
+      extendedContainer.cbnData = dataParsed.cbnData;
 
-      return importedContainer;
+      return extendedContainer;
     },
   };
 
   SceneLoader.RegisterPlugin(customLoader);
 }
 
-type InstanceData = {
-  name: string;
-  tags?: string;
-};
-
-function _isMeshInstanceData(data: any): data is InstanceData {
-  const hasName = isString(data.name);
-  const hasValidTags = !data.tags || isString(data.tags);
-  return hasName && hasValidTags;
+function _isDataWithMeshes(data: any): data is DataWithMeshes {
+  return isArray(data?.meshes);
 }
 
-type MeshData = {
-  name: string;
-  materialId?: string;
-  instances?: unknown[];
-};
+function _isDataWithDecalConfigurations(data: any): data is DataWithDecalConfigurations {
+  return isArray(data?.cbnData?.decals);
+}
 
 function _isMeshData(data: any): data is MeshData {
   const hasName = isString(data.name);
@@ -61,10 +91,25 @@ function _isMeshData(data: any): data is MeshData {
   return hasName && hasValidMaterialId;
 }
 
-type DataWithMeshes = { meshes: unknown[] };
+function _isMeshInstanceData(data: any): data is InstanceData {
+  const hasName = isString(data.name);
+  const hasValidTags = !data.tags || isString(data.tags);
 
-function _isDataWithMeshes(data: any): data is DataWithMeshes {
-  return data && isArray(data.meshes);
+  return hasName && hasValidTags;
+}
+
+function _isDecalConfiguration(data: any): data is ParsedDecalConfiguration {
+  const hasValidProps =
+    isString(data.name) && isString(data.sourceMeshName) && isArray(data.position) && isArray(data.size);
+
+  if (!hasValidProps) {
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidDecalConfiguration,
+      message: `Configuration for decal "${data.name}" invalid`,
+    });
+  }
+
+  return hasValidProps;
 }
 
 /**
@@ -128,3 +173,34 @@ function _reconstructTagsForInstancedMeshes(dataParsed: unknown, container: Asse
     }
   });
 }
+
+/**
+ * This function interprets the decal configuration, that is stored top level in the babylon file (`dataParsed`) and
+ * creates decal meshes in the given `container`.
+ *
+ * Having the decal information stored in that way is required for the "decals editor" in the asset manager, as meshes
+ * created from decals have to be updateable.
+ *
+ * @param container This is being manipulated, by adding decal meshes to it based on the decal configuration read from
+ *                  `dataParsed`.
+ */
+function _createDecals(dataParsed: unknown, container: AssetContainer): void {
+  if (!_isDataWithDecalConfigurations(dataParsed)) return;
+
+  const validatedDecals = dataParsed.cbnData.decals.filter(_isDecalConfiguration);
+
+  validatedDecals.forEach(decalConfig => {
+    const { materialId, tags, ...decalMeshConfig } = decalConfig;
+    const decalMesh = createDecalMesh(decalMeshConfig, container, false);
+
+    // optionally set material and tags directly
+    if (materialId) {
+      window.Cbn?.Assets.assertMaterialExists(materialId);
+      setInternalMetadataValue(decalMesh, 'deferredMaterial', materialId);
+    }
+
+    if (tags) {
+      setTagsAsString(decalMesh, tags);
+    }
+  });
+}

package/src/internal/metadata-helper.ts

@@ -1,7 +1,7 @@
 import { BaseTexture, Material, Node } from '../index';
 import { cloneDeep } from 'lodash-es';
 
-type MetadataValue = string | number | boolean | undefined;
+type MetadataValue = string | number | boolean | object | undefined;
 type MetadataTarget = Node | Material | BaseTexture;
 type MetadataKeys =
   // CBN babylon loader

package/src/manager/model-manager.ts

@@ -1,6 +1,7 @@
 import {
   AssetContainer,
   BuiltInParameter,
+  DecalConfiguration,
   MaterialManager,
   MeshBuilder,
   ParameterManager,
@@ -14,6 +15,21 @@ 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;
@@ -43,6 +59,7 @@ type Model = {
   url: string;
   state: ModelAssetState;
   assetContainer: AssetContainer;
+  cbnBabylonFileData?: CbnBabylonFileData;
   isClone: boolean;
   visibilityCallId?: number;
 };
@@ -359,6 +376,34 @@ export class ModelManager {
     return model.assetContainer;
   }
 
+  /**
+   * Returns the decals configuration of a certain model.\
+   * The model will be loaded before being able to access this configuration.\
+   * 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<ParsedDecalConfiguration[]> {
+    const model = this._getModel(name);
+    if (!model) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelNotRegistered,
+        message: `Can't get decals configuration of model "${name}" as model is not registered`,
+      });
+    }
+
+    if (model.state === 'notLoaded') {
+      await this._loadModel(model);
+    } else if (model.state === 'loading') {
+      await this._loadModelPromises[model.name];
+    }
+
+    if (model.state !== 'inScene') {
+      await this._prepareModelForScene(model);
+    }
+
+    return model.cbnBabylonFileData?.decals ?? [];
+  }
+
   /**
    * Get model by name
    */
@@ -384,7 +429,18 @@ export class ModelManager {
 
       let assetContainer;
       try {
-        assetContainer = await SceneLoader.LoadAssetContainerAsync('', model.url, this.viewer.scene);
+        const fullContainer = (await SceneLoader.LoadAssetContainerAsync(
+          '',
+          model.url,
+          this.viewer.scene
+        )) as ExtendedAssetContainer;
+
+        // crop and store custom cbn data from .babylon file
+        model.cbnBabylonFileData = fullContainer.cbnData;
+        delete fullContainer.cbnData;
+
+        // from here it's a basic asset container again
+        assetContainer = fullContainer as AssetContainer;
       } catch (e) {
         throw new ViewerError({
           id: ViewerErrorIds.AssetLoadingFailed,

package/src/viewer-error.ts

@@ -29,6 +29,7 @@ export const ViewerErrorIds = {
   TextureCouldNotBeParsed: 'TextureCouldNotBeParsed',
   MaterialAlreadyExists: 'MaterialAlreadyExists',
   NotAClonedMaterial: 'NotAClonedMaterial',
+  InvalidDecalConfiguration: 'InvalidDecalConfiguration',
 };
 
 /** @internal */