@inweb/viewer-three 25.12.0 → 26.1.0

package/src/Viewer/commands/index.ts

@@ -21,25 +21,101 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
-import "./ApplyModelTransform";
-import "./ClearMarkup";
-import "./ClearSelected";
-import "./ClearSlices";
-import "./CreatePreview";
-import "./Explode";
-import "./GetDefaultViewPositions";
-import "./GetModels";
-import "./GetSelected";
-import "./HideSelected";
-import "./IsolateSelected";
-import "./RegenerateAll";
-import "./ResetView";
-import "./SelectModel";
-import "./SetActiveDragger";
-import "./SetDefaultViewPosition";
-import "./SetMarkupColor";
-import "./SetSelected";
-import "./ShowAll";
-import "./ZoomToExtents";
-import "./ZoomToObjects";
-import "./ZoomToSelected";
+import { ICommandsRegistry, commandsRegistry } from "@inweb/viewer-core";
+
+import { applyModelTransform } from "./ApplyModelTransform";
+import { clearMarkup } from "./ClearMarkup";
+import { clearSelected } from "./ClearSelected";
+import { clearSlices } from "./ClearSlices";
+import { createPreview } from "./CreatePreview";
+import { explode, collect } from "./Explode";
+import { getDefaultViewPositions } from "./GetDefaultViewPositions";
+import { getModels } from "./GetModels";
+import { getSelected } from "./GetSelected";
+import { hideSelected } from "./HideSelected";
+import { isolateSelected } from "./IsolateSelected";
+import { regenerateAll } from "./RegenerateAll";
+import { resetView } from "./ResetView";
+import { selectModel } from "./SelectModel";
+import { setActiveDragger } from "./SetActiveDragger";
+import { setDefaultViewPosition } from "./SetDefaultViewPosition";
+import { setMarkupColor } from "./SetMarkupColor";
+import { setSelected } from "./SetSelected";
+import { showAll } from "./ShowAll";
+import { zoomToExtents } from "./ZoomToExtents";
+import { zoomToObjects } from "./ZoomToObjects";
+import { zoomToSelected } from "./ZoomToSelected";
+
+/**
+ * A commands registry. Use this registry to register custom commands.
+ *
+ * To implement custom command:
+ *
+ * 1. Define a command handler with a first `viewer` parameter.
+ * 2. Register command handler in the commands registry by calling the {@link commands.registerCommand}.
+ *
+ * @example <caption>Implementing a custom command.</caption>
+ *   import { commands, Viewer } from "@inweb/viewer-three";
+ *
+ *   function commandHandler(viewer: Viewer, name = "world"): void {
+ *     console.log(`Hello ${name}!!!`);
+ *   }
+ *
+ *   commands.registerCommand("sayHello", commandHandler);
+ *
+ * @example <caption>Calling a custom command.</caption>
+ *   viewer.executeCommand("sayHello", "user");
+ */
+export const commands: ICommandsRegistry = commandsRegistry("threejs");
+
+// build-in commands
+
+commands.registerCommand("applyModelTransform", applyModelTransform);
+commands.registerCommand("clearMarkup", clearMarkup);
+commands.registerCommand("clearSelected", clearSelected);
+commands.registerCommand("clearSlices", clearSlices);
+commands.registerCommand("createPreview", createPreview);
+commands.registerCommand("explode", explode);
+commands.registerCommand("collect", collect);
+commands.registerCommand("getDefaultViewPositions", getDefaultViewPositions);
+commands.registerCommand("getModels", getModels);
+commands.registerCommand("getSelected", getSelected);
+commands.registerCommand("hideSelected", hideSelected);
+commands.registerCommand("isolateSelected", isolateSelected);
+commands.registerCommand("regenerateAll", regenerateAll);
+commands.registerCommand("resetView", resetView);
+commands.registerCommand("selectModel", selectModel);
+commands.registerCommand("setActiveDragger", setActiveDragger);
+commands.registerCommand("setDefaultViewPosition", setDefaultViewPosition);
+commands.registerCommand("setMarkupColor", setMarkupColor);
+commands.registerCommand("setSelected", setSelected);
+commands.registerCommand("showAll", showAll);
+commands.registerCommand("zoomToExtents", zoomToExtents);
+commands.registerCommand("zoomToObjects", zoomToObjects);
+commands.registerCommand("zoomToSelected", zoomToSelected);
+
+commands.registerCommand("top", (viewer) => setDefaultViewPosition(viewer, "top"));
+commands.registerCommand("bottom", (viewer) => setDefaultViewPosition(viewer, "bottom"));
+commands.registerCommand("left", (viewer) => setDefaultViewPosition(viewer, "left"));
+commands.registerCommand("right", (viewer) => setDefaultViewPosition(viewer, "right"));
+commands.registerCommand("front", (viewer) => setDefaultViewPosition(viewer, "front"));
+commands.registerCommand("back", (viewer) => setDefaultViewPosition(viewer, "back"));
+commands.registerCommand("sw", (viewer) => setDefaultViewPosition(viewer, "sw"));
+commands.registerCommand("se", (viewer) => setDefaultViewPosition(viewer, "se"));
+commands.registerCommand("ne", (viewer) => setDefaultViewPosition(viewer, "ne"));
+commands.registerCommand("nw", (viewer) => setDefaultViewPosition(viewer, "nw"));
+
+commands.registerCommandAlias("clearMarkup", "clearOverlay");
+commands.registerCommandAlias("clearSelected", "unselect");
+commands.registerCommandAlias("zoomToExtents", "zoomExtents");
+
+commands.registerCommandAlias("top", "k3DViewTop");
+commands.registerCommandAlias("bottom", "k3DViewBottom");
+commands.registerCommandAlias("left", "k3DViewLeft");
+commands.registerCommandAlias("right", "k3DViewRight");
+commands.registerCommandAlias("front", "k3DViewFront");
+commands.registerCommandAlias("back", "k3DViewBack");
+commands.registerCommandAlias("se", "k3DViewSE");
+commands.registerCommandAlias("sw", "k3DViewSW");
+commands.registerCommandAlias("ne", "k3DViewNE");
+commands.registerCommandAlias("nw", "k3DViewNW");

package/src/Viewer/components/AxesHelperComponent.ts

@@ -23,10 +23,10 @@
 
 import { AxesHelper, Vector3 } from "three";
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class AxesHelperComponent implements IDisposable {
+export class AxesHelperComponent implements IComponent {
   private viewer: Viewer;
   private axesHelper1: AxesHelper;
   private axesHelper2: AxesHelper;

package/src/Viewer/components/BackgroundComponent.ts

@@ -24,10 +24,10 @@
 import { Color, PMREMGenerator } from "three";
 import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class BackgroundComponent implements IDisposable {
+export class BackgroundComponent implements IComponent {
   protected viewer: Viewer;
   protected backgroundColor: Color;
 

package/src/Viewer/components/DefaultPositionComponent.ts

@@ -23,11 +23,10 @@
 
 import { Vector3 } from "three";
 
-import { GeometryEndEvent } from "@inweb/viewer-core";
-import { IDisposable } from "../IDisposable";
+import { GeometryEndEvent, IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class DefaultPositionComponent implements IDisposable {
+export class DefaultPositionComponent implements IComponent {
   protected viewer: Viewer;
   public defaultCameraPositions: any;
 

package/src/Viewer/components/ExtentsComponent.ts

@@ -23,10 +23,10 @@
 
 import { Box3, Vector3 } from "three";
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class ExtentsComponent implements IDisposable {
+export class ExtentsComponent implements IComponent {
   private viewer: Viewer;
 
   constructor(viewer: Viewer) {

package/src/Viewer/components/ExtentsHelperComponent.ts

@@ -23,10 +23,10 @@
 
 import { Box3, Box3Helper, Color } from "three";
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class ExtentsHelperComponent implements IDisposable {
+export class ExtentsHelperComponent implements IComponent {
   private viewer: Viewer;
   private boxHelper: Box3Helper;
 

package/src/Viewer/components/LightComponent.ts

@@ -23,10 +23,10 @@
 
 import { AmbientLight, DirectionalLight } from "three";
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class LightComponent implements IDisposable {
+export class LightComponent implements IComponent {
   protected viewer: Viewer;
   protected ambientLight: AmbientLight;
   protected directionalLight: DirectionalLight;

package/src/Viewer/components/RenderLoopComponent.ts

@@ -21,10 +21,10 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class RenderLoopComponent implements IDisposable {
+export class RenderLoopComponent implements IComponent {
   protected viewer: Viewer;
   protected requestId: number;
 

package/src/Viewer/components/ResizeCanvasComponent.ts

@@ -21,10 +21,10 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class ResizeCanvasComponent implements IDisposable {
+export class ResizeCanvasComponent implements IComponent {
   protected viewer: Viewer;
   protected resizeObserver: ResizeObserver;
 

package/src/Viewer/components/SelectionComponent.ts

@@ -23,10 +23,10 @@
 
 import { Intersection, MeshBasicMaterial, Object3D, Raycaster, Vector2 } from "three";
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
-export class SelectionComponent implements IDisposable {
+export class SelectionComponent implements IComponent {
   protected viewer: Viewer;
   protected raycaster: Raycaster;
   protected downPosition: Vector2;

package/src/Viewer/components/ViewPositionComponent.ts

@@ -23,8 +23,7 @@
 
 import { Euler, Quaternion, Object3D, Vector3 } from "three";
 
-import { CommandEvent, RenderEvent } from "@inweb/viewer-core";
-import { IDisposable } from "../IDisposable";
+import { CommandEvent, IComponent, RenderEvent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 
 export const defaultViewPositions = {
@@ -40,7 +39,7 @@ export const defaultViewPositions = {
   nw: new Vector3(-0.5, 0.5, 1.0).normalize(),
 };
 
-export class ViewPositionComponent implements IDisposable {
+export class ViewPositionComponent implements IComponent {
   private position: string;
   private center: Vector3;
   private targetPosition: Vector3;

package/src/Viewer/components/WCSHelperComponent.ts

@@ -21,11 +21,11 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
-import { IDisposable } from "../IDisposable";
+import { IComponent } from "@inweb/viewer-core";
 import type { Viewer } from "../Viewer";
 import { WCSHelper } from "../helpers/WCSHelper";
 
-export class WCSHelperComponent implements IDisposable {
+export class WCSHelperComponent implements IComponent {
   private wcsHelper: WCSHelper;
   private viewer: Viewer;
 

package/src/Viewer/components/index.ts

@@ -0,0 +1,91 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import { IComponentsRegistry, componentsRegistry } from "@inweb/viewer-core";
+
+// import { AxesHelperComponent } from "./AxesHelperComponent";
+import { BackgroundComponent } from "./BackgroundComponent";
+import { DefaultPositionComponent } from "./DefaultPositionComponent";
+import { ExtentsComponent } from "./ExtentsComponent";
+// import { ExtentsHelperComponent } from "./ExtentsHelperComponent";
+import { LightComponent } from "./LightComponent";
+import { RenderLoopComponent } from "./RenderLoopComponent";
+import { ResizeCanvasComponent } from "./ResizeCanvasComponent";
+import { SelectionComponent } from "./SelectionComponent";
+// import { ViewPositionComponent } from "./ViewPositionComponent";
+import { WCSHelperComponent } from "./WCSHelperComponent";
+
+/**
+ * Viewer components registry. Use this registry to register custom components.
+ *
+ * To implement custom component:
+ *
+ * 1. Define a component class implements {@link IComponent}.
+ * 2. Define a constructor with a `viewer` parameter and add mouse event listeners for the specified viewer.
+ * 3. Define the component logic in the event listeners. For example, listen for the `mousedown`
+ *    event and select objects when the left mouse button is pressed.
+ * 4. Override {@link IComponent.dispose} and remove mouse event listeners from the viewer.
+ * 5. Register component provider in the components registry by calling the
+ *    {@link components.registerComponent}.
+ *
+ * @example <caption>Implementing a custom component.</caption>
+ *   import { IComponent, components, Viewer } from "@inweb/viewer-three";
+ *
+ *   class MyComponent implements IComponent {
+ *     protected viewer: Viewer;
+ *
+ *     constructor(viewer: Viewer) {
+ *       this.viewer = viewer;
+ *       this.viewer.addEventListener("mousedown", this.onMouseDown);
+ *     }
+ *
+ *     override dispose() {
+ *       this.viewer.removeEventListener("mousedown", this.onMouseDown);
+ *     }
+ *
+ *     onMouseDown = (event: PointerEvent) => {
+ *       // place custom logic here
+ *     };
+ *   }
+ *
+ *   components.registerComponent(
+ *     "MyComponent",
+ *     (viewer): IComponent => new MyComponent(viewer)
+ *   );
+ */
+export const components: IComponentsRegistry = componentsRegistry("threejs");
+
+// build-in components
+
+components.registerComponent("ExtentsComponent", (viewer) => new ExtentsComponent(viewer));
+components.registerComponent("LightComponent", (viewer) => new LightComponent(viewer));
+components.registerComponent("BackgroundComponent", (viewer) => new BackgroundComponent(viewer));
+components.registerComponent("ResizeCanvasComponent", (viewer) => new ResizeCanvasComponent(viewer));
+components.registerComponent("RenderLoopComponent", (viewer) => new RenderLoopComponent(viewer));
+components.registerComponent("DefaultPositionComponent", (viewer) => new DefaultPositionComponent(viewer));
+components.registerComponent("SelectionComponent", (viewer) => new SelectionComponent(viewer));
+components.registerComponent("WCSHelperComponent", (viewer) => new WCSHelperComponent(viewer));
+
+// components.registerComponent("AxesHelperComponent", (viewer) => new AxesHelperComponent(viewer));
+// components.registerComponent("ExtentsHelperComponent", (viewer) => new ExtentsHelperComponent(viewer));
+// components.registerComponent("ViewPositionComponent", (viewer) => new ViewPositionComponent(viewer));

package/src/Viewer/draggers/OrbitDragger.ts

@@ -22,12 +22,12 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { MOUSE, TOUCH } from "three";
+import { type IDragger } from "@inweb/viewer-core";
 
-import type { IDisposable } from "../IDisposable";
 import type { Viewer } from "../Viewer";
 import { OrbitControls, STATE } from "../controls/OrbitControls.js";
 
-export class OrbitDragger implements IDisposable {
+export class OrbitDragger implements IDragger {
   protected viewer: Viewer;
   protected orbit: OrbitControls;
   protected changed: boolean;
@@ -57,6 +57,7 @@ export class OrbitDragger implements IDisposable {
     this.viewer.off("drawviewpoint", this.updateControls);
     this.viewer.off("contextmenu", this.stopContextMenu);
 
+    this.orbit.removeEventListener("start", this.controlsStart);
     this.orbit.removeEventListener("change", this.controlsChange);
     this.orbit.dispose();
   }

package/src/Viewer/draggers/WalkDragger.ts

@@ -22,11 +22,12 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { Vector3 } from "three";
+import { type IDragger } from "@inweb/viewer-core";
 
 import type { Viewer } from "../Viewer";
 import { WalkControls } from "../controls/WalkControls";
 
-export class WalkDragger {
+export class WalkDragger implements IDragger {
   protected viewer: Viewer;
   public controls: WalkControls;
 

package/src/Viewer/draggers/index.ts

@@ -0,0 +1,83 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import { IDraggersRegistry, draggersRegistry } from "@inweb/viewer-core";
+
+import { CuttingPlaneXAxisDragger } from "./CuttingPlaneXAxis";
+import { CuttingPlaneYAxisDragger } from "./CuttingPlaneYAxis";
+import { CuttingPlaneZAxisDragger } from "./CuttingPlaneZAxis";
+import { MeasureLineDragger } from "./MeasureLineDragger";
+import { OrbitDragger } from "./OrbitDragger";
+import { PanDragger } from "./PanDragger";
+import { WalkDragger } from "./WalkDragger";
+import { ZoomDragger } from "./ZoomDragger";
+
+/**
+ * Viewer draggers registry. Use this registry to register custom draggers.
+ *
+ * To implement custom dragger:
+ *
+ * 1. Define a dragger class implements {@link IDragger}.
+ * 2. Define a constructor with a `viewer` parameter and add mouse event listeners for the specified viewer.
+ * 3. Define the dragger logic in the event listeners. For example, listen for the `mousemove`
+ *    event and zoom in/out when the left mouse button is pressed.
+ * 4. Override {@link IDragger.dispose} and remove mouse event listeners from the viewer.
+ * 5. Register dragger provider in the draggers registry by calling the {@link draggers.registerDragger}.
+ *
+ * @example <caption>Implementing a custom dragger.</caption>
+ *   import { IDragger, draggers, Viewer } from "@inweb/viewer-three";
+ *
+ *   class MyDragger implements IDragger {
+ *     protected viewer: Viewer;
+ *
+ *     constructor(viewer: Viewer) {
+ *       this.viewer = viewer;
+ *       this.viewer.addEventListener("pointermove", this.onPointerMove);
+ *     }
+ *
+ *     override dispose() {
+ *       this.viewer.removeEventListener("pointermove", this.onPointerMove);
+ *     }
+ *
+ *     onPointerMove = (event: PointerEvent) => {
+ *       // place custom logic here
+ *     };
+ *   }
+ *
+ *   draggers.registerDragger("MyDragger", (viewer): IDragger => new MyDragger(viewer));
+ *
+ * @example <caption>Activating a custom dragger.</caption>
+ *   viewer.setActiveDragger("MyDragger");
+ */
+export const draggers: IDraggersRegistry = draggersRegistry("threejs");
+
+// build-in draggers
+
+draggers.registerDragger("Pan", (viewer) => new PanDragger(viewer));
+draggers.registerDragger("Orbit", (viewer) => new OrbitDragger(viewer));
+draggers.registerDragger("Zoom", (viewer) => new ZoomDragger(viewer));
+draggers.registerDragger("MeasureLine", (viewer) => new MeasureLineDragger(viewer));
+draggers.registerDragger("CuttingPlaneXAxis", (viewer) => new CuttingPlaneXAxisDragger(viewer));
+draggers.registerDragger("CuttingPlaneYAxis", (viewer) => new CuttingPlaneYAxisDragger(viewer));
+draggers.registerDragger("CuttingPlaneZAxis", (viewer) => new CuttingPlaneZAxisDragger(viewer));
+draggers.registerDragger("Walk", (viewer) => new WalkDragger(viewer));

package/src/index.ts

@@ -21,7 +21,10 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
-import "./Viewer/commands";
-
 export * from "@inweb/viewer-core";
+export * from "@inweb/markup";
+
+export { draggers } from "./Viewer/draggers";
+export { commands } from "./Viewer/commands";
+export { components } from "./Viewer/components";
 export { Viewer } from "./Viewer/Viewer";

package/lib/Viewer/IDisposable.d.ts

@@ -1,6 +0,0 @@
-/**
- * An object that performs a cleanup operation when `.dispose()` is called.
- */
-export interface IDisposable {
-    dispose(): void;
-}

package/src/Viewer/IDisposable.ts

@@ -1,29 +0,0 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
-// All rights reserved.
-//
-// This software and its documentation and related materials are owned by
-// the Alliance. The software may only be incorporated into application
-// programs owned by members of the Alliance, subject to a signed
-// Membership Agreement and Supplemental Software License Agreement with the
-// Alliance. The structure and organization of this software are the valuable
-// trade secrets of the Alliance and its suppliers. The software is also
-// protected by copyright law and international treaty provisions. Application
-// programs incorporating this software must include the following statement
-// with their copyright notices:
-//
-//   This application incorporates Open Design Alliance software pursuant to a
-//   license agreement with Open Design Alliance.
-//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
-//   All rights reserved.
-//
-// By use of this software, its documentation or related materials, you
-// acknowledge and accept the above terms.
-///////////////////////////////////////////////////////////////////////////////
-
-/**
- * An object that performs a cleanup operation when `.dispose()` is called.
- */
-export interface IDisposable {
-  dispose(): void;
-}