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 "model-viewer" element. |
| 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 addon will be wrapped with an element with CSS class `.modelViewerWrapper`, regardless of whether the device supports Fullscreen API. Check the chapter `Fullscreen` for more information. |
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 annotations visibility status of the model. |
| setScale | number | Sets the model's scale. |
| requestFullscreen | ... | Enters module in fullscreen mode. Check the chapter `Fullscreen` for more information. |
| exitFullscreen | ... | Exits module from fullscreen mode. Check the chapter `Fullscreen` 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.