Namespace: Tag

Two properties are required:

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

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. They also do not have "share" buttons as they associated with them.

mpSdk.Tag.add({
 label: 'New tag',
 description: 'This tag was added through the Matterport SDK',
 anchorPosition: {
   x: 0,
   y: 0,
   z: 0,
 },
 stemVector: { // make the Tag 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,
 },
}, {
 label: 'New tag 2',
 anchorPosition: {
   x: 1,
   y: 2,
   z: 3,
 },
 stemVector: {
   x: ,
   y: ,
   z: ,
 }
});

const tagIds: string[]; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`

// prevent navigating to the tag on click
const noNavigationTag = tagIds[0];
mpSdk.Tag.allowAction(noNavigationTag, {
  opening: true,
  // implies navigating: false, etc
});

// prevent the billboard from showing
const noBillboardTag = tagIds[1];
mpSdk.Tag.allowAction(noBillboardTag, {
  navigating: true,
  // implies opening: false, etc
});

const noActionsTag = tagIds[2];
mpSdk.Tag.allowAction(noActionsTag, {
  // implies opening: false and navigating: false, etc
});

const tagId: string; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
const attachmentIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.registerAttachment` or through `mpSdk.Tag.attachments`

mpSdk.Tag.attach(tagId, ...attachmentIds);
// or
mpSdk.Tag.attach(tagId, attachmentId[0], attachmentId[1]);

const tagId: string; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
mpSdk.Tag.open(tagId);
mpSdk.Tag.close(tagId);

const tagId: string; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
const attachmentIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.registerAttachment` or through `mpSdk.Tag.attachments`

mpSdk.Tag.detach(tagId, ...attachmentIds);
// or
mpSdk.Tag.detach(tagId, attachmentId[0], attachmentId[1]);

const tagId: string; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
mpSdk.Tag.dock(tagId);

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

mpSdk.Tag.editBillboard(id, {
  label: 'This is a new title',
  description: 'This image was set dynamically by the Showcase sdk',
});

const tagIds: string[]; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`

// change the first Tag to yellow
mpSdk.Tag.editColor(tagIds[0], {
  r: 0.9,
  g: 0,
  b: 0.9,
});

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

// change the icon of the Tag using the id used in a previous `Asset.registerTexture` call
mpSdk.Tag.editIcon(id, 'customIconId');

// change the icon of the Tag to a font id.
mpSdk.Tag.editIcon(id, 'public_buildings_apartment');

A completely transparent/invisible Tag is still interactable and will respond to mouse hovers and clicks.

const tagIds: string[]; // ... acquired through previous calls to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
// make the first Tag invisible
mpSdk.Tag.editOpacity(tagIds[0], 0);

// make another Tag transparent
mpSdk.Tag.editOpacity(tagIds[1], 0.5);

// and another completely opaque
mpSdk.Tag.editOpacity(tagIds[2], 1);

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.

const tagId: string; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`

mpSdk.Tag.editPosition(tagId, {
 anchorPosition: {
   x: 0,
   y: 0,
   z: 0,
 },
 stemVector: { // make the Tag stick straight up and make it 0.30 meters (~1 foot) tall
   x: 0,
   y: 0.30,
   z: 0,
 },
});

const newRoomId; // precomputed room id
const tagId1, tagId2, tagId3; // predetermined tag ids.
const tagIds: MpSdk.Tag.EditPositionDescriptor[] = []; // an array of tag edit position descriptors

// updates anchorPosition for tag1
tagIds.push({
  id: tag1,
  options: {
    anchorPosition: {
      x: 0,
      y: 0,
      z: 0,
    },
  },
});

// updates roomId for tag2
tagIds.push({
  id: tag2,
  options: {
    roomId: newRoomId,
  },
});

// updates stemVector for tag3
tagIds.push({
  id: tag3,
  options: {
    stemVector: { // make the Tag stick straight up and make it 0.30 meters (~1 foot) tall
      x: 0,
      y: 0.30,
      z: 0,
    },
  },
});

// apply bulk updates
await mpSdk.Tag.editPositions(...tagIds);

const tagId: string = tagData[0].id; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`

// make the first Tag have an invsible stem
mpSdk.Tag.editStem(tagId, {stemVisible: false});

// make another Tag have a long stem
mpSdk.Tag.editStem(tagId, {stemHeight: 1});

mpSdk.Tag.open(tagId);

// if the tag has had its `dock` option removed through a call to `Tag.allowAction`, it can be `force`d open
mpSdk.Tag.allowAction(tagId, {
  opening: false,
});
mpSdk.Tag.open(tagId,
  force: true,
});

Custom HTML can be added as an attachment through the use of registerSandbox instead.

// register a couple of attachments to use later
const [attachmentId1, attachmentId2] = mpSdk.Tag.registerAttachment(
  'https://[link.to/media]',
  'https://[link.to/other_media]',
);

const htmlToInject = `
  <style>
    button {
      width: 100px;
      height: 50px;
    }
  </style>
  <button id='btn1'>CLICK ME</button>
  <script>
    var btn1 = document.getElementById('btn1');
    btn1.addEventListener('click', () => {
      // send data out of the sandbox
      window.send('buttonClick', 12345);
    });
    // receive data from outside of the sandbox
    window.on('updateButton', (newLabel, color) => {
      btn1.innerText = newLabel;
      btn1.style.backgroundColor = color;
    });
  </script>
`;

// create and register the sandbox
const [sandboxId, messenger] = await mpSdk.Tag.registerSandbox(htmlToInject);
// attach the sandbox to a tag
mpSdk.Tag.attach(tagId, sandboxId);
// receive data from the sandbox
messenger.on('buttonClick', (buttonId) => {
  console.log('clicked button with id:', buttonId);
});
// send data to the sandbox
messenger.send('I send messages', 'red');

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

const tagIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`
// remove one tag
mpSdk.Tag.remove(tagIds[0]);

// or remove multiple at the same time
mpSdk.Tag.remove(...tagIds);

const tagIds: string[]; // ... acquired through a previous call to `mpSdk.Tag.add` or through `mpSdk.Tag.data`

// reset the icon of the first Tag to its original
mpSdk.Tag.resetIcon(tagIds[0].id);

Disabling the dock setting will remove the dock buttons from all tags. Enabling the dock setting does not automatically show the dock button in all tags. The dock button will only be displayed in a tag if both the dock setting is true and docking is allowed by the tag (see Tag.allowAction).

// hide the dock buttons
mpSdk.Tag.toggleDocking(false);

// show the dock buttons
mpSdk.Tag.toggleDocking(true);

// toggle the current visibility of the dock buttons
mpSdk.Tag.toggleDocking();

// hide the controls
mpSdk.Tag.toggleNavControls(false);

// show the controls
mpSdk.Tag.toggleNavControls(true);

// toggle the current visibility of the controls
mpSdk.Tag.toggleNavControls();

Disabling the share setting will remove the share buttons from all tags. Enabling the share setting does not automatically show the share button in all tags. The share button will only be displayed in a tag if both the share setting is true and sharing is allowed by the tag (see Tag.allowAction).

// hide the share buttons
mpSdk.Tag.toggleSharing(false);

// show the share buttons
mpSdk.Tag.toggleSharing(true);

// toggle the current visibility of the share buttons
mpSdk.Tag.toggleSharing();