XViewr SDK Documentation

XViewer SDK v4.0.1 is a 3D visualization SDK built on Three.js. It provides a modular, plugin-based architecture for loading, rendering, measuring, annotating, and interacting with CAD-grade 3D scenes in the browser.

Architecture at a Glance

Four layers, talking through an event bus and a service registry:

• Core — ViewerCore owns the lifecycle, the Three.js scene/camera/renderer, and the registries (services, plugins, config, events).
• Services — long-lived, stateful subsystems registered at startup (camera, loading, materials, measurement, selection, rendering, etc.). Plugins read and write through them.
• Plugins — feature modules that can be activated and deactivated. They render, handle interaction, and coordinate services.
• Types — public configuration shapes and shared data types.

Plugins never reach across to each other directly. They communicate via the EventBus and the services they depend on.

import { ViewerCore, LoaderPlugin } from '@optellix/xviewr-sdk';

const viewer = new ViewerCore(document.getElementById('viewer'), {
  viewer: {
    camera: { type: 'perspective', fov: 75, position: { x: 5, y: 5, z: 5 } },
    licensing: { key: 'YOUR_LICENSE_KEY' },
  },
  rendering: { antialias: true },
  plugins: [
    { name: 'rendering', enabled: true },
    { name: 'camera',    enabled: true },
    { name: 'loader',    enabled: true },
    { name: 'selection', enabled: true },
  ],
});

await viewer.ready();
const loaderPlugin = viewer.pluginManager.getPlugin('loader');
await loaderPlugin.loadFile(myGlbFile);

Getting Started

See the Quick Start guide for a complete walkthrough: install, licensing, loading a model, and common next steps.

For the full config shape see types/configuration.md. Errors thrown by the SDK are in errors.md.

Module Index

Core

Module	Description
ViewerCore	Main entry class. Owns the scene, camera, renderer, and registries. Exposes ready(), dispose(), getService, getPlugin.
Plugins	IPlugin contract, PluginContext, PluginMetadata, PluginStatus, IPluginManager. How plugins are registered, activated, and torn down.
Services	IService, ServiceContext, IServiceRegistry, ServiceStatus, ILogger. How to consume and register custom services.
Event Bus	IEventBus (emit, on, once, off). Cross-module communication.
Config Manager	IConfigManager for dot-path config get/set, validation, and watchers.

Services

Module	Description
CameraService	Camera state, controls (orbit/trackball/arcball), view presets, fit-to-view, projection switching.
LoaderService	File loading with pluggable ILoader implementations, chunked manifest loading, detached and batch GLB loading.
LODService	Streaming LOD for chunked models. Cache budget, watermarks, eviction.
LicenseService	XVR1/ES256 license validation, plugin and feature gating, expiry events.
MaterialService	Material modes (default/matcap/random/wireframe/shaded-with-wireframe), original tracking, X-ray sets, scoped clipping planes, material registration events.
MeshService	Mesh registry, deterministic IDs, queries, hide/show/ghost/x-ray/isolate, processing pipeline, batch registration, edge-line utilities.
AdvancedMeshService	Spatial-hash/BVH backed contact and proximity neighbour queries, contact graph caching, configurable thresholds.
MeasurementService	Descriptor-based 3D measurements (distance, angle, area, multi-point, spline, AABB/OBB, volume + async worker path, circle, arc, STEP edge length).
SelectionService	Object selection, hover, multi-select, neighbour selection, raycasting, custom highlight strategies.
StorageService	Queryable scene-hierarchy graph (assemblies, parts, BOM).
RenderingService	Renderer config, shadow map, tone mapping, exposure, quality presets, screenshot.
PostProcessingService	EffectComposer pipeline, custom passes, shared color/depth/normal buffers.
CrossSection types	Public types for the cross-section plugin (SectionCapStyle).
CommandRunnerService	Optional LLM-friendly command facade. Registry, validation, never-throwing execute, machine-readable catalog.

Plugins

Module	Description
CameraPlugin	Animated camera transitions, save/restore camera states.
LoaderPlugin	High-level file loading, drag-and-drop, chunked LOD streaming, detached and batch GLB flows.
AnimationPlugin	Tween/timeline forwarders, scene-state capture, restore, delta animation.
EnvironmentPlugin	HDRI, lighting, shadows, background.
ExplosionPlugin	Hierarchical mesh explosion with axis/radial/depth/object/rigid modes and auto-centered origins.
GridPlugin	Reference grid: orientation, auto-fit to scene or object.
LabelPlugin	HTML overlay labels with per-type renderers, leaders, drag support.
MeasurementPlugin	Interactive measurement tools (including spline, STEP edge, async volume), edge snapping, label/leader styling.
CanvasExportPlugin	PNG/JPEG/WebP export with measurement/label compositing.
RenderingPlugin	Plugin wrapper for RenderingService and PostProcessingService.
SelectionPlugin	Click, region, neighbour, edge hover, clipped raycast filtering, focus-on-selection.
ModelTreePlugin	Hierarchical model tree, filtering, search, optional UI panel.
CrossSectionPlugin	Interactive clipping planes with transform gizmo, object-scoped planes, object axis sections, live BVH contours, and IGES export.
TransformControlsPlugin	Translate/rotate/scale gizmo.
TechnicalDrawingPlugin	CAD-style hidden-line drawings with PNG/SVG export.
ViewCubePlugin	Overlay navigation cube with snap and drag.
ImageViewerPlugin	Standalone 2D image canvas with zoom and pan.
MarkupPlugin	Pen/eraser overlay synced to image transform.
SlashCommandPlugin	Text-input driver for the command system: parse, autocomplete, chain with &&.

Types and Errors

Module	Description
Configuration	XViewerConfig and all sub-configs (camera, controls, environment, rendering, post-processing, plugins, features).
Common Types	Shared types: view presets, load options, screenshot options, chunked manifest types, measurement results.
Errors	XViewerError hierarchy and when each subclass is thrown.

How the Pieces Fit Together

1. ViewerCore instantiates the registries and built-in services from your XViewerConfig.
2. CameraPlugin loads as a core plugin during startup. Other built-in plugins are loaded explicitly with viewer.loadPlugin(new PluginClass()).
3. Services hold state and expose typed APIs. Example: LoaderService loads a model, MeshService registers its meshes, MaterialService tracks originals, SelectionService listens for input and emits selection events.
4. Plugins react to events and call into services. Example: MeasurementPlugin listens for clicks via SelectionService, asks MeasurementService to compute the result, and renders the label using LabelPlugin-style overlays.
5. On viewer.dispose(), plugins deactivate, services dispose GPU resources, and the renderer is torn down.