@inweb/viewer-core/src/viewer/IViewpoint.ts

3D CAD and BIM data Viewer core

///////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2002-2025, 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-2025 by Open Design Alliance.
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

/**
 * 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;
}

/**
 * Defines the 3D point.
 */
export interface IPoint {
  /**
   * X coordinate.
   */
  x: number;

  /**
   * Y coordinate.
   */
  y: number;

  /**
   * Z coordinate.
   */
  z: number;
}

/**
 * Defines the embedded picture in the viewpoint.
 */
export interface IBitmap {
  /**
   * GUID for identifying bitmap uniquely.
   */
  guid: string;

  /**
   * 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;
}

/**
 * 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;

  /**
   * The entire vertical scaling from view to world.
   */
  view_to_world_scale: number;
}

/**
 * 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;
}

/**
 * Defines the subsection of a model (clipping plane).
 */
export interface IClippingPlane {
  /**
   * 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;
}

/**
 * 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;
}

/**
 * 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;
}

/**
 * Defines the markup arrow object of the viewpoint.
 */
export interface IArrow {
  /**
   * Coordinates of the start point of arrow.
   */
  start: IPoint;

  /**
   * Coordinates 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;
}

/**
 * Defines the markup cloud object of the viewpoint.
 */
export interface ICloud {
  /**
   * Coordinates of the top-left point (position) of the cloud.
   */
  position: IPoint;

  /**
   * Coordinates of the bottom-right point of the rectangle.
   */
  position2: IPoint;

  /**
   * Deprecated. Use {@link position2} instead. Width of the cloud.
   */
  width?: number;

  /**
   * Deprecated. Use {@link position2} instead. 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;
}

/**
 * Defines the markup ellipse object of the viewpoint.
 */
export interface IEllipse {
  /**
   * Coordinates of the center point (position) of the ellipse.
   */
  position: IPoint;

  /**
   * Coordinates of point of A radius of the ellipse.
   */
  position2: IPoint;

  /**
   * Coordinates of point of B radius of the ellipse.
   */
  position3: IPoint;

  /**
   * Deprecated. Use {@link position2} and {@link position3} instead. 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;
}

/**
 * Defines the markup image object of the viewpoint.
 */
export interface IImage {
  /**
   * Coordinates of the top-left point (position) of the image.
   */
  position: IPoint;

  /**
   * Coordinates of the bottom-right point (position) of the image.
   */
  position2: IPoint;

  /**
   * Image source as base64-encoded
   * {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}.
   */
  src: string;

  /**
   * Deprecated. Use {@link position2} instead. Width of the image.
   */
  width?: number;

  /**
   * Deprecated. Use {@link position2} instead. 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 of the rectangle.
   */
  position: IPoint;

  /**
   * Coordinates of the bottom-right point of the rectangle.
   */
  position2: IPoint;

  /**
   * Deprecated. Use {@link position2} instead. Width of the rectangle.
   */
  width?: number;

  /**
   * Deprecated. Use {@link position2} instead. 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;
}

/**
 * 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;
}

/**
 * Defines the entity in the model.
 */
export interface IEntity {
  /**
   * Component original handle in the model.
   */
  handle: string;
}

/**
 * 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;
}

/**
 * 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 view of the camera.
   */
  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[];

  /**
   * Selected components.
   */
  selection?: IEntity[];

  /**
   * Visibility of components.
   */
  visibility?: IEntity[];

  /**
   * 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;
}