Percept Software Installation Guide

Preparing the Percept Software Environment

Thank you for choosing Blickfeld Percept. In this chapter we will guide you through the necessary steps in the Percept software installation process.

Minimum Hardware Requirements

Percept and the applications you can create with Percept and your Blickfeld LiDAR are very versatile and therefore the hardware requirements will differ depending on your use case. Our recommendation is:

  • CPU: Intel i5/i7 or AMD Ryzen 5/7

  • RAM: 8/16 GB

  • SSD/HDD: 512 GB

  • Network: Gigabit-Ethernet

Supported Operating Systems

Currently we support Windows 10 (with WSL2) and Ubuntu Linux (18.04 and 20.04).

In order to run Percept you need to install Docker first on your operating machine. The following section will guide you through this process.

As the Percept Architecture is based on Docker, there is a chance that it will run on your favorite Linux Distribution, too.

How to install Docker

Percept is provided to you as a Docker container. A Docker container can be compared to a virtual machine and is executed on the host by the Docker daemon.

The Percept container contains all necessary programs, algorithms and binaries to acquire, process and visualize point clouds. The provided Percept web interface lets you easily create, configure, start and visualize projects.

Ports used by Percept

Percept will use the following Ports for communication. Some of them can be configured by the user in the provided docker compose file, while some of them are fixed and cannot be changed.

It can happen, especially on Windows based systems that another system resource or application is using Port 80. Therefore, the frontend will not start. If this is the case for you set another port used for the frontend in the docker-compose file (docker-compose.yml).
Table 1. Ports used by Percept
Port Configurable

80

can be changed in the docker-compose file

9901

can be changed in the docker-compose file

5000

can be change in the docker-compose file

58080

cannot be change, ask the Blickfeld Team for further information

Windows

To run Percept on Windows you will need to have Docker and the Windows Subsystem for Linux 2 short WSL2 setup on your PC.

  1. To install Docker on Windows please follow this recipe from the official Docker website:

    1. Docker installation on Windows

After installing Docker, the "Docker Desktop" Application should be available and the docker command should be executable inside the Windows Command Line Tool as cmd-prompt.

Docker Desktop GUI
Figure 1. Docker Desktop GUI

If your version of Windows supports WSL2 (Windows subsystem for Linux) we recommend enabling and using it as a backend for Docker for Windows.

Docker for Windows detects if your system is capable of using WSL2. Follow the steps in the Docker GUI to install and enable WSL2. Further information can be found on the Docker website: Docker WSL2 integration

If WSL2 is not installed Docker is using the Hyper-V backend to execute containers which might lead to lower performance in compute-heavy or IO-intensive applications.

Since the Percept containers communicate with TCP between each other, we require to enable Expose daemon on tcp://localhost:2375 without TLS in the Settings of the Docker Desktop GUI as shown in the following image:

Docker enable TCP connection without TLS
Figure 2. Docker Desktop GUI: Enable TCP without TLS

To finish the installation of Docker, please reboot your PC.

Linux

Ubuntu

To run Percept you will need to install Docker on your Ubuntu machine.

  1. To install Docker on Ubuntu please follow this recipe from the official Docker website (We tested it with "install using the repository"):

    1. Docker installation on Ubuntu

The Percept containers communicate with TCP with each other, therefore we have to enable TCP without TLS on localhost:2375. This is also needed for some Docker volumes to share data between Percept and your PC, e.g. to save Project-Settings.

For your convenience we included a configure.sh script in the zip folder of Percept (needs root permission). Please follow the steps to configure Percept:

The command sudo ./configure.sh docker will replace the Docker /etc/docker/daemon.json and the /etc/systemd/system/docker.service.d/docker.conf with our templates. If you have some Docker configuration already, you might just check out the additional needed content and skip the second step

  1. sudo ./configure.sh user your_user_name (replace your_user_name with your user name)

  2. sudo ./configure.sh docker

  3. sudo ./configure.sh volumes

Percept also requires docker-compose. You can either install it with apt install docker-compose or by following the docker documentation Install Docker Compose

To finish the installation of Docker, please reboot your PC.

Required Docker Version

Please make sure that you have at least the docker version 20.10.XX

on Windows you can check the version either

  1. use the command line and enter docker --version

  2. or have a look in the docker desktop gui under settings (docker engine version)

Docker Version
Figure 3. Image shows the docker version (in the docker engine section) denoted as v20.10.12

on Ubuntu

  1. open a terminal and enter docker --version

How to install Percept

If you have Docker installed and set up, we can now load the Percept image into the local Docker registry.

These steps are the same for Windows and Linux

  1. Extract the downloaded archive and navigate to the folder:

    1. for Percept licensed version: cd Downloads/blickfeld-percept-v1.x.x_licensed/blickfeld-percept-v1.x.x_licensed

    2. for Percept trial version: cd Downloads/blickfeld-percept-v1.x.x_trial/blickfeld-percept-v1.x.x_trial

  2. Load the Percept image into the local Docker registry by executing the following command on the command line:

    1. docker load -i percept-v1.x.x.tar.gz

  3. To make sure, that the image was loaded correctly, check the Docker image registry contents (the output should be similar to the one shown in the image List of Docker Images below, the "TAG" depends on the Percept version used):

    1. docker images

List of Docker Images
Figure 4. List of Docker Images
Loading the Percept image into the docker registry might take some time

How to start Percept

After setting up Docker on your machine and loading the Percept image into the Docker registry, you are ready to go and use Percept.

The docker-compose file lists all services, exposed ports and mapped folders. It will start the server, frontend and the NTP-server. In Addition, the server will also start an envoy-proxy to allow the communication between the frontend and the server.
Percept will automatically start Docker containers if required, e.g. when you run multiple projects at the same time.
The NTP container is started to provide a possibility to time synchronize the devices via NTP. You may want to remove this part from the docker-compose file, if you have your own NTP server running. You will learn more on when to use time synchronization in later chapters.

Windows

  1. To start Percept you have to open up the Windows Command Line Tool (You can do this by typing in cmd in the window start popup and hit enter).

Open Windows command line tool
Figure 5. How to open the Windows command line tool

  1. Inside the command line tool you have to navigate to the folder you downloaded and extracted Percept using the appropriate command line tool commands (e.g. "cd download" for changing from your user home directory to the download directory, see screenshot).

Start Percept from command line tool
Figure 6. Start Percept from command line tool

  1. Once you are inside the Percept directory type in and execute the following command:

    1. docker-compose up

  2. Windows might ask for permission to share local directories. To make sure Percept runs as intended click on "Share it"

  3. Open a web-browser and access the Percept web interface.

Ubuntu

  1. To start Percept execute the following command inside the Percept directory

    1. docker-compose up

Running an upgraded Percept version

After upgrading Percept to another version, errors might occur when you try to start Percept. This can be resolved by removing stopped containers. Type docker container prune -f in the Command Line Tool and start Percept again.

How to access the Web Interface

  1. To access the Web Interface of Percept open a web-browser and enter

    1. http://localhost/ or http://127.0.0.1:80/ and you should see the Percept start screen as shown in the image below

Percept start screen
Figure 7. Welcome to Percept Web Interface