README

GLTFHandler lets you upload and interact with GLTF models on MediaWiki. It uses google/model-viewer library to display the 3D models and optionally view them in your environment using augmented reality (on supported devices).

For developers, a documentation for the glTF parser can be found here.

Motive

Existing 3D extensions in the MediaWiki ecosphere do not support the glTF format which has become a standard for scenes and models. glTF libraries in PHP are lacking if not non-existent, requiring wiki maintainers to install third party libraries in addition to the extension for validating 3D assets. This makes the installation process inconvenient, and at times sufficiently challenging.

Features

Work out of the box—no dependency installation needed
Support .gltf and .glb files
Validate structure of .gltf and .glb files
Bounding box calculation to properly size the output canvas
Use google/model-viewer library to render 3D models, which supports all evergreen desktop and mobile browsers—Chrome, Firefox, Safari, and Edge.
Allow custom output options for model-viewer (see usage)

Installation

Requires MediaWiki 1.42.0 or later.

Download GLTFHandler extension. You can get the extension via Git (specifying GLTFHandler as the destination directory):
```
git clone https://github.com/Muqsit/mediawiki-extensions-GLTFHandler.git GLTFHandler
```
Or download it as zip archive.

In either case, the "GLTFHandler" extension should end up in the "extensions" directory of your MediaWiki installation. If you got the zip archive, you will need to put it into a directory called GLTFHandler.
Add the following code at the bottom of your LocalSettings.php:
```
wfLoadExtension( 'GLTFHandler' );
```
✔️Done—Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Usage

GLTFHandler uses the exact syntax as your ordinary media files:

[[File:MyModel.glb]]
[[File:MyModel.gltf]]
[[File:MyModel.glb|thumb|400px]]

At the moment, the following file parameters are supported. See model-viewer documentataion for live examples. All parameters are optional.

Camera Properties
Parameter	Description
`camera-orbit`	Set the starting and/or subsequent orbital position of the camera. You can control the azimuthal, theta, and polar, phi, angles (phi is measured down from the top), and the radius from the center of the model. Accepts values of the form "`$theta $phi $radius`", like `camera-orbit="-10deg 75deg 1.5m"`. Also supports units in radians (`rad`) for angles and centimeters (`cm`) or millimeters (`mm`) for camera distance. Camera distance can also be set as a percentage (`%`), where 100% gives the model tight framing within any window based on all possible theta and phi values. Pertains to model-viewer's `camera-orbit` attribute.
`max-camera-orbit`	Set the maximum orbital values of the camera. Takes values in the same form as `camera-orbit`. Pertains to model-viewer's `max-camera-orbit` attribute.

Skybox Properties
Parameter	Description
`environment`	A .hdr or .jpg file. Controls the environmental reflection of the model. Pertains to model-viewer's `environment-image` attribute.
`skybox`	An equirectangular projection image (.png, .hdr, .jpg). Sets the background image of the scene. Pertains to model-viewer's `skybox-image` attribute.
`skybox-height`	Causes the skybox to be projected onto the ground plane. The height indicates the camera's distance above the ground and acts to scale the image at ground level to the correct size. Accepts units in meters (`m`), centimeters (`cm`), or millimeters (`mm`). The default value of `0m` disables ground projection. Pertains to model-viewer's `skybox-height` attribute.

Animation Properties
Parameter	Description
`animation-name`	Selects an animation to play by name. If not specified, the first animation is implicitly selected. Pertains to model-viewer's `animation-name` attribute.
`autoplay`	If the model has animations, the selected animation will automatically begin to play. Pertains to model-viewer's `autoplay` attribute.

Other Properties
Parameter	Description
`ar`	Enable the ability to launch AR experiences on supported devices. Pertains to model-viewer's `ar` attribute.
`poster`	An image file. Displays an image instead of the model, useful for showing the user something before a model is loaded and ready to render. Pertains to model-viewer's `poster` attribute.

Example usage of optional parameters:

[[File:MyModel.glb|ar|autoplay|environment=SomeEnvironment.png|poster=SomePoster.png]]
[[File:MyModel.glb|camera-orbit=-30deg 90deg 22|skybox=SomeSkybox.jpg|skybox-height=1.5m]]
[[File:MyModel.glb|autoplay|animation-name=Running]]

Limitations

A glTF file containing a local or a remote URI is disallowed. This is both a safety mechanism (in case a local URI does not exist) and a security mechanism (to avoid loading unsafe assets at the user and the server's end).
No thumbnail generation at its current stage. In short, by thumbnail we mean generating a preview image (e.g., a PNG) for the glTF model. Supporting this will most likely break portability of this extension. But this is much needed for 1) broader site accessibility, and 2) for OpenGraph tags as they do not support 3D assets in embeds.
Limitations imposed by the parser.

muqsit / gltfhandler

Maintainers

Details