AR/3D Viewer (Labs)
Last updated: Jul-20-2023
Want to elevate your website's impact and improve content velocity? We’re ramping up Beta customers for Dimensions, an exciting new 3D product.
We invite you to join a 30-minute exploratory call and apply to join our Private Beta. Fill out this survey to apply.
Overview
The AR/3D Viewer web component enables you to view and interact with 3D models in the browser and see them in augmented reality (AR) using your mobile devices.
The 3D Model Configurator is a Media Library app that you can use alongside the AR/3D Viewer to define texture variants and set the default quality for your model.
Get started
The AR/3D Viewer component can work in any frontend setup (vanilla JavaScript, React, Vue, Angular, etc..).
To use the component:
Prerequisite: To use the AR/3D Viewer, you first need to upload a 3D model to Cloudinary.
-
Add this script tag to the page:
-
Specify the
ar-3d-viewer
element where you want the viewer to appear on the page, with the following attributes:-
cloud
: Set to the cloud name of your Cloudinary product environment. -
models
: Set to the public ID of a 3D model in your Cloudinary product environment.NoteThe attributes are reactive, so updating themodels
attribute will remove the previous model and load the new one.
For example, specifying the 3D model with public ID
docs/CldLogo3D
in thedemo
Cloudinary product environment: -
Here's the full example, and the rendered output:
AR/3D Viewer attributes
The following attributes can be used in the ar-3d-viewer
component:
Attribute | Type | Description |
---|---|---|
cloud | String | The cloud name of your Cloudinary product environment. |
models | String | A comma-delimited string of 3D model public IDs that you want to show in the viewer. Currently, only one public ID is supported. See Supported 3D models. |
ar | Boolean | Shows/hides the AR button. See Augmented reality. Possible values:
Default: |
placement | String | Places the object either in a horizontal or vertical plane (used in Android ARCore). See Augmented reality. Possible values:
Default: |
hdr | String | The HDR file to use. Either specify the public ID of an HDR file stored in your product environment, or basic , which provides a basic HDR file. See Dynamic lighting.Default: No HDR file is used. |
skybox | Boolean | If true , the HDR also renders an environment image. See Dynamic lighting.Possible values:
Default: |
shadow | Boolean | If true , renders shadow for the model. See Shadow.Possible values:
Default: |
animation-play | Boolean | If true , plays an animation for a model with a built-in animation. See Animation. Possible values:
Default: |
animation-name | String | Applicable if animiation-play="true" . The name of a specific animation to play, for models with multiple animations. See Animation.Note: not providing a name, or providing a wrong name results in the first available animation being played. |
variants | Boolean | If true , presents variants for the model that have been pre-defined using the 3D Model Configurator Media Library app. See Texture variants. Possible values:
Default: |
optimize | Boolean | If true , applies an optimization transformation to the model. Can also be predefined via the 3D Model Configurator Media Library app. See Optimize. Possible values:
Default: |
quality | Integer | Applicable if optimize="true" . The quality level to use for the optimization manually. See Optimize.Range: Default: |
wireframe | Boolean | If true , shows the wireframe of the model. See Optimize. Possible values:
Default: |
analytics | Boolean | If true , sends Google Analytics (for customers that have Google Analytics loaded in their site). See Analytics. Possible values:
Default: |
Supported 3D models
You can use any 3D model that is supported for upload as an image type.
Models are transformed to GLB for use in the viewer, and to USDZ when viewed in AR on iOS devices. They are also transformed into animated GIF and poster files, for the loader and the AR splash page in mobile.
Augmented reality
The View in AR button is shown by default in the AR/3D Viewer and lets you view the model in your own environment using augmented reality. To hide this button set ar
to false
.
Clicking this button brings up a QR code that you can scan with a mobile device to open the device's built-in AR app. This works on iOS12+ for Apple devices and ARCore supported devices running Android 7.0 Nougat (API Level 24) or later.
On Android devices you can choose to place the model on a vertical surface by specifying placement="wall"
. By default, it is placed on a horizontal surface (placement="floor"
).
Dynamic lighting
The standard 3D scene has built-in lighting set up, but you can load your own HDR file to use as a lighting source and also as a skybox. There is also a basic
option.
See the difference between using the built-in lighting on the left and the basic
lighting on the right (hdr="basic"
):
To load your own HDR file, set the hdr
attribute to the public ID of an HDR file that you previously uploaded to Cloudinary. Note that HDR files are treated as raw assets, so the public ID includes the extension, for example hdr="docs/park.hdr"
.
To use the HDR file as a skybox, and not only as a lighting source, provide skybox="true"
:
Setting hdr
to basic
, with skybox="true"
, shows the basic
skybox environment:
Shadow
Make your 3D models cast a shadow in the scene by setting shadow
to true
.
For example:
Animation
If your 3D model supports animations, you can select which animation to play by setting animation-name
to the name of the animation, and animation-play
to true
. If you don't specify an animation name, the first one defined in the model is played.
Here's the cat with the Walk
animation, including a shadow:
"Cute Little Kitty" https://skfb.ly/ospAT by Diskette96 is licensed under Creative Commons Attribution.
Hotspots
The AR/3D Viewer supports hotspots that you can specify using HTML5 slots. A hotspot can be either a label or a button. The button supports only the click
event.
The following attributes can be set:
Attribute | Type | Description |
---|---|---|
slot | String | The Hotspot ID in the form: hotspot-<NUMBER> . |
data-position | Float | The x/y/z position of the hotspot in the form <X> <Y> <Z> . The values are in virtual meters from the center of the model and are not limited in range. |
For example:
"Cute Little Kitty" https://skfb.ly/ospAT by Diskette96 is licensed under Creative Commons Attribution.
Analytics
Integrate with Google Tag Manager
With Google Tag Manager integrated on your page, you can tell the AR/3D Viewer to update Google Tag Manager's dataLayer
array whenever an event is triggered by including the analytics
attribute.
For example:
Full list of reported events:
Event | Category | Action | Label | Name | Notes |
---|---|---|---|---|---|
cloudinaryEvent | ar/3d viewer widget | click | Changed variant to <VARIANT_NAME> | variant-changed | |
cloudinaryEvent | ar/3d viewer widget | click | Clicked on ar button to open qr modal | ar-button-clicked | When AR button is clicked on desktop |
cloudinaryEvent | ar/3d viewer widget | click | Clicked on ar button to open ar app | ar-button-clicked | When AR button is clicked on a mobile device |
cloudinaryEvent | ar/3d viewer widget | click | Clicked on copy ar link | ar-url-copied | |
cloudinaryEvent | ar/3d viewer widget | click | Clicked on hotspot <HOTSPOT_ID> | hotspot-clicked |
Custom events
You can send your own events by setting a listener to the set of events sent by the viewer.
For example:
Full list of events:
Event name | Data passed |
---|---|
loaded | generator, meshCount, meshData, trianglesCount |
loading-failed | |
variant-changed | name (variant name) |
ar-button-clicked | device (desktop/mobile) mode (qr/ar) |
hotspot-clicked | id (slot name) |
ar-url-copied |
AR/3D Viewer demo
You can play with different settings on various 3D models, using the AR/3D Viewer Demo.