Mattertag Namespace

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

Index

Types

EditableProperties

EditableProperties: object

Type declaration

InjectionOptions

InjectionOptions: object

Options that can be specified when injection custom HTML into a Mattertag.

Type declaration

  • Optional messageFcnMapping?: Mattertag.MessengerFcnMapping

    A map for the three global functions we provide in your iframe sandbox. Only needs to be used if scripts you are importing also have a global send, on, or off function.

  • Optional size?: Size

    The size of the frame to create

  • Optional windowPath?: undefined | string

    The path between Showcase's window and your window (with the sdk).

    If you embed Showcase normally, this can be omitted.

    If you put Showcase within another level of iframe on your page, the path would be 'parent.parent'; Showcase's parent is the iframe, the parent of that frame is your page.

    If you programmatically open Showcase in a new window, use 'opener'.

    When using the Bundle SDK use ''.

MattertagData

MattertagData: object

Type declaration

  • anchorNormal: Vector3
  • anchorPosition: Vector3

    The world space position of the mattertag anchor within the model

  • color: Color
  • description: string
  • enabled: boolean
  • floorId: number
  • floorIndex: number
  • floorInfo: object
    • id: string
    • sequence: number
  • label: string
  • media: object
  • mediaSrc: string
  • mediaType: Mattertag.MediaType
  • parsedDescription: Mattertag.DescriptionChunk[]
  • sid: string
  • stemHeight: number
  • stemVector: Vector3

    The world space (non-normal) direction of the mattertag's stem

  • stemVisible: boolean

MessengerFcnMapping

MessengerFcnMapping: object

Map the global functions we provide in your sandbox to other names.

Type declaration

  • Optional off?: undefined | string
  • Optional on?: undefined | string
  • Optional send?: undefined | string

ObservableMattertagData

ObservableMattertagData: object

Type declaration

  • anchorPosition: Vector3

    The world space position of the mattertag anchor within the model

  • color: Color
  • description: string
  • enabled: boolean
  • floorIndex: number
  • floorInfo: object
    • id: string
    • sequence: number
  • label: string
  • media: object
  • sid: string
  • stemVector: Vector3

    The world space (non-normal) direction of the mattertag's stem

  • stemVisible: boolean

PreventableActions

PreventableActions: object

Type declaration

  • navigating: boolean
  • opening: boolean

Properties

data

An observable collection of Mattertag data that can be subscribed to.

When first subscribing, the current set of Mattertag will call the observer's onAdded for each Mattertag as the data becomes available.

showcase.Mattertag.data.subscribe({
  onAdded: function (index, item, collection) {
    console.log('Mattertag added to the collection', index, item, collection);
  },
  onRemoved: function (index, item, collection) {
    console.log('Mattertag removed from the collection', index, item, collection);
  },
  onUpdated: function (index, item, collection) {
    console.log('Mattertag updated in place in the collection', index, item, collection);
  }
});

Methods

add

  • Add one or more Mattertags to Showcase. Each input Mattertag supports setting the label, description, color, anchorPosition, and stemVector.

    Two properties are required:

    • anchorPosition, the point where the tag connects to the model
    • stemVector, the direction, aka normal, and height that the Mattertag stem points

    See Pointer.intersection for a way to retrive a new anchorPosition and stemVector.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    mpSdk.Mattertag.add([{
     label: "New tag",
     description: "This tag was added through the Matterport SDK",
     anchorPosition: {
       x: 0,
       y: 0,
       z: 0,
     },
     stemVector: { // make the Mattertag stick straight up and make it 0.30 meters (~1 foot) tall
       x: 0,
       y: 0.30,
       z: 0,
     },
     color: { // blue disc
       r: 0.0,
       g: 0.0,
       b: 1.0,
     },
     floorIndex: 0, // optional, if not specified the sdk will provide an estimate of the floor index for the anchor position provided.
    }])
    

    Parameters

    Returns Promise<string[]>

    A promise that resolves with the sids for the newly added Mattertags.

editBillboard

  • Edit the data in a Mattertag billboard.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    mpSdk.Mattertag.editBillboard(sid, {
      label: 'This is a new title',
      description: 'This image was set dynamically by the Showcase sdk'
      media: {
        type: mpSdk.Mattertag.
        src: 'https://www.image.site/image.jpg'
      }
    });
    

    Parameters

    Returns Promise<void>

editColor

  • editColor(tagSid: string, color: Color): Promise<void>
  • Edit the color of a Mattertag

    // acquired through a previous call to mpSdk.Mattertag.getData();
    var mattertagData;
    
    // change the first Mattertag to yellow
    mpSdk.Mattertag.editColor(mattertagData[0].sid, {
      r: 0.9,
      g: 0.9,
      b: 0,
    });
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to edit

    • color: Color

      The new color to be applied to the Mattertag disc

    Returns Promise<void>

editIcon

  • editIcon(tagSid: string, iconId: string): Promise<void>
  • Change the icon of the Mattertag disc

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    // acquired through a previous call to mpSdk.Mattertag.getData();
    var mattertagData;
    
    // change the icon of the first Mattertag using the id used in a previously registeredIcon call
    mpSdk.Mattertag.editIcon(mattertagData[0].sid, 'customIconId');
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to edit

    • iconId: string

      The id of the icon to apply

      Errors

      Warns if the provided iconSrc is an .svg file which doesn't have a 'width' or 'height' attribute. Defaults to a resolution of 128x128 if neither exist.

    Returns Promise<void>

editOpacity

  • editOpacity(tagSid: string, opacity: number): Promise<void>
  • Edit the opacity of a Mattertag

    // acquired through a previous call to mpSdk.Mattertag.getData();
    var mattertagData;
    
    // make the first Mattertag invisible
    mpSdk.Mattertag.editOpacity(mattertagData[0].sid, 0);
    
    // make another Mattertag transparent
    mpSdk.Mattertag.editOpacity(mattertagData[1].sid, 0.5);
    
    // and another completely opaque
    mpSdk.Mattertag.editOpacity(mattertagData[2].sid, 1);
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to edit

    • opacity: number

      THe target opacity for the Mattertag in the range of [0, 1]

    Returns Promise<void>

editPosition

  • Move and reorient a Mattertag.

    See Pointer.intersection for a way to retrieve a new anchorPosition and stemVector.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    var mattertagData; // ... acquired through a previous call to mpSdk.Mattertag.getData();
    
    mpSdk.Mattertag.editPosition(mattertagData[0].sid, {
     anchorPosition: {
       x: 0,
       y: 0,
       z: 0,
     },
     stemVector: { // make the Mattertag stick straight up and make it 0.30 meters (~1 foot) tall
       x: 0,
       y: 0.30,
       z: 0,
     },
     floorIndex: 2,
    });
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to reposition

    • moveOptions: Partial<Mattertag.PositionOptions>

      The new anchorPosition, stemVector and/or floorId.

    Returns Promise<void>

getData

  • deprecated

    Use the observable data collection instead

    This function returns metadata on the collection of Mattertags.

    mpSdk.Mattertag.getData()
      .then(function(mattertags) {
        // Mattertag data retreival complete.
        if(mattertags.length > 0) {
          console.log('First mattertag label: ' + mattertags[0].label);
          console.log('First mattertag description: ' + mattertags[0].description);
        }
      })
      .catch(function(error) {
        // Mattertag data retrieval error.
      });
    

    Returns Promise<Mattertag.MattertagData[]>

getDiscPosition

  • Get the disc's (3d) position of a Mattertag. The original data only represent the point that attaches the tag to the model.

    var mattertags; // get mattertag collection from mpSdk.Mattertag.getData
    var tagDiscPosition = mpSdk.Mattertag.getDiscPosition(mattertags[0]);
    

    Parameters

    Returns Vector3

injectHTML

  • Add a custom frame that can host custom HTML and JavaScript, and communicate bi-directionally with your page.

    The frame that contains your custom code will have certain limitations due to being sandboxed by the sandbox='allow-scripts attribute. Attempting to access properties of other windows will also be blocked by the browser. (see the MDN pages about iframe sandbox)

    Currently, the HTML CAN ONLY BE SET ONCE by a call to injectHTML. This includes removing or clearing the HTML.

    var mattertagData; // ... acquired through a previous call to mpSdk.Mattertag.getData();
    
    // create a 100x50px button within the Mattertag and send out an ID when it is clicked
    var htmlToInject = ' \
      <style> \
        button { \
          width: 100px; \
          height: 50px; \
        } \
      </style> \
      <button id="btn1">CLICK ME</button> \
      <script> \
        var btn1 = document.getElementById("btn1"); \
        btn1.addEventListener("click", function () { \
          window.send("buttonClick", 12345); \
        }); \
      </script>';
    
    mpSdk.Mattertag.injectHTML(mattertagData[0], htmlToInject, {
      size: {
        w: 100,
        h: 50,
      }
    })
      .then(function (messenger) {
        messenger.on("buttonClick", function (buttonId) {
          console.log('clicked button with id:', buttonId);
        });
      });
    

    Parameters

    Returns Promise<Mattertag.IMessenger>

navigateToTag

  • This function navigates to the Mattertag disc with the provided sid, opening the billboard on arrival.

    mpSdk.Mattertag.navigateToTag(sid, mpSdk.Mattertag.Transition.FLY);
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to navigate to

    • transition: Mattertag.Transition

      The type of transition to navigate to a sweep where the Mattertag disc is visible

    Returns Promise<string>

preventAction

  • Prevents the "default" Showcase action on a Mattertag from occurring: hover to open billboard, click to navigate to view.

    var mattertagData; // ... acquired through a previous call to mpSdk.Mattertag.getData();
    
    // prevent navigating to the tag on click
    var noNavigationTag = mattertagData[0];
    mpSdk.Mattertag.preventAction(noNavigationTag.sid, {
      navigating: true,
    });
    
    // prevent the billboard from showing
    var noBillboardTag = mattertagData[1];
    mpSdk.Mattertag.preventAction(noBillboardTag.sid, {
      opening: true,
    });
    
    var noActionsTag = mattertagData[2];
    mpSdk.Mattertag.preventAction(noActionsTag.sid, {
      opening: true,
      navigating: true,
    });
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to remove actions from

    • actions: Partial<Mattertag.PreventableActions>

      The set of actions to prevent

    Returns Promise<void>

registerIcon

  • registerIcon(iconId: string, iconSrc: string): Promise<void>
  • Register an icon to use with subsequent Mattertag.editIcon calls.

    Note: It is recommended to host your own images to mitigate cross origin limitations.

    mpSdk.Mattertag.registerIcon('customIconId', 'https://[link.to/image]');
    

    Parameters

    • iconId: string

      A user specified string to use as a lookup of this icon

    • iconSrc: string

      The src of the icon, like the src of an

    Returns Promise<void>

remove

  • remove(tagSids: string | string[]): Promise<string[]>
  • Removes one or more Mattertags from Showcase.

    Note: these changes are not persisted between refreshes of Showcase. They are only valid for the current browser session.

    var mattertagData; // ... acquired through a previous call to mpSdk.Mattertag.getData();
    var first = mattertagData[0];
    mpSdk.Mattertag.remove(first.sid);
    
    var second = mattertagData[1];
    var third = mattertagData[2];
    mpSdk.Mattertag.remove([second.sid, third.sid]);
    

    Parameters

    • tagSids: string | string[]

      A single Mattertag sid or array of Mattertag sids to remove.

    Returns Promise<string[]>

    A promise with an array of Mattertag sids that were actually removed.

resetIcon

  • resetIcon(tagSid: string): Promise<void>
  • Resets the icon of the Mattertag disc back to its original icon.

    // acquired through a previous call to mpSdk.Mattertag.getData();
    var mattertagData;
    
    // reset the icon of the first Mattertag to its original
    mpSdk.Mattertag.resetIcon(mattertagData[0].sid);
    

    Parameters

    • tagSid: string

      The sid of the Mattertag to reset

    Returns Promise<void>