@inweb/viewer-core/src/options/IOptions.ts

3D CAD and BIM data Viewer core

///////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2002-2026, 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-2026 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 type CameraMode = "perspective" | "orthographic";

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 Open Cloud 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;

  /**
   * Deprecated since `27.5`. Use {@link sectionFillColor} instead.
   *
   * @deprecated
   */
  cuttingPlaneFillColor: RGB;

  /**
   * Show solid fill on section caps.
   *
   * When disabled, neither the fill nor the hatch is drawn (the outline, if enabled, is still shown).
   *
   * @defaultValue true
   */
  enableSectionFill: boolean;

  /**
   * Section cap fill color.
   *
   * @defaultValue { red: 0xff, green: 0x98, blue: 0x00 }
   */
  sectionFillColor: { r: number; g: number; b: number };

  /**
   * Use the intersected object's color for the section cap fill.
   *
   * When enabled, each section cap is filled with a color derived from the intersected object and
   * `sectionFillColor` is ignored. The outline color is not affected.
   *
   * @defaultValue false
   */
  sectionUseObjectColor: boolean;

  /**
   * Overlay a hatch pattern on top of the section fill.
   *
   * @defaultValue true
   */
  enableSectionHatch: boolean;

  /**
   * Hatch line color used on top of the section fill.
   *
   * @defaultValue { red: 0x4b, green: 0x4c, blue: 0x35 }
   */
  sectionHatchColor: { r: number; g: number; b: number };

  /**
   * Distance between hatch lines, in screen-space pixels.
   *
   * Larger values produce sparser hatching.
   *
   * @defaultValue 8
   */
  sectionHatchScale: number;

  /**
   * Draw the outline contour along the section boundary.
   *
   * @defaultValue true
   */
  enableSectionOutline: boolean;

  /**
   * Color of the section outline contour.
   *
   * @defaultValue { red: 0, green: 0, blue: 0 }
   */
  sectionOutlineColor: { r: number; g: number; b: number };

  /**
   * Width of the section outline contour, in pixels.
   *
   * @defaultValue 2
   */
  sectionOutlineWidth: number;

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

  /**
   * Preferred viewer for newely uploaded files. Can be one of:
   *
   * - `vsfx` - `VSFX` (default), for opening a file in `VisualizeJS` viewer.
   * - `gltf` - `glTF`, for opening a file in `Three.js` viewer.
   */
  geometryType: string;

  /**
   * Unit of measurement for the ruler tool (distance measurements).
   *
   * When set to `Default`, the ruler uses the file's native units. Otherwise, distances are
   * automatically converted to the specified unit.
   *
   * Available values:
   *
   * - `Default` - Use file's native units (recommended)
   * - `Millimeters`, `mm` - Metric: 0.001 m
   * - `Centimeters`, `cm` - Metric: 0.01 m
   * - `Meters`, `m` - Metric: 1 m (base unit)
   * - `Kilometers`, `km` - Metric: 1000 m
   * - `Micrometers`, `µm` - Metric: 0.000001 m
   * - `Inches`, `in` - Imperial: 0.0254 m
   * - `Feet`, `ft` - Imperial: 0.3048 m
   * - `Yards`, `yd` - Imperial: 0.9144 m
   * - `Miles`, `mi` - Imperial: 1609.344 m
   * - `Mils`, `mil` - Imperial: 0.0000254 m
   * - `MicroInches`, `µin` - Imperial: 0.0000000254 m
   *
   * @defaultValue "Default"
   */
  rulerUnit: string;

  /**
   * Number of decimal places to display in ruler measurements.
   *
   * Controls the precision of distance values shown by the ruler tool. Higher values provide more
   * precision but may clutter the display with unnecessary digits.
   *
   * Available values:
   *
   * - `Default` - Use file's native units precision, if supported, otherwise use 2 digits.
   * - `Auto` - Automatically choose precision based on distance value.
   * - `0`...`10` - Use specified number of decimal places (range 0-10, inclusive).
   *
   * @defaultValue 2
   */
  rulerPrecision: "Default" | "Auto" | number;

  /**
   * Camera projection mode:
   *
   * - `perspective` - Perspective camera with field of view.
   * - `orthographic` - Orthographic camera with parallel projection.
   *
   * @defaultValue "perspective"
   */
  cameraMode: CameraMode;

  /**
   * Default MIME type for snapshot images.
   *
   * Supported formats:
   *
   * - `image/png` - PNG format with lossless compression (recommended for quality)
   * - `image/jpeg` - JPEG format with lossy compression (smaller file size)
   * - `image/webp` - WebP format (modern browsers only)
   *
   * @defaultValue "image/jpeg"
   */
  snapshotMimeType: string;

  /**
   * Default quality level for snapshot images when using lossy formats (JPEG, WebP).
   *
   * A number between 0 and 1, where:
   *
   * - `0` - Lowest quality, smallest file size
   * - `1` - Highest quality, largest file size
   * - `0.25` - Good balance between quality and size (recommended)
   *
   * This parameter is ignored for lossless formats like PNG.
   *
   * @defaultValue 0.25
   */
  snapshotQuality: number;
}

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 },
    enableSectionFill: true,
    sectionFillColor: { r: 0xff, g: 0x98, b: 0x00 },
    sectionUseObjectColor: false,
    enableSectionHatch: true,
    sectionHatchColor: { r: 0, g: 0, b: 0 },
    sectionHatchScale: 8,
    enableSectionOutline: true,
    sectionOutlineColor: { r: 0, g: 0, b: 0 },
    sectionOutlineWidth: 2,
    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",
    rulerPrecision: 2,
    cameraMode: "perspective",
    snapshotMimeType: "image/jpeg",
    snapshotQuality: 0.25,
  };
}