@inweb/viewer-visualize 25.8.15 → 25.8.19

package/src/Viewer/Viewer.ts

@@ -62,7 +62,7 @@ const OVERLAY_VIEW_NAME = "$OVERLAY_VIEW_NAME";
 const isExist = (value) => value !== undefined && value !== null;
 
 /**
- * The `Client.js` library class that provides methods to integrate with the
+ * 3D viewer powered by
  * {@link https://cloud.opendesign.com/docs/index.html#/visualizejs | VisualizeJS} library.
  */
 
@@ -98,19 +98,17 @@ export class Viewer
   public client: Client | undefined;
 
   /**
-   * @param client - The `Client` instance that provides access to a server. Do not specify
-   *   `Client` if you need a standalone viewer instance without access to server models.
+   * @param client - The `Client` instance that provides access to a Open Cloud Server. Do not
+   *   specify `Client` if you need a standalone viewer instance to view `VSFX` files from the
+   *   web or from local computer.
    * @param params - An object containing viewer configuration parameters.
    * @param params.visualizeJsUrl - `VisualizeJS` library URL. Set this URL to use your own
-   *   library instance, or leave it undefined or blank to use the default URL defined by
-   *   `Client.js` you are using.
-   *
-   *   _Note: Your own `VisualizeJS` library version must match the version of the `Client.js`
-   *   you are using._
+   *   library instance, or specify `undefined` or blank to use the default URL defined by
+   *   `Viewer.visualize` library you are using.
    * @param params.enableAutoUpdate - Enable auto-update of the viewer after any changes. If
-   *   the auto-update is disabled, you need to register the `update` event handler and update
-   *   the viewer and the active dragger manually. Default is `true`.
-   * @param params.markupType - Specifies type of the markup core: `Visualize` (deprecated) or
+   *   the auto-update is disabled, you need to register an `update` event handler and update
+   *   the `VisualizeJS` viewer and active dragger manually. Default is `true`.
+   * @param params.markupType - The type of the markup core: `Visualize` (deprecated) or
    *   `Konva`. Default is `Konva`.
    */
   constructor(
@@ -157,7 +155,7 @@ export class Viewer
   /**
    * Viewer options.
    */
-  get options(): Options {
+  get options(): IOptions {
     return this._options;
   }
 
@@ -171,7 +169,7 @@ export class Viewer
   }
 
   /**
-   * 2D markup core.
+   * 2D markup core instance used to create markups.
    *
    * @readonly
    */
@@ -180,11 +178,12 @@ export class Viewer
   }
 
   /**
-   * Change the viewer configuration parameters.
+   * Changes the viewer parameters.
    *
-   * @param params - An object containing new configuration parameters.
+   * @param params - An object containing new parameters.
    * @param params.visualizeJsUrl - `VisualizeJS` library URL. Set this URL to use your own
-   *   library instance or leave it blank to use the default URL defined by `Client.js`.
+   *   library instance or specify `undefined` or blank to use the default URL defined by
+   *   `Viewer.visualize` library you are using.
    */
   configure(params: { visualizeJsUrl?: string }): this {
     this._visualizeJsUrl = params.visualizeJsUrl || "VISUALIZE_JS_URL";
@@ -192,7 +191,7 @@ export class Viewer
   }
 
   /**
-   * Load `VisualizeJS` module and initialize it with the specified canvas. Call
+   * Loads the `VisualizeJS` module and initialize it with the specified canvas. Call
    * {@link dispose | dispose()} to release allocated resources.
    *
    * Fires:
@@ -264,8 +263,8 @@ export class Viewer
   }
 
   /**
-   * Releases all resources allocated by this `Viewer` instance. Call this method before
-   * release the `Viewer` instance.
+   * Releases all resources allocated by this viewer instance. Call this method before release
+   * the `Viewer` instance.
    */
   dispose(): this {
     this.cancel();
@@ -301,7 +300,7 @@ export class Viewer
   }
 
   /**
-   * Returns `true` if `VisualizeJS` module has been loaded andinitialized.
+   * Returns `true` if `VisualizeJS` module has been loaded and initialized.
    */
   isInitialized(): boolean {
     return !!this.visualizeJs;
@@ -345,8 +344,10 @@ export class Viewer
   }
 
   /**
-   * Updates the viewer. Do nothing if the auto-update mode is disabled in the constructor (use
-   * the `update` event to update viewer manually).
+   * Updates the viewer.
+   *
+   * Do nothing if the auto-update mode is disabled in the constructor. In this case, register
+   * an `update` event handler and update the `Visualize` viewer and active dragger manually.
    *
    * Fires:
    *
@@ -367,21 +368,15 @@ export class Viewer
     this.emitEvent({ type: "update", data: force });
   }
 
-  /**
-   * Update with internal schedule, need after change operation when have long update for
-   * update without lock UI
-   *
-   * @param maxScheduleUpdateTimeInMs - Maximum time for one update, by default 30 ms
-   * @param maxScheduleUpdateCount - Maximum count of schedule update
-   * @returns return void Promise
-   */
-
   private scheduleUpdateAsync(maxScheduleUpdateTimeInMs = 50): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       setTimeout(() => {
         try {
-          this.visViewer()?.update(maxScheduleUpdateTimeInMs);
-          this.activeDragger()?.updatePreview();
+          if (this._enableAutoUpdate) {
+            this.visViewer()?.update(maxScheduleUpdateTimeInMs);
+            this.activeDragger()?.updatePreview();
+          }
+          this.emitEvent({ type: "update", data: false });
           resolve();
         } catch (e) {
           console.error(e);
@@ -391,6 +386,20 @@ export class Viewer
     });
   }
 
+  /**
+   * Updates the viewer asynchronously without locking the user interface. Used to update the
+   * viewer after changes that require a long rendering time.
+   *
+   * Do nothing if the auto-update mode is disabled in the constructor. In this case, register
+   * an `update` event handler and update the `VisualizeJS` viewer and active dragger manually.
+   *
+   * Fires:
+   *
+   * - {@link UpdateEvent | update}
+   *
+   * @param maxScheduleUpdateTimeInMs - Maximum time for one update, default 30 ms.
+   * @param maxScheduleUpdateCount - Maximum count of scheduled updates.
+   */
   async updateAsync(maxScheduleUpdateTimeInMs = 50, maxScheduleUpdateCount = 50): Promise<void> {
     this._isRunAsyncUpdate = true;
     const device = this.visViewer().getActiveDevice();
@@ -611,7 +620,7 @@ export class Viewer
   }
 
   /**
-   * List of names of available draggers:
+   * List of names of registered draggers. By default, the following draggers are registered:
    *
    * - `Line`
    * - `Text`
@@ -633,7 +642,8 @@ export class Viewer
   }
 
   /**
-   * Register dragger on draggerFactory.
+   * Registers a dragger for the viewer. Dragger is an object that received mouse/keyboard
+   * events and does something to the viewer.
    *
    * @param name - Dragger name.
    * @param dragger - Dragger class.
@@ -650,7 +660,7 @@ export class Viewer
   }
 
   /**
-   * Set active dragger. `Viewer` must be initialized before enable dragger or exception is thrown.
+   * Changes the active dragger. Viewer must be initialized before enable dragger or exception is thrown.
    *
    * Fires:
    *
@@ -688,7 +698,7 @@ export class Viewer
   }
 
   /**
-   * Reset the state of the active dragger.
+   * Resets the state of the active dragger.
    */
   resetActiveDragger(): void {
     const dragger = this._activeDragger;
@@ -699,7 +709,7 @@ export class Viewer
   }
 
   /**
-   * Remove all cutting planes.
+   * Removes all cutting planes.
    */
   clearSlices(): void {
     if (!this.visualizeJs) return;
@@ -713,7 +723,7 @@ export class Viewer
   }
 
   /**
-   * Clear overlay view.
+   * Clears the overlay view.
    */
   clearOverlay(): void {
     if (!this.visualizeJs) return;
@@ -723,7 +733,7 @@ export class Viewer
   }
 
   /**
-   * Create overlay view.
+   * Creates an overlay view. Overlay view is used to draw cutting planes and `Visualize` markups.
    */
   syncOverlay(): any {
     if (!this.visualizeJs) return;
@@ -758,7 +768,7 @@ export class Viewer
   }
 
   /**
-   * Returns `true` if current drawing is 3D drawing.
+   * Returns `true` if current model is 3D model.
    */
   is3D(): boolean {
     if (!this.visualizeJs) return false;
@@ -776,12 +786,16 @@ export class Viewer
   screenToWorld(position: { x: number; y: number }): { x: number; y: number; z: number } {
     if (!this.visualizeJs) return { x: position.x, y: position.y, z: 0 };
 
-    const worldPoint = this.visViewer().screenToWorld(
+    const activeView = this.visViewer().activeView;
+    const worldPoint = activeView.transformScreenToWorld(
       position.x * window.devicePixelRatio,
       position.y * window.devicePixelRatio
     );
+
     const result = { x: worldPoint[0], y: worldPoint[1], z: worldPoint[2] };
 
+    activeView.delete();
+
     return result;
   }
 
@@ -789,15 +803,10 @@ export class Viewer
     if (!this.visualizeJs) return { x: position.x, y: position.y };
 
     const activeView = this.visViewer().activeView;
-    const worldMatrix = activeView.worldToDeviceMatrix;
-    const worldPoint = this.visLib().Point3d.createFromArray([position.x, position.y, position.z]);
+    const devicePoint = activeView.transformWorldToScreen(position.x, position.y, position.z);
 
-    const devicePoint = worldPoint.transformBy(worldMatrix);
-    const result = { x: devicePoint.x / window.devicePixelRatio, y: devicePoint.y / window.devicePixelRatio };
+    const result = { x: devicePoint[0] / window.devicePixelRatio, y: devicePoint[1] / window.devicePixelRatio };
 
-    devicePoint.delete();
-    worldPoint.delete();
-    worldMatrix.delete();
     activeView.delete();
 
     return result;
@@ -822,16 +831,14 @@ export class Viewer
   }
 
   /**
-   * Returns a list of original handles for the selected entities.
+   * Returns a list of original handles for the selected objects.
    */
   getSelected(): string[] {
     return this.executeCommand("getSelected");
   }
 
   /**
-   * Select model entities by original handles that are obtained using
-   * {@link File.getProperties | File.getProperties()} or
-   * {@link File.searchProperties | File.searchProperties()} methods.
+   * Selects the model objects by original handles that are obtained using `File.searchProperties()`.
    *
    * Fires:
    *
@@ -843,13 +850,8 @@ export class Viewer
     this.executeCommand("setSelected", handles);
   }
 
-  /**
-   * Load model references into the viewer. References are images, fonts, or any other files to
-   * correct rendering of the model.
-   *
-   * @param model - Instance of model with references. If a `File` instance is specified
-   *   instead of a model, the file references will be loaded.
-   */
+  // Internal loading routines
+
   async loadReferences(model: Model | File | Assembly): Promise<this> {
     if (!this.visualizeJs) return this;
     if (!this.client) return this;
@@ -874,8 +876,6 @@ export class Viewer
     return this;
   }
 
-  // Internal loading routines
-
   applyModelTransformMatrix(model: Model | Assembly) {
     this.executeCommand("applyModelTransform", model);
   }
@@ -899,7 +899,7 @@ export class Viewer
   }
 
   /**
-   * Loads a model of a file or assembly into the viewer.
+   * Loads a model/file/assembly into the viewer.
    *
    * This method requires a {@link Client} instance to work. For standalone viewer instance use
    * {@link openVsfFile | openVsfFile()} or {@link openVsfxFile | openVsfxFile()}.
@@ -934,7 +934,7 @@ export class Viewer
     if (!model) throw new Error("No default model found");
 
     const overrideOptions = new Options();
-    overrideOptions.data = this.options.data;
+    overrideOptions.data = this._options.data;
     if (file.type === ".rcs" && !overrideOptions.enablePartialMode) {
       console.log("Partial load mode is forced for RCS file");
       overrideOptions.enablePartialMode = true;
@@ -955,7 +955,7 @@ export class Viewer
   }
 
   /**
-   * Loads a VSF file into the viewer.
+   * Loads a `VSF` file into the viewer.
    *
    * Fires:
    *
@@ -1001,7 +1001,7 @@ export class Viewer
   }
 
   /**
-   * Loads a VSFX file into the viewer.
+   * Loads a `VSFX` file into the viewer.
    *
    * Fires:
    *
@@ -1065,7 +1065,7 @@ export class Viewer
   }
 
   /**
-   * Unloads the model and clears the viewer.
+   * Unloads the model and clears the viewer and markups.
    */
   clear(): this {
     if (!this.visualizeJs) return this;
@@ -1088,16 +1088,18 @@ export class Viewer
   }
 
   /**
-   * Get markup color.
-   *
-   * @returns Color with `RGB` values.
+   * Returns the color of new markup objects.
    */
   getMarkupColor(): { r: number; g: number; b: number } {
     return this._markup.getMarkupColor();
   }
 
   /**
-   * Set markup color.
+   * Sets the color of new markup objects.
+   *
+   * Fires:
+   *
+   * - {@link ChangeMarkupColorEvent | changemarkupcolor}
    *
    * @param r - `Red` part of color.
    * @param g - `Green` part of color.
@@ -1110,7 +1112,7 @@ export class Viewer
   }
 
   /**
-   * Colorize all markup entities with the specified color.
+   * Colors all markup objects with the specified color.
    *
    * @param r - `Red` part of color.
    * @param g - `Green` part of color.
@@ -1121,7 +1123,7 @@ export class Viewer
   }
 
   /**
-   * Colorize all selected markup entities with the specified color.
+   * Colors selected markup objects with the specified color.
    *
    * @param r - `Red` part of color.
    * @param g - `Green` part of color.
@@ -1132,7 +1134,7 @@ export class Viewer
   }
 
   /**
-   * Add an empty markup entity to the overlay.
+   * Adds an empty `Visualize` markup entity to the overlay.
    */
   addMarkupEntity(entityName: string) {
     if (!this.visualizeJs) return null;
@@ -1155,8 +1157,9 @@ export class Viewer
   }
 
   /**
-   * Draw a viewpoint. To get a list of available model viewpoints, use the
-   * `Model.getViewpoints()` or `File.getViewpoints()` or `Assembly.getViewpoints()`.
+   * Sets the viewer state to the specified viewpoint.
+   *
+   * To get a list of available model viewpoints, use the `File.getViewpoints()`.
    *
    * @param viewpoint - Viewpoint data.
    */
@@ -1167,8 +1170,9 @@ export class Viewer
   }
 
   /**
-   * Create a viewpoint. To add a viewpoint to the list of model viewpoints, use the
-   * `Model.saveViewpoint()` or `File.saveViewpoint()` or . `Assembly.saveViewpoint()`.
+   * Saves the viewer state at the viewpoint.
+   *
+   * To save a viewpoint to a model on the server, use the `File.saveViewpoint()`.
    */
   createViewpoint(): IViewpoint {
     const vp = this._markup.getViewpoint();