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
pkg:composer/ateeducacion/omeka-s-threedviewer
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
modulesdirectory - 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.ziprelease of the modulemake test– Run PHPUnit tests
Run make help for a full list.
