Matterport SDK
Usage of the SDK constitutes your agreement with the Matterport SDK Agreement. Email developers@matterport.com with any questions.

Index

Types

Color

Color: object

An RGB represenation of a color. Each property is normalized to the range [0, 1]

Type declaration

  • b: number
  • g: number
  • r: number

ConditionCallback

ConditionCallback: function

A callback that describes a condition of an IObservable to wait for. Returning true will resolve the promise returned by IObservable.waitUntil

The functional style version of the ICondition

Type declaration

    • (data: DataT): boolean
    • Parameters

      • data: DataT

      Returns boolean

MpSdk

MpSdk: object

The entire MP Sdk returned from a successful call to MP_SDK.connect. The Scene namespace is only available when connecting using the Bundle SDK

// for the Embed SDK
const sdk: MpSdk = await showcaseEmbeddingWindow.MP_SDK.connect(...);
// for the Bundle SDK
const sdk: MpSdk = await bundleWindow.MP_SDK.connect(...);

Type declaration

ObserverCallback

ObserverCallback: function

A callback that can be subscribed to changes of an IObservable

The functional style version of the IObserver

Type declaration

    • (data: DataT): void
    • Parameters

      • data: DataT

      Returns void

Orientation

Orientation: object

An orientation described with Euler-like angles in degrees.

Type declaration

  • pitch: number
  • roll: number
  • yaw: number

Rotation

Rotation: object

Type declaration

  • x: number
  • y: number
  • Optional z?: undefined | number

ShowcaseBundleWindow

ShowcaseBundleWindow: Window & typeof globalThis & object

A Window type that can be used to cast the bundle's iframe's contentWindow to hint at the existance of the MP_SDK object.

const bundleIframe = document.getElementById<HTMLIFrameElement>('showcase');
const showcaseWindow = bundleIframe.contentWindow as ShowcaseBundleWindow;
showcaseWindow.MP_SDK.connect(showcaseWindow);

ShowcaseEmbedWindow

ShowcaseEmbedWindow: Window & typeof globalThis & object

When including the sdk script (<script src='https://static.matterport.com/showcase-sdk/2.0.1-0-g64e7e88/sdk.js'>) on your page, an MP_SDK will be attached to the window object.

This type can be used to cast the window object to access the types available on the MP_SDK object.

const showcaseEmbeddingWindow = window as ShowcaseEmbedWindow;
showcaseEmbeddingWindow.MP_SDK.connect( ... )

Size

Size: object

Type declaration

  • h: number
  • w: number

Vector2

Vector2: object

Type declaration

  • x: number
  • y: number

Vector3

Vector3: object

Type declaration

  • x: number
  • y: number
  • z: number

Functions

disconnect

  • disconnect(): void
  • Stop sending and receiving messages and cleanup any resources associated with the sdk

    mpSdk.disconnect();
    // mpSdk can no longer make function calls, receive any callbacks to event, observable, or collection
    
    // all sdk functionality should throw errors
    try {
      await mpSdk.Mode.moveTo( ... );
    } catch (e) {
      console.error(e);
    }
    

    Returns void

off

  • off(event: any, callback: function): Emitter
  • Unsubscribes from an event.

    const callback = (model) => {
      console.log('My model loaded!');
    };
    
    // Start listening to the event.
    mpSdk.on(mpSdk.Event.MODEL_LOADED, callback);
    
    // Stop listening to the event.
    mpSdk.off(mpSdk.Event.MODEL_LOADED, callback);
    

    Parameters

    • event: any

      The event to stop.

    • callback: function

      The original callback.

        • (...any: any[]): void
        • Parameters

          • Rest ...any: any[]

          Returns void

    Returns Emitter

on

  • deprecated

    Use App.state observable to get phase change notifications.

    Parameters

    Returns Emitter

  • This event fires when the camera's pose has changed via a position or orientation change.

    The callback is called with the new pose of the camera.

    mpSdk.on(mpSdk.Camera.Event.MOVE,
      function(pose) {
        console.log(`Camera moved to position: ${pose.position}`);
        console.log(`with orientation: ${pose.rotation}`);
        console.log(`in mode: ${pose.mode}`);
        console.log(`currently at sweep: ${pose.sweep}`);
      }
    );
    
    @deprecated Use []
    

    Parameters

    Returns Emitter

  • This event fires when a floor change is starting.

    the callback returns the floor index that we are moving to, and the floor index we are moving from.

    mpSdk.on(mpSdk.Floor.Event.CHANGE_START,
      function(to, from) {
        console.log('Starting to move to floor ' + to + ' from floor ' + from);
      }
    );
    

    Parameters

    • event: Floor.Event.CHANGE_START
    • callback: function
        • (to: number, from: number): void
        • Parameters

          • to: number
          • from: number

          Returns void

    Returns Emitter

  • This event fires when a floor change is ending.

    the callback returns the floor index (0 based, counting from the bottom) and the floorName, as set in workshop, or defaulting to the same as floorIndex

    mpSdk.on(mpSdk.Floor.Event.CHANGE_END,
      function(floorIndex, floorName) {
        console.log('Arrived at floor ' + floorName);
        console.log('it is the ' + floorIndex+1 + 'th floor from the bottom');
      }
    );
    

    Parameters

    • event: Floor.Event.CHANGE_END
    • callback: function
        • (floorIndex: number, floorName: string): void
        • Parameters

          • floorIndex: number
          • floorName: string

          Returns void

    Returns Emitter

  • deprecated

    This event fires when the labels' on screen position has changed.

    mpSdk.on(Label.Event.POSITION_UPDATED,
      function(labels) {
        // Label data updated.
        console.log('On-screen position of first label: ' + JSON.stringify(labels[0].position));
      }
    );
    

    Parameters

    Returns Emitter

  • This event fires when the input pointer hovers onto or out of a mattertag disc.

    mpSdk.on(mpSdk.Mattertag.Event.HOVER,
      function (tagSid, hovering) {
        if (hovering) {
          console.log('Begin Hovering on', tagSid);
        } else {
          console.log('End Hovering on', tagSid);
        }
      }
    );
    

    Parameters

    • event: Mattertag.Event.HOVER
    • callback: function
        • (tagSid: string, hovering: boolean): void
        • Parameters

          • tagSid: string
          • hovering: boolean

          Returns void

    Returns Emitter

  • This event fires when the input pointer clicks a Mattertag disc.

    mpSdk.on(mpSdk.Mattertag.Event.CLICK,
      function (tagSid) {
        console.log(tagSid + ' was selected');
      }
    );
    

    Parameters

    • event: Mattertag.Event.CLICK
    • callback: function
        • (tagSid: string): void
        • Parameters

          • tagSid: string

          Returns void

    Returns Emitter

  • This event fires when a mattertag link is opened.

    mpSdk.on(mpSdk.Mattertag.Event.LINK_OPEN,
      function (tagSid, url) {
        console.log('The link ' + url + ' opened for sid ' + tagSid);
      }
    );
    

    Parameters

    • event: Mattertag.Event.LINK_OPEN
    • callback: function
        • (tagSid: string, url: string): void
        • Parameters

          • tagSid: string
          • url: string

          Returns void

    Returns Emitter

  • This event fires when the camera is starting to transition to a mode.

    mpSdk.on(mpSdk.Mode.Event.CHANGE_START,
      function(oldMode, newMode){
        console.log('Mode changing from ' + oldMode);
        console.log('Mode changing to  ' + newMode);
      }
    );
    

    Parameters

    • event: Mode.Event.CHANGE_START
    • callback: function
        • (oldMode: string, newMode: string): void
        • Parameters

          • oldMode: string
          • newMode: string

          Returns void

    Returns Emitter

  • This event fires when the camera has completed a transition to a mode.

    mpSdk.on(mpSdk.Mode.Event.CHANGE_END,
      function(oldMode, newMode){
        console.log('Mode changed from ' + oldMode);
        console.log('Mode changed to  ' + newMode);
      }
    );
    

    Parameters

    • event: Mode.Event.CHANGE_END
    • callback: function
        • (oldMode: string, newMode: string): void
        • Parameters

          • oldMode: string
          • newMode: string

          Returns void

    Returns Emitter

  • This event fires when the model has been loaded.

    mpSdk.on(mpSdk.Model.Event.MODEL_LOADED,
      function(model){
        console.log('Model sid:' + model.sid);
      }
    );
    

    Parameters

    Returns Emitter

  • This event fires when first entering a sweep.

    mpSdk.on(mpSdk.Sweep.Event.ENTER,
      function(oldSweep, newSweep){
        console.log('Leaving sweep ' + oldSweep);
        console.log('Entering sweep ' + newSweep);
      }
    );
    

    Parameters

    • event: Sweep.Event.ENTER
    • callback: function
        • (oldSweep: string, newSweep: string): void
        • Parameters

          • oldSweep: string
          • newSweep: string

          Returns void

    Returns Emitter

  • This event fires when exiting a sweep.

    mpSdk.on(mpSdk.Sweep.Event.EXIT,
      function(fromSweep, toSweep){
        console.log('Leaving sweep ' + fromSweep);
        console.log('Transitioning to sweep ' + toSweep);
      }
    );
    

    Parameters

    • event: Sweep.Event.EXIT
    • callback: function
        • (fromSweep: string, toSweep: string | undefined): void
        • Parameters

          • fromSweep: string

            The exit sweep.

          • toSweep: string | undefined

            The destination sweep. This value is only valid for inside mode. It is undefined for floorplan and dollhouse mode.

          Returns void

    Returns Emitter

  • This event fires when the tour has started.

    mpSdk.on(mpSdk.Tour.Event.STARTED,
      function() {
        console.log('Tour started!');
      }
    );
    

    Parameters

    Returns Emitter

  • This event fires when the tour has stopped.

    mpSdk.on(mpSdk.Tour.Event.STOPPED,
      function() {
        console.log('Tour stopped!');
      }
    );
    

    Parameters

    Returns Emitter

  • This event fires when the tour has ended.

    mpSdk.on(mpSdk.Tour.Event.ENDED,
      function() {
        console.log('Tour ended!');
      }
    );
    

    Parameters

    Returns Emitter

  • This event fires when the tour has stepped.

    mpSdk.on(mpSdk.Tour.Event.STEPPED,
      function(activeIndex) {
        console.log('Tour has reached step ' + activeIndex);
      }
    );
    

    Parameters

    • event: Tour.Event.STEPPED
    • callback: function
        • (activeIndex: number): void
        • Parameters

          • activeIndex: number

          Returns void

    Returns Emitter