ateeducacion / omeka-s-threedviewer
Embeds 3D models (GLB, etc.) in Omeka S collections using either model-viewer.js or three.js
Installs: 4
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:omeka-s-module
Requires
- php: >=7.4
Requires (Dev)
- laminas/laminas-form: ^3.4
- phpunit/phpunit: *
- squizlabs/php_codesniffer: *
- zerocrates/extract-tagged-strings: dev-master
This package is auto-updated.
Last update: 2025-10-03 10:37:32 UTC
README
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
- Download the latest release from the GitHub repository
- Extract the zip file to your Omeka S
modules
directory - Log in to the Omeka S admin panel and navigate to Modules
- Click "Install" next to Three3DViewer
Installation
See general end user documentation for Installing a module
Usage
- Upload STL or GLB files to your Omeka S items as you would any other media file
- When viewing an item with a 3D model, the model will automatically be displayed in an interactive viewer
- Use your mouse to:
- Left-click and drag to rotate the model
- Right-click and drag to pan
- Scroll to zoom in and out
- 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:
Role | Password | |
---|---|---|
admin@example.com | global_admin | PLEASE_CHANGEME |
editor@example.com | 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 modemake upd
– Start in detached mode (background)make down
– Stop and remove containersmake shell
– Open a shell inside the Omeka S containermake lint
– Run PHP_CodeSniffermake fix
– Auto-fix coding style issuesmake package VERSION=1.2.3
– Build a.zip
release of the modulemake test
– Run PHPUnit tests
Run make help
for a full list.