ThreeJSPin

Utilize Contextual Comments to integrate a personalized commenting feature into your ThreeJS model. This enables participants to add comments to specific points within the model, which can be viewable by everyone.

Before we start

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

Initializing ThreeJS

To initialize the Contextual Comments for ThreeJS, you will need to first create a scene and a camera with the ThreeJS Model, similar to 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, similar to 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.147.0.

Installing SuperViz ThreeJS extension

The ThreeJsPin adapter is not available from the @superviz/sdk package, instead, to use it you must use the @superviz/threejs-plugin package.

Install with CDN

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>

Install with npm

To install the @superviz/threejs-plugin package with npm, run the following command:

npm install --save @superviz/threejs-plugin

Install with Yarn

To install the @superviz/threejs-plugin package with Yarn, run the following command:

yarn add @superviz/threejs-plugin

Install with pnpm

To install the @superviz/threejs-plugin package with pnpm, run the following command:

pnpm install --save @superviz/threejs-plugin

How to use it

Before creating the Comments component, you will need to use ThreeJSPin adapter. To construct it, you will need to pass the scene, renderer, and camera object from your ThreeJS initialization.

import { ThreeJsPin } from '@superviz/threejs-plugin';

// Creating a ThreeJSPin adapter
const pinAdapter = new ThreeJsPin(scene, renderer, camera);

warning

Please, make sure to only initialize the adapter once the ThreeJS scene, renderer, and camera are fully loaded, otherwise you won’t be able to initialize the use of the component.

Properties

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

Name	Type	Description
scene	Scene	Required. The ThreeJS scene object, already loaded.
camera	Camera	Required. The ThreeJS scene’s camera, previously created.
player	Object3D	Required. The 3D object you want your avatar to be added to. For first person experiences you can use cameras object here. If no player provided, we’ll use the camera.
controls	OrbitControls	Required if using OrbitControls. The ThreeJS OrbitControls object, previously created.

Adding Comments Component

After initializing the ThreeJSPin, you can pass it as a parameter for the Comments component, similar to the following code:

import { Comments } from '@superviz/sdk/lib/components';
import { ThreeJsPin } from '@superviz/threejs-plugin';

// Creating a ThreeJSPin adapter
const pinAdapter = new ThreeJsPin(scene, renderer, camera);

// Construct the Comments with the ThreeJSPin adapter
const comments = new Comments(pinAdapter);
room.addComponent(comments);