3D Embed API guide

Overview

The 3D Embed API enables you to create interactive, customizable 3d embeds in your website.

Getting started

Installation

npm install @archilogic/embed-api

Usage

// via npm
import ArchilogicEmbed from '@archilogic/embed-api'
// via browser module
import ArchilogicEmbed from 'https://code.archilogic.com/embed-api/v1.1.0/embed.module.js'
// via cdn
<script type="text/javascript" src="https://code.archilogic.com/embed-api/v1.1.0/embed.js"></script>

Startup options

const viewer = new ArchilogicEmbed(document.body, {
  // available at https://developers.archilogic.com/api-keys.html
  accessToken: '<accessToken>',
  transparentBackground: true,
  presentationMode: PresentationMode.jumpToCameraDefault,
  minimap: false,
  showTitle: false,
  showLogo: false,
  uiButtons: { 
    birdMode: false, 
    personMode: false,
    fullscreen: false,
    bookmarkStrip: false,
    share: false,
    help: false,
    presentation: false
  }
})
// await for the viewer embed to be ready
await viewer.viewerReadyPromise.catch(err => console.error('viewer couldnt be initialized', err))

Startup options correspond to different features in the Archilogic Viewer

Updating startup options

It's possible to update the startup options after initialization

// any value from the startup options can be updated
await viewer.set({
  minimap: true
})
// the passed update object will be deep merged with the current options 
await viewer.set({
  showTitle: true,
  uiButtons: {
    birdMode: false
  },
  ...
})

Presentation modes

  • PresentationMode.goToCameraDefault - transition to the default camera position
  • PresentationMode.goToFirstBookmark- transition to the first bookmark
  • PresentationMode.jumpToCameraDefault - go immediately to the default camera position
  • PresentationMode.jumpToFirstBookmark - go immediately to the first bookmark
  • PresentationMode.none - do nothing
  • PresentationMode.tourLoop - loop through the scene bookmarks
  • PresentationMode.tourOnce - loop through the scene bookmarks once
  • PresentationMode.tourOnceAndGoBack - loop through the scene bookmarks and return to the first bookmark

The presentation mode passed to the startup options controls how the scene behaves as it begins to load.

import { PresentationMode } from '@archilogic/embed-api'
// Update after a scene has loaded. This will not start a new presentation, but will take effect once a new scene is loaded or a presentation is started
await viewer.set({ presentationMode: PresentationMode.tourLoop })
// Explicitly start a presentation
viewer.startPresentation()

Methods

The Embed API is promise-based; all actions return promises by default

Load scene

const demoSceneId = 'a9aaafdf-d5b6-4b4a-82a0-9efb6d5b155a'
await viewer.loadScene(demoSceneId).catch(err => {
  // scene couldn't be loaded - it may be private or the ID couldn't be found
  console.error('There was an error loading the scene:', err)
})

Common navigation

Common navigation actions are exposed as methods. Promises will be resolved if a navigation transition is interupted by a user-action

// zoomExtents, goToBirdMode and goToPersonMode all accept an `{ animate }` property, which is true by default 
await viewer.goToBirdMode({ animate: true })
await viewer.goToPersonMode({ animate: false })
await viewer.zoomExtents({ animate: true })

Bookmark navigation

// list the bookmarks of the currently loaded scene
const bookmarks = await viewer.listBookmarks()
const randomBookmark = bookmarks[Math.floor(Math.random() * bookmarks.length)]
await viewer.goToBookmark({ bookmarkId: randomBookmark.id, animate: true })

Space navigation

viewer.zoomExtents can also be used to navigate to the extents of a specific space

// list the spaces of the currently loaded scene
const spaces = await viewer.listSpaces()
const randomSpace = spaces[Math.floor(Math.random() * spaces.length)]
await viewer.zoomExtents({ animate: false, spaceId: randomSpace.id  })

Removing an instance

// will immediately stop the embedded viewer from receiving messages 
// and clean up any existing event listeners
viewer.destroy()

Events

Supported events: sceneDefined, loadingStart, loadingDone

// listening for user input
const eventId = viewer.on('loadingDone', () => {
  // loading is done
  // remove the listener
  viewer.off(eventId)
})

Sync usage

Used syncronously, methods will cancel each other, this can be used to interupt and cancel actions when needed

// only `goToPersonMode` will have effect
viewer.goToBirdMode()
viewer.goToPersonMode()
// only scene4 will be loaded, the rest will be cancelled
viewer.loadScene(scene1)
viewer.loadScene(scene2)
viewer.loadScene(scene3)
viewer.loadScene(scene4)