Dynamic objects

Dynamic objects are tracked 3D entities in your scene, objects that Cognitive3D monitors for position, rotation, and engagement over time. Unlike static scene geometry, dynamic objects represent content that users interact with: imported models, collaboration tools, avatars, UI panels, and more.

When you register a dynamic object, Cognitive3D automatically tracks:

• Position and rotation over time
• User gaze and attention directed at the object

This spatial data helps answer questions like: "Which parts of the model do users examine most closely?" or "How do users spatially arrange objects during a review session?"

Register entities as dynamic objects when:

• Users can interact with them — Models they can grab, move, or manipulate
• They represent meaningful content — Imported files, placed annotations, spawned tools
• They appear/disappear during the session — Tracking object lifecycle

The SDK automatically tracks controllers and hands.

Basic Usage

Register a dynamic object when it's instantiated in your scene:

KotlinJava

Cognitive3DManager.registerDynamicObject(
    name = "model_nice_home_3d",    // Name
    meshName = "nice_home_3d",      // Mesh name for grouping similar objects
    entity = gltfEntity             // The Entity reference from Jetpack XR
)

Cognitive3DManager.registerDynamicObject(
    "model_nice_home_3d",    // Name
    "nice_home_3d",          // Mesh name for grouping similar objects
    gltfEntity               // The Entity reference from Jetpack XR
);

• name: Name of the entity. This could be same as exported and uploaded 3D model
• meshName: A category name for this type of object. All instances of the same model should share a mesh name, enabling aggregate analysis ("How much attention do architectural models get vs. product models?"). This should be same as exported and uploaded 3D model
• entity: The Jetpack XR Entity that Cognitive3D will track.

Examples

Use dynamic objects when you need to track where 3D content is positioned and how users interact with it spatially.

Registering imported 3D models

Track user-loaded models to analyze which files get the most attention and how users position them in space:

KotlinJava

fun onModelLoaded(model: LoadedModel, entity: GltfEntity) {
    // Register for spatial tracking
    Cognitive3DManager.registerDynamicObject(
        name = "model_${model.name}",
        meshName = model.originalFileName.substringBeforeLast("."),  // Group by original file
        entity = entity
    )

    // Send event with additional metadata (not tracked by dynamic object system)
    Cognitive3DManager.sendCustomEvent("Model registered", mapOf(
        "model_id" to model.id,
        "model_name" to model.displayName,
        "file_type" to model.fileExtension,
        "polygon_count" to model.polygonCount,
        "imported_by" to model.importedByUserId
    ))
}

public void onModelLoaded(LoadedModel model, GltfEntity entity) {
    // Register for spatial tracking
    String fileName = model.getOriginalFileName();
    String meshName = fileName.substring(0, fileName.lastIndexOf("."));

    Cognitive3DManager.registerDynamicObject(
        "model_" + model.getName(),
        meshName,
        entity
    );

    // Send event with additional metadata
    Map<String, Object> properties = new HashMap<>();
    properties.put("model_id", model.getId());
    properties.put("model_name", model.getDisplayName());
    properties.put("file_type", model.getFileExtension());
    properties.put("polygon_count", model.getPolygonCount());
    properties.put("imported_by", model.getImportedByUserId());

    Cognitive3DManager.sendCustomEvent("Model registered", properties);
}

Registering collaboration tools

Track tools like laser pointers or rulers to understand which tools users rely on and where they point them:

KotlinJava

fun onToolSpawned(tool: CollaborationTool, entity: Entity) {
    Cognitive3DManager.registerDynamicObject(
        name = "tool_${tool.name}",
        meshName = "tool_${tool.type.name.lowercase()}",  // "tool_laser_pointer", "tool_ruler", etc.
        entity = entity
    )

    Cognitive3DManager.sendCustomEvent("Tool spawned", mapOf(
        "tool_type" to tool.type.name,
        "spawned_by" to tool.ownerId
    ))
}

public void onToolSpawned(CollaborationTool tool, Entity entity) {
    Cognitive3DManager.registerDynamicObject(
        "tool_" + tool.getName(),
        "tool_" + tool.getType().name().toLowerCase(),
        entity
    );

    Map<String, Object> properties = new HashMap<>();
    properties.put("tool_type", tool.getType().name());
    properties.put("spawned_by", tool.getOwnerId());

    Cognitive3DManager.sendCustomEvent("Tool spawned", properties);
}

Best Practices

What to register

• User-loaded content (models, images, documents)
• Interactive tools (pointers, markers, measurement tools)
• Persistent spatial content (annotations, pins, labels)

What to skip

• Static environment geometry
• Transient visual effects (particles, highlights)
• UI elements that aren't spatially meaningful

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.