<model-viewer src="path/to/3dmodel.glb" alt="A 3D model"></model-viewer>
<model-viewer camera-controls skybox-image="path/to/skyboxImage.jpg" alt="A 3D model" src="path/to/3dmodel.glb"> </model-viewer>
Some useful links:
The web standards for AR are still a work in progress, and constantly changing, as is browser support. model-viewer gets around this by using operating-system specific 'AR viewing apps' that integrate seamlessly with the browser experience. There are 3 modes available:
webxrfor browsers that support the current
WebXRspec (Chrome 86+ on Android)
quick-lookfor iOS devices
scene-viewerfor Android devices
Preparing a model
model-viewer accepts only
.glb models. (
.gltf models often have textures stored as separate files. It's important to to keep them in the same relative location to the
.gltf). For displaying a model in AR on iOS, one also needs to provide a
.usdz version of the model.
Here are some tools that can help with converting a model to these formats :
- Models uploaded to Sketchfab are automatically converted to a variety of formats that can then be downloaded
- The three.js editor allows you to drag a model into it, and then export in a variety of formats
- Apple Reality Convertor for USDZ conversion (only for mac os 10.15.4+)
Note on 3d model feature support:
QuickLook (on iOS devices) does not support all features part of the
.gltf spec. When converting a model to
.usdz, some of these features could be emulated, while some will not work at all. See here for a list of
.usdz limitations from Sketchfab, and a more detailed list along with emulations possible through the Google command line tool.
There are a few attributes that need to be included in the HTML tag for a model to work in AR:
<model-viewer src="path/to/3dmodel.glb" ios-src="path/to/USDZmodel.usdz" ar ar-mode="webxr scene-viewer quick-look" alt="A 3D model that works in AR"> </model-viewer>
See here for more examples. The object can also be placed on a wall instead of the floor, and the AR button can be customized. It's important to note that the AR button will only be displayed on devices that support AR, so while developing on a laptop/desktop this button will not appear.
quick-look is specified in the
ar-mode list, but no
.usdz model is provided, one will be generated on the fly. This is a new feature however, and might not produce desired results.
Note about scale:
The only options for pre-setting scale (
ar-scale) in AR mode are
fixed - auto allows the model to be resized by pinching, whereas fixed always renders the model at 100% scale. The
gltf format's scale is set in meters — so a model of scale 1 will render fairly large in AR mode — keep this unit in mind while preparing the model.
model-viewer comes with default camera controls for rotation and zoom, the ability to set the camera orbit and target, auto-rotate, field of view and more. The camera works on a spherical coordinate system, set by a radius, and inclination and azimuth angles. Interact with this demo to see how these values affect the camera (+ play around with different lighting settings). See here for more examples and documentation.
model-viewer lets you add annotations to the model by specifying its position and normal. Annotations can be styled through CSS, and can be set to be 'always visible' or occluded depending on the rotation of the model. Annotation ('hotspot') locations can be selected through the model-viewer editor (generates an HTML snippet and allows for entering label text), or on this page (displays position and normal values).
Here is how an annotation is plugged into the model-viewer HTML:
<model-viewer src="scene.glb" camera-controls> <button class="Hotspot" slot="hotspot-1" data-position="0.08125757912266225m 0.01903929367409709m 0.048820624535711885m" data-normal="-0.004757698885123861m 7.089523799901993e-11m -0.9999886820866116m" data-visibility-attribute="visible"> <div class="HotspotAnnotation">Here is a label for the annotation</div> </button> </model-viewer>
Note: Annotations currently work only in the browser and in WebXR mode for AR (Chrome 83+ on Android).
Using model-viewer with React / bundling tools
<script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js" /> <script nomodule src="https://unpkg.com/@google/model-viewer/dist/model-viewer-legacy.js" />
You can also use an
import statement like so: