Extension:GLTFHandler

Category:GPL licensed extensions
MediaWiki extensions manual
GLTFHandler
Release status: betaCategory:Beta status extensions
Implementation MediaCategory:Media handling extensions
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.Category:Extensions with release branches compatibility policy
PHP 8.0
Database changes No
Composer muqsit/gltfhandler Category:Extensions supporting Composer
License GNU General Public License 2.0 or later
Download

Download master snapshot
GitHub:

Note:
No localisation updates are
provided by translatewiki.net .

Category:Extensions in GitHub version control
README
Hooks used
Category:All extensionsCategory:Extensions not in ExtensionJson

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' );
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed. Category:3D extensions

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
ParameterDescription
camera-orbitSet 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-orbitSet 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
ParameterDescription
environmentA .hdr or .jpg file. Controls the environmental reflection of the model.
Pertains to model-viewer's environment-image attribute.
skyboxAn equirectangular projection image (.png, .hdr, .jpg). Sets the background image of the scene.
Pertains to model-viewer's skybox-image attribute.
skybox-heightCauses 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
ParameterDescription
animation-nameSelects an animation to play by name. If not specified, the first animation is implicitly selected.
Pertains to model-viewer's animation-name attribute.
autoplayIf the model has animations, the selected animation will automatically begin to play.
Pertains to model-viewer's autoplay attribute.
Other Properties
ParameterDescription
arEnable the ability to launch AR experiences on supported devices.
Pertains to model-viewer's ar attribute.
posterAn 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.
Category:3D extensions Category:All extensions Category:BeforePageDisplay extensions Category:Beta status extensions Category:Extensions in GitHub version control Category:Extensions not in ExtensionJson Category:Extensions supporting Composer Category:Extensions with release branches compatibility policy Category:GPL licensed extensions Category:Media handling extensions Category:MimeMagicImproveFromExtension extensions