Model Viewer Embed Tool - Integration Guide

Live Sample

Single 3D Model Viewer (chair0):

modelId

envMap (optional - uses default HDRI if empty)

theme

arPlacement

exposure (0.85)

Options

enableAR enableFullscreen

postProcessing.brightness (100)

postProcessing.contrast (100)

postProcessing.saturation (100)

1. Include `tool.js`

Host tool.js on any HTML page:

        <!-- Include tool.js -->
<script src="https://usdc-testing.s3.us-east-1.amazonaws.com/tool.js"></script>
      

2. Add a Container

Create a simple container div where the 3D viewer will be rendered:

<div id="my-model-viewer" style="width: 100%; height: 600px;"></div>

3. Initialize the Viewer

Call initModelViewer once the page has loaded:

        <script>
document.addEventListener('DOMContentLoaded', () => {
  initModelViewer({
    containerId: 'my-model-viewer',
    modelId: 'chair0',                // required
    envMap: 'studio_small_09',        // optional (uses model-viewer default HDRI if not specified)
    theme: 'theme3',                  // optional
    enableAR: true,                   // optional (default: true)
    arPlacement: 'floor',             // optional (default: 'floor', options: 'floor' or 'wall')
    exposure: '0.85',                 // optional (default: '0.85')
    enableFullscreen: true,           // optional (default: true)
    postProcessing: {                 // optional
      brightness: 100,                // 0–200 (default 100)
      contrast: 100,                  // 0–200 (default 100)
      saturation: 100,                // 0–200 (default 100)
      gamma: 100,                     // 50–200 (default 100)
      hue: 0,                         // -180–180 (default 0)
      temperature: 6500,              // 2000–10000 (default 6500)
      red: 100,                       // 0–200 (default 100)
      green: 100,                     // 0–200 (default 100)
      blue: 100                       // 0–200 (default 100)
    }
  });
});
</script>
      

API Reference: `initModelViewer(options)`

containerId (string, required) – ID of the div where the viewer will be injected.
modelId (string, required) – Logical model identifier (e.g. chair0, chair1).
envMap (string, optional) – Environment map ID from the internal config (e.g. studio_small_09). If not specified, uses model-viewer's default HDRI.
theme (string, optional) – Theme ID from theme-config.js (e.g. theme1, theme2, theme3).
enableAR (boolean, default: true) – Show AR button on supported devices.
arPlacement (string, default: 'floor') – AR placement mode. Options: 'floor' or 'wall'.
exposure (string, default: '0.85') – Exposure value for the model viewer (e.g., '0.85', '1.0', '1.5').
enableFullscreen (boolean, default: true) – Show fullscreen toggle and camera presets.
postProcessing (object, optional) – Fine-tune viewer look:
- brightness (0–200, default 100)
- contrast (0–200, default 100)
- saturation (0–200, default 100)
- gamma (50–200, default 100)
- hue (-180–180, default 0)
- temperature (2000–10000, default 6500)
- red / green / blue (0–200, default 100)

URL Parameters

You can override the model ID and automatically trigger fullscreen using URL parameters. This is useful for deep linking to specific models or creating shareable links.

Note: URL parameters will override the modelId specified in your initModelViewer call, but all other settings (containerId, theme, etc.) remain unchanged.

Available Parameters:

arboost-id (string) – Overrides the modelId in your initialization call. Example: ?arboost-id=chair1
arboost-fullscreen (boolean) – Automatically enters fullscreen mode after initialization. Set to true to enable. Example: ?arboost-fullscreen=true

Examples:

        // Load chair1 model (overrides modelId in initModelViewer)
https://yoursite.com/page.html?arboost-id=chair1

// Load chair1 and automatically enter fullscreen
https://yoursite.com/page.html?arboost-id=chair1&arboost-fullscreen=true

// Your code remains the same - URL parameters are handled automatically
initModelViewer({
  containerId: 'my-viewer',
  modelId: 'chair0',  // This will be overridden by ?arboost-id=chair1
  enableAR: true,
  enableFullscreen: true
});
      

How it works: When initModelViewer is called, the wrapper function automatically checks for URL parameters. If arboost-id is present, it replaces the modelId in your config. If arboost-fullscreen=true is present, it automatically triggers the fullscreen button after the viewer initializes. No changes to your code are required!

3D Model Viewer Embed Tool