Presence for Matterport SDK

The Matterport plugin is designed to seamlessly integrate Presence controls, Mouse Pointers, avatars, and lasers into your digital twin application.

Before we start

Before utilizing the Matterport component, it is essential to initialize a room with a defined name and ID for the participant.

Below are a few important notes:

• If you want to use 3D avatars, see initialization for further info. if no avatar has been provided, then a default avatar from SuperViz will be used.
• The minimum Matterport SDK Bundle version required is 3.1.77.2-1-g3baaac4893.
• Make sure to use the SDK Bundle and NOT the "SDK for Embeds" when using Matterport.

Matterport Loader vs Matterport Plugin

There are two different approaches how to implement SuperViz into a Matterport SDK instance.

• Choose Matterport loader if you want SuperViz to handle the loading of the Matterport SDK instance and then add the SuperViz plugin. You only need to pass your Matterport SDK key, and the path to the bundle the component takes care of the rest.
• Choose Plugin if you've already built your Matterport SDK application and want to have complete control of the loading part. Then you just need to pass your Matterport SDK instance and the component takes care of the rest.

tip

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

How to use

Matterport Loader

import { MatterportIframe } from "@superviz/react-sdk";

function Room() {
return (
  <MatterportIframe
    bundleUrl={PATH_TO_BUNDLE+ `/showcase.html?applicationKey=${MATTERPORT_KEY}&m=`+MODEL_ID}
    matterportKey={"<MATTERPORT_KEY>"}
  />
);
}

export default Room;

Matterport Plugin

import { MatterportPresence } from "@superviz/react-sdk";
import { useState } from "react";

function Room() {
 const [mpSdkInstance, setMpSdkInstance] = useState(null);
 const showcase = document.getElementById("showcase");
   const showcaseWindow = showcase.contentWindow;

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

     const matterportSDK = await showcaseWindow.MP_SDK.connect(showcaseWindow);
     setMpSdkInstance(matterportSDK);
   });
 }, []);

 return (
   <MatterportPresence matterportSdkInstance={mpSdkInstance}>
     <iframe id="showcase" />
   </MatterportPresence>
 );
}

export default Room;

Properties

Matterport loader

Name	Type	Description
bundleUrl	string	Required. Path to matterport bundle in your project.
matterportKey	string	Required. Matterport API key retrieved from Matterport
isAvatarsEnabled	boolean	Optional. Enable or disable the need for an avatar in the room. Default value: false
isLaserEnabled	boolean	Optional. Enable or disable laser pointers. If isAvatarsEnabled is set to false, this will also be false. Default value: false
isNameEnabled	boolean	Optional. Enable or disable showing the participant's name on top of the avatars. Default value: false
avatarConfig	AvatarConfig	Optional. Configuration for the avatar, like scale, position, and laser configuration.

This component works as an iFrame, so besides the properties shown above, you can also use the HTMLIFrameElement properties, check the MDN documentation for more information.

Matterport Plugin

Name	Type	Description
matterportSdkInstance	MpSdk	Required. Matterport SDK instance. Default value: false
isAvatarsEnabled	boolean	Optional. Enable or disable the need for an avatar in the room. Default value: false
isLaserEnabled	boolean	Optional. Enable or disable laser pointers. If isAvatarsEnabled is set to false, this will also be false. Default value: false
isNameEnabled	boolean	Optional. Enable or disable showing the participant's name on top of the avatars. Default value: false
avatarConfig	AvatarConfig	Optional. Configuration for the avatar, like scale, position, and laser configuration.

Events

Matterport loader

onMpSdkLoaded

Type: ({ matterportSdkInstance, showcaseWindow }: MatterportLoadedCallback) => void

A callback function is called when the Matterport SDK is loaded.

Matterport Plugin

No events available

useMatterport Hook

follow

Type: function (participantId?: string) => void

When called with a participant ID as an argument, this function enables other participants to follow the specified participant in the Matterport 3D space. If no ID is provided, the follow feature is disabled.

function Room() {
  const { follow } = useMatterport();

  function followUser() {
    follow('participant-id');
  };

  function unFollow() {
    follow();
  };

  return (
    <>
      <button onClick={followUser}>Follow user</button>
      <button onClick={unFollow}>Unfollow</button>
    </>
  )
}

goto

Type: function (participantId: string) => void

When invoked with a participant ID as an argument, this function allows other participants to instantly navigate to the specified participant's position in the 3D space, enabling easy and quick location of participants.

function Room() {
  const { goTo } = useAutodesk();

  function goToUser() {
    goTo('participant-id');
  };

  return <button onClick={goToUser}>Go to user</button>
}

Types Definition

AvatarConfig

Type: object

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

Name	Type	Description
height	number	Required. The height you want your avatar to be positioned from the ground, in pixels.
scale	number	Required. The scale you want your avatar to be rendered, in percent 0 to 1.
laserOrigin	Position	Required. 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.

Name	Type	Description
x	number	Required. Represents the x-axis (horizontal) position.
y	number	Required. Represents the y-axis (vertical) position.
z	number	Required. Represents the z-axis (depth) position.

Example:

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