Configuration

The viewer is constructed from a single XViewerConfig object. It groups the DOM target, camera and controls, environment, licensing, rendering, plugins, and feature flags.

XViewerConfig

interface XViewerConfig {
  viewer: ViewerConfig;
  plugins: PluginConfig[];
  features: FeatureFlags;
  rendering: RenderingConfig;
  development?: {
    enableLogging: boolean;
    logLevel: "debug" | "info" | "warn" | "error";
    enablePerformanceMonitoring: boolean;
    showStats: boolean;
  };
  selection?: SelectionConfig;
}

Field	Purpose
viewer	Container element, camera, controls, environment, licensing. Required.
plugins	List of plugins to register, with per-plugin config and load order.
features	Top-level on/off switches for built-in features.
rendering	Renderer settings: antialias, tone mapping, shadows, post-processing.
development	Optional logging and stats overlays.
selection	Optional selection service config. See SelectionConfig.

ViewerConfig

interface ViewerConfig {
  container: HTMLElement;
  camera: CameraConfig;
  controls: ControlsConfig;
  environment: EnvironmentConfig;
  licensing: LicensingConfig;
}

container is the DOM element the renderer attaches to. It must be in the document and sized before the viewer is constructed.

CameraConfig

interface CameraConfig {
  type: CameraType;                       // "perspective" | "orthographic"
  fov?: number;
  near?: number;
  far?: number;
  position?: { x: number; y: number; z: number };
  target?: { x: number; y: number; z: number };
}

fov only applies to perspective cameras. near/far define the clip range.

ControlsConfig

interface ControlsConfig {
  type: ControlsType;
  minDistance?: number;
  maxDistance?: number;
  minZoom?: number;
  maxZoom?: number;
  // OrbitControls
  enableDamping?: boolean;
  dampingFactor?: number;
  enableZoom?: boolean;
  enablePan?: boolean;
  enableRotate?: boolean;
  // TrackballControls
  staticMoving?: boolean;
  dynamicDampingFactor?: number;
  rotateSpeed?: number;
  zoomSpeed?: number;
  panSpeed?: number;
  zoomToCursor?: boolean;
  cursorPan?: boolean;
}

ControlsType is one of "OrbitControls" | "ArcballControls" | "FlyControls" | "FirstPersonControls" | "MapControls" | "TrackballControls" | "PointerLockControls". Fields apply only to the matching control type and are ignored otherwise.

EnvironmentConfig

interface EnvironmentConfig {
  preset?: string;
  intensity?: number;
  backgroundBlurriness?: number;
  background?: ViewerBackgroundInput;
}

preset is the name of a built-in HDRI environment. background accepts a structured config, a THREE.Color, a THREE.Texture, or null.

Background

type ViewerBackgroundInput =
  | ViewerBackgroundConfig
  | THREE.Color
  | THREE.Texture
  | null;

type ViewerBackgroundConfig =
  | { type: "transparent" }
  | { type: "solid"; color: string }
  | { type: "gradient"; shape?: BackgroundGradientShape; startColor: string; endColor: string }
  | { type: "image"; url: string; mode?: BackgroundImageMode; fallbackColor?: string };

type BackgroundGradientShape = "vertical" | "radial";
type BackgroundImageMode = "fit" | "fill" | "tile";

LicensingConfig

interface LicensingConfig {
  key: string;
  revocationEndpoint?: string;
  revocationMode?: "off" | "background" | "strict";
  trustedTimeEndpoint?: string;
}

key is a signed license token. revocationMode: "background" checks revocationEndpoint after construction. revocationMode: "strict" requires a revocation endpoint and fails closed when the check cannot complete.

RenderingConfig

interface RenderingConfig {
  antialias?: boolean;
  alpha?: boolean;
  preserveDrawingBuffer?: boolean;
  shadowMap?: ShadowMapConfig;
  toneMapping?: string;
  toneMappingExposure?: number;
  outputColorSpace?: string;
  pixelRatio?: number;
  postProcessing?: PostProcessingConfig;
}

interface ShadowMapConfig {
  enabled: boolean;
  type: string;          // e.g. "PCFSoftShadowMap"
}

Post-processing

interface PostProcessingConfig {
  enabled?: boolean;
  passes?: PostProcessingPassesConfig;
}

interface PostProcessingPassesConfig {}

Post-processing no longer registers a built-in ambient occlusion pass from configuration. Use PostProcessingService.addPass() to add project-specific passes.

PluginConfig

interface PluginConfig {
  name: string;
  enabled: boolean;
  config?: Record<string, any>;
  loadOrder?: number;
}

loadOrder is ascending. Plugins without a loadOrder load after those that have one.

FeatureFlags

interface FeatureFlags {
  enableCrossSection: boolean;
  enableMeasurement: boolean;
  enableSelection: boolean;
  enableTransform: boolean;
  enableLabels: boolean;
  enableAnimation: boolean;
  enableGrid: boolean;
  enableShadows: boolean;
  enableEnvironment: boolean;
}

Feature flags are part of the public configuration shape. In the current runtime, built-in services are registered independently of these flags; use plugin loading and license claims to control active capabilities.

Complete example

import { ViewerCore, XViewerConfig, CameraType } from "@optellix/xviewr-sdk";

const config: XViewerConfig = {
  viewer: {
    container: document.getElementById("viewer")!,
    camera: {
      type: CameraType.Perspective,
      fov: 50,
      near: 0.1,
      far: 10000,
      position: { x: 5, y: 5, z: 5 },
      target: { x: 0, y: 0, z: 0 },
    },
    controls: {
      type: "OrbitControls",
      enableDamping: true,
      dampingFactor: 0.08,
      minDistance: 0.1,
      maxDistance: 5000,
    },
    environment: {
      preset: "studio",
      intensity: 1.0,
      backgroundBlurriness: 0.2,
      background: {
        type: "gradient",
        shape: "vertical",
        startColor: "#1a1a1a",
        endColor: "#404040",
      },
    },
    licensing: {
      key: "<signed-license-token>",
      revocationMode: "off",
    },
  },
  rendering: {
    antialias: true,
    alpha: false,
    pixelRatio: window.devicePixelRatio,
    toneMapping: "ACESFilmic",
    toneMappingExposure: 1.0,
    outputColorSpace: "srgb",
    shadowMap: { enabled: true, type: "PCFSoftShadowMap" },
    postProcessing: {
      enabled: true,
    },
  },
  features: {
    enableCrossSection: true,
    enableMeasurement: true,
    enableSelection: true,
    enableTransform: true,
    enableLabels: true,
    enableAnimation: true,
    enableGrid: true,
    enableShadows: true,
    enableEnvironment: true,
  },
  plugins: [
    { name: "loader", enabled: true, loadOrder: 0 },
    { name: "camera", enabled: true, loadOrder: 1 },
    { name: "environment", enabled: true, loadOrder: 2 },
    { name: "grid", enabled: true, loadOrder: 3 },
    { name: "selection", enabled: true, loadOrder: 4 },
    { name: "measurement", enabled: true, loadOrder: 5 },
  ],
  development: {
    enableLogging: true,
    logLevel: "info",
    enablePerformanceMonitoring: false,
    showStats: false,
  },
};

const viewer = new ViewerCore(document.getElementById("viewer")!, config);

---

Confidential. Optellix Pvt. Ltd. proprietary documentation. Subject to applicable data-protection laws including DPDP 2023, GDPR, and CCPA.