Pointscene API documentation

Introduction

Pointscene API provides tools to analyse, manage and stream reality capture data.
With Pointscene API you can have a faster and more predictable time from development to production.

The API has built-in support for point clouds, raster files, mesh* models, images* and vector* files.
You can use the API to create custom applications that leverage existing libraries such as OpenLayers or Cesium JS.

The power of Pointscene API comes from fully customizable workflows.
Workflows can be used to convert data into streaming formats, extract metadata and much more.

Please email us at sales@pointscene.com for API access.

Quickstart

This quickstart chapter will jump directly into the interesting bits of Pointscene API.
Pointscene API is leveraging open source components such as GDAL and PDAL.

Different open source components are used as tasks and tasks are used to build workflows.
Workflows are used to manipulate and extract meaningful information from the input data.
For a more in-depth documentation and complete list of available tasks you can have a look directly at the docs here: Pointscene GraphQL API.

A growing list of API examples will be updated on our Github repository: API examples.

Example workflow: Convert ortho mosaic to Cloud Optimized GeoTIFF (COG) for streaming TMS tiles

We will use the createWorkflow mutation to define the workflow tasks for the conversion.

mutation {
createWorkflow(
# Define which instance is the owner of the workflow and its outputs
instanceId: ${Your instance Id}
title: "Create COG for streaming TMS tiles"
tasks: [
{
# Define input data to be downloaded from an external source
name: "download"
type: "web.download"
args: {
# Define the file URL e.g. a signed URL to your cloud storage
url: ${Your ortho URL}
}
}
{
# Run gdal.translate to generate COG
# Reference: https://gdal.org/programs/gdal_translate.html
name: "cog"
type: "gdal.translate"
args: {
of: "COG"
co: [
"BIGTIFF=IF_SAFER"
]
}
# Define task input from "download"
inputs: ["download"]
}
{
# Extract metadata such as geographic boundary
# Reference: https://gdal.org/programs/gdalinfo.html
name: "info"
type: "gdal.info"
args: {}
# Use "cog" task as input
inputs: ["cog"]
}
{
# Sync extracted metadata to the DB for use in queries
name: "sync"
type: "resource.sync"
args: {}
# Use input from "info" task
inputs: ["info"]
}
{
# Upload converted COG to storage
name: "upload"
type: "resource.upload"
args: {}
inputs: ["sync", "cog"]
}
{
# Enable resource so it can be queried
name: "enable"
type: "resource.enable"
args: {}
inputs: ["sync"]
}
]) {
id
}
}
Note: sync, upload and enable tasks can be abstracted for convenience and are here to show the level of customization possible.

Pointscene API entities

This chapter will explain the different entities in Pointscene API.
As an overview Pointscene API consists of instances, workflows, resources and assets. Instances are the base entity for which all the other entities, users and clients can be linked to.

Instances

Instances are the base entity used to link all resources, assets, workflows, users and clients.
Depending on your domain or business logic it may make sense to think of instances as worksites or projects.

Users can be given access to different roles linked to an instance.
Clients can be given scoped access to different instances.

Resources and assets linked to an instance can be queried based on metadata such as geospatial extent.

Workflows

Workflows provide a way to manipulate input data.
They are constructed from tasks that carry out a specific operation and allow for a fully customizable way to process and manage business critical data.

Workflows and queries are consumed through Pointscene GraphQL API.
Pointscene GraphQL endpoint is located at https://api.pointscene.com/graphql.

Resources

Resources can be anything from single files to complex folder structures and provide a way to manage different files and formats by extracting queryable metadata.
For example files containing geospatial information can be queried by their spatial extent.

Known resources have generic types for rasters, point clouds, vector data, mesh models and photos.
These types will be useful when building workflows.
The workflow engine will check that the task inputs and outputs are compatible.

Resources can be created by workflows, web downloads or user uploads.
It is possible to create several different output resources from a single input resource.
For example when uploading point clouds it is possible to define a workflow that will output separate resources or assets for ortho photos, surface models and streaming point clouds.

Resources of specific types are linked as assets which can be used to stream e.g. slippy map tiles (TMS) or point clouds (Potree, EPT, 3D Tiles) over the internet.

Assets

Assets are a convenient way of accessing resources of specific types.
Compared to resources which contain generic types for the resource data, assets are of a known format.
Assets can be for example Cloud Optimized GeoTIFF's (COG), a streaming point cloud in EPT format or LandXML layers streamed as 3D Tiles.

User and client authentication

User authentication (OAuth2.0) is handled via REST endpoints. REST API documentation can be found here*.
Pointscene REST endpoint for authentication is https://api.pointscene.com/oauth2.

Users can have different roles for instances. Available user roles are:
Viewer - Read access to an instance and its entities
Editor - Read/Write access to an instance and its entities
Owner - Admin access to an instance and its resources

Clients can be granted scoped access. Available scopes for client access are:
instance-read-{id} - Read access to an instance and its entities
instance-write-{id} - Write access to an instance and its entities
instance-create - Can create a new instance

Support

You can contact us at support@pointscene.com.

Links

Pointscene GraphQL API playground
Pointscene GraphQL API documentation
Pointscene REST API documentation
Pointscene API examples

*) Coming soon