Skip to content

Scene Uploads

This guide covers uploading scenes to the Cognitive3D spatial analytics platform using the Upload Web App. Scenes are 3D environments where participant sessions are recorded and visualized.

What is a Scene?

A Scene in Cognitive3D represents a 3D space where participants have experiences. It contains:

  • Static geometry - The 3D environment (walls, floors, furniture, etc.)
  • Session data - Recorded participant activity within that space
  • Dynamic objects - Trackable objects that move within the scene

For more details, see Concepts.

Required Files

To upload a scene, you need the following files:

File Required Description
scene.gltf Yes 3D scene geometry in glTF 2.0 format
scene.bin Yes Binary buffer data referenced by the glTF
screenshot.png Yes Scene thumbnail image
Texture files No PNG, JPG, or WEBP images referenced in the glTF

Scene file requirements table showing required files: scene.gltf, scene.bin, and screenshot.png

File Naming

The mesh and binary files must be named exactly scene.gltf and scene.bin. The screenshot must be named screenshot.png.

Screenshot Requirements

  • Format: PNG
  • Recommended size: 512x512 pixels
  • Purpose: Displayed as the scene thumbnail on the dashboard

Texture Files

If your scene uses textures, include them alongside your glTF and bin files. The texture filenames must match what is referenced in your glTF file.

Exporting from 3D Editors

Blender

  1. Open your scene in Blender
  2. Select the objects you want to export (or select all with A)
  3. Go to File > Export > glTF 2.0 (.glb/.gltf)
  4. In the export settings:
    • Set Format to "glTF Separate (.gltf + .bin + textures)"
    • Enable Export Selected if you only want certain objects
    • Under Include, enable Custom Properties if needed
  5. Set the filename to scene.gltf
  6. Click Export glTF 2.0

This creates scene.gltf, scene.bin, and any texture files in the same directory.

Other 3D Editors

Most 3D editors support glTF 2.0 export. Ensure you:

  • Export to glTF Separate format (not GLB binary format)
  • Name the output scene.gltf
  • Include all referenced textures

Uploading a New Scene

New Scene upload form with scene 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 Scene
  4. Enter a Scene Name (this identifies your scene on the dashboard)
  5. Drag and drop your files into the upload area, or click to browse
    • Include scene.gltf, scene.bin, screenshot.png, and any textures
    • You can also upload a ZIP file containing all files
  6. Verify the validation panel shows all required files are present
  7. Click Upload Scene
  8. Wait for the upload to complete

After a successful upload, you will see a confirmation with a link to view your scene on the dashboard.

Updating an Existing Scene

When you update a scene, you create a new version. Session data is associated with specific scene versions.

  1. Go to upload.cognitive3d.com
  2. Enter your Developer API Key and click Authenticate
  3. Select Update Scene
  4. Choose the scene to update from the dropdown list
  5. Drag and drop your updated files
  6. Click Upload Scene

The new version becomes active. Previous versions remain accessible on the dashboard.

Empty Scene Option

If you do not have 3D assets prepared, you can upload an Empty Scene. This is a minimal scene containing a small reference cube, useful for:

New Scene form showing the Empty Scene option with "Don't have scene files?" prompt and Use Empty Scene button

  • Testing your SDK integration before creating custom 3D assets
  • Getting started quickly with session recording
  • Augmented reality applications where the physical environment is the "scene"

To use the Empty Scene:

  1. Select New Scene
  2. Enter a scene name
  3. Click the "Don't have scene files?" prompt
  4. Select Use Empty Scene
  5. Click Upload Scene

You can later update this scene with your actual 3D geometry.

File Size Limits

Limit Value
Single file maximum 500 MB
Total upload maximum 2 GB
Warning threshold 100 MB per file

If your scene exceeds these limits, consider:

  • Reducing texture resolution
  • Simplifying geometry
  • Compressing textures with tools like TinyPNG

Troubleshooting

"Missing required file: scene.gltf"

Ensure your glTF file is named exactly scene.gltf (lowercase). If you exported with a different name, rename it before uploading.

"Multiple .gltf files found"

Only one glTF file is allowed per scene. Remove any extra glTF files from your upload.

Upload fails with large files

For scenes approaching the size limits:

  • Try uploading without a ZIP file (direct file upload)
  • Optimize textures and geometry
  • Check your network connection

Scene appears empty on dashboard

Verify that:

  • The glTF file references the correct bin file
  • All textures are included and have matching filenames
  • The geometry is positioned near the origin (0, 0, 0)

Next Steps

After uploading your scene:

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.