PotreeConverter: turning a scan into a point cloud a browser can stream

A scan is not a point cloud you can stream

The About section states the job in one line: PotreeConverter generates an octree LOD structure for streaming and real-time rendering of massive point clouds.

That phrase carries the whole reason the tool exists. A lidar scan is a flat list of points with attributes, and a modern scan can hold billions of them. A browser cannot load that as one file, and it certainly cannot keep it all in memory, so the data has to be turned into a spatial hierarchy where any view of the scene only needs the level of detail that is visible at that distance.

That hierarchy is the octree, and the level of detail structure is what the converter produces. The result is a directory of files that a viewer streams progressively as the camera moves, and the output can be viewed in web browsers with Potree or as a desktop application with PotreeDesktop.

The audience is therefore a team with survey data, whether from a drone, a terrestrial scanner or a mobile mapping system, who needs to look at it in a browser or on a workstation rather than in the scanner's own software. The related publications are the Potree thesis from TU Wien in 2016 and the 2020 Computer Graphics Forum paper Fast Out-of-Core Octree Generation for Massive Point Clouds by Schütz, Ohrhallinger and Wimmer, which is the out-of-core generation work behind the current converter.

The project is BSD-2-Clause licensed, the last push to the repository was on 2026-09-23, and the recent releases are 2.1.5 on 2026-09-23, 2.1.4 on 2026-09-22 and 2.1.3 on 2026-06-22. The default branch is develop, and the primary language recorded for the repository is JavaScript, which reflects the viewer side of the ecosystem rather than the converter's own implementation.

Version 2.0 turned millions of files into three

Version 2.0 is described as a complete rewrite, and the README lists the differences from 1.7 in four bullets. Two of them are the reason to move.

The first is speed. It is about 10 to 50 times faster than PotreeConverter 1.7 on SSDs. The qualification matters, since the figure is tied to solid state storage, and the README includes a performance comparison chart measured on a Ryzen 2700 with an NVMe SSD.

The second is the file count. Version 2.0 produces a total of 3 files instead of thousands to tens of millions of files, and the README explains why that matters: the reduction in the number of files improves file system operations such as copy, delete and upload to servers from hours and days to seconds and minutes.

That is a bigger deal than it first appears. A one-to-one file per node output is workable on a laptop with a fast disk and painful everywhere else, and the case that hurts most is the upload. A scan that takes days to copy to a server is a scan nobody copies, and a converter whose output cannot be moved is a converter that constrains your whole pipeline.

The third bullet is about attributes: better support for standard LAS attributes and arbitrary extra attributes, with full support such as int64 and uint64 in development. The fourth is a gap rather than a feature: optional compression is not yet available in the new converter but is on the roadmap for a future update.

That last point is the one to check first, because the alternative table in the README shows the previous converter and Entwine both producing LAZ output while 2.0 produces none.

The output format is the contract with Potree

A converter is only useful if something can read its output, and the README is explicit about the compatibility situation.

Although the converter made a major step to version 2.0, the format it produces is also supported by Potree 1.7. That means the new file layout does not force you to upgrade the viewer, which is a genuinely useful property when your viewer is deployed on machines you do not control.

The README also says the Potree viewer is scheduled to make the major step to version 2.0 in 2021, with a rewrite in WebGPU. That sentence is dated, since the current converter releases are in the 2.1 line in 2026, and it is worth treating the viewer's own release notes as the authority on where that schedule ended up rather than this paragraph.

The loading side is short. In Potree you call loadPointCloud with the URL of the metadata.json produced by the converter, and the promise resolves to the point cloud, from which you take the material.

let url = "../pointclouds/D/temp/test/metadata.json";
Potree.loadPointCloud(url).then(e => {
	let pointcloud = e.pointcloud;
	let material = pointcloud.material;

	material.activeAttributeName = "rgba";
	material.minSize = 2;
	material.pointSizeType = Potree.PointSizeType.ADAPTIVE;

	viewer.scene.addPointCloud(pointcloud);
	viewer.fitToScreen();
});

The material settings are the part people iterate on. Setting the active attribute to rgba picks the colour channel to display, minSize sets the smallest point size, and the ADAPTIVE point size type scales the points with distance, which is what makes a streamed cloud look right at every zoom level rather than as a cloud of uniform dots.

Building from source is CMake, and Windows has a prebuilt binary

The getting started section offers Windows binaries or a source build, and the source build is a conventional CMake project.

You need CMake 3.16 or later, then you create a build directory, change into it and run cmake against the parent directory.

mkdir build
cd build
cmake ../

On Linux you then run make, and on Windows you open the Visual Studio 2019 project at ./Converter/Converter.sln and compile it in release mode.

The release mode instruction is not incidental. The converter is a batch tool that processes a whole scan in one pass, and a debug build of the same code is dramatically slower, so the difference between the two builds is the difference between a conversion that takes an afternoon and one that takes a week.

The repository layout is consistent with that: a Converter directory holding the C++ project and its solution file, a CMakeLists.txt at the root, a resources directory for the data the converter needs at runtime, a testing directory, a tools directory, and docs for the images and charts the README uses.

Running it takes an input path and an output directory.

PotreeConverter.exe <input> -o <outputDir>

The input is the point cloud you have, in a format the converter reads, and the output directory is where the three files and the hierarchy go. The output is then served to the viewer as static files, which is why the web deployment story is simple.

Poisson-disk or random sampling, and why it matters

The run command takes an optional sampling strategy, and the two options are described in a single line each.

PotreeConverter.exe <input> -o <outputDir> -m poisson

Poisson-disk sampling is the default, and random sampling is the alternative with -m random.

The distinction is about how points are selected when the input has more points than the output needs, and it is not a cosmetic difference. Poisson-disk sampling produces a distribution with roughly even spacing, which is what you want for a rendered point cloud, because neighbouring points do not clump and the surface does not look patchy. Random selection leaves clumps and holes, and clumps are visible in the render, particularly at lower levels of detail where fewer points are drawn.

So the practical guidance is to leave the default alone unless you have a reason, and the reason to reach for random is a case where you are converting a very large input and the sampling cost dominates. That is a trade of visual quality for time, which is a decision you should make deliberately rather than by accident.

One point about the pipeline is worth stating plainly. The converter does not preserve every point from the input, it selects from them. That is what makes an octree LOD structure possible at all, since a level of detail structure is by definition a subsample, but it also means the density of your output depends on the sampling strategy and on the source data, and a sparse survey will look sparse in the viewer.

The alternatives table is the honest comparison

The README does something that most tool READMEs avoid. It includes a table comparing PotreeConverter 2.0 with PotreeConverter 1.7 and with Entwine, and it lists the differences that might make you choose something else.

On licence, all three are free, with 2.0 and 1.7 under BSD 2-clause and Entwine under LGPL.

On the number of generated files, 2.0 produces 3 files in total, while 1.7 and Entwine produce 1 per node.

On compression, 2.0 produces none, which the table marks as a to-do, while 1.7 offers LAZ optionally and Entwine produces LAZ.

That third row is the one that should decide the question for some teams. If your constraint is upload bandwidth or storage, the newer converter's three file output is a decisive win. If your constraint is disk footprint, the older converter and Entwine win, because LAZ is a compressed format and 2.0 writes uncompressed data.

The README frames the table as a fallback rather than a recommendation: if you find issues, you can still try previous converters or alternatives.

Entwine is worth a moment of attention because it is the same lineage, a streaming point cloud format used by the Potree ecosystem, and the LGPL licence makes it a materially different proposition for an organisation with a licence review process.

Editorial conclusion

PotreeConverter suits a team holding a large terrestrial or drone scan and needing it in a web viewer, because the converter produces the octree structure that Potree streams and the three file output makes copying, uploading and versioning a large dataset practical. It does not suit a pipeline that needs LAZ or other compression today, since the README lists compression as not yet available in the 2.x converter, and it does not suit someone who needs to read a specific scanner format natively. Before you convert, check that the input attributes you need survive the conversion, since the README notes better support for standard LAS attributes and arbitrary extra attributes with full int64 and uint64 support still in development, and note the release cadence, with 2.1.4 and 2.1.5 published on consecutive days in September 2026.

Frequently asked questions

Official sources

1. License: BSD-2-Clause
2. potree/PotreeConverter on GitHub
3. Project website
4. README
5. Releases