This project contains Vertex's 3D Viewer SDK. Vertex is a cloud platform for rendering large 3D models. See Vertex's website for more information.
Our 3D viewer is distributed as a set of standards-based web components that can run in any browser supporting the Custom Elements v1 specification. For browsers that do not support the Custom Elements v1 spec, a polyfill will automatically be used.
The easiest way to get started is by including a <script>
tag in your HTML
file that references our published JS bundles from a CDN.
<html>
<head>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@vertexvis/viewer@0.22.0/dist/viewer/viewer.css"
/>
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@vertexvis/viewer@0.22.0/dist/viewer/viewer.esm.js"
></script>
</head>
<body>
<vertex-viewer id="viewer" src="urn:vertex:stream-key:123" client-id="123"></vertex-viewer>
</body>
</html>
This package also provides a set of utilities for use with its API. These utilities can be imported from a CDN as shown below:
<!-- CDN -->
<html>
<head>
</head>
<body>
<script type="module">
import { ColorMaterial } from 'https://cdn.jsdelivr.net/npm/@vertexvis/viewer@0.22.0/dist/esm/index.mjs';
function main() {
const color = ColorMaterial.fromHex('#ff0000');
}
</script>
</body>
</html>
If you want to interact with a web component via JavaScript, you should ensure
the browser has registered the custom elements prior to calling the elements
methods. You can use
window.customElements.whenDefined
to check if the component has been loaded.
async function main() {
const viewer = document.querySelector('#viewer');
// Wait for the component to be registered.
await customElements.whenDefined('vertex-viewer');
viewer.load("urn:vertex:stream-key:123")
}
Our components support being installed as an NPM dependency and packaged through
a bundler such as Webpack or Rollup. First, add @vertexvis/viewer
as an NPM
dependency to your package.json
:
{
"dependencies": {
"@vertexvis/viewer": "^0.22.0"
}
}
Next, import defineCustomElements
from the loader included as part of the
package. Using the loader will self lazy-load the components used in your
application.
Note: Certain bundler settings may have issues with using the self lazy-loading strategy. See Manually Registering Components for an alternative to register components.
import { defineCustomElements } from '@vertexvis/viewer/loader';
async function main() {
await defineCustomElements();
const viewer = document.querySelector("viewer");
await viewer.load("urn:vertex:stream-key:123");
console.log("Loaded!");
}
main();
We recommended using self lazy-loading to load components, which helps keep bundle sizes to a minimum and only loads components as they're needed. However, some bundler configurations may have problems with this option.
You can manually register components by importing them and registering them with the browser.
import { VertexViewer, VertexViewerDefaultToolbar } from '@vertexvis/viewer';
customElements.define('vertex-viewer', VertexViewer);
customElements.define('vertex-viewer-default-toolbar', VertexViewerDefaultToolbar);
If a component depends on other components, you'll need to register each one
individually. As this can be tedious, we export a defineCustomElements()
method to register all components. Note: this will add all components to
your bundle.
import { defineCustomElements } from '@vertexvis/viewer';
defineCustomElements();
Some of our components provide default values for properties that can be used
once the component is ready. Before interacting with these properties, the
componentOnReady
method must be awaited to ensure the property is defined.
function main() {
await defineCustomElements();
const sceneTree = document.querySelector("scene-tree");
await sceneTree.componentOnReady();
sceneTree.controller.stateChanged(state => {
console.log(`Scene Tree Row Count: ${state.totalRows}`);
});
}
If you plan on targeting IE11 or Edge <= 18, you'll also need to supply polyfills for the Web Component APIs (Custom Elements, Shadow DOM, CSS Variables, etc).
To include the polyfills, import applyPolyfills
from the loader.
import { applyPolyfills, defineCustomElements } from '@vertexvis/viewer/loader';
function main() {
await applyPolyfills();
await defineCustomElements();
console.log("Loaded!");
}
Check out our examples directory and Examples page on our Dev Portal to get an idea of what you can do with Vertex's Viewer component.
Each component provided by the @vertexvis/viewer
package also exposes
its own component-level README with additional examples and property definitions.
See below for the list of components and links to their READMEs:
- <vertex-viewer>
- <vertex-viewer-walk-mode-tool>
- <vertex-viewer-view-cube>
- <vertex-viewer-transform-widget>
- <vertex-viewer-toolbar>
- <vertex-viewer-toolbar-group>
- <vertex-viewer-teleport-tool>
- <vertex-viewer-spinner>
- <vertex-viewer-pin-tool>
- <vertex-viewer-pin-label>
- <vertex-viewer-pin-label-line>
- <vertex-viewer-pin-group>
- <vertex-viewer-measurement-precise>
- <vertex-viewer-measurement-overlays>
- <vertex-viewer-measurement-line>
- <vertex-viewer-measurement-distance>
- <vertex-viewer-measurement-details>
- <vertex-viewer-markup>
- <vertex-viewer-markup-tool>
- <vertex-viewer-markup-freeform>
- <vertex-viewer-markup-circle>
- <vertex-viewer-markup-arrow>
- <vertex-viewer-layer>
- <vertex-viewer-icon>
- <vertex-viewer-hit-result-indicator>
- <vertex-viewer-dom-renderer>
- <vertex-viewer-dom-group>
- <vertex-viewer-dom-element>
- <vertex-viewer-default-toolbar>
- <vertex-viewer-button>
- <vertex-viewer-box-query-tool>
- <vertex-viewer-annotation-callout>
- <vertex-scene-tree>