Resources

3D Webviewer

Integrate VNTANA 3D Web Viewer via iFrame

Steps to Obtain iFrame Embed Code

  1. Login to your account on the VNTANA Platform
  2. Click on Products in the left-hand navigation menu
  3. Select the Product you want to view
  4. In the Embed Code section from the Product View Page, click on the Copy button to copy the entire Embed Code (circled in red below). The iFrame is now copied to your clipboard and can be used anywhere on your site. Just paste it in the HTML of the page you would like to include the 3D Web Viewer.
Additional Notes
  • Make sure your Product is LIVE, so it can be viewed publicly. Click the “Publish to API” button from the Product View Page to publish your product and set its review state to Live.
  • The <iframe> src is the URL to the 3D asset in a Standalone Viewer Page. This shareable link can be copied by clicking the Share button, which is below the Copy button.
  • The asset can easily be swapped out for another asset in your Product List by changing the productUuid value. productUuid can be found on the Product View Page labeled Product ID (see pictures below).
  • The Client Slug and Organization Slug are static values for all of your Products under the same Client and Organization.

Styling the 3D Web Viewer

  • The width and height of the <iframe> can be changed to better fit your site.
  • The <iframe> style can be updated with custom CSS if needed.
  • The background color of the viewer is white. More background options, including a transparent background, will be added soon for greater customization on your site!

VNTANA Viewer Component Integration

Overview

The VNTANA Viewer Module is a wrapper for Google’s model-viewer web component, used to display Khronos GLTF 2.0 content in browsers that provide full support for WebGL 1.0. The viewer component has been developed to be a portable JavaScript Universal Module Definition (UMD) library able to be dynamically loaded and included in web apps or web components. The library includes all dependencies in the packaged component and is therefore standalone and has no dependencies.

Library Functions, Parameters, and Integration

To integrate the viewer into an existing web app or component requires including the UMD module vnview.js using an HTML script tag or dynamic loading method.

The library currently exposes one function, createvnviewer, on the global namespace vnview which creates and returns a viewer class that can be used to load and render content.

var viewer = vnview.createvnviewer(element, options);

The element parameter is an HTML5 DOM element that will contain the viewer. The DOM element will be used as the parent element for the <model-viewer> element.

The options parameter is a JavaScript object that defines parameters for the setup and context of the Viewer. To use an embedded viewer, please set the value of embedded to true. The following options object shows all of the possible settings that can be configured within the Viewer.

onProgress – Any action desired while GLB is loading in viewer.

onSuccess – Any action desired on successful load of GLB in viewer.

onError – Any action desired on unsuccessful load of GLB in viewer. “Error” event can be fired for two reasons: ‘loadfailure’ and ‘webglcontextlost’. (See error under Eventshttps://modelviewer.dev/docs/index.html)

viewerConfigs – Object that holds rendererConfigs

rendererConfigs – Object with all of the saved configurations for the viewer settings. A null value indicates that no settings have been saved, and all values will be set to their default.

autoRotate – Enable/disable auto-rotation of model. Default is false.

showEnvironment – Show/hide the HDRI set under environment. If value is true, viewer background will be set to the environment map, and any preset background (presetBg) will be overridden. Default is false.

environment – Sets the environment map with the provided HDRI file. Default is “Default”

exposure – Sets the exposure. Default is 1.0.

shadowIntensity – Sets the intensity of the shadow cast by the model. Default is 4.0. Ranges from 0-10.

shadowSoftness – Sets the softness of the shadow. If shadowIntensity is set to 0, shadowSoftness has no effect. Default is 0. Ranges from 0-1. (Note: Softer shadows render faster).

presetBg – Sets the background color of the viewer. Default is “Default” (white background). In the future, we can expand the background options by accepting two HEX values for the radial gradient.

yaw – Sets the first value of the camera-orbit attribute, which controls the asset’s rotation about the Normal axis. Units are in radians. Default value is “auto”.

pitch – Sets the second value of the camera-orbit attribute, which controls the asset’s rotation about the Transverse axis. Units are in radians. Default value is “auto”.

distance – Sets the third value of the camera-orbit attribute, which controls the camera’s distance from the asset, in meters. Default value is “auto”.

fov – Sets the field of view of the camera, in degrees. Default value is “auto”.

targetPointX – Sets the X coordinate of the target point (pivot point). Default value is “auto,” which is the automatically calculated center of the bounding box on the X axis.

targetPointY – Sets the Y coordinate of the target point (pivot point). Default value is “auto,” which is the automatically calculated center of the bounding box on the Y axis.

targetPointZ – Sets the Z coordinate of the target point (pivot point). Default value is “auto,” which is the automatically calculated center of the bounding box on the Z axis.

Viewer Content

GLTF content can be loaded into the Viewer using the loadObject(url) method which takes a url to the model file:

viewer.loadObject(url)

Viewer Styles

We recommend including the following rules in your style sheet, in order for the most user friendly experience with the 3D Viewer.

model-viewer {
width: 100%;
height: 100%;
}

#enterFullscreen {
position: absolute;
right: 16px;
bottom: 16px;
width: 40px;
height: 40px;
background: #dbdbdb url(‘https://storage.googleapis.com/vntana-viewer/assets/images/enter_fullscreen_icon.svg’) no-repeat center;
background-size: 25px auto;
cursor: pointer;
}

#exitFullscreen {
position: absolute;
right: 16px;
bottom: 16px;
width: 40px;
height: 40px;
background: #dbdbdb url(‘https://storage.googleapis.com/vntana-viewer/assets/images/exit_fullscreen_icon.svg’) no-repeat center;
background-size: 25px auto;
display: none;
cursor: pointer;
}

Contact support@vntana.com to request access to our Viewer Component Library source code.

VNTANA Viewer Settings And Annotations Component Integration

Overview

The VNTANA Viewer, Settings and Annotations component is a wrapper for Google’s model-viewer web component, with a built in Settings and Annotations Panel. The viewer can display Khronos GLTF 2.0 content in browsers that provide full support for WebGL 1.0. The Settings panel exposes a variety of viewer settings, such as Camera and Lighting, that can be adjusted to create the best visual environment for your 3D asset. The Annotations panel allows users of your application to drop pins directly onto the 3D model, and leave comments and replies with text or uploaded reference images. (Accepted image file types are .png, .jpg, .jpeg, and .svg).

The component has been developed to be a portable JavaScript Universal Module Definition (UMD) library, that can be dynamically loaded and included in web applications or components.

Library Functions, Parameters, and Integration

To integrate the viewer with the settings and annotations panel into an existing web app or component requires including the UMD modules vnview-editor.js and vnview.js using HTML script tags or dynamic loading method.

The library currently exposes one function, createViewerEditor, on the global namespace vnvieweditor which creates and returns a ViewerEditor class.

var viewerEditor = vnvieweditor.createViewerEditor(element, options);

The element parameter is an HTML5 DOM element that will contain the component. The DOM element will be used as the parent element for the viewer and the settings and annotations panel.

The options parameter is a JavaScript object that defines parameters for the setup and context of the Viewer, Settings and Annotations. The following options object shows all of the possible settings that can be configured. Please see the above section about the Viewer Component Integration for all of the possible renderer configs options.

Viewer Options
Settings
  • viewerConfigs – Object that holds rendererConfigs
    • rendererConfigs – Object with all of the saved configurations for the viewer settings. A null value indicates that no settings have been saved, and all values will be set to their default.
    • saveRendererConfigs – Endpoint to save settings.

The settings panel expects the viewerConfigs property within the options object. The viewerConfigs property contains the rendererConfigs object and the saveRendererConfigs function.

rendererConfigs contains all of the 3D viewer configurations that can be saved per asset, such as the Lighting and Camera settings. If nothing is passed to this object, all of the viewer settings will be set to their default values. saveRendererConfigs is required if the settings need to be stored for retrieval at a later time.

For a more detailed list of the available rendererConfigs and their defaults, please see the above section, VNTANA Viewer Component Integration.

Annotations
  • getAnnotations – Endpoint to retrieve annotations list.
  • createAnnotation – Endpoint to create an Annotation. (optional)
  • updateAnnotation – Endpoint to update an Annotation. (optional)
  • deleteAnnotation – Endpoint to delete an Annotation. (optional)
  • resolveAnnotation – Endpoint to resolve an Annotation. (optional)

The annotations panel requires the getAnnotations function to get the current list of annotations, in order to show the annotations history in the correct order, as well as with the correct user information.

The annotations data returned from calling the getAnnotations method is expected in the below structure:

{
“response”: {
“annotations”: {
“grid”: [
{
“commentsCount”: 0,
“created”: “2020-12-01T23:37:54.863Z”,
“dimensions”: “string”,
“number”: 0,
“productUuid”: “string”,
“resolved”: true,
“text”: “string”,
“updated”: “2020-12-01T23:37:54.863Z”,
“userId”: “string”,
“uuid”: “string” // annotationUuid
}
],
“nextNumber”: 0,
“totalCount”: 0
}
}
}

The options object will also accept the parameters createAnnotationupdateAnnotationdeleteAnnotation, and resolveAnnotation to handle the creation, update, deletion, and resolution of individual annotations respectively.

These parameters are not required, however, as each action can also be handled outside of the component using event listeners. The component dispatches Custom Events whenever a user performs any of the annotations actions. Event handlers outside of the component can execute the desired actions (e.g. making an API call to post a new annotation), by listening for the following Custom Events:

  • _vntana_createAnnotation
  • _vntana_updateAnnotation
  • _vntana_deleteAnnotation
  • _vntana_resolveAnnotation

Regardless of the direction chosen in development, the data sent out of the component to the application is the same in both situations, and matches the request bodies for the corresponding endpoints in our Admin API.

createAnnotation request object:

{
“dimensions”: “string”,
“productUuid”: “string”,
“text”: “string”
}

updateAnnotation request object:

{
“dimensions”: “string”,
“text”: “string”,
“uuid”: “string” // annotationUuid*
}

deleteAnnotation request object:

{
“uuid”: “string” // annotationUuid*
}

resolveAnnotation request object:

{
“resolved”: true,
“uuid”: “string” // annotationUuid*
}

* Please note that any annotations created during an active user session will be assigned a temporary ID for the uuid value, since the component does not have access to the actual uuid stored in your database. As such, when updating, deleting, or resolving new annotations, the uuid parameter will be the temporary ID value.

Comments
  • getAnnotationComments – Endpoint to retrieve annotation comments list.
  • createComment – Endpoint to create a Comment. (optional)
  • updateComment – Endpoint to update a Comment. (optional)
  • deleteComment – Endpoint to delete a Comment. (optional)

The annotation comments follow a similar logic to the Annotations. The getAnnotationComments function is required to display any comments that were posted in response to an Annotation. The following request body will be passed to the getAnnotationComments function:

{
“entityType”: “ANNOTATION”,
“entityUuid”: “string”, // annotationUuid
}

The data returned from calling getAnnotationComments from within the component is expected in the below structure:

{
“response”: {
“comments”: {
“grid”: [
{
“created”: “2020-12-02T00:22:04.431Z”,
“entityType”: “ANNOTATION”,
“entityUuid”: “string”,
“message”: “string”,
“updated”: “2020-12-02T00:22:04.432Z”,
“userId”: “string”,
“uuid”: “string”
}
],
“totalCount”: 0
}
}
}

The viewer component also accepts the methods createCommentupdateComment, and deleteComment to handle the creation, update, and deletion of comments in response to an Annotation. As with the Annotations, these parameters are not required within the options object. The component dispatches Custom Events for each of the comments actions as well, which can be handled outside of the component with event listeners. The following Custom Events are dispatched for the creation, update, and deletion of a comment, respectively:

  • _vntana_createComment
  • _vntana_updateComment
  • _vntana_deleteComment

The data sent out of the component for each of these actions mirrors the request bodies of the Comment Resource endpoints in our Admin API, and have been copied here for convenience:

createComment request object:

{
“entityType”: “ANNOTATION”,
“entityUuid”: “string”, // annotationUuid*
“message”: “string”
}

updateComment request object:

{
“entityUuid”: “string”, // annotationUuid*
“message”: “string”,
“uuid”: “string” // commentUuid*
}

deleteComment request object:

{
“uuid”: “string” // commentUuid*
}

* Please note again here, that if a comment is created for a new annotation, the annotationUuid sent to your application will actually be its temporary ID value. Similarly, updating or deleting a new comment will return the comment’s temporary ID, and not the commentUuid stored in your database.

User Management
  • currentUserId – The currently logged in user’s ID. Can be any string that uniquely identifies the user, such as an email address, username, or uuid. The ID is required in order to determine which Annotations and/or Comments the user can edit and delete, since only the user who posted the Annotation/Comment can edit/delete it. The currentUserId will be compared against the userId associated with each Annotation or Comment.
  • usersList – List of users with the permission to create, edit or delete Annotations and Comments. This data is needed in order to display the user’s info next to the annotation or comment he/she posted. Each user object should have the following properties:
    • userId – Unique ID of the user.
    • profileImage – URL to profile image of user. If no value is passed, no image will be shown next to the user’s name.
    • userName – Any string value to display with the Annotation or Comment to easily identify the user who created the post. For example, this can be the user’s full name, account username, or email address.

Contact support@vntana.com to request access to our Viewer Settings and Annotations Component Library source code.

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.