Overview
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.
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 Events: https://modelviewer.dev/docs/index.html)
disablePoster – Disables the poster image that is displayed before the asset loads. Default is false.
pipelineUuid – The UUID of the Pipeline used for processing. Currently, the pipelineUuid only affects the viewer if it is the Custom Jewelry pipeline, but in the future, other pipelines may also have their own custom viewer settings and/or rendering. For Custom Jewelry, gem rendering will be applied. Otherwise, the pipelineUuid value is optional.
thumbnailUrl – The URL of the thumbnail to use as the poster image. The thumbnailUrl is optional; if a value is not provided, then the viewer will automatically try to access the thumbnail generated by the VNTANA Platform.
showModelOnInteraction – If set to true, the model will not be loaded until the user hovers over the viewer. This config is optional. If a value is not provided, the viewer will use its default behavior of dismissing the poster as soon as the asset has finished loading.
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).
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.
showHotspotNumbers – Enable/disable hotspot numbers in Embed links. Default is false (numbers are not shown in hotspot pins).
orientation – Object that contains properties that set the asset’s orientation. Roll specifies the rotation about the Z-axis. Pitch specifies the rotation about the X-axis. Yaw specifies the rotation about the Y-axis. The default for all values (row, pitch, yaw) is 0. Changing any of these settings will reprocess the asset to change its inherent orientation, so that it appears correctly in both the viewer and in AR.
disableZoom – Disables the ability for a user to zoom in and out of the model. Default is false.
shadowFloorPosition – Sets the position of the shadow relative to the model. Negative values move the shadow floor down, farther away from the model, and positive values move the shadow floor up, closer to the model. Default is 0.
rotationSpeed – Sets the rotation speed of the model when autoRotate is enabled. The speed can be set as a percentage relative to the default, which is 100%. For example, to have the model rotate 3x as fast, the rotationSpeed value should be set to 300%. Negative values cause the model to rotate in the opposite direction (clockwise vs. counterclockwise).
postprocessing – Defines the postprocessing settings.
- tonemap – Defines the tonemap to use, TONEMAP_LINEAR or TONEMAP_ACES_HILL_EXPOSURE_BOOST.
- smaa – Enables SMAA. Default is false.
- sharpen.amount – Sets the sharpen filter to the specified amount (0 is off, 1 is the max).
- bloom.strength – Sets the strength of bloom (0 is off).
- bloom.threshold – Sets the pixel brightness threshold after which bloom takes.
- bloom.radius – Sets the radius of bloom highlights.
useAoMaps – Uses ambient occlusion maps present in the 3D model. Default is true.
lights.useSceneLights – Uses the lights present in the 3D model. If false or the model doesn’t have embedded lights, the default lighting setup will be used.
lights.color – Color of the default lights.
lights.intensity – Intensity of the default lights.
Note: To ensure the defaults are used, you can pass rendererConfigs : null and all defaults will be loaded.
Viewer Content
GLTF content can be loaded into the Viewer using the loadObject(url) method which takes a url to the model file:
Viewer Styles
We recommend including the following rules in your style sheet, in order for the most user friendly experience with the 3D Viewer.
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 fort the model-viewer, 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.
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
- fileGLTF – URL of GLB file to load in viewer.
- Example: “https://api.dev.vntana.com/assets/products/524e5f1c-635f-4eec-b73e-9ebb2f9235bb/organizations/vntana-platform/clients/test/c7c1691d-6938-402c-b5c1-178aff095480.glb”
- productUuid – Uuid of asset on VNTANA Platform
- Example: “524e5f1c-635f-4eec-b73e-9ebb2f9235bb”
- clientUuid – Uuid of Workspace on VNTANA Platform to which the asset belongs
- onProgress – Any action desired while GLB is loading in viewer. (optional)
- 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 Events: https://modelviewer.dev/docs/index.html#loading-events) (optional)
- panelOrder – An array indicating the order in which to display the different editor panels. Do not include the panelOrder property if you want to use the default order. Default order is [“settings”, “annotation”]. (optional)
- hideSaveBtn – A boolean that toggles the visibility of the Save button in the Settings panel. Default is false. (optional)
- thumbnailUrl – URL of poster image to load in viewer while the asset loads. (optional)
- Example: “https://api.vntana.com/assets/thumbnail/products/a49b478b-01c5-4514-a539-a7ce8f649cb5/organizations/vntana-tech-test-01/clients/vntana-tech-test-01”
- disablePoster – A boolean that determines whether to display the provided thumbnailUrl as the poster image before the asset loads. Default is false. (optional)
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:
The options object will also accept the parameters createAnnotation, updateAnnotation, deleteAnnotation, 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:
- The createAnnotation function should also return a response object that contains the newly created annotation’s uuid.
updateAnnotation request object:
deleteAnnotation request object:
resolveAnnotation request object:
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:
The data returned from calling getAnnotationComments from within the component is expected in the below structure:
The viewer component also accepts the methods createComment, updateComment, 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:
- The createComment function should also return a response object that contains the newly created comment’s uuid.
updateComment request object:
deleteComment request object:
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.