Extension:GLTFHandler

**MediaWiki extensions manual**
GLTFHandler; Release status: beta
Implementation	Media
Description	Embed 3D GLTF models (.glb and .gltf files) on MediaWiki
Author(s)	Muqsit
Latest version	0.0.7
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
PHP	8.0
Database changes	No
Composer	muqsit/gltfhandler
License	GNU General Public License 2.0 or later
Download	Download master snapshot; GitHub: project page; git repository URL [help]; commit history; ; Note:; No localisation updates are; provided by translatewiki.net. ; README
	Hooks used BeforePageDisplay; MimeMagicImproveFromExtension;

The GLTFHandler extension 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 of the glTF parser's capabilities can be found here.

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 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

Installation

Download and place the file(s) in a directory called GLTFHandler in your extensions/ folder.
Add the following code at the bottom of your LocalSettings.php file:
```
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 documentation 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.