Potree Auth

Application Overview

The core components of the application are:

1. Project
2. Authenticated project asset server
3. Potree asset server
4. Pre-configured potree rendering template
5. Project dashboard

Project

Groups data and manages access to it. Project metadata is defined in a manifest file.

A project is created by placing a YAML-formatted manifest.yml (note: use .yml, not .yaml) in a subdirectory of the data directory (as specified in the application config).

The subdirectory (project directory) name serves as the project_id and should be URL-safe — kebab-case is recommended.

Project Asset Server

Provides authenticated access to files within a project directory, identified by project_id. Access is granted only to users belonging to at least one of the project's groups.

Assets are served at /project-assets/{project_id}/{*path}.

Potree Asset Server

Serves standard potree assets. No authentication required.

Served at /potree-assets/{*path}.

Potree Rendering Template

A pre-configured Potree HTML template (example) is available. It loads settings from a potree.json5 file in the root of the project directory (project_id).

Access requires the user to belong to at least one of the project groups.

Served at /potree/{project_id}.

To use custom Potree HTML, create it in an index.html file and add it to the project directory. Access it via /project-assets/{project_id}/index.html.

Project dashboard

Displays all the projects that a user has authorization to read.

Served at /projects.

Installation

Rust Binary

If you have Rust installed you can build and install potree-auth natively.

Prerequisites

• Rust

Building

cargo install --path .

Docker

You can also build a Docker container by running the following from the root of the project.

Prerequisites

• Docker

Building

make docker-build

Usage

Data Directory

A directory containing all the project directories should be set up. An example directory structure is shown below.

.
└── data-dir/
    ├── project-1/
    │   ├── manifest.yml
    │   ├── potree.json5
    │   └── point-cloud/
    │       ├── file-one.bin
    │       └── file-two.bin
    └── project-2/
        ├── manifest.yml
        ├── potree.json5
        └── point-cloud/
            ├── file-one.bin
            └── file-two.bin

Configuration

Configuration options can be set via command-line arguments, environment variables, or a mixture of both.

Command-line arguments are most convenient when running the application from the binary. To view available options, run:

potree-auth --help

Each CLI argument has a corresponding environment variable, shown in angle brackets (<>). If the environment variable is set, it overrides the need to specify the CLI argument.

potree-auth also supports a .env file in the current working directory. An example is available here.

For authentication-specific settings, see the Authentication section.

Authentication

Authentication is handled via the OIDC Authorization Code flow, supported by most modern Identity Providers (IdPs). Relevant configuration parameters are prefixed with idp_. If these values are not set, authentication is disabled and all users are granted access to all projects.

Note: Users in the admin group have full access to all projects, even if admin is not explicitly listed in the project metadata.