ateeducacion/omeka-s-threedviewer

Embeds 3D models (GLB, etc.) in Omeka S collections using either model-viewer.js or three.js

v1.0.5 2025-10-03 10:34 UTC

Requires

• php: >=7.4

Requires (Dev)

• laminas/laminas-form: ^3.4
• phpunit/phpunit: *
• squizlabs/php_codesniffer: *
• zerocrates/extract-tagged-strings: dev-master

GPL-3.0-or-later

• Área de Tecnología Educativa

• module
• 3d
• Omeka S
• three.js
• model-viewer

README

Try in your browser

This module allows users to view and interact with 3D models (STL and GLB files) directly within Omeka S.

Features

• View 3D models (STL and GLB formats) directly in the browser
• Interactive controls for rotating, zooming, and panning 3D models
• Customizable display options including background color
• Optional auto-rotation for better visualization
• Grid display option for better spatial reference
• Toggle between the original Three.js/model-viewer pipeline and an experimental Babylon.js renderer
• Babylon.js renderer with configurable cameras, lighting, and WebXR support

Installation

Manual Installation

1. Download the latest release from the GitHub repository
2. Extract the zip file to your Omeka S modules directory
3. Log in to the Omeka S admin panel and navigate to Modules
4. Click "Install" next to Three3DViewer

Installation

See general end user documentation for Installing a module

Usage

1. Upload STL or GLB files to your Omeka S items as you would any other media file
2. When viewing an item with a 3D model, the model will automatically be displayed in an interactive viewer
3. Use your mouse to:
   • Left-click and drag to rotate the model
   • Right-click and drag to pan
   • Scroll to zoom in and out
4. The module settings allow administrators to choose the default viewing library. Select the legacy Three.js/model-viewer stack for the original experience or opt into Babylon.js for advanced camera behaviour, lighting presets, optional environment ground/skybox, WebXR (VR/AR) support, and an inspector toolbar for fine-tuning scenes on demand.

Local Development with Docker

This repository includes a Makefile and a docker-compose.yml for quick local development using erseco/alpine-omeka-s.

Quick start

make up

Then open http://localhost:8080.

Sample data import

On first boot, the container automatically installs CSVImport and, if data/sample_3d_data.csv is present, imports it so you immediately have items to test the viewer. To trigger a manual import inside the container, run:

make shell
cd /var/www/html && OMEKA_CSV_IMPORT_FILE=/data/sample_3d_data.csv php import_cli.php "$OMEKA_CSV_IMPORT_FILE"

Preconfigured users

The environment automatically creates several users with different roles:

Email	Role	Password
[e-mail]	global_admin	PLEASE_CHANGEME
[e-mail]	editor	1234

The ThreeDViewer module is automatically enabled, so you can start testing right away.

Useful Make commands

• make up – Start Docker containers in interactive mode
• make upd – Start in detached mode (background)
• make down – Stop and remove containers
• make shell – Open a shell inside the Omeka S container
• make lint – Run PHP_CodeSniffer
• make fix – Auto-fix coding style issues
• make package VERSION=1.2.3 – Build a .zip release of the module
• make test – Run PHPUnit tests

Run make help for a full list.