@combeenation/3d-viewer 12.4.1 → 13.0.0

package/src/internal/paintableHelper.ts

@@ -0,0 +1,310 @@
+import {
+  DynamicTexture,
+  Material,
+  PBRMaterial,
+  ParameterValue,
+  Scene,
+  StandardMaterial,
+  Texture,
+  ViewerError,
+  ViewerErrorIds,
+} from '../index';
+import isSvg from 'is-svg';
+import { isString } from 'lodash-es';
+
+type PaintableValue = {
+  src: string;
+  options?: PaintableOptions;
+};
+
+type PaintableOptions = {
+  uScale?: number;
+  uOffset?: number;
+  vScale?: number;
+  vOffset?: number;
+};
+
+/**
+ * Observer implementation for "paintable" parameter.
+ * Basically creates a dynamic texture from the source image and assigns it as albedo (or diffuse) texture.
+ */
+export async function paintableParameterObserver(
+  newValue: ParameterValue,
+  materials: Material[],
+  scene: Scene
+): Promise<void> {
+  const paintable = parsePaintable(newValue);
+
+  // check if value is svg or image source, do the conversion accordingly
+  const srcIsSvg = isSvg(paintable.src);
+  if (!srcIsSvg && paintable.src.includes('<svg') && paintable.src.includes('</svg>')) {
+    // seems like the user tried to use a SVG string, as <svg> tags are used
+    // inform the user that this is not a valid SVG string
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Invalid value for parameter "paintable" given:\nsource string is no valid SVG string\nGiven value: ${paintable.src}`,
+    });
+  }
+
+  let imageSource: CanvasImageSource;
+  try {
+    imageSource = srcIsSvg ? await _createImageFromSvg(paintable.src) : await _createImageFromImgSrc(paintable.src);
+  } catch {
+    // SVG might be invalid, even if it passes `isSvg` check
+    // in this case the image can't be created and will throw an error, which should be handled by the viewer and
+    // Combeenation viewer control
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Invalid value for parameter "paintable" given:\nimage can't be created from source string\nGiven value: ${paintable.src}`,
+    });
+  }
+
+  // apply image source on desired material(s)
+  for (const material of materials) {
+    _drawPaintableOnMaterial(material, imageSource, scene, paintable.options);
+  }
+}
+
+/**
+ * Parser for paintable value.
+ * ATM this is only used internally, but it could theoretically be used to create ones own paintable implementation.
+ *
+ * @param value The value to parse. Examples:
+ *              ```ts
+ *              // Default definition as JSON object:
+ *              '{ "src": "https://path.to/image.jpg", "uScale": 0.5 }'
+ *
+ *              // Short hand definition, only contains source string:
+ *              'https://path.to/image.jpg'
+ *
+ *              // Full content, paintable texture is flipped in both directions
+ *              '{ "src": "https://path.to/image.jpg", "uScale": -1, "vScale": -1, "uOffset": 0, "vOffset": 0 }'
+ *
+ *              // SVG content can be used directly:
+ *              '<svg>...</svg>'
+ *
+ *              // SVG in src property works as well:
+ *              '{ "src": "<svg>...</svg>", "uScale": 0.5 }'
+ *              ```
+ */
+export function parsePaintable(value: ParameterValue): PaintableValue {
+  if (!isString(value)) {
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Unable to parse paintable value: not a string\nGiven value: ${value}`,
+    });
+  }
+
+  const paintableValue: PaintableValue = { src: '' };
+  let valObj: { [key: string]: any } | null = null;
+
+  try {
+    valObj = JSON.parse(value);
+  } catch {
+    // use string directly
+    paintableValue.src = value;
+
+    if (value.startsWith('{')) {
+      // seems like the user tried to use a JSON string, as the input starts with {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse paintable value: not a valid JSON string\nGiven value: ${value}`,
+      });
+    }
+  }
+
+  if (valObj) {
+    // input string is JSON, src attribute is required
+    if (!valObj.src) {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse paintable value: property "src" is missing\nGiven value: ${value}`,
+      });
+    }
+
+    if (!isString(valObj.src)) {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse paintable value: property "src" is not a string\nGiven value: ${value}`,
+      });
+    }
+
+    // split src and options
+    const { src, ...options } = valObj;
+    paintableValue.src = src;
+
+    // only forward valid paintable options
+    const validOptionKeys = ['uScale', 'vScale', 'uOffset', 'vOffset'];
+    const { validOptions, invalidKeys } = Object.entries(options).reduce(
+      (accRes, [curKey, curValue]) => {
+        const isValidKey = validOptionKeys.includes(curKey);
+        if (isValidKey) {
+          accRes.validOptions[curKey] = curValue;
+        } else {
+          accRes.invalidKeys.push(curKey);
+        }
+
+        return accRes;
+      },
+      { validOptions: {} as { [key: string]: any }, invalidKeys: [] as string[] }
+    );
+
+    if (invalidKeys.length) {
+      console.warn('Invalid paintable options provided: ' + invalidKeys.toString());
+    }
+
+    paintableValue.options = validOptions;
+  }
+
+  return paintableValue;
+}
+
+function _drawPaintableOnMaterial(
+  material: Material,
+  imageSource: HTMLImageElement,
+  scene: Scene,
+  options?: PaintableOptions
+): void {
+  // always take width and height from image source, scaling is done with uvScale properties
+  const widthAndHeight = {
+    width: imageSource.width,
+    height: imageSource.height,
+  };
+
+  const texture = new DynamicTexture(`${material.id}.paintable_texture`, widthAndHeight, scene);
+
+  // draw image on texture
+  const ctx = texture.getContext();
+  ctx.drawImage(imageSource, 0, 0);
+  texture.update();
+
+  // apply settings from paintable options to tweak position and scaling of image on the texture
+  texture.uScale = options?.uScale ?? texture.uScale;
+  texture.vScale = options?.vScale ?? texture.vScale;
+  texture.uOffset = options?.uOffset ?? texture.uOffset;
+  texture.vOffset = options?.vOffset ?? texture.vOffset;
+
+  // wrap mode is preferred, as it will always show the texture, no matter which position offset is currently chosen
+  // clamp mode requires more knowledge (and patience) when adjusting the uv scale and offset values
+  texture.wrapU = Texture.WRAP_ADDRESSMODE;
+  texture.wrapV = Texture.WRAP_ADDRESSMODE;
+
+  // apply the paintable texture on the dedicated material type
+  const materialCls = material.getClassName();
+  switch (materialCls) {
+    case 'PBRMaterial':
+      (material as PBRMaterial).albedoTexture = texture;
+      break;
+    case 'StandardMaterial':
+      (material as StandardMaterial).diffuseTexture = texture;
+      break;
+    default:
+      throw new Error(`Setting paintable texture for material of instance "${materialCls}" not implemented (yet)`);
+  }
+}
+
+/**
+ * Creates a HTML image element based on a SVG string, whereas all the embedded assets in the SVG (eg: fonts, images)
+ * are already loaded and exchanged by their base64 representation.\
+ * There the output image can exist as "standalone" image and may be used for example as a paintable.
+ *
+ * !!CAUTION!!: The used functions within this code section are very well evaluated since most alternatives
+ * somehow don't work in Safari, as mentioned in the following BJS forum entries:
+ * - https://forum.babylonjs.com/t/drawing-svg-content-text-into-dynamictexture-doesnt-work-in-safari-v15/25048
+ * - https://forum.babylonjs.com/t/texture-createfrombase64string-doesnt-seem-to-work-for-ios-devices-initially/25502
+ */
+async function _createImageFromSvg(svgSrc: string): Promise<HTMLImageElement> {
+  // replace assets with their base64 versions in svg source code
+  const svgWithAssetsEmbedded = await _embedAssets(svgSrc);
+
+  // create data string which can be used as an image source
+  const svgEncoded = 'data:image/svg+xml,' + encodeURIComponent(svgWithAssetsEmbedded);
+
+  return _createImageFromImgSrc(svgEncoded);
+}
+
+/**
+ * Creates an HTML image element from a dedicated image source.\
+ * Also waits until the image has loaded.
+ *
+ * !!CAUTION!!: The `setTimeout` after loading is finished is required due to a Safari bug:
+ * - https://bugs.webkit.org/show_bug.cgi?id=39059
+ * - https://bugs.webkit.org/show_bug.cgi?id=219770
+ *
+ * It's not 100% ensured that the timeout solves the issue in every case, but there is no other way unfortunately.\
+ * => Keep an eye on it in future projects
+ *
+ * @param imgSrc Theoretically every source is valid which is also supported by
+ *               [HTMLImageElement.src](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/src).\
+ *               Known exceptions are SVGs with embedded assets that are provided as object URL. See comments in
+ *               {@link createImageFromSvg} for further details.
+ */
+async function _createImageFromImgSrc(imgSrc: string): Promise<HTMLImageElement> {
+  const img = new Image();
+
+  await new Promise((resolve, reject) => {
+    img.onload = (): void => {
+      setTimeout(resolve, 0);
+    };
+    img.onerror = (): void => {
+      reject();
+    };
+    img.crossOrigin = 'anonymous';
+    img.src = imgSrc;
+  });
+
+  return img;
+}
+
+/**
+ * Replaces all supported image & font URLs in the given SVG with their base64 representation.
+ */
+async function _embedAssets(svgSrc: string): Promise<string> {
+  const _imageExtensions = ['png', 'gif', 'jpg', 'jpeg', 'svg', 'bmp'];
+  const _fontExtensions = ['woff2', 'woff', 'ttf', 'otf'];
+  const _assetExtensions = [..._imageExtensions, ..._fontExtensions];
+  // Regex copied from https://stackoverflow.com/a/8943487/1273551, not "stress tested"...
+  const urlRegex = /(\bhttps?:\/\/[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/gi;
+  const allUrls = svgSrc.match(urlRegex) as string[];
+
+  const assetUrls = allUrls.filter(url => {
+    const indexParam = url.indexOf('?');
+    // remove url parameter to recognize extension
+    if (indexParam > -1) {
+      url = url.substring(0, indexParam);
+    }
+    return _assetExtensions.some(extension => url.toLowerCase().endsWith(`.${extension}`));
+  });
+  const assetBase64Fetcher = assetUrls.map(_fetchBase64AssetUrl);
+  const assetFetcherResults = await Promise.all(assetBase64Fetcher);
+  return assetFetcherResults.reduce((svgSrc, x) => svgSrc.replace(x.url, x.base64), svgSrc);
+}
+
+/**
+ * Fetch asset (image or font) and convert it to base64 string representation.
+ */
+async function _fetchBase64AssetUrl(assetUrl: string): Promise<{ url: string; base64: string }> {
+  // TODO WTT: Cache known base64 representation and only fetch/convert when not already known.
+  //           Usually the fetch shouldn't hit the network but the browser cache since the SVG was already drawn..
+  const resp = await fetch(assetUrl);
+  const blob = await resp.blob();
+
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = (event): void => {
+      const target = event.target;
+      if (!target) {
+        return reject(`Asset with URL "${assetUrl}" could not be loaded.`);
+      }
+      const result = target.result;
+      if (!result) {
+        return reject(`Asset with URL "${assetUrl}" returned an empty result.`);
+      }
+      resolve({
+        url: assetUrl,
+        base64: result.toString() as string,
+      });
+    };
+    reader.readAsDataURL(blob);
+  });
+}

package/src/internal/tagsHelper.ts

@@ -0,0 +1,41 @@
+import { Material, Node } from '../index';
+import { Tags } from '@babylonjs/core/Misc/tags';
+
+/**
+ * This is a wrapper around Babylon.js Tags API, as the API is really clunky to use
+ */
+
+type TagTarget = Node | Material;
+
+export function hasTag(object: TagTarget, tag: string): boolean {
+  return Tags.MatchesQuery(object, tag);
+}
+
+export function getTags(object: TagTarget): string[] {
+  const tagsObject = Tags.GetTags(object, false) ?? {};
+  const tags = Object.keys(tagsObject);
+
+  return tags;
+}
+
+export function setTags(object: TagTarget, tags: string[]): void {
+  const tagsString = tags.join(' ');
+  Tags.AddTagsTo(object, tagsString);
+}
+
+export function deleteAllTags(object: TagTarget): void {
+  const curTags = Tags.GetTags(object);
+  if (curTags) {
+    Tags.RemoveTagsFrom(object, curTags);
+  }
+}
+
+export function setTagsAsString(object: TagTarget, tagsString: string): void {
+  Tags.AddTagsTo(object, tagsString);
+}
+
+export function cloneTags(sourceObject: TagTarget, destinationObject: TagTarget): void {
+  if (Tags.HasTags(sourceObject)) {
+    Tags.AddTagsTo(destinationObject, Tags.GetTags(sourceObject, true));
+  }
+}

package/src/manager/cameraManager.ts

@@ -0,0 +1,236 @@
+import {
+  Animation,
+  AnimationGroup,
+  ArcRotateCamera,
+  ExcludedGeometryList,
+  Vector3,
+  Viewer,
+  ViewerEvent,
+} from '../index';
+
+export type CameraPosition = {
+  alpha: number;
+  beta: number;
+  radius: number;
+  target: Vector3;
+};
+
+export type AutofocusSettings = {
+  /** Can be used to customize the margins shown around the 3d model. Defaults to 1. */
+  radiusFactor?: number;
+  adjustWheelPrecision?: boolean;
+  adjustPanningSensibility?: boolean;
+  adjustPinchPrecision?: boolean;
+  /** Desired horizontal camera angle, this won't be overwritten by the autofocus function */
+  alpha?: number;
+  /** Desired vertical camera angle, this won't be overwritten by the autofocus function */
+  beta?: number;
+  /** Optional list of geometry to be excluded from consideration */
+  exclude?: ExcludedGeometryList;
+  durationMs?: number;
+};
+
+/**
+ * Manager for camera related tasks
+ */
+export class CameraManager {
+  public static readonly CAMERA_ANIMATION_NAME = '__cameraAnimation__';
+
+  /** @internal */
+  public static readonly DEFAULT_CAMERA_POSITION: CameraPosition = {
+    alpha: (45 * Math.PI) / 180,
+    beta: (75 * Math.PI) / 180,
+    radius: 1,
+    target: new Vector3(0, 0, 0),
+  };
+
+  protected static readonly _AUTOFOCUS_CONSTANTS = {
+    minZ: 100,
+    wheelPrecision: 100,
+    panningSensibility: 2500,
+    pinchPrecision: 200,
+  };
+
+  protected static readonly _DEFAULT_AUTOFOCUS_RADIUS_FACTOR = 1;
+  protected static readonly _DEFAULT_CAM_SPEED_MS = 250;
+
+  /** @internal */
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning
+   */
+  public async autofocusActiveCamera(settings?: AutofocusSettings): Promise<void> {
+    const activeCamera = this.viewer.scene.activeCamera;
+
+    if (!(activeCamera instanceof ArcRotateCamera)) {
+      throw new Error(`Camera type "${activeCamera?.getClassName()}" is not implemented for "autofocusActiveCamera".`);
+    }
+
+    // get bounding box of all visible meshes, this is the base for the autofocus algorithm
+    const boundingInfo = this.viewer.calculateBoundingInfo(settings?.exclude);
+    // optionally show bounding sphere for debugging purpose
+    this.viewer.eventManager.fireEvent(ViewerEvent.AutofocusStart, boundingInfo.boundingSphere);
+
+    const radius = boundingInfo.boundingSphere.radius;
+    const center = boundingInfo.boundingSphere.center;
+
+    // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
+    activeCamera.lowerRadiusLimit = radius;
+
+    // additional settings
+    // constants for division are taken directly from Babylon.js repository
+    activeCamera.minZ = Math.min(radius / CameraManager._AUTOFOCUS_CONSTANTS.minZ, 1);
+    if (settings?.adjustWheelPrecision !== false) {
+      activeCamera.wheelPrecision = CameraManager._AUTOFOCUS_CONSTANTS.wheelPrecision / radius;
+    }
+    if (settings?.adjustPanningSensibility !== false) {
+      activeCamera.panningSensibility = CameraManager._AUTOFOCUS_CONSTANTS.panningSensibility / radius;
+    }
+    if (settings?.adjustPinchPrecision !== false) {
+      activeCamera.pinchPrecision = CameraManager._AUTOFOCUS_CONSTANTS.pinchPrecision / radius;
+    }
+
+    const radiusFactor = settings?.radiusFactor ?? CameraManager._DEFAULT_AUTOFOCUS_RADIUS_FACTOR;
+    const alpha = settings?.alpha ?? CameraManager.DEFAULT_CAMERA_POSITION.alpha;
+    const beta = settings?.beta ?? CameraManager.DEFAULT_CAMERA_POSITION.beta;
+
+    // calculation is taken from Babylon.js repository, which on their side took it from this SO post:
+    // http://stackoverflow.com/questions/2866350/move-camera-to-fit-3d-scene
+    // there's a good sketch which explains the calculation quite a bit
+    const aspectRatio = this.viewer.engine.getAspectRatio(activeCamera);
+    const frustumSlopeY = Math.tan(activeCamera.fov / 2);
+    const frustumSlopeX = frustumSlopeY * aspectRatio;
+
+    const distanceForHorizontalFrustum = radius * Math.sqrt(1 + 1 / (frustumSlopeX * frustumSlopeX));
+    const distanceForVerticalFrustum = radius * Math.sqrt(1 + 1 / (frustumSlopeY * frustumSlopeY));
+    const distance = Math.max(distanceForHorizontalFrustum, distanceForVerticalFrustum);
+
+    const newCameraPosition: CameraPosition = {
+      alpha: alpha,
+      beta: beta,
+      radius: distance * radiusFactor,
+      target: center,
+    };
+
+    await this.moveActiveCameraTo(newCameraPosition, settings?.durationMs);
+  }
+
+  /**
+   * Moves the active camera smoothly to certain position
+   *
+   * @param durationMs defaults to 250ms if unset, use 0 for instant movement
+   */
+  public async moveActiveCameraTo(
+    position: CameraPosition,
+    durationMs = CameraManager._DEFAULT_CAM_SPEED_MS
+  ): Promise<void> {
+    const activeCamera = this.viewer.scene.activeCamera;
+
+    if (!(activeCamera instanceof ArcRotateCamera)) {
+      throw new Error(`Camera type "${activeCamera?.getClassName()}" is not implemented yet for "moveActiveCameraTo".`);
+    }
+
+    if (durationMs === 0) {
+      // instant movement without animation
+      activeCamera.alpha = position.alpha ?? activeCamera.alpha;
+      activeCamera.beta = position.beta ?? activeCamera.beta;
+      activeCamera.radius = position.radius ?? activeCamera.radius;
+      activeCamera.target = position.target ?? activeCamera.target;
+    }
+
+    const framesPerSec = 100;
+    const animationGroup = new AnimationGroup(CameraManager.CAMERA_ANIMATION_NAME, this.viewer.scene);
+
+    if (position.alpha !== undefined) {
+      // transform the target's alpha value into the same turn as the current camera position to avoid movements
+      // > 360 degrees
+      const alphaGap = activeCamera.alpha - position.alpha;
+      const cntTurns = Math.round(alphaGap / (2 * Math.PI));
+      const targetAlpha = position.alpha + 2 * Math.PI * cntTurns;
+
+      CameraManager._addCameraAnimationToGroup(
+        'alpha',
+        activeCamera.alpha,
+        targetAlpha,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_FLOAT,
+        animationGroup,
+        activeCamera
+      );
+    }
+    if (position.beta !== undefined) {
+      CameraManager._addCameraAnimationToGroup(
+        'beta',
+        activeCamera.beta,
+        position.beta,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_FLOAT,
+        animationGroup,
+        activeCamera
+      );
+    }
+    if (position.radius !== undefined) {
+      CameraManager._addCameraAnimationToGroup(
+        'radius',
+        activeCamera.radius,
+        position.radius,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_FLOAT,
+        animationGroup,
+        activeCamera
+      );
+    }
+    if (position.target !== undefined) {
+      CameraManager._addCameraAnimationToGroup(
+        'target',
+        activeCamera.target,
+        position.target,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_VECTOR3,
+        animationGroup,
+        activeCamera
+      );
+    }
+
+    // animation is created for 1 second (100 frames), adjust speed ratio according to desired movement time
+    const speedRatio = 1000 / durationMs;
+
+    return new Promise<void>(resolve => {
+      animationGroup.onAnimationGroupEndObservable.addOnce(() => {
+        animationGroup.dispose();
+        resolve();
+      });
+      animationGroup.start(false, speedRatio, 0, 100);
+    });
+  }
+
+  protected static _addCameraAnimationToGroup(
+    targetProperty: string,
+    from: number | Vector3,
+    to: number | Vector3,
+    framesPerSec: number,
+    dataType: number,
+    animationGroup: AnimationGroup,
+    activeCamera: ArcRotateCamera
+  ): void {
+    const alphaAnimation = new Animation(
+      targetProperty,
+      targetProperty,
+      framesPerSec,
+      dataType,
+      Animation.ANIMATIONLOOPMODE_CONSTANT
+    );
+    alphaAnimation.setKeys([
+      {
+        frame: 0,
+        value: from,
+      },
+      {
+        frame: 100,
+        value: to,
+      },
+    ]);
+    animationGroup.addTargetedAnimation(alphaAnimation, activeCamera);
+  }
+}