@inweb/viewer-core/src/options/IOptions.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.
///////////////////////////////////////////////////////////////////////////////

export interface RGB {
  red: number;
  green: number;
  blue: number;
}

/**
 * Viewer options interface.
 */
export interface IOptions {
  /**
   * Show the world coordinate system axes in the bottom-left corner of the viewer.
   *
   * @defaultValue true
   */
  showWCS?: boolean;

  /**
   * Enable camera animation.
   *
   * @defaultValue true
   */
  cameraAnimation?: boolean;

  /**
   * Enable anti-aliasing. Can be one of:
   *
   * - `false` - Disable anti-aliasing.
   * - `true` - Enable anti-aliasing using MSAA.
   * - `fxaa` - Enable Fast Approximate anti-aliasing (FXAA).
   * - `smaa` - Enable Subpixel Morphological anti-aliasing (SMAA).
   * - `msaa` - Enable Multisample anti-aliasing (MSAA), if the underlying WebGL context supports it.
   *
   * @defaultValue true
   */
  antialiasing?: boolean | string;

  /**
   * Show ground shadows below the model.
   *
   * @defaultValue false
   */
  groundShadow?: boolean;

  /**
   * Enable ambient shadows.
   *
   * @defaultValue false
   */
  shadows?: boolean;

  /**
   * Camera speed on X axis.
   *
   * @defaultValue 4
   */
  cameraAxisXSpeed?: number;

  /**
   * Camera speed on Y axis.
   *
   * @defaultValue 1
   */
  cameraAxisYSpeed?: number;

  /**
   * Enable ambient occlusion.
   *
   * @defaultValue false
   */
  ambientOcclusion?: boolean;

  /**
   * Enable streaming of drawings from the server.
   *
   * If streaming is disabled, the file/assembly will be loaded in one go. The viewer will only update
   * once the loading is complete, which may take a while.
   *
   * If streaming is enabled, {@link enablePartialMode | partial streaming} mode may be enabled as well.
   *
   * @defaultValue true
   */
  enableStreamingMode?: boolean;

  /**
   * Enable partial streaming mode to be able open large drawing.
   *
   * In partial streaming mode, the viewer keeps only visible objects in memory and loads other objects
   * when the camera changes.
   *
   * Only used if {@link enableStreamingMode | streaming} is enabled. If partial streaming is enabled,
   * then {@link sceneGraph | scene graph} will be disabled.
   *
   * @defaultValue false
   */
  enablePartialMode?: boolean;

  /**
   * The size of the memory buffer for graphics data, in bytes.
   *
   * @defaultValue 3294967296
   */
  memoryLimit?: number;

  /**
   * Cutting planes fill color.
   *
   * @defaultValue { red: 0xff, green: 0x98, blue: 0x00 }
   */
  cuttingPlaneFillColor?: RGB;

  /**
   * Edges highlight color.
   */
  edgesColor?: { r: number; g: number; b: number };

  /**
   * Faces highlight color.
   */
  facesColor?: { r: number; g: number; b: number };

  /**
   * Show highlighted edges.
   */
  edgesVisibility?: boolean;

  /**
   * Show highlighted edges over drawing.
   */
  edgesOverlap?: boolean;

  /**
   * Show highlighted faces over drawing.
   */
  facesOverlap?: boolean;

  /**
   * Highlighted faces transparency value, from 0 to 255.
   */
  facesTransparancy?: number;

  /**
   * Enable custom highlight settings.
   */
  enableCustomHighlight?: boolean;

  /**
   * Enable scene graph.
   *
   * Scene graph increases perfomance improvement, but consumes memory. If scene graph is enabled, then
   * {@link enablePartialMode | partial streaming} mode will be disabled.
   */
  sceneGraph: boolean;

  /**
   * Show the edges of the model:
   *
   * - `false` - No model edges are displayed. Usefull for less memory consumption.
   * - `true` - Display isolines.
   */
  edgeModel: boolean;

  /**
   * Reverse the mouse wheel direction for zooming:
   *
   * - `false` - Moving the wheel up zooms in, moving down zooms out.
   * - `true` - Moving the wheel up zooms out, moving down zooms in.
   */
  reverseZoomWheel: boolean;

  /**
   * Enable mouse wheel zooming.
   */
  enableZoomWheel: boolean;

  /**
   * Enable touch gestures.
   *
   * This option will be ignored when {@link enableZoomWheel | mouse wheel zooming} is disabled, since
   * gestures contains touch zoom.
   */
  enableGestures: boolean;

  /**
   * Deprecated since `25.8`.
   */
  geometryType?: string;

  /**
   * Ruler unit.
   *
   * Available values: Default, Millimeters, Centimeters, Meters, Feet, Inches, Yards, Kilometers, Miles,
   * Micrometers, MicroInches
   *
   * @defaultValue Default
   */
  rulerUnit: string;

  /**
   * Resets options to default values.
   *
   * @param fields - Name of fields to be reset.
   */
  resetToDefaults?: (fields?: string[]) => void;
}

export function defaultOptions(): IOptions {
  return {
    showWCS: true,
    cameraAnimation: true,
    antialiasing: true,
    groundShadow: false,
    shadows: false,
    cameraAxisXSpeed: 4,
    cameraAxisYSpeed: 1,
    ambientOcclusion: false,
    enableStreamingMode: true,
    enablePartialMode: false,
    memoryLimit: 3294967296,
    cuttingPlaneFillColor: { red: 0xff, green: 0x98, blue: 0x00 },
    edgesColor: { r: 0xff, g: 0x98, b: 0x00 },
    facesColor: { r: 0xff, g: 0x98, b: 0x00 },
    edgesVisibility: true,
    edgesOverlap: true,
    facesOverlap: false,
    facesTransparancy: 200,
    enableCustomHighlight: true,
    sceneGraph: false,
    edgeModel: true,
    reverseZoomWheel: false,
    enableZoomWheel: true,
    enableGestures: true,
    geometryType: "vsfx",
    rulerUnit: "Default",
  };
}