PotreeConverter Python Wrapper

A Python wrapper for PotreeConverter that provides a clean CLI interface using Pydantic for parameter validation. This wrapper makes it easy to convert LAS/LAZ point cloud files into Potree's octree format for web-based visualization.

About PotreeConverter

PotreeConverter generates an octree LOD structure for streaming and real-time rendering of massive point clouds. The results can be viewed in web browsers with Potree.

Original Repository: https://github.com/potree/PotreeConverter

Features

• ✅ Core PotreeConverter parameters exposed - Conversion, sampling, encoding, attributes, and page generation
• ✅ Type-safe parameter validation - Using Pydantic for robust input validation
• ✅ Multiple parameter aliases - Supports both Python-style (--output_dir) and CLI-style (--output-dir) naming
• ✅ Slim Docker image - ~200-250MB using Python 3.11-slim base
• ✅ Pre-built binary - Uses official PotreeConverter 2.1.1 release from GitHub
• ✅ Multi-attribute special coloring - Adds optional neighbor-aware coloring dimensions while preserving source RGB
• ✅ Comprehensive logging - Detailed execution logs with timestamps

Quick Start

Build the Docker Image

docker build -t 3dtrees_potree .

Basic Usage

Convert a single LAS/LAZ file:

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input.las \
  --outdir /data/output

Convert all files in a directory:

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input_dir \
  --outdir /data/output

Available Parameters

Parameter	Alias	Type	Default	Description
--source	-i	List[str]	required	Input file(s) or directory containing LAS/LAZ files
--outdir	-o	Path	auto-generated	Output directory
--encoding		str	BROTLI	Encoding type: BROTLI, UNCOMPRESSED, DEFAULT
--method	-m	str	poisson	Sampling method: poisson, poisson_average, random
--chunk-method		str	LASZIP	Chunking method
--attributes		List[str]	[]	Attributes in output file
--special-coloring		bool	False	Add instance-based coloring dimensions before conversion
--special-coloring-palette		str	candy	Palette name or comma-separated #RRGGBB colors for special coloring
--special-coloring-n-colors		int	10	Number of non-ground coloring IDs
--special-coloring-n-neighbors		int	10	Number of nearest instance centroids used to avoid nearby color collisions
--special-coloring-instance-attributes		List[str]	PredInstance_SAT, PredInstance_FoMa	Instance attributes to color; comma-separated or repeated values are supported
--special-coloring-instance-attribute		str	None	Backward-compatible single instance attribute override
--special-coloring-ground-id		int	0	Instance ID treated as ground/background; negative instance IDs are also treated as background
--special-coloring-ground-color		str	#808080	Ground/background color
--special-coloring-sidecar-json		bool	False	Write special_coloring_mapping.json and patch generated Potree HTML viewers to use it
--keep-chunks		bool	False	Skip deleting temporary chunks
--no-chunking		bool	False	Disable chunking phase
--no-indexing		bool	False	Disable indexing phase
--generate-page	-p	str	None	Generate web page with given name
--title		str	None	Page title for generated web page

Usage Examples

With Custom Sampling Method

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input.las \
  --outdir /data/output \
  --method poisson_average

With BROTLI Compression

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input.las \
  --outdir /data/output \
  --encoding BROTLI

Multiple Input Files

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/file1.las /data/file2.las /data/file3.las \
  --outdir /data/output

Generate Web Viewer Page

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input.las \
  --outdir /data/output \
  --generate-page mycloud \
  --title "My Point Cloud Visualization"

Advanced: Custom Attributes and Flags

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input.las \
  --outdir /data/output \
  --method random \
  --encoding BROTLI \
  --attributes intensity classification \
  --keep-chunks

With Special Instance Coloring

Preserve original RGB while adding display-only coloring attributes based on instance extra dimensions. By default, --special-coloring reads PredInstance_SAT and PredInstance_FoMa. Bare PredInstance and PredInstance_SAT produce coloring_id_sat. If the input uses PredInstance_FM, it is accepted as the FoMa alias and produces coloring_id_fm.

docker run --rm --cpus=10 --memory=50g -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input_segmented.laz \
  --outdir /data/output \
  --special-coloring \
  --special-coloring-sidecar-json

Custom attributes may be repeated or comma-separated:

docker run --rm -v /path/to/data:/data 3dtrees_potree \
  python /src/run.py \
  --source /data/input_segmented.laz \
  --outdir /data/output \
  --special-coloring \
  --special-coloring-instance-attributes PredInstance_SAT,PredInstance_FM

This adds one coloring dimension per requested instance attribute to the generated Potree point cloud. When --special-coloring-sidecar-json is set, the tool writes mapping JSON files to the output directory, copies them beside generated metadata.json files for frontend discovery, and patches generated Potree HTML viewers to use the first sidecar color mapping. Instance values equal to the ground ID, and negative instance values such as -1, map to coloring ID 0.

Built-in special coloring palettes are sky, sea, cozy, fairy, winter, rainbow, pastel, candy, and boring.

View Help

docker run --rm 3dtrees_potree python /src/run.py --help

Project Structure

.
├── Dockerfile              # Docker image definition
├── src/
│   ├── parameters.py       # Pydantic parameter definitions
│   ├── run.py              # Main execution script
│   └── special_coloring.py # Instance coloring preprocessing
├── tests/                  # Unit tests for wrapper logic
└── README.md              # This file

How It Works

1. parameters.py - Defines all PotreeConverter parameters using Pydantic's BaseSettings class with CLI argument parsing
2. run.py - Parses CLI arguments, builds the PotreeConverter command, and executes it via subprocess
3. Dockerfile - Creates a slim image with Python 3.11, PotreeConverter binary, and Python dependencies. The image intentionally leaves entrypoint control to callers so Galaxy can launch its generated shell script.

Performance

Tested with: 1.6M points, 10.5 MB LAZ file
Conversion time: ~5 seconds
Throughput: ~0.3M points/second
Memory usage: ~8GB peak

Performance scales with input size and available CPU cores (automatically uses all available threads).

Output Format

PotreeConverter 2.0 produces:

• 3 files total (instead of thousands in v1.7)
• Octree LOD structure for efficient streaming
• Compatible with Potree 1.7+ viewer
• Optional web page with embedded viewer

With --special-coloring-sidecar-json, the output directory also contains:

• special_coloring_mapping.json*: Mapping from coloring IDs to RGB/hex colors and from each instance attribute to its coloring IDs

Requirements

• Docker
• Input: LAS/LAZ point cloud files
• Sufficient disk space for output (typically similar to input size)

License

This wrapper is provided as-is. PotreeConverter itself is licensed under the BSD 2-clause license.

References

• PotreeConverter: https://github.com/potree/PotreeConverter
• Potree Viewer: https://github.com/potree/potree
• Paper: Fast Out-of-Core Octree Generation for Massive Point Clouds

Troubleshooting

Permission Issues

Ensure the mounted volume has proper permissions:

chmod -R 755 /path/to/data

Out of Memory

For very large point clouds, ensure Docker has sufficient memory allocated (8GB+ recommended).

File Not Found

Make sure to use absolute paths and verify the file exists in the mounted volume:

ls -la /path/to/data/