Overview
The VNTANA Viewer is a custom web component, and can thus be placed into your web page as any standard HTML element. This reference serves to summarize the steps required to implement the HTML element in your website.
NPM Package
The VNTANA Custom HTML Element is now available as an NPM package as well as code bundle hosted by at npmjs. The details can be found here. New versions of the viewer will only be provided via this package/code bundle.
Important: Previous versions (pre-2.1.0) hosted by the viewer-builds.vntana domain will remain available for a while but no new versions will be available there.
On Premise Solution
The VNTANA 3D Webviewer is typically implemented via loading the viewer script in your page. If it is necessary to access the Webviewer in an environment with no or limited internet access, an ‘On Premise’ solution can be worked out. This generally involves provision of a custom script to be loaded from your internal servers or as a basic node project that can be run via a tool like http-server to serve it locally.
For more info on our ‘On Premise’ capabilities, book a call with our sales team.
Sample Implementation
This guide will summarize the main points on integrating the Viewer. For more details and examples, a sample repository is available which covers a couple of examples for implementing the HTML element. The repository can be found here.
Basic Usage
The viewer is a custom web component, and can thus be placed into your web page as any standard HTML element. Before doing so, the script containing the element definition needs to be loaded. ES and UMD modules are available, and can be obtained from the following links:
The viewer element is a custom HTML element, and can thus be manipulated, styled, and placed anywhere in the DOM just as a regular element would be. If no attributes are specified, the viewer acts as an empty element. Note that although the viewer doesn’t have any children in this example, the closing tag is still mandatory.
Attributes and Properties
The viewer can be manipulated either by setting and removing attributes in HTML or JavaScript, or directly through its properties. All attributes are passed as strings except boolean attributes, for which it suffices to set or remove the attribute to indicate their state. For example, if we wanted to set shadow intensity to 0.3 and enable auto-rotation of the camera, we would use the following code:
Removing the attribute or passing invalid values is equivalent to resetting its value to default. Continuing with the example above, removing the shadow-intensity attribute will reset its value to default value of 0, and removing the enable-auto-rotate attribute will set its value to false. If we were to set the shadow-intensity value to “something" it would also be reset to 0, and setting it to an out-of-bounds value like 50 would result in the value being clamped to 1.
The property interface is more appropriate if viewer parameters will change during the component’s lifetime. Unlike their corresponding attributes, property values are not kept as strings (strings will automatically be parsed if needed) and are automatically converted to basic types. The attribute values are automatically reflected in property values and converted, but the converse doesn’t hold – changing property values won’t change the attributes. For example, when we set shadow-intensity to 0.3 in the previous example, the viewer’s shadowIntensity property was immediately set to 0.3.
Property value types can be generally classified into the following categories:
strings Falsy values are converted to empty string, to everything else the call to String() is first applied.
booleans All strings are converted to true, to everything else the call to Boolean() is applied first.
colors Can be specified as a # followed by a six-digit hex code or an equivalent number. Always stored in hex code format.
numbers Numbers are treated as numbers, and strings are parsed for numbers. Everything else is discarded. Most numbers have some restrictions on them (for example, they need to belong to some range or be finite). Unless otherwise stated, all numeric values are assumed to be finite.
quantities Quantities represent number-unit pairs, and primarily refer to angles and distances/offsets. Supported angle units are radians (default) and degrees, while distances support meters (default), and in some cases may be specified as percentages to indicate relative quantities. Values passed without units are assumed to have default units. Alternatively, values passed as strings may have a unit suffix (e.g. “50deg” or “10m”).
vectors Vectors are combinations of numbers and quantities, provided as strings and separated by whitespace (for example, “30deg -20m 80rad”)
arrays Arrays are passed as stringified JSONs to attributes or directly to properties. If the passed value is a string, it will be parsed as a JSON, and treated as an array otherwise.