Scenes

To visualize user behavior and analytics data within the Cognitive3D dashboard, you need to upload your scene's geometry. This provides the 3D context for heatmaps, gaze paths, and event locations in SceneExplorer.

Exporting a Three.js Scene

The C3DThreeAdapter provides a convenient helper method, exportScene(), to simplify this process. This guide will walk you through exporting your scene from a live Three.js application and uploading it to the Cognitive3D platform. The exportScene() method bundles your THREE.Scene object into the specific file format required by our platform. It generates a .gltf file, a .bin file for geometry, a settings.json configuration file, and a screenshot.png for use as a thumbnail.

ThreeJS Exporting Scene: Prerequisites

Before calling the export function, you must have the following objects available in your application:

• An initialized C3DThreeAdapter instance.
• The THREE.Scene object you wish to export.
• Your active THREE.WebGLRenderer instance.
• The THREE.Camera currently viewing the scene.

ThreeJS Exporting Scene: Usage

To trigger the export, call the exportScene method on your adapter instance. This is typically done via a UI button or a keyboard button click.

// Ensure you have access to your adapter, scene, renderer, and camera
const c3dthreejsAdapter = new C3DThreeAdapter(c3d);
const myScene = yourThreeJsScene;
const myRenderer = yourThreeJsRenderer;
const myCamera = yourThreeJsCamera;
const sceneNameForExport = "MyMainLevel"; // A descriptive name for your scene

c3dthreejsAdapter.exportScene(myScene, sceneNameForExport, myRenderer, myCamera);

ThreeJS Exporting Scene: How It Works

When you call exportScene(), the following happens: Three.js's built-in GLTFExporter parses your scene graph and creates four files in memory:

• scene.gltf: A JSON file describing the scene's structure, nodes, and materials.
• scene.bin: A binary file containing the raw geometry data (vertices, indices, etc.).
• settings.json: A configuration file required by our backend, containing the sceneName and scale.
• screenshot.png: A snapshot of the current view from the provided camera, rendered by the renderer.

Saving the Files: The adapter then attempts to save these files if your browser supports it (like modern Chrome or Edge), a dialog will appear asking you to select a directory. The four files will be automatically saved into a sub-folder named scene inside your chosen directory, ready for upload.

Uploading the Scene Files (Engine independent)

Once you have the four scene files (scene.gltf, scene.bin, settings.json, and screenshot.png) collected in a single directory, you can upload them using our command-line utility, c3d-upload-tools.

Upload tools Prerequisites

• You have cloned the c3d-upload-tools repository.
• You have set your C3D_DEVELOPER_API_KEY described in the c3d-upload-tools Quick Start section.

Upload tools: Usage

• Open your terminal or command prompt.
• Navigate to the c3d-upload-tools directory.
• Run the upload-scene.sh script, pointing the --scene_dir argument to the folder containing your four exported files.

For example, assuming your exported files are in a folder called 'my-exported-scene' on your Desktop:

./upload-scene.sh --scene_dir ~/Desktop/my-exported-scene

Getting Your Scene ID

After a successful upload, the script will output a confirmation message containing the Scene ID and the new Scene Version.

✅ Scene uploaded successfully!
   Scene ID:      a1b2c3d4-e5f6-g7h8i9j0
   Version:       1
   Scene Name:    MyMainLevel

You must copy the new Scene ID and Version and update your SDK configuration (usually settings.js) to match. This ensures that the analytics data sent from your application is correctly associated with the 3D geometry you just uploaded.

// In your settings.js or equivalent configuration file
allSceneData: [
  {
    sceneName: "MyMainLevel",
    sceneId: "a1b2c3d4-e5f6-g7h8i9j0", // <-- Paste your new Scene ID here
    versionNumber: "1",                // <-- Update the version number
  },
  // ... other scenes
],

Scene Change

In your application, a user may move between different levels/ scenes within a single continuous session. The Cognitive3D SDK is designed to handle these transitions seamlessly, ensuring that analytics data is correctly associated with the specific scene in which it occurred.

When a user transitions to a new scene, you must inform the SDK of this change by calling the c3d.setScene() method.

Scene Change: How It Works

Calling c3d.setScene() triggers two important actions in the background:

1. Sends Batched Data: The SDK immediately sends all batched analytics data (such as gaze, custom events, and sensor data) that has been collected for the previous scene. This ensures that all data is correctly attributed to the scene it came from before the new scene is activated.

2. Refreshes Dynamic Objects: If you are tracking Dynamic Objects, the SDK refreshes the object manifest. This means it re-sends the registration information for all tracked objects to the backend, ensuring they are correctly visualized in the new scene context in SceneExplorer.

Example

// settings.js
export default {
  config: {
    // ... other settings
    allSceneData: [
      {
        sceneName: "MainMenu",
        sceneId: "a1b2c3d4-e5f6-g7h8-i9j0",
        versionNumber: "1",
      },
      {
        sceneName: "Level_01_Tutorial",
        sceneId: "k1l2m3n4-o5p6-q7r8-s9t0",
        versionNumber: "1",
      },
    ],
  },
};

// In your application's scene loading logic...

function loadNewScene(sceneName) {
    console.log(`Loading scene: ${sceneName}`);

    // --- Cognitive3D Scene Change ---
    // Inform the SDK that the active scene is changing.
    c3d.setScene(sceneName);

    // ... your code to load the new scene's assets and logic ...
}

// Example usage:
// When the user clicks the "Start Tutorial" button from the main menu:
loadNewScene("Level_01_Tutorial");

If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.