AR/3D Viewer and 3D Model Configurator

Last updated: Feb-19-2023

Important
The tools and applications offered on Cloudinary Labs are unsupported, pre-production prototypes. They are provided on an “AS IS” basis. While some of them will eventually be added to one or more of the Cloudinary products as fully supported features, the implementation or other elements of their functionality may change significantly. Furthermore, some Cloudinary Labs tools or applications could be temporarily or permanently removed without notice, at Cloudinary's discretion.

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.

Note

To try out the AR/3D Viewer you need to upload a 3D model to Cloudinary.

On this page:

Get started

The AR/3D Viewer component can work in any frontend setup (vanilla JavaScript, React, Vue, Angular, etc..).

To use the component:

  1. Add this script tag to the page:

  2. 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.
      Note
      The attributes are reactive, so updating the models attribute will remove the previous model and load the new one.

    For example, specifying the 3D model with public ID docs/CldLogo3D in the demo 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:

  • true: Shows the AR button.
  • false: Hides the AR button.

Default: true.
placement String Places the object either in a horizontal or vertical plane (used in Android ARCore). See Augmented reality.

Possible values:

  • floor: Places the object in a horizontal plane.
  • wall: Places the object in a vertical plane.

Default: floor.
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:

  • true: Renders an environment image.
  • false: Doesn't render an environment image.

Default: false.
shadow Boolean If true, renders shadow for the model. See Shadow.

Possible values:

  • true: Renders shadow for the model.
  • false: Doesn't render shadow for the model.

Default: false.
animation-play Boolean If true, plays an animation for a model with a built-in animation. See Animation.

Possible values:

  • true: Plays an animation.
  • false: Doesn't play an animation.

Default: false.
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:

  • true: Shows variants.
  • false: Doesn't show variants.

Default: false.
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:

  • true: Applies optimization.
  • false: Doesn't apply optimization.

Default: false.
quality Integer Applicable if optimize="true". The quality level to use for the optimization manually. See Optimize.

Range: 10 to 90.

Default: 80.
wireframe Boolean If true, shows the wireframe of the model. See Optimize.

Possible values:

  • true: Shows the wireframe.
  • false: Doesn't show the wireframe.

Default: false.
analytics Boolean If true, sends Google Analytics (for customers that have Google Analytics loaded in their site). See Analytics.

Possible values:

  • true: Sends Google Analytics.
  • false: Doesn't send Google Analytics.

Default: false.

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.

View in AR button

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.

Tip
Clicking the View in AR button on a mobile device initiates the AR experience immediately, rather than showing the QR code.

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.

AR/3D demo

Discover more about using 3D models in Cloudinary:

✔️ Feedback sent!

Rate this page: