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";

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.

---

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