Developer Documentation

<script src="https://cdn.jsdelivr.net/npm/universal-3d-viewer@0.2.0/dist/library/universal-3d-viewer.umd.js"></script>
<universal-3d-viewer
  src="/model.glb"
  camera-controls
  asset-base-path="https://cdn.jsdelivr.net/npm/universal-3d-viewer@0.2.0/public/"
  style="width: 100%; height: 500px;"
></universal-3d-viewer>

<div id="viewport" style="width: 600px; height: 400px"></div>
<script src="/assets/universal-3d-viewer.min.js"></script>
<script src="/assets/my-viewer.js"></script>

// my-viewer.js
const viewer = new Universal3DViewer.Universal3DViewer({
  container: document.getElementById('viewport'),
  assetBasePath: '/assets/decoders/',
})
viewer.load('/model.glb').catch((err) => {
  if (!Universal3DViewer.isAbortError(err)) console.error(err)
})

npm install universal-3d-viewer three

// Automatically registers the <universal-3d-viewer> custom element
import 'universal-3d-viewer'

// Or import the headless programmatic class
import { Universal3DViewer } from 'universal-3d-viewer'

<universal-3d-viewer
  src="https://example.com/models/sneaker.glb"
  poster="https://example.com/models/sneaker-poster.webp"
  camera-controls
  auto-rotate
  ar
  style="width: 100%; height: 500px;"
></universal-3d-viewer>

universal-3d-viewer::part(toolbar) {
  bottom: 24px;
  background: rgba(0, 0, 0, 0.9);
}

universal-3d-viewer::part(ar-button) {
  background: #10b981;
  font-weight: 700;
}

universal-3d-viewer::part(progress-bar) {
  background: linear-gradient(90deg, #f59e0b, #ef4444);
}

universal-3d-viewer::part(gallery-thumb) {
  border-radius: 4px;
}

universal-3d-viewer {
  /* Keep occluded pins faintly visible rather than hiding them outright */
  --min-hotspot-opacity: 0.25;
  --max-hotspot-opacity: 1;
  --progress-bar-color: linear-gradient(90deg, #10b981, #34d399);
  --progress-bar-height: 4px;
}

/* Each hotspot also reflects its own state */
universal-3d-viewer [slot^="hotspot-"]:not([data-visible]) {
  pointer-events: none;
}

const viewer = document.querySelector('universal-3d-viewer');

// Reset camera to initial home position with smooth animation
viewer.resetCamera(true);

// Frame model bounding box with padding
viewer.fitToScreen(1.25, true);

// Toggle or configure auto-rotation
viewer.toggleAutoRotate();
viewer.viewer.setAutoRotate(true, { speed: 3.0, delay: 2000 });

// Granular control locks
viewer.viewer.setZoomEnabled(false);
viewer.viewer.setPanEnabled(false);
viewer.viewer.setOrbitEnabled(true);

// Set specific orbit angles (theta, phi, radius)
viewer.viewer.setCameraOrbit(Math.PI / 4, Math.PI / 3, 2.5, true);

// Read and write the view in camera-orbit syntax
viewer.cameraOrbit = '45deg 60deg 120%';   // animates
console.log(viewer.cameraOrbit);           // "45deg 60deg 3.6m"
viewer.cameraTarget = '0m 1m 0m';

// Jump straight there instead of animating
viewer.setCameraOrbitSpec('top', false);

// Constrain how far the user can orbit
viewer.setCameraOrbitLimits('auto 20deg 1m', 'auto 90deg 8m');

// Orthographic for dimensional comparison, perspective for presentation
viewer.setCameraProjection('orthographic');

// Stand a Z-up CAD model upright
viewer.setUpAxis('z');

// Measurements from the loaded model
const size = viewer.getDimensions();        // THREE.Vector3
const centre = viewer.getBoundingBoxCenter();

// What is under this pixel?
const hit = viewer.positionAndNormalFromPoint(event.clientX, event.clientY);
if (hit) {
  viewer.addHotspot({ id: 'pin', position: hit.position, normal: hit.normal, element: pinEl });
}

import { Universal3DViewer } from 'universal-3d-viewer'

const viewer = new Universal3DViewer({
  container: document.getElementById('viewport'),
  fitInsets: { top: 64 },   // a 64 px header floats over the canvas
  reducedMotion: false,     // always animate, whatever the OS says
})

await viewer.load('/scene.glb')
for (const cam of viewer.getAuthoredCameras()) {
  console.log(cam.index, cam.name, cam.type)
}
viewer.viewFromAuthoredCamera(0)

// Later, when the header collapses
viewer.setFitInsets({ top: 0 })
viewer.fitToScreen()

viewer.setReducedMotion(null) // follow prefers-reduced-motion again

import { Universal3DViewer, ModelLoadError, isAbortError, filesFromDataTransfer } from 'universal-3d-viewer'

viewer.load(url).catch((err) => { if (!isAbortError(err)) throw err })

// A drop of model.gltf + model.bin + textures, cancellable
const controller = new AbortController()
dropZone.addEventListener('drop', async (event) => {
  event.preventDefault()
  const files = await filesFromDataTransfer(event.dataTransfer)
  const main = files.find((f) => /\.(gltf|glb|obj|stl|step|stp|ifc)$/i.test(f.name))
  if (!main) return
  try {
    await viewer.load(main, { companions: files.filter((f) => f !== main), signal: controller.signal })
  } catch (err) {
    if (isAbortError(err)) return
    if (err instanceof ModelLoadError) showMessage(err.message) // e.g. code 'missing-resource'
    else throw err
  }
})
cancelButton.addEventListener('click', () => controller.abort())

// 1. Change PBR color (pass part name or '*' for all meshes)
viewer.setPartColor('Cushion', '#ff3366');

// 2. Live Texture Swapping (color, roughness, metalness, normal)
await viewer.updateTexture('Cushion', 'map', 'https://cdn.example.com/leather-texture.webp', {
  repeat: [2, 2],
  flipY: true
});

// 3. Inspect all discovered parts and materials
const parts = viewer.viewer.getParts();
console.log(parts); // [{ name: "Seat", materialName: "Leather", color: "#3b82f6", ... }]

viewer.addEventListener('scene-graph-ready', async () => {
  const material = viewer.model.getMaterialByName('Body');

  // Base PBR
  material.pbrMetallicRoughness.setBaseColorFactor([0.8, 0.1, 0.1, 1]);
  material.pbrMetallicRoughness.setBaseColorFactor('#cc1111');   // hex also works
  material.pbrMetallicRoughness.setMetallicFactor(1);
  material.pbrMetallicRoughness.setRoughnessFactor(0.25);

  // Emission, transparency, culling
  material.setEmissiveFactor('#221100');
  material.setAlphaMode('BLEND');       // 'OPAQUE' | 'MASK' | 'BLEND'
  material.setDoubleSided(true);

  // glTF extensions (MeshPhysicalMaterial only; warns otherwise)
  material.setClearcoatFactor(1);
  material.setTransmissionFactor(0.9);
  material.setIor(1.5);

  // Textures
  const texture = await viewer.createTexture('/textures/carbon.jpg');
  material.pbrMetallicRoughness.baseColorTexture.setTexture(texture);
  material.normalTexture.setTexture(null);   // clear a slot

  // Undo everything above. Prefer material.reset() over
  // viewer.resetNodeMaterial(name) — most CAD output leaves materials
  // unnamed, and a name lookup cannot reach those.
  material.reset();
});

// Material variants authored into the glTF
console.log(viewer.availableVariants);  // ['Chrome', 'Matte']
viewer.variantName = 'Chrome';

// Toggle edges on or off
viewer.toggleEdges();

// Or configure explicitly
viewer.viewer.setEdges(true, {
  color: '#38bdf8',
  thresholdAngle: 25 // Crease angle in degrees
});

// 1. Switch lighting presets ('studio' | 'neutral' | 'sunset' | 'warehouse' | 'night')
viewer.setEnvironmentPreset('sunset');

// 2. Load custom HDR / EXR / WebP environment map
await viewer.setEnvironmentImage('https://cdn.example.com/lighting/studio.hdr');

// 3. Set 360 Skybox Background
await viewer.setSkyboxImage('https://cdn.example.com/skybox/city.jpg');
viewer.toggleSkybox(true);

// 4. Tone mapping & Exposure
viewer.viewer.setExposure(1.2);
viewer.viewer.setToneMapping('aces');

// Add a hotspot programmatically
viewer.addHotspot({
  id: 'turbocharger',
  position: [0.15, 0.45, -0.1],
  normal: [0, 1, 0], // Optional surface normal
  element: `
    <div class="hotspot-pin">
      <span>1</span>
      <div class="tooltip">High-Efficiency Turbocharger</div>
    </div>
  `,
  occlude: true, // Auto-hide when behind model
  onClick: (id) => alert('Clicked hotspot: ' + id)
});

// Remove a hotspot
viewer.removeHotspot('turbocharger');

// Fly camera smoothly to focus on a hotspot
viewer.focusHotspot('turbocharger');

// Clear all hotspots
viewer.viewer.clearHotspots();

// A label typed by a user: plain text, never HTML
viewer.addHotspot({
  id: 'note-' + note.id,
  position: note.position,
  element: note.label,
  asText: true,
});

// 1. Get full recursive tree
const tree = viewer.getSceneTree();
console.log(tree); // { name: "Root", children: [{ name: "Engine", polyCount: 12400, ... }] }

// 2. Hide or show specific parts (e.g. for exploded view / x-ray)
viewer.setNodeVisibility('Engine_Cover', false);
viewer.setNodeVisibility('Wheel_Rear_Right', true);

// 3. Reset all nodes to visible
viewer.resetVisibility();

// 1. List all animation clips in the model
const animations = viewer.getModelAnimations(); // (or viewer.getAnimations() on headless SDK)
console.log(animations); // [{ name: "Run", duration: 1.4, index: 0 }, { name: "Jump", ... }]

// 2. Play with options (loop, speed, cross-fade)
viewer.playAnimation('Run', {
  loop: true,
  timeScale: 1.5,
  crossFadeDuration: 0.4
});

// 3. Playback controls
viewer.pauseAnimation();
viewer.resumeAnimation();
viewer.setAnimationTime(0.75); // Scrub to 0.75 seconds
viewer.stopAnimation();

viewer.setRotationLimits({
  minPolarAngle: '15deg',
  maxPolarAngle: '90deg',   // Prevents camera from dipping below the floor
  minAzimuthAngle: '-45deg', // Restricts horizontal turntable sweep
  maxAzimuthAngle: '45deg'
});

// 1. Generate multi-angle snapshots and retrieve Blob URLs
const images = await viewer.generateGalleryImages({
  views: ['front', 'right', 'back', 'left', 'top', 'isometric'],
  format: 'image/webp',
  quality: 0.95
});

// 2. Build your own Custom UI (Row after row, custom thumbnail list, etc.)
const customGalleryRow = document.getElementById('my-custom-gallery');
images.forEach((img) => {
  const thumb = document.createElement('img');
  thumb.src = img.blobUrl;
  thumb.title = img.label;
  thumb.onclick = () => {
    // Smoothly fly camera to this angle
    viewer.setCameraOrbit(img.orbit.theta, img.orbit.phi, img.orbit.radius, true);
  };
  customGalleryRow.appendChild(thumb);
});

// 3. Built-in Strip Show / Hide Controls
viewer.showGallery(false);         // Hide built-in row strip (ideal when using custom UI)
viewer.showGallery(true);          // Show built-in horizontal row strip
viewer.toggleGallery();            // Toggle visibility
console.log(viewer.isGalleryVisible()); // Check current visibility state

viewer.addEventListener('surface-click', (e) => {
  const { point, normal, meshName } = e.detail;
  console.log(`Clicked on ${meshName} at [${point.x}, ${point.y}, ${point.z}]`);

  // Drop a new pin at the hit location with fly-to enabled
  viewer.addHotspot({
    id: 'pin-' + Date.now(),
    position: [point.x, point.y, point.z],
    normal: [normal.x, normal.y, normal.z],
    flyToOnClick: true,
    element: '<div class="hotspot-pin">📍</div>'
  });
});

const dataUrl = viewer.captureScreenshot({
  format: 'image/webp',
  quality: 0.95
});

// Download image or show in modal
const link = document.createElement('a');
link.download = 'model-render.webp';
link.href = dataUrl;
link.click();

// Save the configured model as a GLB
const blob = await viewer.exportScene({ format: 'glb', optimize: true });

const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = 'configured-model.glb';
link.click();

// Upload it instead
const body = new FormData();
body.append('model', blob, 'configured-model.glb');
await fetch('/api/save-configuration', { method: 'POST', body });

// Rendered frame as a Blob or data URL
const png = await viewer.toBlob({ mimeType: 'image/png' });
const dataUrl = viewer.toDataURL('image/webp', 0.9);

const viewer = document.querySelector('universal-3d-viewer');

// Only offer AR when this device can actually run one of the modes
if (await viewer.canActivateAR()) {
  arButton.hidden = false;
}

viewer.addEventListener('ar-status', (e) => {
  // 'session-started' -> 'object-placed' -> 'not-presenting' ('failed' if nothing could launch)
  console.log('AR:', e.detail.status);
});

viewer.addEventListener('ar-tracking', (e) => {
  hintEl.hidden = e.detail.status === 'tracking';
});

await viewer.activateAR();

// End the immersive session programmatically
await viewer.exitAR();

import { Universal3DViewer } from 'universal-3d-viewer';

Universal3DViewer.modelCacheSize = 10;   // default 5; 0 disables caching
// Estimated bytes of parsed geometry and textures the cache may hold
// (default 256 MB); least recently used models are evicted beyond it.
Universal3DViewer.modelCacheByteBudget = 128 * 1024 * 1024;
Universal3DViewer.clearModelCache();

// Hand the render pass to a postprocessing composer. You build it from the
// engine's renderer/scene/camera and own its passes; the viewer just calls
// render() each frame instead of renderer.render(), and resizes it with the
// canvas. Rebuild your passes on camera-projection-change — switching
// projection replaces the camera object.
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';

const { renderer, scene, camera } = viewer.engine;
const composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, camera));
viewer.registerEffectComposer(composer);

viewer.unregisterEffectComposer();   // back to the plain renderer

<!-- Headless Viewer -->
<universal-3d-viewer id="my-viewer" src="model.glb" no-default-ui></universal-3d-viewer>

<!-- Bespoke External HTML Controls -->
<div class="custom-control-bar">
  <button onclick="document.getElementById('my-viewer').resetCamera()">Reset View</button>
  <button onclick="document.getElementById('my-viewer').toggleAutoRotate()">Spin</button>
  <button onclick="document.getElementById('my-viewer').toggleEdges()">CAD Lines</button>
  <button onclick="document.getElementById('my-viewer').toggleFullscreen()">Fullscreen</button>
</div>

import { ViewerPlugin, PluginContext, PluginToolbarAction } from 'universal-3d-viewer';

export class CustomWatermarkPlugin implements ViewerPlugin {
  public readonly id = 'watermark';
  public readonly name = 'Company Watermark Overlay';
  public readonly version = '1.0.0';

  private context: PluginContext | null = null;

  // 1. Initialized with full access to Three.js scene, camera, renderer & overlays
  public init(context: PluginContext): void {
    this.context = context;
    // ...add your meshes or DOM nodes, then ask for a frame (see below)
    context.invalidate();
  }

  // 2. Render loop hook executed before every frame
  public update(delta: number): void {
    // Animate custom 3D objects, update particle physics, or lerp overlays
  }

  // 3. Called when a new 3D model is loaded and centered
  public onModelLoaded(model: THREE.Group): void {
    console.log('Model loaded into scene:', model);
  }

  // 4. Optional toolbar button automatically injected into the Shadow DOM toolbar
  public getToolbarAction(): PluginToolbarAction | null {
    return {
      id: this.id,
      label: 'Toggle Watermark',
      iconSvg: '<svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor">...</svg>',
      onClick: (active) => console.log('Toggled active:', active)
    };
  }

  // 5. Cleanup when plugin or viewer is disposed
  public dispose(): void {
    this.context = null;
  }
}

import { Universal3DViewer, MeasurementPlugin, ExplodedViewPlugin, ClippingPlanePlugin } from 'universal-3d-viewer';

// 1. Programmatic registration on Universal3DViewer or <universal-3d-viewer>
const viewer = new Universal3DViewer({ container: document.getElementById('viewer-div') });

await viewer.use(new MeasurementPlugin({ unit: 'mm' }));
await viewer.use(new ExplodedViewPlugin());
await viewer.use(new ClippingPlanePlugin());

// Retrieve an active plugin instance at any time:
const measurement = viewer.getPlugin('measurement');
measurement.activate();

// Or remove a plugin:
viewer.removePlugin('measurement');

<!-- Automatically instantiates and registers Measurement, Exploded View, and Clipping Plane -->
<universal-3d-viewer
  src="assembly.glb"
  camera-controls
  plugins="measurement,exploded,clipping">
</universal-3d-viewer>

import { MeasurementPlugin } from 'universal-3d-viewer';

const measure = new MeasurementPlugin({ unit: 'mm' });
await viewer.use(measure);

measure.activate();           // Crosshair cursor mode
measure.setUnit('in');        // Switch between 'mm', 'cm', 'm', 'in'
console.log(measure.getMeasurement()); // { distance: 124.5, formatted: "124.5 mm", ... }
measure.clear();              // Clear measurements and markers

// Three measurement modes
measure.setMode('distance');  // two points (default)
measure.setMode('angle');     // three points; the middle one is the vertex
measure.setMode('path');      // any number of points, finished explicitly

measure.setUnit('mm');        // 'mm' | 'cm' | 'm' | 'in' — relabels existing readings

// A path ends on Enter, on Escape, or programmatically
measure.finishPath();

// Measurements accumulate rather than replacing each other
const all = measure.getMeasurements();
measure.removeMeasurement(all[0].id);
measure.cancelActive();   // abandon the one being placed
measure.clear();          // remove every measurement

viewer.addEventListener('measurement-change', (e) => {
  if (!e.detail) return;
  const { type, distance, angle, totalLength, formatted } = e.detail;
  label.textContent = formatted;   // "25.40 mm" or "90.0°"
});

import { ExplodedViewPlugin } from 'universal-3d-viewer';

const exploded = new ExplodedViewPlugin();
await viewer.use(exploded);

exploded.setExplosion(0.75);     // Set explosion factor (0.0 = assembled, 1.0 = fully disassembled)
exploded.animateTo(1.0, 0.8);   // Smoothly animate to exploded state over 0.8 seconds
exploded.reset();                // Instantly reassemble

import { ClippingPlanePlugin } from 'universal-3d-viewer';

const clipping = new ClippingPlanePlugin();
await viewer.use(clipping);

clipping.enable();               // Activate section cutting plane
clipping.setAxis('z');           // Cut along 'x', 'y', or 'z' axis
clipping.setOffset(0.25);        // Position plane (-1.0 to 1.0 across model bounds)
clipping.flip();                 // Invert cut normal direction

// Cut on more than one axis at once — the planes intersect
clipping.addPlane('x', 0.5);     // a second cut, on another axis
clipping.setPlaneOffset('x', -0.2);
clipping.flipPlane('x');
clipping.removePlane('x');

// Or reduce the model to a box: an opposed pair of planes on every axis
clipping.setBoxClip(-0.5, 0.5);
console.log(clipping.getPlaneCount());  // 6
clipping.clearExtraPlanes();            // back to the single primary cut

import { Universal3DViewer } from 'universal-3d-viewer';

// Register custom format loader adapter
Universal3DViewer.registerLoader({
  id: 'custom-format-adapter',
  supportedExtensions: ['.custom3d', '.myformat'],
  canHandle(file, magicBytes) {
    return file.name.endsWith('.custom3d');
  },
  async load(file, onProgress) {
    const group = new THREE.Group();
    // Parse custom file buffer and construct Three.js meshes...
    return { scene: group, animations: [], stats: { polyCount: 500, meshCount: 1 } };
  }
});

{%- assign model_media = product.media | where: "media_type", "model" | first -%}
{%- if model_media -%}
  {%- comment -%}
    The UMD bundle: a classic script with three.js inside that registers the element.
    Pinned to 0.2.0; the URL resolves once that version is published to npm.
  {%- endcomment -%}
  {%- assign u3d_cdn = 'https://cdn.jsdelivr.net/npm/universal-3d-viewer@0.2.0' -%}
  <script src="{{ u3d_cdn }}/dist/library/universal-3d-viewer.umd.js" defer></script>

  <universal-3d-viewer
    id="product-viewer-{{ product.id }}"
    src="{{ model_media.sources[0].url }}"
    asset-base-path="{{ u3d_cdn }}/public/"
    poster="{{ model_media.preview_image | image_url: width: 1000 }}"
    alt="{{ product.title | escape }}"
    camera-controls
    auto-rotate
    ar
    loading="lazy"
    environment-preset="studio"
    style="width: 100%; height: 500px;"
  >
    <button slot="ar-button" class="shopify-ar-pill">View in your room (AR)</button>
  </universal-3d-viewer>

  <script>
    // Live product variant switching
    document.addEventListener('variant:change', function(e) {
      if (e.detail && e.detail.variant) {
        const color = e.detail.variant.metafields.custom.color_hex;
        const viewer = document.getElementById('product-viewer-{{ product.id }}');
        if (viewer && color) {
          viewer.setPartColor('Body', color);
        }
      }
    });
  </script>
{%- endif -%}

[universal_3d_viewer
    src="https://example.com/models/watch.glb"
    poster="https://example.com/models/watch-poster.webp"
    camera_controls="true"
    auto_rotate="true"
    edges="true"
    environment_preset="studio"
    ar="true"
    height="550px"
]

import React, { useRef } from 'react';
import 'universal-3d-viewer';

export function Product3DViewer({ modelUrl, posterUrl }: { modelUrl: string; posterUrl: string }) {
  const viewerRef = useRef(null);

  const handleReset = () => {
    viewerRef.current?.resetCamera();
  };

  return (
    <div style={{ width: '100%', height: '500px', position: 'relative' }}>
      <universal-3d-viewer
        ref={viewerRef}
        src={modelUrl}
        poster={posterUrl}
        camera-controls
        auto-rotate
        ar
        style={{ width: '100%', height: '100%' }}
      >
        <button slot="hotspot-details" data-position="0 0.5 0">
          Feature Info
        </button>
      </universal-3d-viewer>
    </div>
  );
}

<template>
  <div class="viewer-wrapper">
    <universal-3d-viewer
      ref="viewer"
      :src="modelSrc"
      camera-controls
      auto-rotate
      @surface-click="onSurfaceClick"
    ></universal-3d-viewer>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import 'universal-3d-viewer';

const modelSrc = ref('https://example.com/model.glb');
const viewer = ref(null);

function onSurfaceClick(event) {
  console.log('Surface clicked:', event.detail.point);
}
</script>