Skip to content

Dynamic Object Uploads

This guide covers uploading dynamic objects to the Cognitive3D spatial analytics platform using the Upload Web App. Dynamic objects are trackable items that move within your scenes.

What is a Dynamic Object?

Dynamic Objects in Cognitive3D represent items that can be tracked and analyzed within a scene. Examples include:

  • Interactive items participants manipulate
  • Moving elements in your environment
  • Characters or NPCs

Dynamic objects have their own 3D mesh for visualization on the dashboard and can record position, rotation, scale, and custom properties over time.

For more details, see Concepts.

Prerequisites

Before uploading a dynamic object, you need:

  1. An existing scene - Dynamic objects belong to scenes
  2. 3D mesh files - glTF or GLB format
  3. A thumbnail image - For the object gallery view

Scene Required

You must have at least one scene uploaded before you can add dynamic objects. See Scene Uploads to upload a scene first.

Required Files

To upload a dynamic object, you need:

File Required Description
{name}.gltf or {name}.glb Yes 3D mesh in glTF 2.0 format
{name}.bin Conditional Binary data (required for .gltf, not needed for .glb)
screenshot.png or cvr_object_thumbnail.png Yes Object thumbnail image
Texture files No PNG, JPG, WEBP images referenced in the mesh

File Naming

The mesh filename becomes the object's Mesh Name in Cognitive3D. For example:

  • controller.gltf + controller.bin → Mesh name: "controller"
  • chair.glb → Mesh name: "chair"

GLB vs glTF

GLB files are self-contained binaries that include the mesh and binary data in one file. If you use GLB format, you do not need a separate .bin file.

Thumbnail Requirements

  • Format: PNG
  • Filename: Either screenshot.png or cvr_object_thumbnail.png
  • Recommended size: 256x256 pixels or larger
  • Purpose: Displayed in the Object Explorer gallery

Exporting from 3D Editors

Blender

  1. Select the object you want to export
  2. Go to File > Export > glTF 2.0 (.glb/.gltf)
  3. In the export settings:
    • Set Format to "glTF Separate" or "glTF Binary (.glb)"
    • Enable Export Selected
    • Set the filename to match your object name
  4. Click Export glTF 2.0

Other 3D Editors

When exporting dynamic objects:

  • Use glTF 2.0 format (either .gltf + .bin or .glb)
  • Export only the object mesh, not the entire scene
  • Center the object at the origin for best results
  • Include referenced textures

Uploading a New Dynamic Object

New Object upload form with scene selector, mesh name field, and drag-and-drop file upload area

  1. Go to upload.cognitive3d.com
  2. Enter your Developer API Key and click Authenticate
  3. Select New Object
  4. Choose the Scene where this object will be used
  5. Enter an Object Name (display name for the dashboard)
  6. Drag and drop your files:
    • Your mesh file ({name}.gltf + {name}.bin or {name}.glb)
    • Your thumbnail (screenshot.png or cvr_object_thumbnail.png)
    • Any texture files
  7. Verify the validation panel shows all required files
  8. Click Upload Object

The mesh name is automatically detected from your uploaded files.

Updating an Existing Dynamic Object

To update a dynamic object's 3D mesh:

  1. Go to upload.cognitive3d.com
  2. Enter your Developer API Key and click Authenticate
  3. Select Update Object
  4. Choose the Scene containing the object
  5. Choose the Object to update from the dropdown
  6. Upload your new mesh and thumbnail files
  7. Click Upload Object

This creates a new version of the object mesh.

Sample Object Option

If you do not have a 3D mesh prepared, you can use the Sample Object feature to create a default cube. This is useful for:

  • Testing dynamic object tracking in your SDK
  • Getting started before creating custom 3D assets
  • Placeholder objects during development

To use the Sample Object:

  1. Select New Object
  2. Choose your scene
  3. Enter an object name
  4. Click the "Don't have object files?" prompt
  5. Select Use Sample Object
  6. Click Upload Object

You can later update this object with your actual 3D mesh.

File Size Limits

Limit Value
Single file maximum 500 MB
Total upload maximum 2 GB

Dynamic object meshes are typically much smaller than scene files. If your object mesh is very large, consider:

  • Reducing polygon count
  • Using lower resolution textures
  • Simplifying the mesh for visualization purposes

Multiple Objects in a Scene

A scene can have many dynamic objects. Each object is uploaded separately with its own mesh and thumbnail. Common patterns include:

  • Interactive items: Tools, objects participants can pick up
  • UI elements: Panels or menus that move with the user
  • Non-player characters: NPCs that participants interact with

Each unique object type needs to be uploaded once. The SDK then creates instances of these objects during sessions.

Troubleshooting

"Missing required file: *.gltf or *.glb"

Ensure you have included a mesh file. The file extension must be .gltf or .glb (lowercase).

"Missing required file: {name}.bin"

If using glTF format (not GLB), you need the corresponding .bin file. The base name must match your .gltf file.

"Multiple .gltf/.glb files found"

Only one mesh file is allowed per object upload. Remove extra mesh files.

Object appears incorrectly positioned

  • Center the object at the origin (0, 0, 0) in your 3D editor before export
  • Apply all transforms in your 3D editor before exporting
  • Check that scale is appropriate for your scene units

Thumbnail not showing

Ensure your thumbnail is named exactly screenshot.png or cvr_object_thumbnail.png and is a valid PNG file.

Next Steps

After uploading dynamic objects:

intercom 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.