The Pointerra 3D Viewer JavaScript API is a JavaScript library that enables viewing of point clouds (and other reality capture data) hosted within the Pointerra service on any HTML5 web page. Although there is no licensing required to use the library, access control is maintained via API tokens - so you will require a valid Pointerra account (with a corresponding API token) to load data or utilise the functionality of the viewer.
To load the viewer, you simply need to include the loader script from:
https://static.pointerra.io/viewer/js/pointerra-client.js
The loader script will allow you to create an instance of the viewer. By default, it will query the Pointerra service and determine the current production viewer viewer to instantiate (you can override this with a specific version number if desired)
This example shows how to create (an empty) Pointerra viewer component on a web page hosted by your own web server (assumed to be localhost running on port 8080 in this example)
Get a web server (IIS, nodejs, etc) running on localhost, port 8080.
Create minimal.html as
<html lang="en">
<head>
<meta charset="utf-8" />
<script type="text/javascript" src="https://static.pointerra.io/viewer/js/pointerra-client.js"></script>
<style>
body {
font-family: 'Open Sans', sans-serif;
background: #eee;
color: #333;
padding: 0;
margin: 0;
font-size: 14px;
}
.pointerra-viewer {
position: relative;
margin: 10vh 20vw;
width: 60vw;
height: 60vh;
}
</style>
</head>
<body>
<div id="pointerra-viewer" tabindex="0" class="pointerra-viewer"> </div>
<script>
pointerra.loadClient({
targetElement: "#pointerra-viewer",
pointerraAccessToken: "<YOUR_API_KEY>",
})
</script>
</body>
</html>Run your web server and navigate to http://localhost:8080/minimal.html. This should create an empty 3D viewer inside the specified target element (#pointerra-viewer).
To create a viewer instance (and the corresponding API instance), you need to specify an element (normally a div) to host the viewer, and then call pointerraClient.create(options)
On success, the creation method returns a promise to the core API object. If there is an error in creating the viewer, then a null object will be returned.
let api = null
pointerra.loadClient({
targetElement: "#pointerra-viewer",
pointerraAccessToken: "<YOUR_API_KEY>"
}).then(pointerraApi => {
api = pointerraApi
})A full list of the options that can be passed into the creation function can be found in the IClientOptions interface documentation
As per the sample code above, the following properties are mandatory when using the API:
Authentication to the Pointerra service can be through the use of an API Key, or by providing an instance of the Pointerra JWT helper. Using JWT for authentication means that you do not need to risk exposing your API key - instead requiring users to provide credentials by logging in with their Pointerra username and password.
Using JWT also allows your session to operate in the context of the logged in user (i.e. with their access permissions) and is the recommended way to authenticate. The helper has a built in login UI, or you can handle this yourself. Below is a minimal viewer example that uses the JWT authentication. There is also an NPM module available for the JWT helper.
<html lang="en">
<head>
<meta charset="utf-8" />
<script type="text/javascript" src="https://static.pointerra.io/viewer/js/pointerra-client.js"></script>
<script type="text/javascript" src="https://static.pointerra.io/viewer/js/jwt.js"></script>
<style>
body {
font-family: 'Open Sans', sans-serif;
background: #eee;
color: #333;
padding: 0;
margin: 0;
font-size: 14px;
}
.pointerra-viewer {
position: relative;
margin: 10vh 20vw;
width: 60vw;
height: 60vh;
}
</style>
</head>
<body>
<div id="pointerra-viewer" tabindex="0" class="pointerra-viewer"> </div>
<script>
pointerra.loadClient({
targetElement: "#pointerra-viewer",
jwt: PointerraJWT,
})
</script>
</body>
</html>This example shows how to initialise the viewer with full plugin support. Plugins will be required if you need to view more than just a basic point cloud. This includes any of the following:
In the code below, take note of the additional plugin property passed into the loadClient options. If you know that you won't be using the functionality from any particular plugin (e.g. you don't require the overview map window because you are providing your own 2D map), then you could omit it from your code.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<script type="text/javascript" src="https://static.pointerra.io/viewer/js/pointerra-client.js"></script>
<script type="text/javascript" src="https://static.pointerra.io/viewer/js/jwt.js"></script>
<style>
body {
font-family: 'Open Sans', sans-serif;
background: #eee;
color: #333;
padding: 0;
margin: 0;
font-size: 14px;
}
.pointerra-viewer-container {
position: relative;
margin: 20vh 20vw;
width: 60vw;
height: 60vh;
}
</style>
</head>
<body>
<div id="pointerra-viewer" class="pointerra-viewer-container" tabindex="0"> </div>
<script>
let api = null
pointerra.loadClient({
targetElement: "#pointerra-viewer",
jwt: PointerraJWT,
plugins: [
pointerra.Plugins.LeafletMap('https://tileserver.pointerra.io'),
pointerra.Plugins.Datasets(),
pointerra.Plugins.PanoViewer(),
pointerra.Plugins.PhotosViewer(),
pointerra.Plugins.SphericalImages()
],
pointcloudId: <your_pointcloud_id>,
viewer: {
enableTools: true
}
}).then((pointerraApi) => {
api = pointerraApi
})
</script>
</body>
</html>Methods and events within the API are organised into namespaces, based on key areas of functionality. Example namespaces within the API include; bookmark, poi, scene, etc. Each namespace is attached as a property to the api, and has its own section within this documentation.
For example, to get the set the background color for the viewer, you would use the setBackgroundColor() method from the viewer API:
api.viewer.setBackgroundColor('#ff0000')There are a small number of utility methods and properties that are not in a namespace. These are documented in the ApiBase section. For example, to obtain all of the options that were passed in during viewer creation:
const creationoptions = api.optionsThe viewer component makes extensive use of events to communicate changes in state to the host JavaScript environment. To listen for a specific event, you should add an event listener as follows:
api.[namespace].[event_name].addEventListener((event_data) => {
// Do work here.
})For example, to listen for changes to the camera location and pose, you would subscribe to the cameraChanged event in the scene namespace:
api.scene.events.cameraChanged.addEventListener((cameraData) => {
// Do something with new camera location...
})The available events and the data supplied to the handler functions are listed in the relevant namespace API documentation sections.