Skip to content

Scene Uploads

Upload scene geometry to the Cognitive3D 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
.glb file (any name) One model form 3D scene geometry as a single glTF 2.0 Binary file, textures included
scene.gltf + scene.bin One model form 3D scene geometry in glTF 2.0 Separate format
screenshot.png Recommended Scene thumbnail image
Texture files With scene.gltf PNG, JPG, or WEBP images referenced in the glTF

Scene file requirements table showing the scene model, scene.bin, and screenshot.png

File Naming

A glTF Separate export must be named exactly scene.gltf and scene.bin. A .glb can have any name; upload exactly one. 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 and you export glTF Separate, include them alongside your glTF and bin files. The texture filenames must match what is referenced in your glTF file. A .glb normally carries its textures inside the file, so there is nothing extra to include; a .glb that references texture files outside itself is rejected on upload, so re-export it with the textures embedded.

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 Binary (.glb)" for a single file, or "glTF Separate (.gltf + .bin + textures)"
    • Enable Export Selected if you only want certain objects
    • Under Include, enable Custom Properties if needed
  5. For glTF Separate, set the filename to scene.gltf; a .glb can have any name
  6. Click Export glTF 2.0

glTF Binary creates one .glb file with the textures inside it. glTF Separate 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 2.0, either Binary (.glb) or Separate (.gltf + .bin + textures)
  • Name a glTF Separate export scene.gltf
  • Include all referenced textures with a glTF Separate export

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 Get Started
  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 your scene model (one .glb, or scene.gltf + scene.bin + any textures) and screenshot.png
    • You can also upload a ZIP file containing all files — the webapp will automatically extract and validate the contents
  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
  • A Download Scene Settings button — this saves a JSON file containing sceneId, sceneName, versionNumber, and versionId. You will need these values to configure your SDK (visionOS, WebXR, Android XR, etc.).

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 Get Started
  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
Warning threshold 100 MB total
Maximum recommended 500 MB total

If your scene exceeds these limits, consider:

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

Troubleshooting

The scene model is marked missing

The file list shows scene.glb (or scene.gltf + scene.bin) as missing and the button reads Missing Required Files. Include one .glb, or a glTF file named exactly scene.gltf (lowercase) with its scene.bin. If you exported glTF Separate under a different name, rename the pair before uploading.

"Upload either one .glb or scene.gltf + scene.bin, not both"

The upload contains both model forms. Remove the .glb or the .gltf + .bin pair so one model remains.

"Upload exactly one .glb as the model"

More than one .glb was selected. Keep the scene model and remove the others.

A .glb upload fails with "Could not convert …"

The files passed validation but the platform could not convert the .glb: it references texture or buffer files outside itself, it is malformed, two of its images point at the same image data, or its JSON is over 8 MB. Re-export it from your 3D editor with textures embedded, or export glTF Separate instead. The message names the file and the reason.

"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 (glTF Separate only)
  • All textures are included and have matching filenames (glTF Separate only)
  • 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.