Documentation
Model Viewer 3D
Description
The Model Viewer 3D module allows for displaying 3D models.
Please note that when using a mobile device, an additional icon will be visible in the vicinity of the 3D model. Interacting with the icon allows switching the preview to the Augmented Reality mode https://modelviewer.dev/examples/augmentedreality.
Properties
The list starts with the common properties. Learn more about them by visiting the Modules description section. The other available properties are described below.
| Property name | Description |
|---|---|
| Model | Path to the file containing the 3D model. Supports only the glTF/GLB 3D models. |
| Model iOS | Path to the file containing the 3D model. Allows uploading an alternative format due to iOS's lack of support for glTF/GLB in AR. |
| Poster | Displays an image instead of the model, useful for showing the user something before the model is loaded and ready to render. |
| Annotations | Additional text displayed in the preview. |
| Environment Image | Controls the environmental reflection of the model. Normally, if "Skybox Image" is set, that image will also be used for the "Environment Image". |
| Skybox Image | Sets the background image of the scene. Takes a URL to an equirectangular projection image that is used for the skybox, as well as applied as an environment map on the model. Supports PNG, HDR, and JPG images. |
| Shadow Intensity | Controls the opacity of the shadow. Setting it to 0 turns off the shadow. |
| Shadow Softness | Controls the blurriness of the shadow. Setting it to 0 results in hard shadows. Softness should not be changed for each frame, as this has a performance cost. |
| Auto Rotate | Automatically slowly rotates the model. |
| Scale | Sets scale of the model. |
| Labels Enabled on Start | Labels are visible immediately after loading the model. |
| Alt Text | Sets the alternative text for the 3D model. |
| Additional Attributes | Additional attributes that could be set for the model (see the Additional Attributes section below). Data should be entered in JSON format. |
| Copyright Info | This field contains information relating to copyright. |
| Interaction Prompt | Allows disabling the visual and audible interaction prompt. If checked, the interaction prompt is set to "auto". The interaction prompt will be displayed as soon as the interaction-prompt-threshold time has elapsed (after the model is loaded). The interaction prompt will only display if camera controls are enabled. |
| Enable fullscreen | Allows to enter fullscreen mode. After checking this property, the content of the module will be wrapped with an element with CSS class '.modelViewerWrapper', regardless of whether the device supports Fullscreen API. See the Fullscreen section below for more information. |
| Lang attribute | This property allows defining the language for this module (different than the language of the lesson). |
Supported commands
| Command name | Params | Description |
|---|---|---|
| hide | ... | Hides the module if it is visible. |
| show | ... | Shows the module if it is hidden. |
| showAnnotations | ... | Shows annotations if they are available for the model. |
| hideAnnotations | ... | Hides annotations available for the model. |
| getAnnotationsVisibility | ... | Returns the annotations visibility status of the model. |
| setScale | number | Sets the model's scale. |
| requestFullscreen | ... | Enters module in fullscreen mode. Check the Fullscreen section below for more information. |
| exitFullscreen | ... | Exits the module from fullscreen mode. Check the Fullscreen section below for more information. |
Additional Attributes Examples
| Attribute | Description |
|---|---|
| autoplay | Possible values: "true", "false". When set to "true", the animation is played automatically when the page is loaded. |
| animation-name | Changes the default animation to the specified one. |
| camera-orbit | Sets the starting position of the camera. The properties are specified in the following order: x-axis, y-axis, and camera distance. Example value: "0deg 75deg 105%". |
| max-camera-orbit | Sets the maximum orbital values of the camera - useful if the default 3D model values are too large/too small. Example value: "auto 360deg 120%". |
| camera-target | Sets the starting point that the camera orbits around. The properties are specified in the following order: x-axis, y-axis, and z-axis. Example value: "1m -1m 0m". |
The full list of attributes is available at https://modelviewer.dev/docs/.
CSS classes
| Class name | Description |
|---|---|
| .copyMessage | Sets styles for the message wrapper. |
| .copyMessage-visible | Sets styles for the displayed message wrapper. |
| .buttonsContainer | Sets styles for the button's container. |
| .labelsButton | Sets styles for the button, which changes the view of annotations. |
| .labelsButton-selected | Sets styles for the clicked button, which changes the view of annotations. |
| .copyButton | Sets styles for the copy button. |
| .model-viewer-button | Sets styles for all the buttons. |
| .fullscreenButton | Sets styles for the fullscreenButton. This button is used to request fullscreen mode and exit fullscreen mode. |
| .modelViewerWrapper | Sets styles for the wrapper of the content when the "Enable fullscreen" property is selected. |
| .modelViewerFullscreen | Sets styles for the wrapper of the content when fullscreen mode is active. |
Fullscreen
For the module to start supporting fullscreen functionality, it must:
- Support Fullscreen API. At this point, iPhones do not support the Fullscreen API.
- The "Enable fullscreen" property must be selected.
When these conditions are met, the module will:
- Show in view a button that allows entering fullscreen mode.
- Allow the use of 'requestFullscreen' and 'exitFullscreen' commands.
When the "Enable fullscreen" property is selected, the content of the module will be wrapped with an element with the CSS class '.modelViewerWrapper', regardless of whether the device supports Fullscreen API.
Demo presentation
Demo presentation showing how to use the Model Viewer 3D module.