Heratio Help Center article. Category: Viewers & Media.

3D Model Viewer

User Guide

View and interact with 3D models of objects in your collection directly in your web browser.

Overview

Supported Formats

All viewer libraries (model-viewer, Three.js, loaders) are served from local vendor files. No external CDN dependencies are required.

Compressed glTF (Draco / KTX2)

The viewers ship with self-hosted Draco (geometry) and KTX2/Basis (texture) decoders, so Draco-compressed meshes and KTX2-textured glTF/GLB load without any external CDN. This is transparent: uncompressed models work exactly as before, and compressed ones (for example after the optimiser runs - see below) just work in both the record viewer and the exhibition walkthrough.

OBJ and FBX are converted for you

OBJ and FBX uploads are kept as the preservation master and a web-ready GLB is generated from them (FBX via the FBX2glTF tool, OBJ via obj2gltf), then texture-capped and Draco-compressed by the model optimiser (ahg:optimize-models). You always view the GLB; the original OBJ/FBX is preserved alongside the record.

Viewing a 3D Model

Step 1: Find a Record with a 3D Model

Browse or search for a record that has a 3D model attached, and look for the 3D cube icon on the record page.

Step 2: Open the Viewer

Click the 3D model thumbnail or the View 3D button. The model loads inside the viewer, with the interaction toolbar (Rotate, Zoom, Measure, Fullscreen) along the bottom.

Controls

Mouse Controls

Touch Controls (Mobile / Tablet)

Viewer Features

Toolbar Options

Augmented Reality (AR)

On iPhone / iPad

1. Open the record on your device
2. Tap the AR button
3. Point the camera at a flat surface
4. The object appears in your space.

On Android

1. Open the record in Chrome
2. Tap the AR button
3. Follow the prompts to place the object

Interactive Hotspots

3D models can have interactive annotation points (hotspots) placed on their surface. Click a hotspot to view its title and description.

Hotspot Types

Damage hotspots automatically link to the object's condition assessment page when the ahgConditionPlugin is installed.

Managing Hotspots (Editors)

Editors and administrators can add, edit, and delete hotspots from the 3D Model Edit page:

1. Open a 3D model and click Edit
2. Click on the model surface to detect a position
3. Fill in the hotspot form (type, title, description, position)
4. Click Add Hotspot

Multi-Angle Gallery

When multi-angle renders have been generated for a 3D model, a gallery of 6 views appears below the viewer on the record view page:

• Front - straight-on front view
• Back - rear view
• Left - left side profile
• Right - right side profile
• Top - bird's-eye view from above
• Detail - close-up at 45-degree angle

Click any thumbnail to open a full-size lightbox view. These renders are generated automatically by Blender and cached for fast access.

AI 3D Description

Voice Command

Say "describe object" or "describe 3D" while viewing a record with a 3D model. The system will:

1. Generate 6 multi-angle renders of the object using Blender
2. Send all 6 views to an AI model for analysis
3. Read the description aloud
4. Offer to save the description to the record

Save Options

After hearing the AI description, you can say:

• "save to description" - save to the record's scope and content field
• "save to alt text" - save as the digital object's alt text
• "save to both" - save to both fields
• "discard" - discard the AI description

IIIF 3D Manifests

Each 3D model has an IIIF Presentation API 3.0 manifest available at:

https://your-site/iiif/3d/{model_id}/manifest.json

This manifest includes the model, its metadata, viewer settings, and any hotspot annotations. It can be used by external IIIF-compatible viewers and repositories.

Thumbnails & Derivatives

3D models (GLB, GLTF, OBJ, STL, PLY) automatically get thumbnail and reference images generated via Blender when uploaded. If thumbnails are missing, an administrator can regenerate them:

php atom-framework/bin/atom 3d:derivatives           # Process all
php atom-framework/bin/atom 3d:derivatives --id=123  # Specific object
php atom-framework/bin/atom 3d:derivatives --dry-run  # Preview only

Type-a-Command

If you prefer typing to speaking, right-click the floating microphone button (bottom-right corner). A text input will appear where you can type any voice command and press Enter. This is useful in noisy environments or when speech recognition is unavailable.

Tips for Best Experience

Troubleshooting

Need Help?

Contact your system administrator if you experience issues.

Part of the Heratio Framework - The Archive and Heritage Digital Commons Group (Pty) Ltd