# Vertex Web Viewer SDK This project contains Vertex's 3D Viewer SDK. Vertex is a cloud platform for rendering large 3D models. See [Vertex's website][vertex] for more information. Our 3D viewer is distributed as a set of standards-based [web components] that can run in modern browsers matching this project's Browserslist targets. ## Installation ### Script Tag The easiest way to get started is by including a ` ``` --- This package also provides a set of utilities for use with its API. These utilities can be imported from a CDN as shown below: ```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`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined) to check if the component has been loaded. ```js 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") } ``` ### NPM Dependency 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`: ```json { "dependencies": { "@vertexvis/viewer": "^1.0.1" } } ``` 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](#manually-registering-components) for an alternative to register components. ```js 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(); ``` ## Manually Registering Components 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. ```js 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. ```js import { defineCustomElements } from '@vertexvis/viewer'; defineCustomElements(); ``` ## Interacting With Component Properties 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. ```js 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}`); }); } ``` ## Examples Check out our [examples](../../examples) directory and [Examples](https://developer.vertex3d.com/examples) page on our Dev Portal to get an idea of what you can do with Vertex's Viewer component. ## Documentation 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: - [\](./src/components/viewer) - [\](./src/components/viewer-walk-mode-tool) - [\](./src/components/viewer-view-cube) - [\](./src/components/viewer-transform-widget) - [\](./src/components/viewer-toolbar) - [\](./src/components/viewer-toolbar-group) - [\](./src/components/viewer-teleport-tool) - [\](./src/components/viewer-spinner) - [\](./src/components/viewer-pin-tool) - [\](./src/components/viewer-pin-label) - [\](./src/components/viewer-pin-label-line) - [\](./src/components/viewer-pin-group) - [\](./src/components/viewer-measurement-precise) - [\](./src/components/viewer-measurement-overlays) - [\](./src/components/viewer-measurement-line) - [\](./src/components/viewer-measurement-distance) - [\](./src/components/viewer-measurement-details) - [\](./src/components/viewer-markup) - [\](./src/components/viewer-markup-tool) - [\](./src/components/viewer-markup-freeform) - [\](./src/components/viewer-markup-circle) - [\](./src/components/viewer-markup-arrow) - [\](./src/components/viewer-layer) - [\](./src/components/viewer-icon) - [\](./src/components/viewer-hit-result-indicator) - [\](./src/components/viewer-dom-renderer) - [\](./src/components/viewer-dom-group) - [\](./src/components/viewer-dom-element) - [\](./src/components/viewer-default-toolbar) - [\](./src/components/viewer-button) - [\](./src/components/viewer-box-query-tool) - [\](./src/components/viewer-annotation-callout) - [\](./src/components/scene-tree) - [\](./src/components/scene-tree-toolbar) - [\](./src/components/scene-tree-toolbar-group) - [\](./src/components/scene-tree-table-resize-divider) - [\](./src/components/scene-tree-table-layout) - [\](./src/components/scene-tree-table-header) - [\](./src/components/scene-tree-table-column) - [\](./src/components/scene-tree-table-cell) - [\](./src/components/scene-tree-search) - [\](./src/components/scene-tree-notification-banner) In addition to the above documentation, controllers exposed on the `` element have dedicated READMEs corresponding to their functionality: - [model-views](./src/lib/model-views/readme.md) - [pmi](./src/lib/pmi/readme.md) [vertex]: https://www.vertex3d.com [web components]: https://developer.mozilla.org/en-US/docs/Web/Web_Components