Skip to main content

Presence for Three.js

Our Three.js plugin is designed to seamlessly integrate avatars, mouse, and host controls into your digital twin 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 ThreeJS​

To initialize the Presence3D for ThreeJS, you will need to first create a scene and a camera with the ThreeJS Model, like in the code below:

const element = document.getElementById("element-id");

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ canvas: element });

To allow the participant’s camera to orbit around the target it’s also important to enable OrbitControls from ThreeJS, like in the code below:

import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

const renderer = new THREE.WebGLRenderer();
const camera = new THREE.PerspectiveCamera(45, 1, 1, 10000);

const controls = new OrbitControls(camera, renderer.domElement);

The minimum ThreeJs version required is 0.164.0.

Installing SuperViz ThreeJS extension​

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

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

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

How to use it​

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

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

const threeJSPresence = new Presence3D(scene, camera, camera, {
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isNameEnabled: true,
	isMouseEnabled: true,
	renderLocalAvatar: true,
  avatarConfig: {
    height: 0,
    scale: 1,
    laserOrigin: { x: 0, y: 0, z: 0 },
  },
});

room.addComponent(threeJSPresence);

When initializing the Presence3D you must pass the scene, camera, and one player to its constructor. The player's property is the element where the participant's avatar will be placed. Optionally, you can use an options object as the last argument in the constructor.

The table below shows the arguments passed on the constructor object:

NameTypeDescription
sceneSceneRequired. The ThreeJS scene object, already loaded.
cameraCameraRequired. The ThreeJS scene’s camera, previously created.
playerObject3DRequired. The 3D object you want your avatar to be added to. For first-person experiences, you can use camera objects here.
optionsThreeJsComponentOptionsUse this object to change configurations on how avatars, mouse cursors, and lasers will be placed into your 3D model.
warning

Please, make sure to only initialize the Presence3D once the ThreeJS camera, renderer, and scene are 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 ThreeJS scene. You can, after, call the method without parameters to stop following the participant.

Example:

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

// Call the method without parameters to stop following the past participant
threeJSPresence.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 ThreeJS model, facilitating quick location of participants.

Example:

threeJSPresence.goTo("<PARTICIPANT_ID>");

Types Definition​

ThreeJsComponentOptions​

Type: object

An object describing the options when initializing the Presence3D for ThreeJS.t

NameTypeDescription
avatarConfigAvatarConfigConfiguration for the avatar, like scale, position, on laser settings.
isAvatarsEnabledbooleanEnable or disable the need for an avatar in the room.
Default value: true
isLaserEnabledbooleanEnable or disable laser pointers. If isAvatarsEnabled is set to false, this will also be false.
Default value: true
isMouseEnabledbooleanEnable or disable Mouse presence within the 3D model.
Default value: true
isNameEnabledbooleanEnable or disable showing the participant's name on top of the avatars.
Default value: true
renderLocalAvatarbooleanWhen set true, the participant avatar will be displayed, emulating a third-person view. When set false, the view for the participant will be in the first person.
Default value: false

Example:

{
  isAvatarsEnabled: true,
  isLaserEnabled: true,
  isMouseEnabled: true,
  isNameEnabled: true,
  renderLocalAvatar: false,
  avatarConfig: {
    height: 1.6,
    scale: 1,
    laserOrigin: {
      x: 0,
      y: 0,
      z: 0
    }
  }
}

AvatarConfig​

Type: object

An object describing the configuration for the 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
}