Common Types

Shared types used across the public API. Imported from @optellix/xviewr-sdk.

View and camera

Axis

type Axis = "X" | "Y" | "Z" | "-X" | "-Y" | "-Z";

Signed axis identifier used for orientation, view alignment, and explosion direction.

ViewPreset

type ViewPreset = "top" | "bottom" | "left" | "right" | "front" | "back" | "iso";

Standard camera view presets.

ControlsType

type ControlsType =
  | "OrbitControls"
  | "ArcballControls"
  | "FlyControls"
  | "FirstPersonControls"
  | "MapControls"
  | "TrackballControls"
  | "PointerLockControls";

Selects the active camera controls. Pass via ControlsConfig.type.

MaterialMode

type MaterialMode =
  | "Default"
  | "Matcap"
  | "Random"
  | "Wireframe"
  | "ShadedWithWireframe";

Override mode applied by MaterialService. Default leaves materials untouched.

FitOptions

interface FitOptions {
  sceneOrientation?: string;
  padding?: number;
  animated?: boolean;
  duration?: number;
}

Used when framing the camera to a target.

Loading

FileSpec

interface FileSpec {
  url: string;
  type: "glb" | "gltf" | "obj" | "stl" | "ply" | "fbx" | "e57" | "las" | "laz" | "step" | "chunked";
  filename?: string;
  mtlUrl?: string;
  textureMap?: Record<string, string>;
}

Describes an asset for the loader. mtlUrl and textureMap apply to OBJ. chunked selects the chunked LOD pipeline.

LoadOptions

interface LoadOptions {
  onProgress?: (progress: number) => void;
  validateFile?: boolean;
  timeout?: number;
  [key: string]: any;
}

Base load options. Loader-specific extensions add fields.

GlbLoadOptions

interface GlbLoadOptions extends LoadOptions {
  disableMatrixAutoUpdate?: boolean;
  loadEdges?: boolean;
  edgesJsonUrl?: string;
  resolution?: THREE.Vector2;
}

loadEdges enables edge line generation. edgesJsonUrl loads precomputed edges instead of generating at runtime.

Screenshots

ScreenshotOptions

interface ScreenshotOptions {
  width?: number;
  height?: number;
  transparentBackground?: boolean;
  fitToView?: boolean;
}

Width/height default to the canvas size. fitToView reframes the camera before capture.

Measurement

MeasurementResult

interface MeasurementResult {
  distance?: number;
  angle?: number;
  radius?: number;
  volume?: number;
  position: THREE.Vector3;
  points: THREE.Vector3[];
  [key: string]: any;
}

Legacy result shape. New code uses the descriptor-based result types exported from services (DistanceResult, AngleResult, etc.). points are the picked positions in world space, position is the anchor for labels.

ExplosionValues

interface ExplosionValues {
  x?: number;
  y?: number;
  z?: number;
  radial?: number;
}

Per-axis and radial offset magnitudes consumed by ExplosionPlugin.

Chunked loading

For very large models served as an octree of LOD chunks.

ChunkedLoadOptions

interface ChunkedLoadOptions {
  onChunkLoaded?: (chunkId: number, loaded: number, total: number) => void;
  baselineLevel?: ChunkAssetLevel;
  showOnly?: ChunkAssetLevel | null;
  baselineConcurrency?: number;
  lod0ActivationPixels?: number;
  maxFetchInFlight?: number;
  lod0EvictDelayMs?: number;
  lodConfig?: Partial<LodConfig>;
}

Field	Purpose
onChunkLoaded	Per-chunk progress callback.
baselineLevel	Which LOD to load eagerly (lod0 highest detail, lod1 lower).
showOnly	Force a single level to render, suppressing LOD selection.
baselineConcurrency	Parallel baseline fetches.
lod0ActivationPixels	Pixel-coverage threshold at which lod0 is promoted.
maxFetchInFlight	Cap on in-flight detail fetches.
lod0EvictDelayMs	Delay before evicting lod0 after a chunk falls below threshold.
lodConfig	Partial LOD service overrides for this load.

ChunkAssetLevel

type ChunkAssetLevel = "lod0" | "lod1";

ChunkMetadata

interface ChunkMetadata {
  id: number;
  depth: number;
  center: [number, number, number];
  min: [number, number, number];
  max: [number, number, number];
  prim_count?: number;
  lod0_file?: string;
  lod1_file?: string;
  lod0_url: string;
  lod1_url?: string;
}

One entry per octree leaf in the manifest.

ChunkManifest

interface ChunkManifest {
  type?: string;
  tree?: OctreeNode;
  hierarchy?: { nodes: any[] };
  chunks: NormalizedChunkMetadata[];
}

The viewer normalizes the backend manifest into this shape internally. tree is the octree used for view-frustum queries.

ChunkedModelHandle

interface ChunkedModelHandle {
  root: THREE.Group;
  update(camera: THREE.Camera): void;
  setMoving(moving: boolean): void;
  setSelectedMesh(mesh: THREE.Object3D | null): void;
  setClippingPlane(plane: THREE.Plane | null): void;
  dispose(): void;
}

Returned by the chunked loader. Call update(camera) each frame to drive LOD selection. setMoving(true) while the camera is animating to suppress fetch storms. dispose() releases all GPU resources.

Measurement display

MeasurementDisplayUnit

interface MeasurementDisplayUnit {
  scale: number;
  lengthSuffix: string;
  areaSuffix?: string;
  volumeSuffix?: string;
  precision?: number;
}

Controls how measurement values are formatted in labels. scale multiplies the raw world-space value; suffixes are appended per result kind.

StepMeasurementSubMode

type StepMeasurementSubMode =
  | "coordinate"
  | "single-edge-length"
  | "multi-edge-length"
  | "linear-point-to-point"
  | "linear-point-to-edge"
  | "linear-point-to-circle";

Sub-mode selector for the STEP-edge measurement descriptor.

StepMeasurementPointKind

type StepMeasurementPointKind = "edge-start" | "edge-end";

Which endpoint of a STEP edge a picked point belongs to.

---

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