@inweb/viewer-core 25.8.20 → 25.8.21

package/lib/viewer/IViewpoint.d.ts

@@ -1,181 +1,450 @@
 /**
- * BCF-style Location of the Viewpoint
- */
-export interface ILocation {
-    x: number;
-    y: number;
-    z: number;
-}
-/**
- * BCF-style Direction of the Viewpoint
+ * Defines the 3D direction vector. Direction must not be a zero vector.
  */
 export interface IDirection {
+    /**
+     * X direction.
+     */
     x: number;
+    /**
+     * Y direction.
+     */
     y: number;
+    /**
+     * Z direction.
+     */
     z: number;
 }
 /**
- * BCF-style Point of the Viewpoint
+ * Defines the 3D point.
  */
 export interface IPoint {
+    /**
+     * X coordinate.
+     */
     x: number;
+    /**
+     * Y coordinate.
+     */
     y: number;
+    /**
+     * Z coordinate.
+     */
     z: number;
 }
 /**
- * BCF-style Bitmap of the Viewpoint
+ * Defines the embedded picture in the viewpoint.
  */
 export interface IBitmap {
+    /**
+     * GUID for identifying bitmap uniquely.
+     */
     guid: string;
-    location: ILocation;
+    /**
+     * Location of the center of the bitmap in world coordinates.
+     */
+    location: IPoint;
+    /**
+     * Normal vector of the bitmap.
+     */
     normal: IDirection;
+    /**
+     * Up vector of the bitmap.
+     */
     up: IDirection;
+    /**
+     * Height of the bitmap in the model, in meters.
+     */
     height: number;
 }
 /**
- * BCF-style Orthogonal Camera of the Viewpoint
+ * Describes a viewpoint using an orthogonal camera.
  */
 export interface IOrthogonalCamera {
+    /**
+     * Camera location.
+     */
     view_point: IPoint;
+    /**
+     * Camera direction.
+     */
     direction: IDirection;
+    /**
+     * Camera up vector.
+     */
     up_vector: IDirection;
+    /**
+     * View field width to calculate aspect ratio.
+     */
     field_width: number;
+    /**
+     * View field height to calculate aspect ratio.
+     */
     field_height: number;
 }
 /**
- * BCF-style Clipping Plane of the Viewpoint
+ * Defines the subsection of a model (clipping plane).
  */
 export interface IClippingPlane {
-    location: ILocation;
+    /**
+     * Origin of the clipping plane.
+     */
+    location: IPoint;
+    /**
+     * Direction of the clipping plane. The Direction vector points in the _invisible_ direction
+     * meaning the half-space that is clipped.
+     */
     direction: IDirection;
 }
 /**
- * BCF-style Perspective Camera of the Viewpoint
+ * Describes a viewpoint using an perspective camera.
  */
 export interface IPerspectiveCamera {
+    /**
+     * Camera location.
+     */
     view_point: IPoint;
+    /**
+     * Camera direction.
+     */
     direction: IDirection;
+    /**
+     * Camera up vector.
+     */
     up_vector: IDirection;
+    /**
+     * The entire vertical field of view angle of the camera, expressed in degrees. Valid range 0
+     * to 180 exclusive.
+     */
     field_of_view: number;
 }
 /**
- * BCF-style markup Line object of the Viewpoint
+ * Defines the markup line object of the viewpoint.
  */
 export interface ILine {
+    /**
+     * Array of line points.
+     */
     points: IPoint[];
+    /**
+     * Line type. Can be `solid`, `dot` or `dash`.
+     *
+     * @default "solid"
+     */
     type?: string;
+    /**
+     * Line width.
+     */
     width?: number;
+    /**
+     * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color?: string;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
- * BCF-style markup Text object of the Viewpoint
+ * Defines the markup text object of the viewpoint.
  */
 export interface IText {
+    /**
+     * Coordinates of the top-left point (position) of the text.
+     */
     position: IPoint;
+    /**
+     * Text string.
+     */
     text: string;
+    /**
+     * Text rotation angle of the object, in degress.
+     */
     angle?: number;
+    /**
+     * Font size of the text.
+     */
     font_size?: number;
+    /**
+     * Deprecated. Use {@link font_size} instead.
+     */
     text_size?: number;
+    /**
+     * Text color in hexadecimal color syntax `#RGB` using its primary color components (red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color?: string;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
- * Arrow markup object of the Viewpoint
+ * Defines the markup arrow object of the viewpoint.
  */
 export interface IArrow {
+    /**
+     * Coordinales of the start point of arrow.
+     */
     start: IPoint;
+    /**
+     * Coordinales of the end point of arrow.
+     */
     end: IPoint;
+    /**
+     * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color?: string;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
- * Cloud markup object of the Viewpoint
+ * Defines the markup cloud object of the viewpoint.
  */
 export interface ICloud {
+    /**
+     * Coordinates of the top-left point (position) of the cloud.
+     */
     position: IPoint;
+    /**
+     * Width of the cloud.
+     */
     width?: number;
+    /**
+     * Height of the cloud.
+     */
     height?: number;
+    /**
+     * Line width of the cloud.
+     */
     line_width?: number;
+    /**
+     * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color?: string;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
- * Ellipse markup object of the Viewpoint
+ * Defines the markup ellipse object of the viewpoint.
  */
 export interface IEllipse {
+    /**
+     * Coordinates of the center point (position) of the ellipse.
+     */
     position: IPoint;
+    /**
+     * Ellipse radius along the X and Y axes.
+     */
     radius: {
         x: number;
         y: number;
     };
+    /**
+     * Line width of the ellipse.
+     */
     line_width?: number;
+    /**
+     * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color?: string;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
- * Image markup object of the Viewpoint
+ * Defines the markup image object of the viewpoint.
  */
 export interface IImage {
+    /**
+     * Coordinates of the top-left point (position) of the image.
+     */
     position: IPoint;
+    /**
+     * Image source as base64-encoded
+     * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
+     */
     src: string;
-    width: number;
-    height: number;
+    /**
+     * Width of the image.
+     */
+    width?: number;
+    /**
+     * Height of the image.
+     */
+    height?: number;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
  * Rectangle markup object of the Viewpoint
  */
 export interface IRectangle {
+    /**
+     * Coordinates of the top-left point (position) of the rectangle.
+     */
     position: IPoint;
+    /**
+     * Width of the rectangle.
+     */
     width?: number;
+    /**
+     * Height of the rectangle.
+     */
     height?: number;
+    /**
+     * Line width of the rectangle.
+     */
     line_width?: number;
+    /**
+     * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color?: string;
+    /**
+     * Internal markup object identifier.
+     */
     id?: string;
 }
 /**
- * BCF-style Coloring of the Viewpoint
+ * Defines the viewpoint colored components.
  */
 export interface IColoring {
+    /**
+     * Component original handle in the model.
+     */
     handle: string;
+    /**
+     * Color in hexadecimal color syntax `#ARGB` using its primary color components (alpha, red,
+     * green, blue) written as hexadecimal numbers.
+     */
     color: string;
 }
 /**
- * BCF-style Entity of the Viewpoint
+ * Defines the component in the model.
  */
-export interface IEntity {
+export interface IComponent {
+    /**
+     * Component original handle in the model.
+     */
     handle: string;
 }
 /**
- * BCF-style Snapshot of the Viewpoint
+ * Defines the viewpoint shapshot.
  */
 export interface ISnapshot {
+    /**
+     * Snapshot image data as base64-encoded
+     * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
+     */
     data: string;
 }
 /**
- * BCF-style Viewpoint with markup objects.
+ * Defines the model viewpoint with markup.
+ *
+ * This viewpoint is {@link https://github.com/buildingSMART/BCF-API | BCF-compatible}.
+ *
+ * Optional/mandatory fields clarification:
+ *
+ * - A viewpoint must contain a _camera definition_.
+ * - _Camera definition_ is exactly one of `perspective_camera` or `orthogonal_camera`.
  */
 export interface IViewpoint {
+    /**
+     * Embedded pictures in the viewpoint. A list of bitmaps can be used to add more information,
+     * for example, text in the visualization.
+     */
     bitmaps?: IBitmap[];
+    /**
+     * GUID for identifying viewpoint uniquely.
+     */
     guid?: string;
+    /**
+     * Identifier of the file for which the viewpoint was created.
+     */
     file_id?: string;
+    /**
+     * Identifier of the assembly for which the viewpoint was created.
+     */
     assembly_id?: string;
+    /**
+     * Orthogonal camera view.
+     */
     orthogonal_camera?: IOrthogonalCamera;
+    /**
+     * Perspective view of the camera.
+     */
     perspective_camera?: IPerspectiveCamera;
+    /**
+     * Viewpoint description.
+     */
     description?: string;
+    /**
+     * Viewpoint index (sort order).
+     */
     index?: number;
+    /**
+     * List of markup Line objects.
+     */
     lines?: ILine[];
+    /**
+     * List of markup Texts objects.
+     */
     texts?: IText[];
+    /**
+     * Clipping planes for the model view.
+     */
     clipping_planes?: IClippingPlane[];
-    selection?: IEntity[];
-    visibility?: IEntity[];
+    /**
+     * Selected components.
+     */
+    selection?: IComponent[];
+    /**
+     * Visibility of components.
+     */
+    visibility?: IComponent[];
+    /**
+     * Colored components.
+     */
     coloring?: IColoring[];
+    /**
+     * List of markup Arrow objects.
+     */
     arrows?: IArrow[];
+    /**
+     * List of markup Cloud objects.
+     */
     clouds?: ICloud[];
+    /**
+     * List of markup Ellipse objects.
+     */
     ellipses?: IEllipse[];
+    /**
+     * List of markup Image objects.
+     */
     images?: IImage[];
+    /**
+     * List of markup Rectangle objects.
+     */
     rectangles?: IRectangle[];
+    /**
+     * Viewpoint custom fields object, to store custom data.
+     */
     custom_fields?: any;
+    /**
+     * Snapshot image of the viewpoint. The longest dimension of should not exceed 1500 px,
+     * length or width.
+     */
     snapshot?: ISnapshot;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/viewer-core",
-  "version": "25.8.20",
+  "version": "25.8.21",
   "description": "3D CAD and BIM data Viewer core",
   "homepage": "https://cloud.opendesign.com/docs/index.html",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,9 +26,9 @@
     "test": "karma start karma.conf.js"
   },
   "devDependencies": {
-    "@inweb/eventemitter2": "~25.8.20"
+    "@inweb/eventemitter2": "~25.8.21"
   },
   "peerDependencies": {
-    "@inweb/eventemitter2": "~25.8.20"
+    "@inweb/eventemitter2": "~25.8.21"
   }
 }

package/src/viewer/IViewpoint.ts

@@ -22,140 +22,343 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * BCF-style Location of the Viewpoint
- */
-export interface ILocation {
-  x: number;
-  y: number;
-  z: number;
-}
-
-/**
- * BCF-style Direction of the Viewpoint
+ * Defines the 3D direction vector. Direction must not be a zero vector.
  */
 export interface IDirection {
+  /**
+   * X direction.
+   */
   x: number;
+
+  /**
+   * Y direction.
+   */
   y: number;
+
+  /**
+   * Z direction.
+   */
   z: number;
 }
 
 /**
- * BCF-style Point of the Viewpoint
+ * Defines the 3D point.
  */
 export interface IPoint {
+  /**
+   * X coordinate.
+   */
   x: number;
+
+  /**
+   * Y coordinate.
+   */
   y: number;
+
+  /**
+   * Z coordinate.
+   */
   z: number;
 }
 
 /**
- * BCF-style Bitmap of the Viewpoint
+ * Defines the embedded picture in the viewpoint.
  */
 export interface IBitmap {
+  /**
+   * GUID for identifying bitmap uniquely.
+   */
   guid: string;
-  location: ILocation;
+
+  /**
+   * Location of the center of the bitmap in world coordinates.
+   */
+  location: IPoint;
+
+  /**
+   * Normal vector of the bitmap.
+   */
   normal: IDirection;
+
+  /**
+   * Up vector of the bitmap.
+   */
   up: IDirection;
+
+  /**
+   * Height of the bitmap in the model, in meters.
+   */
   height: number;
 }
 
 /**
- * BCF-style Orthogonal Camera of the Viewpoint
+ * Describes a viewpoint using an orthogonal camera.
  */
 export interface IOrthogonalCamera {
+  /**
+   * Camera location.
+   */
   view_point: IPoint;
+
+  /**
+   * Camera direction.
+   */
   direction: IDirection;
+
+  /**
+   * Camera up vector.
+   */
   up_vector: IDirection;
+
+  /**
+   * View field width to calculate aspect ratio.
+   */
   field_width: number;
+
+  /**
+   * View field height to calculate aspect ratio.
+   */
   field_height: number;
 }
 
 /**
- * BCF-style Clipping Plane of the Viewpoint
+ * Defines the subsection of a model (clipping plane).
  */
 export interface IClippingPlane {
-  location: ILocation;
+  /**
+   * Origin of the clipping plane.
+   */
+  location: IPoint;
+
+  /**
+   * Direction of the clipping plane. The Direction vector points in the _invisible_ direction
+   * meaning the half-space that is clipped.
+   */
   direction: IDirection;
 }
 
 /**
- * BCF-style Perspective Camera of the Viewpoint
+ * Describes a viewpoint using an perspective camera.
  */
 export interface IPerspectiveCamera {
+  /**
+   * Camera location.
+   */
   view_point: IPoint;
+
+  /**
+   * Camera direction.
+   */
   direction: IDirection;
+
+  /**
+   * Camera up vector.
+   */
   up_vector: IDirection;
+
+  /**
+   * The entire vertical field of view angle of the camera, expressed in degrees. Valid range 0
+   * to 180 exclusive.
+   */
   field_of_view: number;
 }
 
 /**
- * BCF-style markup Line object of the Viewpoint
+ * Defines the markup line object of the viewpoint.
  */
 export interface ILine {
+  /**
+   * Array of line points.
+   */
   points: IPoint[];
+
+  /**
+   * Line type. Can be `solid`, `dot` or `dash`.
+   *
+   * @default "solid"
+   */
   type?: string;
+
+  /**
+   * Line width.
+   */
   width?: number;
+
+  /**
+   * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
 /**
- * BCF-style markup Text object of the Viewpoint
+ * Defines the markup text object of the viewpoint.
  */
 export interface IText {
+  /**
+   * Coordinates of the top-left point (position) of the text.
+   */
   position: IPoint;
+
+  /**
+   * Text string.
+   */
   text: string;
+
+  /**
+   * Text rotation angle of the object, in degress.
+   */
   angle?: number;
+
+  /**
+   * Font size of the text.
+   */
   font_size?: number;
+
+  /**
+   * Deprecated. Use {@link font_size} instead.
+   */
+
   text_size?: number;
+
+  /**
+   * Text color in hexadecimal color syntax `#RGB` using its primary color components (red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
 /**
- * Arrow markup object of the Viewpoint
+ * Defines the markup arrow object of the viewpoint.
  */
 export interface IArrow {
+  /**
+   * Coordinales of the start point of arrow.
+   */
   start: IPoint;
+
+  /**
+   * Coordinales of the end point of arrow.
+   */
   end: IPoint;
+
+  /**
+   * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
 /**
- * Cloud markup object of the Viewpoint
+ * Defines the markup cloud object of the viewpoint.
  */
 export interface ICloud {
+  /**
+   * Coordinates of the top-left point (position) of the cloud.
+   */
   position: IPoint;
+
+  /**
+   * Width of the cloud.
+   */
   width?: number;
+
+  /**
+   * Height of the cloud.
+   */
   height?: number;
+
+  /**
+   * Line width of the cloud.
+   */
   line_width?: number;
+
+  /**
+   * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
 /**
- * Ellipse markup object of the Viewpoint
+ * Defines the markup ellipse object of the viewpoint.
  */
 export interface IEllipse {
+  /**
+   * Coordinates of the center point (position) of the ellipse.
+   */
   position: IPoint;
-  radius: {
-    x: number;
-    y: number;
-  };
+
+  /**
+   * Ellipse radius along the X and Y axes.
+   */
+  radius: { x: number; y: number };
+
+  /**
+   * Line width of the ellipse.
+   */
   line_width?: number;
+
+  /**
+   * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
 /**
- * Image markup object of the Viewpoint
+ * Defines the markup image object of the viewpoint.
  */
 export interface IImage {
+  /**
+   * Coordinates of the top-left point (position) of the image.
+   */
   position: IPoint;
+
+  /**
+   * Image source as base64-encoded
+   * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
+   */
   src: string;
-  width: number;
-  height: number;
+
+  /**
+   * Width of the image.
+   */
+  width?: number;
+
+  /**
+   * Height of the image.
+   */
+  height?: number;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
@@ -163,59 +366,190 @@ export interface IImage {
  * Rectangle markup object of the Viewpoint
  */
 export interface IRectangle {
+  /**
+   * Coordinates of the top-left point (position) of the rectangle.
+   */
   position: IPoint;
+
+  /**
+   * Width of the rectangle.
+   */
   width?: number;
+
+  /**
+   * Height of the rectangle.
+   */
   height?: number;
+
+  /**
+   * Line width of the rectangle.
+   */
   line_width?: number;
+
+  /**
+   * Line color in hexadecimal color syntax `#RGB` using its primary color components (red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color?: string;
+
+  /**
+   * Internal markup object identifier.
+   */
   id?: string;
 }
 
 /**
- * BCF-style Coloring of the Viewpoint
+ * Defines the viewpoint colored components.
  */
 export interface IColoring {
+  /**
+   * Component original handle in the model.
+   */
   handle: string;
+
+  /**
+   * Color in hexadecimal color syntax `#ARGB` using its primary color components (alpha, red,
+   * green, blue) written as hexadecimal numbers.
+   */
   color: string;
 }
 
 /**
- * BCF-style Entity of the Viewpoint
+ * Defines the component in the model.
  */
-export interface IEntity {
+export interface IComponent {
+  /**
+   * Component original handle in the model.
+   */
   handle: string;
 }
 
 /**
- * BCF-style Snapshot of the Viewpoint
+ * Defines the viewpoint shapshot.
  */
 export interface ISnapshot {
+  /**
+   * Snapshot image data as base64-encoded
+   * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
+   */
   data: string;
 }
 
 /**
- * BCF-style Viewpoint with markup objects.
+ * Defines the model viewpoint with markup.
+ *
+ * This viewpoint is {@link https://github.com/buildingSMART/BCF-API | BCF-compatible}.
+ *
+ * Optional/mandatory fields clarification:
+ *
+ * - A viewpoint must contain a _camera definition_.
+ * - _Camera definition_ is exactly one of `perspective_camera` or `orthogonal_camera`.
  */
 export interface IViewpoint {
+  /**
+   * Embedded pictures in the viewpoint. A list of bitmaps can be used to add more information,
+   * for example, text in the visualization.
+   */
   bitmaps?: IBitmap[];
+
+  /**
+   * GUID for identifying viewpoint uniquely.
+   */
   guid?: string;
+
+  /**
+   * Identifier of the file for which the viewpoint was created.
+   */
   file_id?: string;
+
+  /**
+   * Identifier of the assembly for which the viewpoint was created.
+   */
   assembly_id?: string;
+
+  /**
+   * Orthogonal camera view.
+   */
   orthogonal_camera?: IOrthogonalCamera;
+
+  /**
+   * Perspective view of the camera.
+   */
   perspective_camera?: IPerspectiveCamera;
+
+  /**
+   * Viewpoint description.
+   */
   description?: string;
+
+  /**
+   * Viewpoint index (sort order).
+   */
   index?: number;
+
+  /**
+   * List of markup Line objects.
+   */
   lines?: ILine[];
+
+  /**
+   * List of markup Texts objects.
+   */
   texts?: IText[];
+
+  /**
+   * Clipping planes for the model view.
+   */
   clipping_planes?: IClippingPlane[];
-  selection?: IEntity[];
-  visibility?: IEntity[];
+
+  /**
+   * Selected components.
+   */
+  selection?: IComponent[];
+
+  /**
+   * Visibility of components.
+   */
+  visibility?: IComponent[];
+
+  /**
+   * Colored components.
+   */
   coloring?: IColoring[];
+
+  /**
+   * List of markup Arrow objects.
+   */
   arrows?: IArrow[];
+
+  /**
+   * List of markup Cloud objects.
+   */
   clouds?: ICloud[];
+
+  /**
+   * List of markup Ellipse objects.
+   */
   ellipses?: IEllipse[];
+
+  /**
+   * List of markup Image objects.
+   */
   images?: IImage[];
+
+  /**
+   * List of markup Rectangle objects.
+   */
   rectangles?: IRectangle[];
+
+  /**
+   * Viewpoint custom fields object, to store custom data.
+   */
   custom_fields?: any;
+
+  /**
+   * Snapshot image of the viewpoint. The longest dimension of should not exceed 1500 px,
+   * length or width.
+   */
   snapshot?: ISnapshot;
 }