@inweb/markup 25.8.16 → 25.8.19

package/lib/markup/IMarkup.d.ts

@@ -3,7 +3,7 @@ import { IViewpoint } from "@inweb/viewer-core";
 import { IWorldTransform } from "./IWorldTransform";
 import { IMarkupObject } from "./IMarkupObject";
 /**
- * Markup edit mode. Matches the type of markup object being created or object selecting mode.
+ * Defines the markup edit mode. Matches the type of markup object being created.
  */
 export type MarkupMode = "SelectMarkup" | "Line" | "Text" | "Rectangle" | "Ellipse" | "Arrow" | "Image" | "Cloud";
 /**
@@ -11,30 +11,35 @@ export type MarkupMode = "SelectMarkup" | "Line" | "Text" | "Rectangle" | "Ellip
  */
 export interface IMarkup {
     /**
-     * Line width of the markup objects. Default is 4.
+     * Line width of new markup objects.
+     *
+     * @default 4
      */
     lineWidth: number;
     /**
-     * Type of the markup line. Available types: `solid`, `dot`, `dash`. Default is `solid`.
+     * Line type of new markup objects. Can be `solid`, `dot` or `dash`.
+     *
+     * @default `solid`
      */
     lineType: string;
     /**
-     * Font size of the markup text. Default is 34 px.
+     * Font size of new markup text, in pixels.
+     *
+     * @default 34
      */
     fontSize: number;
     /**
-     * Initializes the markup instance.
+     * Initializes the markup instance. Call {@link dispose | dispose()} to release allocated resources.
      *
-     * @param container - Container element used to operate on. This is usually a `canvas` or
-     *   `div` on top of which the markup is drawn. If the `container` is an element of type
-     *   {@link https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement | HTMLCanvasElement},
+     * @param container - Container element used to operate on. This is usually a `<canvas>` or
+     *   `<div>` on top of which the markup is drawn. If the `container` is a `<canvas>` element,
      *   its content will be combined with the markup in the viewpoint snapshot.
      * @param pointerEvents - List of pointing device events that the markup should redirect to
      *   the `viewer`.
      * @param viewer - `Viewer` instance that receives pointing device events.
      * @param worldTransformer - Transformer of screen space into the `viewer` world space and
-     *   vice versa. If a transformer is defined, viewpoint objects will be stored in world
-     *   coordinates, otherwise in screen coordinates.
+     *   vice versa. If a transformer is defined, markup objects will be stored at the viewpoint
+     *   in world coordinates, otherwise in screen coordinates.
      */
     initialize(container: HTMLElement, pointerEvents?: string[], viewer?: IEventEmitter, worldTransformer?: IWorldTransform): void;
     /**
@@ -42,15 +47,15 @@ export interface IMarkup {
      */
     dispose(): void;
     /**
-     * Create markup overlay.
+     * Creates the markup overlay.
      */
     syncOverlay(): void;
     /**
-     * Clear markup overlay.
+     * Deletes all markup objects and clears the markup overlay.
      */
     clearOverlay(): void;
     /**
-     * Set markup color.
+     * Sets the color of new markup objects.
      *
      * @param r - `Red` part of color.
      * @param g - `Green` part of color.
@@ -58,9 +63,7 @@ export interface IMarkup {
      */
     setMarkupColor(r: number, g: number, b: number): void;
     /**
-     * Get markup color.
-     *
-     * @returns Color with `RGB` values.
+     * Returns the color of new markup objects.
      */
     getMarkupColor(): {
         r: number;
@@ -68,7 +71,7 @@ export interface IMarkup {
         b: number;
     };
     /**
-     * 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.
@@ -76,7 +79,7 @@ export interface IMarkup {
      */
     colorizeAllMarkup(r: number, g: number, b: number): void;
     /**
-     * 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.
@@ -84,45 +87,46 @@ export interface IMarkup {
      */
     colorizeSelectedMarkups(r: number, g: number, b: number): void;
     /**
-     * Draw a viewpoint. To get a list of available model viewpoints, use the
+     * Sets the markup state to the specified viewpoint.
      *
      * @param viewpoint - Viewpoint data.
      */
     setViewpoint(viewpoint: IViewpoint): void;
     /**
-     * Create a viewpoint.
+     * Saves the markup state at the viewpoint.
      */
     getViewpoint(): IViewpoint;
     /**
      * Enables mouse interactions to select or draw markups.
      *
-     * @param mode - Edit mode. Matches the type of markup object being created or object
-     *   selecting mode. To exit edit mode provide this to `false`.
+     * @param mode - Edit mode. Matches the type of markup object being created. Specify `false`
+     *   to exit edit mode.
      */
     enableEditMode(mode: MarkupMode | false): this;
     /**
-     * Create a Markup object.
+     * Creates a markup object.
      *
-     * @param type - string identificator of Markup object type.
+     * @param type - Markup object type. Can be `Line`, `Text`, `Rectangle`, `Ellipse`, `Arrow`,
+     *   `Image` or `Cloud`.
      * @param params - Markup object parameters.
      */
     createObject(type: string, params: any): IMarkupObject;
     /**
-     * Get Markup objects.
+     * Returns the list of all markup objects.
      */
     getObjects(): IMarkupObject[];
     /**
-     * Get selected Markup objects.
+     * Returns the list of selected markup objects.
      */
     getSelectedObjects(): IMarkupObject[];
     /**
-     * Select Markup objects.
+     * Selects specified markup objects.
      *
-     * @param objects
+     * @param objects - The list of markup objects.
      */
     selectObjects(objects: IMarkupObject[]): void;
     /**
-     * Clear Markup objects selection.
+     * Clears the markup objects selection.
      */
     clearSelected(): void;
 }

package/lib/markup/IMarkupLine.d.ts

@@ -1,7 +1,7 @@
 import { IMarkupObject } from "./IMarkupObject";
 import { IMarkupColorable } from "./IMarkupColorable";
 /**
- * Type of the markup line.
+ * Defines the type of the markup line.
  */
 export type MarkupLineType = "solid" | "dot" | "dash";
 /**

package/lib/markup/IWorldTransform.d.ts

@@ -5,7 +5,7 @@ export interface IWorldTransform {
     /**
      * Transforms `position` from screen space into world space.
      *
-     * @param position - screen position in pixels.
+     * @param position - Screen position in pixels.
      */
     screenToWorld(position: {
         x: number;
@@ -18,7 +18,7 @@ export interface IWorldTransform {
     /**
      * Transforms `position` from world space into screen space.
      *
-     * @param position - position in world space coordinates.
+     * @param position - Position in world space coordinates.
      */
     worldToScreen(position: {
         x: number;

package/lib/markup/Konva/KonvaImage.d.ts

@@ -3,6 +3,7 @@ export declare class KonvaImage implements IMarkupImage {
     private _ref;
     private _canvasImage;
     private _ratio;
+    private readonly EPSILON;
     constructor(params: {
         position: {
             x: number;
@@ -11,6 +12,8 @@ export declare class KonvaImage implements IMarkupImage {
         src: string;
         width?: number;
         height?: number;
+        maxWidth?: number;
+        maxHeight?: number;
         id?: string;
     }, ref?: any);
     getSrc(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/markup",
-  "version": "25.8.16",
+  "version": "25.8.19",
   "description": "JavaScript 2D markups",
   "homepage": "https://cloud.opendesign.com/docs/index.html",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,8 +26,8 @@
     "docs": "typedoc"
   },
   "dependencies": {
-    "@inweb/eventemitter2": "~25.8.16",
-    "@inweb/viewer-core": "~25.8.16"
+    "@inweb/eventemitter2": "~25.8.19",
+    "@inweb/viewer-core": "~25.8.19"
   },
   "devDependencies": {
     "konva": "^9.2.0"

package/src/markup/IMarkup.ts

@@ -27,7 +27,7 @@ import { IWorldTransform } from "./IWorldTransform";
 import { IMarkupObject } from "./IMarkupObject";
 
 /**
- * Markup edit mode. Matches the type of markup object being created or object selecting mode.
+ * Defines the markup edit mode. Matches the type of markup object being created.
  */
 export type MarkupMode = "SelectMarkup" | "Line" | "Text" | "Rectangle" | "Ellipse" | "Arrow" | "Image" | "Cloud";
 
@@ -36,33 +36,38 @@ export type MarkupMode = "SelectMarkup" | "Line" | "Text" | "Rectangle" | "Ellip
  */
 export interface IMarkup {
   /**
-   * Line width of the markup objects. Default is 4.
+   * Line width of new markup objects.
+   *
+   * @default 4
    */
   lineWidth: number;
 
   /**
-   * Type of the markup line. Available types: `solid`, `dot`, `dash`. Default is `solid`.
+   * Line type of new markup objects. Can be `solid`, `dot` or `dash`.
+   *
+   * @default `solid`
    */
   lineType: string;
 
   /**
-   * Font size of the markup text. Default is 34 px.
+   * Font size of new markup text, in pixels.
+   *
+   * @default 34
    */
   fontSize: number;
 
   /**
-   * Initializes the markup instance.
+   * Initializes the markup instance. Call {@link dispose | dispose()} to release allocated resources.
    *
-   * @param container - Container element used to operate on. This is usually a `canvas` or
-   *   `div` on top of which the markup is drawn. If the `container` is an element of type
-   *   {@link https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement | HTMLCanvasElement},
+   * @param container - Container element used to operate on. This is usually a `<canvas>` or
+   *   `<div>` on top of which the markup is drawn. If the `container` is a `<canvas>` element,
    *   its content will be combined with the markup in the viewpoint snapshot.
    * @param pointerEvents - List of pointing device events that the markup should redirect to
    *   the `viewer`.
    * @param viewer - `Viewer` instance that receives pointing device events.
    * @param worldTransformer - Transformer of screen space into the `viewer` world space and
-   *   vice versa. If a transformer is defined, viewpoint objects will be stored in world
-   *   coordinates, otherwise in screen coordinates.
+   *   vice versa. If a transformer is defined, markup objects will be stored at the viewpoint
+   *   in world coordinates, otherwise in screen coordinates.
    */
   initialize(
     container: HTMLElement,
@@ -77,17 +82,17 @@ export interface IMarkup {
   dispose(): void;
 
   /**
-   * Create markup overlay.
+   * Creates the markup overlay.
    */
   syncOverlay(): void;
 
   /**
-   * Clear markup overlay.
+   * Deletes all markup objects and clears the markup overlay.
    */
   clearOverlay(): void;
 
   /**
-   * Set markup color.
+   * Sets the color of new markup objects.
    *
    * @param r - `Red` part of color.
    * @param g - `Green` part of color.
@@ -96,14 +101,12 @@ export interface IMarkup {
   setMarkupColor(r: number, g: number, b: number): void;
 
   /**
-   * Get markup color.
-   *
-   * @returns Color with `RGB` values.
+   * Returns the color of new markup objects.
    */
   getMarkupColor(): { r: number; g: number; b: number };
 
   /**
-   * 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.
@@ -112,7 +115,7 @@ export interface IMarkup {
   colorizeAllMarkup(r: number, g: number, b: number): void;
 
   /**
-   * 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.
@@ -121,52 +124,53 @@ export interface IMarkup {
   colorizeSelectedMarkups(r: number, g: number, b: number): void;
 
   /**
-   * Draw a viewpoint. To get a list of available model viewpoints, use the
+   * Sets the markup state to the specified viewpoint.
    *
    * @param viewpoint - Viewpoint data.
    */
   setViewpoint(viewpoint: IViewpoint): void;
 
   /**
-   * Create a viewpoint.
+   * Saves the markup state at the viewpoint.
    */
   getViewpoint(): IViewpoint;
 
   /**
    * Enables mouse interactions to select or draw markups.
    *
-   * @param mode - Edit mode. Matches the type of markup object being created or object
-   *   selecting mode. To exit edit mode provide this to `false`.
+   * @param mode - Edit mode. Matches the type of markup object being created. Specify `false`
+   *   to exit edit mode.
    */
   enableEditMode(mode: MarkupMode | false): this;
 
   /**
-   * Create a Markup object.
+   * Creates a markup object.
    *
-   * @param type - string identificator of Markup object type.
+   * @param type - Markup object type. Can be `Line`, `Text`, `Rectangle`, `Ellipse`, `Arrow`,
+   *   `Image` or `Cloud`.
    * @param params - Markup object parameters.
    */
   createObject(type: string, params: any): IMarkupObject;
 
   /**
-   * Get Markup objects.
+   * Returns the list of all markup objects.
    */
   getObjects(): IMarkupObject[];
 
   /**
-   * Get selected Markup objects.
+   * Returns the list of selected markup objects.
    */
   getSelectedObjects(): IMarkupObject[];
 
   /**
-   * Select Markup objects.
+   * Selects specified markup objects.
    *
-   * @param objects
+   * @param objects - The list of markup objects.
    */
   selectObjects(objects: IMarkupObject[]): void;
 
   /**
-   * Clear Markup objects selection.
+   * Clears the markup objects selection.
    */
   clearSelected(): void;
 }

package/src/markup/IMarkupLine.ts

@@ -25,7 +25,7 @@ import { IMarkupObject } from "./IMarkupObject";
 import { IMarkupColorable } from "./IMarkupColorable";
 
 /**
- * Type of the markup line.
+ * Defines the type of the markup line.
  */
 export type MarkupLineType = "solid" | "dot" | "dash";
 

package/src/markup/IWorldTransform.ts

@@ -28,14 +28,14 @@ export interface IWorldTransform {
   /**
    * Transforms `position` from screen space into world space.
    *
-   * @param position - screen position in pixels.
+   * @param position - Screen position in pixels.
    */
   screenToWorld(position: { x: number; y: number }): { x: number; y: number; z: number };
 
   /**
    * Transforms `position` from world space into screen space.
    *
-   * @param position - position in world space coordinates.
+   * @param position - Position in world space coordinates.
    */
   worldToScreen(position: { x: number; y: number; z: number }): { x: number; y: number };
 

package/src/markup/Konva/KonvaImage.ts

@@ -5,6 +5,7 @@ export class KonvaImage implements IMarkupImage {
   private _ref: Konva.Image;
   private _canvasImage: HTMLImageElement;
   private _ratio = 1;
+  private readonly EPSILON = 10e-6;
 
   constructor(
     params: {
@@ -12,6 +13,8 @@ export class KonvaImage implements IMarkupImage {
       src: string;
       width?: number;
       height?: number;
+      maxWidth?: number;
+      maxHeight?: number;
       id?: string;
     },
     ref = null
@@ -21,7 +24,10 @@ export class KonvaImage implements IMarkupImage {
 
       this._ref = ref;
       this._canvasImage = ref.image();
-      this._ratio = this._ref.height() === 0 || this._ref.width() === 0 ? 1 : this._ref.height() / this._ref.width();
+      this._ratio =
+        this._ref.height() <= this.EPSILON || this._ref.width() <= this.EPSILON
+          ? 1
+          : this._ref.height() / this._ref.width();
       return;
     }
 
@@ -40,9 +46,32 @@ export class KonvaImage implements IMarkupImage {
 
     this._canvasImage.onload = () => {
       this._ref.image(this._canvasImage);
-      if (this._ref.height() === 0) this._ref.height(this._canvasImage.height);
-      if (this._ref.width() === 0) this._ref.width(this._canvasImage.width);
-      this._ratio = this._ref.height() === 0 || this._ref.width() === 0 ? 1 : this._ref.height() / this._ref.width();
+      if (this._ref.height() <= this.EPSILON) this._ref.height(this._canvasImage.height);
+      if (this._ref.width() <= this.EPSILON) this._ref.width(this._canvasImage.width);
+
+      this._ratio =
+        this._ref.height() <= this.EPSILON || this._ref.width() <= this.EPSILON
+          ? 1
+          : this._ref.height() / this._ref.width();
+
+      // need to rescale only if input width and height are 0 - we do not loading Viewpoint with existing params
+      if (
+        (params.width <= this.EPSILON || params.height <= this.EPSILON) &&
+        (params.maxWidth >= this.EPSILON || params.maxWidth >= this.EPSILON)
+      ) {
+        const heightOutOfCanvas = params.maxHeight - this._canvasImage.height;
+        const widthOutOfCanvas = params.maxWidth - this._canvasImage.width;
+
+        if (heightOutOfCanvas <= this.EPSILON || widthOutOfCanvas <= this.EPSILON) {
+          if (widthOutOfCanvas <= this.EPSILON && widthOutOfCanvas < heightOutOfCanvas / this._ratio) {
+            this._ref.height(params.maxWidth * this._ratio);
+            this._ref.width(params.maxWidth);
+          } else {
+            this._ref.width(params.maxHeight / this._ratio);
+            this._ref.height(params.maxHeight);
+          }
+        }
+      }
     };
 
     this._canvasImage.src = params.src;

package/src/markup/Konva/KonvaMarkup.ts

@@ -1103,6 +1103,8 @@ export class KonvaMarkup implements IMarkup {
       src,
       width,
       height,
+      maxWidth: this._konvaStage.width() - position.x,
+      maxHeight: this._konvaStage.height() - position.y,
       id,
     });