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

package/src/manager/html-anchor-manager.ts

@@ -0,0 +1,332 @@
+import {
+  AbstractMesh,
+  ArcRotateCamera,
+  Camera,
+  DimensionLineManager,
+  MeshBuilder,
+  ScreenshotSize,
+  StandardMaterial,
+  TransformNode,
+  Vector3,
+  Viewer,
+  Viewport,
+} from '..';
+import html2canvas from 'html2canvas';
+
+export type HtmlAnchorOptions = {
+  /**
+   * Associated anchor mesh will be created underneath this parent node.\
+   * Can be used to make anchor position calculation easier in nested scene structures.
+   */
+  parentNode?: TransformNode;
+  /**
+   * Can be used to filter affected html anchors in {@link HtmlAnchorManager.removeAllHtmlAnchors}
+   */
+  group?: string;
+  /**
+   * `true`: html elements can be occluded by other meshes
+   * `false`: html elements will always be shown in front of the scene
+   *
+   * Default: `false`
+   */
+  hideIfOccluded?: boolean;
+  /**
+   * `true`: html element size is relative to camera distance, just like a "normal" 3d object
+   * `false`: html element size remains constant
+   *
+   * Default: `false`
+   */
+  scaleWithCameraDistance?: boolean;
+  /**
+   * Activates/deactivates `pointer-events` CSS class of anchor element.\
+   * Set this to `true` if the html element should be interactive (e.g. button)
+   *
+   * Default: `false`
+   */
+  enablePointerEvents?: boolean;
+};
+
+/**
+ * Manager for mapping html elements to 3d positions in the scene.\
+ * Common use cases are:
+ * - **Hotspot buttons**: Interactively add/remove elements in the scene or just show some info on hovering
+ * - **Input fields**: Interactively change the size of an element
+ * - **Info label**: Just shows some information on a certain position within the scene
+ *
+ * Html anchors are also used as dimension lables in the {@link DimensionLineManager}
+ */
+export class HtmlAnchorManager {
+  protected static readonly _HTML_ANCHOR_KEY = '$htmlAnchor';
+
+  protected _htmlAnchors: {
+    [name: string]: {
+      parentHtmlElement: HTMLDivElement;
+      anchorMesh: AbstractMesh;
+      options?: HtmlAnchorOptions;
+    };
+  } = {};
+
+  protected _anchorMeshMaterial: StandardMaterial | null = null;
+
+  /** @internal */
+  public constructor(protected viewer: Viewer) {
+    const canvas = viewer.canvas;
+    if (!canvas) {
+      return;
+    }
+
+    // html element positions need to be updated after each camera render call
+    viewer.scene.onAfterRenderCameraObservable.add(() => {
+      Object.values(this._htmlAnchors).forEach(({ parentHtmlElement, anchorMesh, options }) => {
+        this._updateHtmlAnchor(
+          parentHtmlElement,
+          anchorMesh,
+          viewer.scene.activeCamera!,
+          canvas.width,
+          canvas.height,
+          1,
+          options
+        );
+      });
+    });
+  }
+
+  /**
+   * Assign a html element to a certain position in the scene.\
+   * The html elements 2d position will be updated on each camera render, so that the element appears like a "normal"
+   * mesh within the scene.
+   */
+  public addHtmlAnchor(name: string, htmlElement: HTMLElement, position: Vector3, options?: HtmlAnchorOptions): void {
+    const canvasParentHtmlElement = this.viewer.canvas?.parentElement;
+    if (!canvasParentHtmlElement) {
+      console.warn(`No parent for desired html anchor available`);
+      return;
+    }
+
+    if (this._htmlAnchors[name]) {
+      console.warn(`Html anchor "${name}" already exists`);
+      return;
+    }
+
+    const { parentNode, enablePointerEvents } = options ?? {};
+
+    // create a parent for the input html element, which will receive the updated style and transform data
+    // in this way the original input element remains untouched
+    const parentHtmlElement = document.createElement('div');
+    parentHtmlElement.dataset.anchorName = name;
+    parentHtmlElement.style.position = 'absolute';
+    parentHtmlElement.style.margin = '0';
+    parentHtmlElement.appendChild(htmlElement);
+    if (!enablePointerEvents) {
+      parentHtmlElement.style.pointerEvents = 'none';
+    }
+    canvasParentHtmlElement.appendChild(parentHtmlElement);
+
+    // NOTE: creates a sphere with fixed size, which could be problematic in scene with "strange" dimensions
+    // add a property for the sphere size if required
+    const anchorMesh = MeshBuilder.CreateSphere(`${HtmlAnchorManager._HTML_ANCHOR_KEY}_${name}`, { diameter: 0.01 });
+    anchorMesh.position = position;
+    anchorMesh.parent = parentNode ?? null;
+    // anchor mesh will be invisible, we only need it for positioning and occlusion check
+    anchorMesh.material = this._getOrCreateAnchorMeshMaterial();
+    anchorMesh.occlusionType = AbstractMesh.OCCLUSION_TYPE_OPTIMISTIC;
+    anchorMesh.occlusionQueryAlgorithmType = AbstractMesh.OCCLUSION_ALGORITHM_TYPE_CONSERVATIVE;
+    // it's important that the occlusion check mesh is rendered after all "normal" meshes, which should be taken into
+    // account for the occlusion check
+    anchorMesh.renderingGroupId = 1;
+
+    this._htmlAnchors[name] = { parentHtmlElement, anchorMesh, options };
+  }
+
+  /**
+   * Remove html anchor element and disposes all associated ressources
+   */
+  public removeHtmlAnchor(name: string): void {
+    const htmlAnchor = this._htmlAnchors[name];
+    if (!htmlAnchor) {
+      console.warn(`Html anchor "${name}" does not exist`);
+      return;
+    }
+
+    htmlAnchor.parentHtmlElement.remove();
+    htmlAnchor.anchorMesh.dispose();
+
+    delete this._htmlAnchors[name];
+  }
+
+  /**
+   * Removes html anchor elements, as defined by the `groups` input
+   *
+   * @param groups if set, only html anchors which are part of these groups will be removed\
+   *               if left `undefined`, ALL html anchors will be removed
+   */
+  public removeAllHtmlAnchors(groups?: string[]): void {
+    const anchorKeysToRemove = this.getHtmlAnchorKeys(
+      groups,
+      undefined,
+      // system groups should not be remove, as there is a dedicated workflow
+      // (e.g. `DimensionLineManager.removeDimensionLine`) to do this
+      false
+    );
+
+    anchorKeysToRemove.forEach(name => this.removeHtmlAnchor(name));
+  }
+
+  /**
+   * Creates a screenshot of defined html anchors and returns the associated canvas.\
+   * This function is used @internal from the main screenshot function.
+   */
+  public async createScreenshotCanvas(
+    size: ScreenshotSize,
+    camera: ArcRotateCamera,
+    htmlAnchorKeys: string[]
+  ): Promise<HTMLCanvasElement> {
+    const canvasParentHtmlElement = this.viewer.canvas?.parentElement;
+    if (!canvasParentHtmlElement) {
+      console.warn(`No parent for html anchors available`);
+      return new HTMLCanvasElement();
+    }
+
+    const htmlContainer = document.createElement('div');
+    htmlContainer.style.width = `${size.canvasWidth}px`;
+    htmlContainer.style.height = `${size.canvasHeight}px`;
+
+    // the `html2canvas` library requires the html to be present in the DOM
+    // that's why we create it top level and move it out of the viewport
+    // @reviewer: maybe there is a smoother method of doing that?
+    document.body.append(htmlContainer);
+    htmlContainer.style.position = 'absolute';
+    htmlContainer.style.top = `${-size.canvasHeight}px`;
+
+    htmlAnchorKeys.forEach(key => {
+      const { parentHtmlElement, anchorMesh, options } = this._htmlAnchors[key];
+
+      // create clones of html anchors, so that the position of the original elements remains untouched
+      const clonedHtmlNode = parentHtmlElement.cloneNode(true) as HTMLDivElement;
+      htmlContainer.append(clonedHtmlNode);
+
+      // reposition that cloned html element, so that it fits to the desired camera position
+      const baseScale = size.canvasHeight / this.viewer.canvas!.height;
+      this._updateHtmlAnchor(
+        clonedHtmlNode,
+        anchorMesh,
+        camera,
+        size.canvasWidth,
+        size.canvasHeight,
+        baseScale,
+        options
+      );
+    });
+
+    const screenshotHtmlCanvas = await html2canvas(htmlContainer, {
+      width: size.imageWidth,
+      height: size.imageHeight,
+      // apply difference of canvas and image size as offsets
+      x: (size.canvasWidth - size.imageWidth) / 2,
+      y: (size.canvasHeight - size.imageHeight) / 2,
+      logging: false,
+      backgroundColor: null,
+    });
+
+    htmlContainer.remove();
+
+    return screenshotHtmlCanvas;
+  }
+
+  /**
+   * Receive html anchor keys that pass the `includeGroups` and `excludeGroups` filter
+   * @param allowSystemGroups defines if html anchors created by the viewer should be considered (e.g. dimension line
+   *                          labels)
+   * @internal
+   */
+  public getHtmlAnchorKeys(includeGroups?: string[], excludeGroups?: string[], allowSystemGroups?: boolean): string[] {
+    const anchorKeys = Object.keys(this._htmlAnchors).filter(name => {
+      const group = this._htmlAnchors[name].options?.group;
+      const passIncludeGroupFilter =
+        includeGroups === undefined || (group !== undefined && includeGroups.includes(group));
+      const passExcludeGroupFilter =
+        excludeGroups === undefined || group === undefined || !excludeGroups.includes(group);
+      // ATM only dimension labels are system html anchors
+      const passSystemGroupFilter = allowSystemGroups || group !== DimensionLineManager.DIMENSION_LINE_KEY;
+
+      return passIncludeGroupFilter && passExcludeGroupFilter && passSystemGroupFilter;
+    });
+
+    return anchorKeys;
+  }
+
+  /**
+   * Check if input mesh is a html anchor mesh, created by this manager.\
+   * This check is done via the material, as all html anchor meshes have the generic `_anchorMeshMaterial` set.
+   * @internal
+   */
+  public isHtmlAnchorMesh(mesh: AbstractMesh): boolean {
+    return mesh.material === this._anchorMeshMaterial;
+  }
+
+  protected _updateHtmlAnchor(
+    parentHtmlElement: HTMLDivElement,
+    anchorMesh: AbstractMesh,
+    camera: Camera,
+    width: number,
+    height: number,
+    baseScale: number,
+    options?: HtmlAnchorOptions
+  ): void {
+    const { hideIfOccluded, scaleWithCameraDistance } = options ?? {};
+
+    const viewMatrix = camera.getViewMatrix();
+    const projectionMatrix = camera.getProjectionMatrix();
+    const transformMatrix = viewMatrix.multiply(projectionMatrix);
+
+    // convert into 2d space
+    const vertexScreenCoords = Vector3.Project(
+      Vector3.Zero(),
+      anchorMesh.getWorldMatrix(),
+      transformMatrix,
+      new Viewport(0, 0, width, height)
+    );
+
+    // base scale is used if width and height don't equal the viewer canvas, which is the case for screenshots
+    let scale = baseScale;
+    if (scaleWithCameraDistance) {
+      const meshWorldPos = anchorMesh.getAbsolutePosition();
+      // calculate camera world position manually, as there is no help function like for meshes
+      const camWorldMatrix = camera.computeWorldMatrix();
+      const camWorldPos = camWorldMatrix.getTranslation();
+      const distance = Vector3.Distance(meshWorldPos, camWorldPos);
+      const frustumSlopeY = Math.tan(camera.fov / 2);
+      // if the distance from camera to mesh gets larger, the html elements scaling will be decreased
+      // we also consider the cameras FOV, so scale 1 means, that the resulting vertical frustum of the camera
+      // distance equals 1
+      // ...this is probably too small in some scenarios, so we might have to add a general scale setting here
+      scale *= 1 / (distance * frustumSlopeY);
+    }
+
+    const elementXOffset = (parentHtmlElement.offsetWidth * scale) / 2;
+    const elementYOffset = (parentHtmlElement.offsetHeight * scale) / 2;
+    // finally move and scale the HTML element
+    parentHtmlElement.style.transform = `translate3d(calc(${vertexScreenCoords.x}px - 50%), calc(${vertexScreenCoords.y}px - 50%), 0px) scale(${scale})`;
+
+    // check for occlusion if desired
+    // we use the opacity setting, which could also be animated nicely if we want
+    const isInViewport =
+      vertexScreenCoords.x - elementXOffset > 0 &&
+      vertexScreenCoords.x + elementXOffset < width &&
+      vertexScreenCoords.y - elementYOffset > 0 &&
+      vertexScreenCoords.y + elementYOffset < height;
+    const isOccluded = hideIfOccluded && anchorMesh.isOccluded;
+    parentHtmlElement.style.opacity = isInViewport && !isOccluded ? '1' : '0';
+  }
+
+  protected _getOrCreateAnchorMeshMaterial(): StandardMaterial {
+    if (this._anchorMeshMaterial) {
+      return this._anchorMeshMaterial;
+    }
+
+    this._anchorMeshMaterial = new StandardMaterial('$matAnchorMesh');
+    this._anchorMeshMaterial.alpha = 0;
+    this.viewer.scene.removeMaterial(this._anchorMeshMaterial);
+    return this._anchorMeshMaterial;
+  }
+}

package/src/manager/model-manager.ts

@@ -62,7 +62,6 @@ type ModelAsset = BaseAsset & {
 export class ModelManager {
   /**
    * CAUTION: this has to be in sync with the Combeenation backend!
-   * @internal
    */
   public static readonly CBN_FALLBACK_MODEL_ASSET_NAME = '$fallback';
 

package/src/manager/parameter-manager.ts

@@ -97,7 +97,7 @@ export type ParameterObserver = (payload: ParameterObserverPayload) => Promise<v
 
 /**
  * Payload of parameter observer.\
- * Contains current data of parameter entry, which can be usefull for implementing the dedicated observer
+ * Contains current data of parameter entry, which can be useful for implementing the dedicated observer
  */
 export type ParameterObserverPayload = {
   subject: ParameterSubject;

package/src/manager/scene-manager.ts

@@ -105,7 +105,7 @@ type SceneAsset = BaseAsset & {
  * This contains creating or loading scenes with certain settings for lighting, cameras and appearance in genereal.
  */
 export class SceneManager {
-  protected static _DEFAULT_SCENE_ASSET_NAME = '$default';
+  protected static _DEFAULT_SCENE_ASSET_NAME = '$defaultScene';
   protected static _DEFAULT_GROUND_PLANE_NAME = 'BackgroundPlane';
   protected static _DEFAULT_GROUND_SIZING_FACTOR = 5;
 
@@ -294,10 +294,19 @@ export class SceneManager {
         const hasInfiniteDistance = mesh.infiniteDistance;
         // ignore meshes with "BackgroundMaterial" - usually a ground or skybox
         const hasBackgroundMaterial = mesh.material instanceof BackgroundMaterial;
+        // ignore dummy meshes for html anchor occlusion check
+        const isHtmlAnchorMesh = this.viewer.htmlAnchorManager.isHtmlAnchorMesh(mesh);
         // ignore excluded meshes
         const isExcluded = excludeGeometry ? isNodeExcluded(mesh, excludeGeometry) : false;
 
-        return isEnabled && hasValidBBoxInfo && !hasInfiniteDistance && !hasBackgroundMaterial && !isExcluded;
+        return (
+          isEnabled &&
+          hasValidBBoxInfo &&
+          !hasInfiniteDistance &&
+          !hasBackgroundMaterial &&
+          !isHtmlAnchorMesh &&
+          !isExcluded
+        );
       })
       .reduce(
         (accBBoxMinMax, curMesh, idx) => {
@@ -399,7 +408,7 @@ export class SceneManager {
     // camera
     if (cameraSettings.create) {
       const camera = new ArcRotateCamera(
-        `${SceneManager._DEFAULT_SCENE_ASSET_NAME}.camera`,
+        `${SceneManager._DEFAULT_SCENE_ASSET_NAME}_camera`,
         cameraSettings.initialPosition.alpha,
         cameraSettings.initialPosition.beta,
         cameraSettings.initialPosition.radius,

package/src/viewer.ts

@@ -5,10 +5,12 @@ import {
   CameraManager,
   DebugManager,
   DefaultSceneSettings,
+  DimensionLineManager,
   Engine,
   EngineOptions,
   EventManager,
   GltfExportManager,
+  HtmlAnchorManager,
   MaterialManager,
   ModelManager,
   NullEngine,
@@ -80,8 +82,10 @@ export class Viewer {
 
   protected _cameraManager!: CameraManager;
   protected _debugManager!: DebugManager;
+  protected _dimensionLineManager!: DimensionLineManager;
   protected _eventManager!: EventManager;
   protected _gltfExportManager!: GltfExportManager;
+  protected _htmlAnchorManager!: HtmlAnchorManager;
   protected _materialManager!: MaterialManager;
   protected _modelManager!: ModelManager;
   protected _parameterManager!: ParameterManager;
@@ -119,12 +123,18 @@ export class Viewer {
   get debugManager(): DebugManager {
     return this._debugManager;
   }
+  get dimensionLineManager(): DimensionLineManager {
+    return this._dimensionLineManager;
+  }
   get eventManager(): EventManager {
     return this._eventManager;
   }
   get gltfExportManager(): GltfExportManager {
     return this._gltfExportManager;
   }
+  get htmlAnchorManager(): HtmlAnchorManager {
+    return this._htmlAnchorManager;
+  }
   get materialManager(): MaterialManager {
     return this._materialManager;
   }
@@ -171,7 +181,7 @@ export class Viewer {
   }
 
   /**
-   * Pause rendering can be usefull when doing internal scene processings that should not be visible to the user,
+   * Pause rendering can be useful when doing internal scene processings that should not be visible to the user,
    * e.g. cloning meshes for gltf export
    */
   public pauseRendering(): void {
@@ -227,14 +237,20 @@ export class Viewer {
     }
 
     this._scene = new Scene(engine);
+    // NOTE: rendering group id "1" is reserved for occlusion helper sphere (see `HtmlAnchorManager`)
+    // rendering group id "1" has the same depth buffer as 0 in order to make this work
+    // => use rendering group id "2" or higher for keeping meshes in foreground
+    this._scene.setRenderingAutoClearDepthStencil(1, false, false, false);
 
     // NOTE: order of manage seems to be a bit counter intuitive as it's sorted alphabetically
     // semantically one would start with scene manager, etc...
     // still this is a good test as the order of manager constructors should not matter
     this._cameraManager = new CameraManager(this);
     this._debugManager = new DebugManager(this);
+    this._dimensionLineManager = new DimensionLineManager(this);
     this._eventManager = new EventManager(this);
     this._gltfExportManager = new GltfExportManager(this);
+    this._htmlAnchorManager = new HtmlAnchorManager(this);
     this._materialManager = new MaterialManager(this);
     this._modelManager = new ModelManager(this);
     this._parameterManager = new ParameterManager(this);