Getting started

Installation

The easiest way to get roofer is to download the latest binary from GitHub Releases. Alternatively, you can use the Docker image or build roofer from source.

Linux and macOS

On Linux and macOS, you can use the install script:

curl -fsSL https://raw.githubusercontent.com/3DBAG/roofer/refs/heads/main/distribution/install.sh | sh

The script downloads the matching release archive, installs the bundle to ~/.local/share/roofer, and installs a roofer launcher to ~/.local/bin/roofer.

If ~/.local/bin is not yet on your PATH, add it to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

To install a specific version, set ROOFER_VERSION:

curl -fsSL https://raw.githubusercontent.com/3DBAG/roofer/refs/heads/main/distribution/install.sh | ROOFER_VERSION=1.0.0 sh

Windows

On Windows, download the roofer-windows-x86_64-v<version>.zip asset from GitHub Releases, extract it, and add the extracted bin directory to your user PATH.

For example, after extracting the archive to C:\Users\<you>\AppData\Local\Programs\roofer, add this directory to your user PATH:

C:\Users\<you>\AppData\Local\Programs\roofer\bin

Then open a new terminal and check the installation:

roofer --version

Running roofer

To test if roofer is correctly installed you can try to run it with our small test dataset. To download this data you can do:

curl -LO https://data.3dbag.nl/testdata/roofer/wippolder.zip
unzip wippolder.zip

Then, assuming you have installed roofer, you can run with the test dataset as follows:

roofer wippolder/wippolder.las wippolder/wippolder.gpkg output

This should give an output like:

[2025-05-28 10:53:32.420651]    INFO    Region of interest: 85289.898 447042.018, 85466.683 447163.476
[2025-05-28 10:53:32.420827]    INFO    Number of source footprints: 60
[2025-05-28 10:53:32.421427]    INFO    Using 5 threads for the reconstructor pool, 10 threads in total (system offers 10)
[2025-05-28 10:53:32.421755]    INFO    [serializer] Writing output to output
[2025-05-28 10:53:32.424692]    INFO    Simplifying and buffering footprints...
[2025-05-28 10:53:32.428223]    INFO    Cropping pointcloud ...
[2025-05-28 10:53:32.551549]    INFO    Analysing pointcloud ...

And an output file 085289_447042.city.jsonl should have been produced in the output folder. This is a CityJSONSeq file. You can convert it to a regular CityJSON file using cjseq, eg:

cat output/085289_447042.city.jsonl.city.jsonl | cjseq collect > output/085289_447042.city.json

The resulting CityJSON file you can inspect in ninja or another CityJSON compatible software.

To learn more about roofer’s various configuration check out the roofer CLI documentation.