Documentation

Appearance

Viz4D Viewer JavaScript API ​

API latest version v0.2 ​

html
<script type="text/javascript" src="https://r.viz4d.com/api/viewer-api-0.2.js"></script>
Changelog
  • v0.2: Add new fn: toggleFullscreen, toggleMeasure, toggleHotspotVisible, toggleControlMode, toggleHelpDialog, toggleSectionDialog, toggleCaptureDialog, toggleXRDialog
  • v0.1: Initial release
Sample Code
html
<script type="text/javascript" src="https://r.viz4d.com/api/viewer-api-0.2.js"></script>

<!-- Normal iframe embed code -->
<iframe id="viewer-iframe" src="https://viz4d.com/viewer/_YOUR_SCENE_ID_" width="640" height="480" frameborder="0" allowfullscreen mozallowfullscreen="true" webkitallowfullscreen="true" allow="autoplay;fullscreen;xr-spatial-tracking;display-capture;gamepad" xr-spatial-tracking execution-while-out-of-viewport execution-while-not-rendered web-share></iframe>

<script>
    const viewer = new V4DViewerAPI( document.getElementById("viewer-iframe"), {
        btnXR: false,
        btnCrossSection: false
    } );

    viewer.ready().then( async () => {
        console.log("Begin select new mtl");
        await viewer.selectMtl( "FLOOR", "Dark Wood Mtl" );
        console.log("Finish select new mtl");
    });
</script>

V4DViewerAPI Constructor ​

js
const viewer = new V4DViewerAPI ( HTMLIFrameElement, options = {
    debug: false, // verbose logging
    btnXR: true,
    btnFullScreen: true,
    btnCrossSection: true,
    btnCapture: true,
    btnMeasure: true,
    btnHelp: true,
    btnShare: true,
    btnControlMode: true,
    btnHotspot: true,
    btnPlay: true,
    btnInfo: true,
    
    logo: true,
    preloaderInfo: true,
    loadingSign: true,
    progressBar: true,
    menuTour: true,
    initialInfo: true, // Open scene info sidepanel at start, auto close after some seconds
    initialHelp: true, // Show help dialog at start, auto close after some seconds

    tourAutoplay: true,
    autoVariant: false // if true, auto change mtl without needing user action, it will be stopped when user open any configHotspot for the first time
} );

API METHODS ​

play() ​

Returns: Promise<void>

pause( options ) ​

Parameters:

  • options object (optional)
    • showPreloader boolean - Show preloader screen after pause (default: true)

Returns: Promise<void>

isPlaying() ​

Returns: Promise< boolean >

selectMtl( mtlSetID, mtlName, options ) ​

Parameters:

  • mtlSetID string
  • mtlName string
  • options object (optional)
    • transition number - Transition duration in ms (default: 2000)

Returns: Promise<void>

Description: Select a material from existing materials in mtlSet

INFO

This promise resolves in two scenarios:

  1. When the transition animation fully completes
  2. When a new selectMtl() call is made for the same mtlSet before the current transition finishes. In this case, the current transition will be interrupted and the promise will resolve early.

selectMtlBySKU( mtlSetID, mtlSKU, options ) ​

Description: Behavior similar to selectMtl(), but select by SKU instead of name.

getSelectedMtl( mtlSetID ) ​

Parameters:

  • mtlSetID string

Returns: Promise< { name, sku, content } >

Description: Get the currently selected material in mtlSet

openHotspot( hotspotName, options ) ​

Parameters:

  • hotspotName string
  • options object (optional)
    • goToView boolean - Go to the hotspot view after open (default: true)
    • transition number - Transition duration in ms (default: 3000)

Returns: Promise<void>

Description: Open a hotspot. Note: This promise resolve when transitionEnd

openInfo() ​

Returns: Promise<void>

Description: Open the scene info popup (title, description)

isPopupOpen() ​

Returns: Promise< boolean >

Description: Check if any popup is currently opened.

INFO

Only 1 popup can be opened at one time. Open a new popup will auto close the current popup.

closePopup() ​

Returns: Promise<void>

Description: Close the currently opened popup (hotspot / info)

toggleControlMode() ​

Returns: Promise<void>

Description: Switch between Orbit and Walk control modes

toggleMeasure() ​

Returns: Promise<void>

Description: Toggle measure tool

toggleHotspotVisible() ​

Returns: Promise<void>

Description: Toggle visibility of all hotspots

toggleHelpDialog() ​

Returns: Promise<void>

toggleSectionDialog() ​

Returns: Promise<void>

toggleCaptureDialog() ​

Returns: Promise<void>

toggleXRDialog() ​

Returns: Promise<void>

on( eventName, callback ) ​

Returns: void

Description: Add a callback to an event

off( eventName, callback ) ​

Returns: void

Description: Remove a callback from an event

once( eventName, callback ) ​

Returns: void

Description: Add a callback to an event, but it will be removed after the first time it is triggered.

LOADING STATES

Viewer has 3 loading states, sorted in chronological order:

initialized >> ready >> loaded

initialized() ​

Returns: Promise<void>

Description: This promise resolve when the Viewer finish initialization and begin to loading assets.

List of fn available before initialized: on, off, once, initialized, ready, loaded, isPlaying, pause, play

Note

If Viewer has autoplay off (?autoplay=0) then initialized only trigger after the Viewer play.

ready() Promise<void> ​

This promise resolve when scene has loaded minimum necessary data of all objects and materials, but not fully loaded, which means low LOD of meshes/textures are added to scene, but higher LOD are still loading progressively.

INFO

All api fn are available after this ready state.

loaded() Promise<void> ​

This promise resolve when all data of scene is fully loaded.

API EVENTS ​

Events Usage Example:
javascript
viewer.on("playStateChange", (isPlaying) => {
    console.log("Viewer is now:", isPlaying ? "playing" : "paused");
});

viewer.on("hotspotOpen", ({ name, sku, content }) => {
    console.log(`Hotspot "${name}" opened`);
});

playStateChange ​

Callback Parameters:

  • isPlaying boolean - Current play state of the viewer

hotspotOpen ​

Callback Parameters: object

typescript
{
    name: string,    // Name of the opened hotspot
    sku: string,     // SKU of the opened hotspot
    content: string  // Markdown content of the hotspot
}

hotspotClose ​

Callback Parameters: void

selectMtlStart ​

Callback Parameters: object

typescript
{
    mtlSetID: string,  // ID of the material set being changed
    name: string       // Name of the new material
}

selectMtlEnd ​

Callback Parameters: object

typescript
{
    mtlSetID: string,  // ID of the material set that was changed
    name: string       // Name of the applied material
}