IVION Streaming API Sample Application

Overview

Use this application when you integrate IVION point clouds, panoramas or maps into your own software and want working code to start from. You need access to an IVION instance with API access. Run the application to see the streaming APIs in action, and read its source code to see how each step of the usage guides is implemented.

The application shows the point clouds, panoramas and maps of a site together in one 3D scene in site coordinates. It consists of two parts:

• libivion: a C++ library that handles logging in, listing sites and datasets, pre-signed download URLs, point cloud streaming, NVR archives, panorama tiles and map tiles.

• sample-app: an OpenGL application that uses libivion to display the data.

Point cloud and floor maps of a site in the same view

Note:

• The streaming APIs require API access, which is included in IVION Professional and IVION Enterprise but not in IVION Core. On an instance without API access, the application shows a message instead of the site list.

• The source code is licensed under the Zero-Clause BSD (0BSD) license. You can copy any part of it into your own application.

The application implements the steps described in these articles:

• Point Streaming API Usage Guide

• Panorama Streaming API Usage Guide

• Map Streaming API Usage Guide

• NVR File Format Specification

Downloads

The source code builds on macOS, Windows and Linux. The prebuilt applications for macOS and Windows let you try the streaming APIs without building anything first.

Connecting to an instance

1. Start the application.

2. Enter the URL of your IVION instance, for example https://{instance_name}.iv.navvis.com, or select a recently used one.

3. Click the Connect and log in button. A browser window opens.

4. Log in to IVION in the browser and allow the application to access the instance.

5. Select a site. The application loads the site and enables the first dataset that has panoramas.

The application stores the credentials in the file .ivion-sample-app in your home directory and reuses them for the next login. To log in as a different user, delete this file. To connect to an instance that allows anonymous access without logging in, click the Anonymous access checkbox before you connect.

To open another site or connect to another instance, click the Change site or Change instance button at the top of the panel.

Exploring a site

The panel on the side of the window controls what the scene shows:

• Datasets: switch datasets on and off. Click the Go to button to view a dataset from above.

• Point clouds: the application streams the point cloud level by level up to an adjustable octree level. You can apply Hide Overlap and Point Cloud Cleanup separately.

• Panoramas: a marker on the floor shows the position of each panorama. Click a marker to enter the panorama. You can blend the panorama over the point cloud. If the dataset has depth images, the panel shows the distance and the site coordinate of the point under the cursor.

• Maps: you can switch each map on and off individually. Outdoor maps are shown by default.

• Debugging: show the octree node bounds of point clouds and the tile borders and resolution levels of panoramas and maps. Slow down tile downloads to watch the order in which tiles load.

Inside a panorama: the markers show the neighboring panoramas, and the panel shows the distance and site coordinate under the cursor

Use the following controls to move through the scene:

Building from source

To build the application, you need CMake 3.21 or newer, Conan 2 and a C++17 compiler. Conan installs all other dependencies, except SDL2 on Linux, which comes from your distribution. Build the library first, then the application:

cd libivion
conan create . --build=missing
cd ../sample-app
conan build . --build=missing

The file README.md in the source code describes the build for each platform in detail, including Visual Studio on Windows.

Where to look in the code

Most of the application's code is about rendering and the user interface. The calls to libivion that the usage guides describe are in the following functions, all in the sample-app/src directory:

FAQ