Skip to main content

Presence for Matterport SDK

Our Matterport plugin is designed to seamlessly integrate avatars, mouse-pointers, lasers, and host controls into your digital twin tool. Additionally, the feature-rich SuperViz SDK for Matterport provides ample flexibility for creating the ideal user experience for your Matterport tool.

Before we start​

It is important to initialize a room with a defined name, ID, and avatar for the participant and for the group, as it will be used to store the comment data on our servers.

If no avatar is provided, then a default avatar from SuperViz will be used.

tip

When using Video Conference together with Presence3D you can enable users to select from our list of avatars, by setting the flag defaultAvatars as true on the Video Conference constructor.

Initializing Matterport SDK​

To initialize the Presence3D for Matterport, you will need to first have an iframe loaded with the Matterport SDK Bundle and have it accessible from a variable, like in the code below:

<iframe
  src="/bundle/showcase.html?m=[YOUR_SDK_KEY_HERE]"
  id="showcase">
</iframe>

<script>
  const showcase = document.getElementById("showcase");
	const showcaseWindow = showcase.contentWindow;

	showcase.addEventListener('load', async () => {
    if(!showcaseWindow) return;

    const mpSdk = await showcaseWindow.MP_SDK.connect(showcaseWindow);
  });

</script>

The minimum Matterport SDK Bundle version required is 3.1.77.2-1-g3baaac4893.

warning

To make sure everything works fine, make sure to use the SDK Bundle and not the SDK for Embeds when using Matterport.

Installing SuperViz Matterport extension​

The Presence3D component is not available from the @superviz/sdk package, instead, to use Presence 3D you must use the @superviz/matterport-plugin package.

To use the @superviz/matterport-plugin package please add the script below before the </head>

<script type="module" src="https://unpkg.com/@superviz/matterport-plugin@latest"></script>

How to use it​

To add a Matterport Presence3D component, you can use the following code:

import { Presence3D } from "@superviz/matterport-plugin";

const matterportPresence = new Presence3D(mpSdk, {
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isNameEnabled: true,
  avatarConfig: {
    height: 0,
    scale: 1,
    laserOrigin: { x: 0, y: 0, z: 0 },
  },
});

room.addComponent(matterportPresence);

When initializing the Presence3D you must pass the Matterport SDK instance loaded from the iframe as the first parameter (the mpSdk variable on the sample above), and as a second parameter you can use an options object with the listed properties:

NameTypeDescription
isAvatarsEnabledbooleanEnable or disable the need for avatar in the room.
Default value: false
isLaserEnabledbooleanEnable or disable laser pointers. If isAvatarsEnabled is set to false, this will also be false.
Default value: false
isNameEnabledbooleanEnable or disable showing the participant's name on top of the avatars.
Default value: false
avatarConfigAvatarConfigRequired. Configuration for avatar, like scale, position, and laser configuration.
warning

Please, make sure to only initialize the Presence3D once the Matterport Bundle iframe is fully loaded, otherwise you won’t be able to initialize the use of the component.

Methods​

follow()​

The follow() method, when called with a participant id as an argument, allows other participants to follow the referenced participant on the Matterport. You can, after, call the method without parameters to stop following the participant.

Example:

// Pass a participant ID to start following it
matterportPresence.follow("<PARTICIPANT_ID>");

// Call the method without parameters to stop following the past participant
matterportPresence.follow();

goTo()​

The goTo() method, when called with a participant id as an argument, allows other participants to quickly jump to the referenced participant position on the Matterport, facilitating quick location of participants.

Example:

matterportPresence.goTo("<PARTICIPANT_ID>");

Types Definition​

AvatarConfig​

Type: object

An object describing the configuration for avatar, like scale, position, and laser configuration.

NameTypeDescription
heightnumberRequired. The scale you want your avatar to be rendered, in pixels.
scalenumberRequired. The height you want your avatar to be positioned from the ground, in pixels.
laserOriginPositionRequired. Represents the origin position of your laser beam in relation to your avatar model.

Example:

avatarConfig: {
  height: 1.6,
  scale: 1,
  laserOrigin: {
    x: 0,
    y: 0,
    z: 0
  }
}

Position​

Type: object

Represents the origin position of your laser beam in relation to your avatar model.

NameTypeDescription
xnumberRequired. Represents the x-axis (horizontal) position.
ynumberRequired. Represents the y-axis (vertical) position.
znumberRequired. Represents the z-axis (depth) position.

Example:

laserOrigin: {
  x: 0,
  y: 0,
  z: 0
}