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

package/src/manager/dimension-line-manager.ts

@@ -0,0 +1,255 @@
+import { Color3, LinesMesh, MeshBuilder, Tags, TransformNode, Vector3, Viewer } from '../index';
+import { merge } from 'lodash-es';
+
+/**
+ * General options that are used for each dimension line
+ */
+export type DefaultDimensionLineOptions = {
+  /**
+   * Default: `Color3.Black()`
+   */
+  lineColor: Color3;
+  /**
+   * Default: 50mm
+   */
+  closingLineHeight: number;
+  /**
+   * Height of dimension label
+   *
+   * Default: 24px
+   */
+  labelHeight: number;
+  /**
+   * Corner radius of dimension label
+   *
+   * Default: 1/2 of `labelHeight`, to create a half circle
+   */
+  borderRadius?: number;
+  /**
+   * Text padding in x direction
+   *
+   * Default: 1/2 of `labelHeight`
+   */
+  textPadding?: number;
+  /**
+   * Default: Arial
+   */
+  fontFamily: string;
+  /**
+   * Text color of dimension label
+   *
+   * Default: black
+   */
+  textColor: string;
+  /**
+   * Color of border
+   *
+   * Default: black
+   */
+  borderColor: string;
+  /**
+   * Background color of dimension label
+   *
+   * Default: white
+   */
+  backgroundColor: 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;
+};
+
+/**
+ * Specific options for each dimension line
+ */
+export type DimensionLineOptions = Partial<DefaultDimensionLineOptions> & {
+  /**
+   * Optional parent node of dimension line group, can be used for easier calculation of start and end point
+   *
+   * Default: no parent node set
+   */
+  parentNode?: TransformNode;
+  /**
+   * Optional direction of the closing lines on start and end.\
+   * Use built-in vector functions like `Vector3.Left()` or `Vector3.Forward()` for simple directions of use a custom
+   * normal vector like `Vector3(1, 0.5 ,0)`.
+   *
+   * Default: x or y direction is taken, depending on the normal vector between start and end point
+   */
+  closingLineDirection?: Vector3;
+  /**
+   * Optional label text
+   *
+   * Default: dimension line size is calculated from `startPoint` and `endPoint` and suffixed with "mm" (e.g. "1200 mm")
+   */
+  labelText?: string;
+};
+
+/**
+ * Manager for dimension lines, which can be used to display certain dimensions like object sizes in the scene
+ */
+export class DimensionLineManager {
+  public static readonly DIMENSION_LINE_KEY = '$dimLine';
+
+  protected _defaultLineOptions: DefaultDimensionLineOptions = {
+    lineColor: Color3.Black(),
+    closingLineHeight: 50,
+    labelHeight: 24,
+    fontFamily: 'Arial',
+    textColor: 'black',
+    borderColor: 'black',
+    backgroundColor: 'white',
+    hideIfOccluded: false,
+    scaleWithCameraDistance: false,
+  };
+
+  // map with all dimension lines that are currently visible in the scene
+  // holds data of all disposable objects for a clean up
+  protected _dimensionLineObjs: {
+    [name: string]: {
+      linesMesh: LinesMesh;
+      htmlLabelName: string;
+    };
+  } = {};
+
+  /** @internal */
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Define dimension line options that are used for each line by default.\
+   * Options can be overwritten by each line individually.
+   */
+  public setDefaultDimensionLineOptions(defaultLineOptions: Partial<DefaultDimensionLineOptions>): void {
+    merge(this._defaultLineOptions, defaultLineOptions);
+  }
+
+  /**
+   * Create dimension line between two points
+   */
+  public addDimensionLine(name: string, startPoint: Vector3, endPoint: Vector3, options?: DimensionLineOptions): void {
+    if (this._dimensionLineObjs[name]) {
+      console.warn(`Dimension line "${name}" already exists`);
+      return;
+    }
+
+    const {
+      parentNode,
+      closingLineDirection: closingLineDirectionIn,
+      labelText: labelTextIn,
+      ...inputDefaultOptions
+    } = options ?? {};
+
+    const resDefaultOptions = { ...this._defaultLineOptions };
+    merge(resDefaultOptions, inputDefaultOptions);
+    const {
+      lineColor,
+      closingLineHeight,
+      labelHeight,
+      textPadding,
+      borderRadius,
+      fontFamily,
+      textColor,
+      borderColor,
+      backgroundColor,
+      hideIfOccluded,
+      scaleWithCameraDistance,
+    } = resDefaultOptions;
+
+    let closingLineDirection = closingLineDirectionIn;
+    if (!closingLineDirection) {
+      // evaluate closing line direction if not given
+      const normal = endPoint.subtract(startPoint);
+      const yIsMainDirection = Math.abs(normal.y) > Math.abs(normal.x) && Math.abs(normal.y) > Math.abs(normal.z);
+      closingLineDirection = yIsMainDirection ? Vector3.Right() : Vector3.Up();
+    }
+
+    // calculate and create main and closing lines
+    const lineCenter = Vector3.Center(startPoint, endPoint);
+    const relStartPt = startPoint.subtract(lineCenter);
+    const relEndPt = endPoint.subtract(lineCenter);
+    const closingLineOffsetVector = closingLineDirection.normalizeToNew().scale(closingLineHeight / 2 / 1000);
+    const closingLineStartPts = [relStartPt.add(closingLineOffsetVector), relStartPt.subtract(closingLineOffsetVector)];
+    const closingLineEndPts = [relEndPt.add(closingLineOffsetVector), relEndPt.subtract(closingLineOffsetVector)];
+
+    const linesMesh = MeshBuilder.CreateLineSystem(`${DimensionLineManager.DIMENSION_LINE_KEY}_${name}`, {
+      lines: [[relStartPt, relEndPt], closingLineStartPts, closingLineEndPts],
+    });
+    linesMesh.position = lineCenter;
+    linesMesh.color = lineColor;
+    // rendering group id 1 reserved for html anchor meshes, which are required for occlusion checking
+    linesMesh.renderingGroupId = hideIfOccluded ? 0 : 2;
+    // tag can be used to exclude dimension lines from autofocus or gltf export
+    Tags.AddTagsTo(linesMesh, DimensionLineManager.DIMENSION_LINE_KEY);
+    if (parentNode) {
+      linesMesh.parent = parentNode;
+    }
+
+    let labelText = labelTextIn;
+    if (labelText === undefined) {
+      // create default text if not explicitely overwritten by the function
+      const length = Vector3.Distance(startPoint, endPoint);
+      const lengthRounded = Math.round(length * 1000 * 100) / 100;
+      labelText = `${lengthRounded} mm`;
+    }
+
+    // create default html element
+    const span = document.createElement('span');
+    span.textContent = labelText;
+    span.style.display = 'block';
+    span.style.height = `${labelHeight}px`;
+    span.style.lineHeight = `${labelHeight}px`;
+    span.style.fontFamily = fontFamily;
+    span.style.fontSize = `${(labelHeight * 2) / 3}px`;
+    span.style.border = `1px solid ${borderColor}`;
+    span.style.paddingLeft = `${textPadding ?? labelHeight / 2}px`;
+    span.style.paddingRight = `${textPadding ?? labelHeight / 2}px`;
+    span.style.borderRadius = `${borderRadius ?? labelHeight / 2}px`;
+    span.style.color = textColor;
+    span.style.background = backgroundColor;
+
+    const htmlLabelName = `${DimensionLineManager.DIMENSION_LINE_KEY}_${name}`;
+    this.viewer.htmlAnchorManager.addHtmlAnchor(name, span, Vector3.Zero(), {
+      parentNode: linesMesh,
+      group: DimensionLineManager.DIMENSION_LINE_KEY,
+      hideIfOccluded,
+      scaleWithCameraDistance,
+    });
+
+    this._dimensionLineObjs[name] = { linesMesh, htmlLabelName };
+  }
+
+  /**
+   * Remove dimension line and disposes all associated ressources
+   */
+  public removeDimensionLine(name: string): void {
+    const dimensionLine = this._dimensionLineObjs[name];
+    if (!dimensionLine) {
+      console.warn(`Dimension line "${name}" does not exist`);
+      return;
+    }
+
+    this.viewer.htmlAnchorManager.removeHtmlAnchor(name);
+    dimensionLine.linesMesh.dispose(false, true);
+
+    delete this._dimensionLineObjs[name];
+  }
+
+  /**
+   * Remove all dimension lines that have been created with the `DimensionLineManager`
+   */
+  public removeAllDimensionLines(): void {
+    Object.keys(this._dimensionLineObjs).forEach(dimLineName => {
+      this.removeDimensionLine(dimLineName);
+    });
+  }
+}

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

@@ -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,