Integrating Real-Time Presence Features with Autodesk APS Viewer Using SuperViz

In this tutorial, we will guide you through adding real-time presence features to an Autodesk APS Viewer application using SuperViz. Real-time presence allows multiple users to interact with a 3D model collaboratively, seeing each other's actions and comments in real time. This feature is particularly useful for design review sessions, collaborative planning, and any scenario where real-time feedback on 3D models is essential.

We'll demonstrate how to set up an Autodesk APS Viewer with SuperViz, enabling participants to share their presence in a 3D space, leave comments, and interact with the model collaboratively. This setup will allow multiple participants to join a session, see each other's positions and interactions within the 3D model, and add contextual comments. Let's get started!

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz and Autodesk Viewer.

1. Create a New React Project

First, create a new React application using Vite with TypeScript.

1
npm create vite@latest presence-autodesk-app -- --template react-ts
2
cd presence-autodesk-app

2. Install Required Libraries

Next, install the necessary libraries for our project:

1
npm install @superviz/room @superviz/collaboration @superviz/autodesk-viewer-plugin uuid

• @superviz/room: Core package for creating and managing SuperViz rooms.
• @superviz/collaboration: Contains collaboration components like comments.
• @superviz/autodesk-viewer-plugin: Plugin for adding SuperViz presence features to an Autodesk Viewer application.
• uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.

1
npm install -D tailwindcss postcss autoprefixer
2
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.

1
/** @type {import('tailwindcss').Config} */
2
export default {
3
content: [
4
"./index.html",
5
"./src/**/*.{js,ts,jsx,tsx}",
6
],
7
theme: {
8
extend: {},
9
},
10
plugins: [],
11
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key, Autodesk client ID, and client secret. These credentials will be used to authenticate your application with SuperViz and Autodesk services.

1
VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY
2
VITE_FORGE_CLIENT_ID=YOUR_AUTODESK_CLIENT_ID
3
VITE_FORGE_CLIENT_SECRET=YOUR_AUTODESK_CLIENT_SECRET

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and Autodesk Viewer, and handle real-time presence and comments.

1. Import Required Packages

Open src/App.tsx and add the necessary imports for our application:

1
import { createRoom, Room } from "@superviz/room";
2
import { v4 as generateId } from "uuid";
3

4
import { useCallback, useEffect, useRef } from "react";
5
import { Presence3D, AutodeskPin } from "@superviz/autodesk-viewer-plugin";
6
import { Comments } from "@superviz/collaboration";
7

8
// SuperViz developer token ::
9
const DEVELOPER_TOKEN = import.meta.env.VITE_SUPERVIZ_API_KEY;
10
const CLIENT_ID = import.meta.env.VITE_FORGE_CLIENT_ID as string
11
const CLIENT_SECRET = import.meta.env.VITE_FORGE_CLIENT_SECRET as string
12
const DOCUMENT_ID = `urn:${btoa("urn:adsk.objects:os.object:e8d17563-1a4e-4471-bd72-a0a7e8d719bc/fileifc.ifc")}`

Explanation:

• createRoom, Room: From SuperViz room package for creating and managing rooms.
• Presence3D, AutodeskPin: From the Autodesk viewer plugin to add presence and pinning capabilities.
• Comments: From the collaboration package to enable contextual comments.
• Environment Variables: We're accessing our SuperViz and Forge credentials using environment variables.
• DOCUMENT_ID: The URN for the Autodesk model we want to load.

2. Create the App Component

Set up the main App component with necessary refs:

1
const App = () => {
2
  const autodeskViewer = useRef<Autodesk.Viewing.GuiViewer3D | null>(null)
3
  const roomRef = useRef<Room | null>(null);

Explanation:

• autodeskViewer: A ref to store the Autodesk Viewer instance.
• roomRef: A ref to store the SuperViz room instance.

3. Initialize SuperViz

Create a function to initialize the SuperViz environment and integrate presence and comments:

1
// Initialize ::
2
  const initializeSuperViz = useCallback(async () => {
3
    try {
4
      const room = await createRoom({
5
        developerToken: DEVELOPER_TOKEN,
6
        roomId: "ROOM_ID",
7
        participant: {
8
          id: generateId(),
9
          name: "Name " + Math.floor(Math.random() * 10),
10
        },
11
        group: {
12
          id: "GROUP_ID",
13
          name: "GROUP_NAME",
14
        },
15
      });
16

17
      // Store the room instance in the ref
18
      roomRef.current = room;
19

20
      const presence = new Presence3D(autodeskViewer.current!,{
21
        isAvatarsEnabled: false
22
      })
23
      room.addComponent(presence)
24

25
      const pinAdapter = new AutodeskPin(autodeskViewer.current!)
26
      const comments = new Comments(pinAdapter, {
27
        buttonLocation: 'top-right',
28
      })
29
      room.addComponent(comments)
30

31
    } catch (error) {
32
      console.error("Error initializing SuperViz Room:", error);
33
    }
34
  }, []);

Explanation:

• createRoom: Creates a new SuperViz room with participant and group information.
• roomRef.current: Stores the room instance for later access.
• Presence3D: Adds 3D presence to the Autodesk viewer with avatars disabled.
• AutodeskPin & Comments: Enables participants to place pins and leave comments on specific parts of the 3D model.

4. Handle Document Loading

Create functions to handle document loading success and failure:

1
const onDocumentLoadSuccess = useCallback(async (document: Autodesk.Viewing.Document) => {
2
    const viewable = document.getRoot().getDefaultGeometry();
3

4
    if(!viewable) return
5

6
    try {
7
      await autodeskViewer.current!.loadDocumentNode(document, viewable, {
8
        applyScaling: 'meters'
9
      })
10

11
      await initializeSuperViz()
12
    } catch (error) {
13
      console.log('Document loaded failed', error)
14
    }
15

16
  }, [initializeSuperViz])
17

18
  const onDocumentLoadFailure = () => {
19
    console.log('Document loaded failed')
20
  }

Explanation:

• onDocumentLoadSuccess: When the document loads successfully, we get the default geometry and load it into the viewer, then initialize SuperViz.
• onDocumentLoadFailure: Handles any errors that occur during document loading.

5. Initialize Autodesk Viewer

Create a function to initialize the Autodesk Viewer with authentication and configuration:

1
const initializeAutodesk = useCallback(async () => {
2
    const viewerElement = document.getElementById('viewer')!
3

4
    const response = await fetch('https://developer.api.autodesk.com/authentication/v2/token', {
5
      method: 'POST',
6
      headers: {
7
        'Content-Type': 'application/x-www-form-urlencoded',
8
        'Authorization': `Basic ${btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)}`
9
      },
10
      body: new URLSearchParams({
11
        grant_type: 'client_credentials',
12
        scope: 'data:read bucket:read',
13
      }).toString()
14
    })
15

16
    const data = await response.json()
17

18
    const options = {
19
      env: 'AutodeskProduction2',
20
      api: 'streamingV2',
21
      accessToken: data.access_token,
22
    }
23

24
    window.Autodesk.Viewing.Initializer(options, async () => {
25
      const viewer = new window.Autodesk.Viewing.GuiViewer3D(viewerElement)
26
      await viewer.start()
27

28
      viewer.setTheme("dark-theme");
29
      viewer.setQualityLevel(false, false);
30
      viewer.setGhosting(false);
31
      viewer.setGroundShadow(false);
32
      viewer.setGroundReflection(false);
33
      viewer.setOptimizeNavigation(true);
34
      viewer.setProgressiveRendering(true);
35

36
      autodeskViewer.current = viewer
37
      window.Autodesk.Viewing.Document.load(DOCUMENT_ID, onDocumentLoadSuccess, onDocumentLoadFailure);
38
    })
39

40
  }, [onDocumentLoadSuccess])

Explanation:

• Authentication: Fetches an access token from Autodesk's authentication API using our client credentials.
• Initializing the Viewer: Sets up the Autodesk Viewer with the access token and configures it with optimized settings.
• Loading the Document: Loads the specified model and calls the appropriate success or failure handlers.

6. Initialize on Component Mount

Use an effect hook to initialize the Autodesk Viewer when the component mounts:

1
useEffect(() => {
2
    initializeAutodesk();
3
  }, [initializeAutodesk]);

Step 3: Render the Application

Finally, return the JSX structure for rendering the Autodesk Viewer and the SuperViz-powered interface:

1
return (
2
    <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
3
      <header className='w-full p-5 bg-purple-400 flex items-center justify-between'>
4
        <h1 className='text-white text-2xl font-bold'>SuperViz Presence Autodesk</h1>
5
      </header>
6
      <main className='w-full h-full flex items-center justify-center relative'>
7
        <div id='viewer' className='w-full h-full overflow-hidden absolute top-0 left-0 w-full! h-full! z-0'></div>
8
      </main>
9
    </div>
10
  );
11
};
12

13
export default App;

Explanation:

• Viewer Container: The viewer div is where the Autodesk Viewer will be rendered, filling the entire screen. This is where users will interact with the 3D model and collaborate in real time.

Step 4: Understanding the Application Structure

Here's a quick overview of how the application components work together:

1. Room Creation and Management
   • The application creates a SuperViz room using the createRoom function.
   • It stores the room instance in a ref for later access.
2. Autodesk Viewer Integration
   • The application authenticates with Autodesk's API and initializes the 3D viewer.
   • It loads the specified model and configures the viewer for optimal performance.
3. SuperViz Components
   • Presence3D: Shows where participants are looking in the 3D model, with avatars disabled for a cleaner interface.
   • AutodeskPin & Comments: Enables participants to place pins and add comments to specific locations in the 3D model.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

1
npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the 3D model and see real-time presence and comments from other participants.

2. Test the Application

• Real-Time Presence: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that presence information is updated in real-time.
• Collaborative Interaction: Test the commenting feature by adding comments to the 3D model and observing how they appear for other participants.

Summary

In this tutorial, we integrated real-time presence and commenting features into an Autodesk Viewer application using SuperViz. We used the @superviz/room package to create a room, the @superviz/collaboration package for comments, and the @superviz/autodesk-viewer-plugin for presence and pinning capabilities. This setup enables multiple users to collaborate seamlessly in a shared 3D model, seeing each other's positions and adding contextual comments.

Feel free to explore the full code and further examples in the GitHub repository for more details.