Hosting a model viewer¶

Overview¶

The Maverick Excelsior Viewer is a cutting-edge WebAssembly-powered 3D visualization platform designed specifically for interactive jewelry display. It delivers photorealistic rendering quality with real-time material customization, providing an unparalleled viewing experience for luxury jewelry presentations.

Key Features¶

• Photorealistic Rendering: Industry-leading WebGL2 rendering with physically accurate materials and lighting
• Real-time Interaction: Smooth rotation, zoom, and pan controls with touch support
• Material Customization: Dynamic material switching for different jewelry components
• Performance Optimization: Adjustable quality settings from medium to ultra
• Responsive Design: Fully responsive with mobile-optimized controls
• Easy Integration: Simple JavaScript API with automatic WebAssembly loading

Quick Start¶

iframe method¶

If you do not need special control, the simplest way to embed a viewer is using an iframe.

See our Embedding an iframe guide for detailed instructions:

<iframe
  src="https://maverickexcelsior.com/iframe/?url=YOUR_WEBEX_FILE_URL"
  width="640" height="640" 
  style="border: none;"
  frameborder="0">
</iframe>

The iframe URL supports several parameters: - ?url=YOUR_WEBEX_FILE_URL - Direct URL to your WebEx file - ?webex=YOUR_WEBEX_FILE_URL - Alternative parameter name for the WebEx file - ?fileid=GOOGLE_DRIVE_ID - Google Drive file ID (automatically constructs the download URL) - ?set_clear_color=black - Background color (hex format or color names)

JavaScript Implementation¶

This is the canonical code snippet that you need to paste into your website in order to embed a Maverick Excelsior Viewer.

<div id="viewer-container">
    <canvas id="canvas-viewer" width="350" height="350"></canvas>
</div>

<script>
    function load_script(src) {
        return new Promise((resolve, reject) => {
            const script = document.createElement('script');
            script.src = src;
            script.onload = resolve;
            script.onerror = reject;
            document.head.appendChild(script);
        });
    }

    async function init() {
        const cdn_base = 'https://cdn.jsdelivr.net/gh/randomcontrol/webex-viewer@latest';

        await load_script(`${cdn_base}/webex-viewer-module.js`);

        window.Module = window.Module || {};
        window.Module.json = {
            open_scene: 'https://editor.maverickexcelsior.com/maverick-excelsior-demo.webex'
        };

        await load_script(`${cdn_base}/webex-viewer.js`);
    }

    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', init);
    } else {
        init();
    }
</script>

Module params¶

The window.Module.json object accepts the following initialization parameters:

Styling¶

The viewer canvas can be styled using standard CSS like any other HTML element. You control the visual presentation through CSS, including dimensions, borders, shadows, and responsive behavior.

#canvas-viewer {
    width: 100%;
    max-width: 640px;
    height: auto;
    aspect-ratio: 1 / 1;
    border: 2px solid #ddd;
    border-radius: 8px;
}

Note that the width and height attributes in the canvas element define the internal rendering buffer dimensions. The viewer automatically takes control of these values and adjusts them based on the physical dimensions of the canvas on screen. When you resize the browser window or modify the canvas size via CSS, the viewer detects these changes and updates the buffer dimensions accordingly.

Default Values¶

The viewer uses the following default values when parameters are not specified:

CDN¶

Note that since Release 115800 our redistributable files are universally served using jsdelivr. We no longer serve a '.zip' file like before. This new method both faster, more reliable, and easier for you to integrate.

The most recent version of the viewer files can always be found here:

https://cdn.jsdelivr.net/gh/randomcontrol/webex-viewer@latest/

For specific version pinning:

https://cdn.jsdelivr.net/gh/randomcontrol/webex-viewer@1.0.0/

For loading optimization you can add this snippet to your HTML.

<!-- Preconnect for faster loading -->
<link rel="preconnect" href="https://cdn.jsdelivr.net">
<link rel="dns-prefetch" href="https://cdn.jsdelivr.net">

Messaging API¶

The Excelsior Viewer exposes a powerful messaging API through the webex_in function, enabling dynamic control and interaction with the 3D viewer after initialization. This allows you to load different models, adjust rendering settings, and respond to viewer events in real-time.

Quick Example¶

// Send commands to the viewer
window.Module.webex_in("set_clear_color", "#FF0000");
window.Module.webex_in("open_scene", "https://example.com/model.webex");

For comprehensive documentation on all available commands and parameters, please refer to the Viewer WASM API reference.