Roofer

https://innovation.3dbag.nl/roofer/
Admin
Roofer is a software that performs fully automatic LoD2 building reconstruction from point clouds...
Tokens:10,171
Snippets:102
Trust Score:8.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Roofer CLI Examples

Source: https://innovation.3dbag.nl/roofer/cli_application.html

Provides examples of how to run the Roofer CLI with different configurations, including specifying LoD, filtering, and using a configuration file.

```bash
roofer pointcloud.laz footprints.gpkg output-dir
```

```bash
roofer --lod12 --lod22 pointcloud.laz footprints.gpkg output-dir
```

```bash
roofer --filter 'identificatie=1980100000265200' pointcloud.laz footprints.gpkg output-dir
```

```bash
roofer -c config.toml output-dir
```

--------------------------------

### Roofer CLI Example Configuration

Source: https://innovation.3dbag.nl/roofer/cli_application.html

An example TOML configuration file for the Roofer CLI application, demonstrating all available options. Note that command-line arguments take precedence over settings in this file.

```toml
## Path to roofprint polygons source. Can be an OGR supported file (eg. GPKG) or database connection string.
# polygon-source = ""
## Output directory. The building models will be written to a CityJSONSequence file in this directory.
# output-directory = ""

### Input options
## Building ID attribute to be used as identifier in CityJSONSeq output.
# id-attribute = 
## Input attribute (boolean) to force individual buildings to always be reconstructed using simple extrusion (LoD 1.1).
# force-lod11-attribute = 
## Input attribute (integer) containing the building's year of construction. Only relevant when multiple pointclouds are provided.
# yoc-attribute = 
## Input attribute (float) with fallback terrain elevation for each building. Used in case no terrain elevation can be derived from the pointcloud. See also --h-terrain-strategy
# h-terrain-attribute = 
## Input attribute (float) containing fallback roof height for buildings in case no roof height can be derived from the pointcloud.
# h-roof-attribute = 
## Select this layer name from `<polygon-source>`. By default the first layer is used.
# polygon-source-layer = 
## Specify WHERE clause in OGR SQL to select specfic features from `<polygon-source>`. See https://gdal.org/en/stable/user/ogr_sql_dialect.html#where
# filter = 
## Axis aligned bounding box specifying the region of interest. Data outside of this region will be ignored.
# box = [100, 100, 200, 200]
## Manually set or override Spatial Reference System for input data.
# srs = "EPSG:7415"
## LAS classification code that contains the building points.
bld-class = 6
## LAS classification code that constains the ground points.
grnd-class = 2
## Disable/enable check if all supplied pointcloud files exist.
skip-pc-check = false

### Crop options
## Simplify input rootprints to remove (nearly) duplicated vertices.
simplify = true
## Enforce this point density ceiling on each building pointcloud.
ceil-point-density = 20
## Cellsize used for quick pointcloud analysis (eg. point density and nodata regions).
cellsize = 0.5
## Minimum building-class point density (points/m²) below which a rootprint's pointcloud is flagged insufficient.
min-building-density = 1
## Cellsize used for the crop phase terrain fallback grid.
terrain-grid-cellsize = 10
## Number of terrain grid cells to search around a building when its local fallback cells do not contain terrain points.
terrain-grid-search-radius = 3
## LoD 1.1 fallback threshold area in square meters. If the area of the roofprint is larger than this value, the building will be always be reconstructed using a LoD 1.1 extrusion.
lod11-fallback-area = 69000
## Do not attempt to reconstruct buildings with insufficient pointcloud data. If `--h-roof-attribute` is set, an LoD 1.1 extrusion will be performed, otherwise no 3D model will be generated.
clear-insufficient = true
## Compute and output the 98th percentile of pointcloud height for each building.
compute-pc-98p = false
## Only perform the crop phase, do not perform reconstruction,
crop-only = false
## Output building pointclouds from crop phase as LAS files.
crop-output = false
## Output building pointclouds for each pointcloud. Only relevant when multiple pointclouds are provided.Implies `--crop-output`
crop-output-all = false
## Output rasterised pointcloud analytics from crop phase as GeoTIFF files. Implies `--crop-output`
crop-rasters = false
## Output index.gpkg file with quick pointcloud analystics from crop phase.
index = false

```

--------------------------------

### Roofer Installation Path on Windows

Source: https://innovation.3dbag.nl/roofer/getting_started.html

This is an example of a directory path where Roofer might be extracted on Windows. Ensure this 'bin' directory is added to your user PATH.

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

```

--------------------------------

### Install Roofer on Linux/macOS

Source: https://innovation.3dbag.nl/roofer/getting_started.html

Use this script to download and install the latest Roofer release on Linux and macOS systems. It places the executable in ~/.local/bin.

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

```

--------------------------------

### Build Roofer with Conan

Source: https://innovation.3dbag.nl/roofer/developers.html

Use this snippet to build roofer using Conan. Ensure Conan 2 is installed. This configuration builds the Release version, sets C++ standard to 20, and enables building applications, spdlog, but disables val3dity and bindings.

```bash
git clone https://github.com/3DBAG/roofer.git
cd roofer
conan profile detect --force
conan install . \
  --output-folder=build \
  --build=missing \
  --settings=build_type=Release \
  --settings=compiler.cppstd=20 \
  --options="&:build_apps=True" \
  --options="&:use_spdlog=True" \
  --options="&:use_val3dity=False" \
  --options="&:build_bindings=False" \
  --options="&:build_testing=False"
# Conan forwards the package options above to the matching RF_* CMake options.
cmake -S . -B build \
  -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build
# Optionally, install roofer
cmake --install build
```

--------------------------------

### Install Specific Roofer Version on Linux/macOS

Source: https://innovation.3dbag.nl/roofer/getting_started.html

To install a particular version of Roofer, set the ROOFER_VERSION environment variable before running the install script.

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

```

--------------------------------

### Verify Roofer Installation on Windows

Source: https://innovation.3dbag.nl/roofer/getting_started.html

After adding Roofer to your PATH on Windows, open a new terminal and run this command to check if the installation was successful.

```powershell
roofer --version

```

--------------------------------

### Roofer Processing Output Example

Source: https://innovation.3dbag.nl/roofer/getting_started.html

This is an example of the log output you might see when Roofer is processing the test data. It indicates the region of interest, number of footprints, and processing steps.

```log
[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 ...

```

--------------------------------

### Build Documentation with Nix

Source: https://innovation.3dbag.nl/roofer/developers.html

Compile roofer documentation using Nix. This involves setting up the development environment and configuring CMake to build the documentation helper and Python bindings. Applications, spdlog, val3dity, bindings, and testing are disabled.

```bash
nix develop
cmake -S . -B build \
  -G Ninja \
  -DRF_BUILD_APPS=OFF \
  -DRF_USE_LOGGER_SPDLOG=OFF \
  -DRF_USE_VAL3DITY=OFF \
  -DRF_BUILD_BINDINGS=ON \
  -DRF_BUILD_TESTING=OFF \
  -DRF_BUILD_DOC_HELPER=ON \
  -DRF_USE_CPM=OFF
cmake --build build --target rooferpy doc-helper
cmake --install build
cd docs
make html
```

--------------------------------

### Build Roofer with Nix

Source: https://innovation.3dbag.nl/roofer/developers.html

Use this snippet to build roofer with Nix. This is suitable for Linux and macOS. It sets up the development environment and configures the build for Release, enabling spdlog, but disabling apps, val3dity, bindings, and testing.

```bash
git clone https://github.com/3DBAG/roofer.git
cd roofer
nix develop
cmake -S . -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DRF_BUILD_APPS=ON \
  -DRF_USE_LOGGER_SPDLOG=ON \
  -DRF_USE_VAL3DITY=OFF \
  -DRF_BUILD_BINDINGS=OFF \
  -DRF_BUILD_TESTING=OFF \
  -DRF_USE_CPM=OFF
cmake --build build
# Optionally, install roofer
cmake --install build
```

--------------------------------

### Nix Build Outputs

Source: https://innovation.3dbag.nl/roofer/developers.html

This snippet shows how to obtain packaged build outputs using Nix. Use `nix build .#default` for the main package and `nix build .#rooferpy` for the Python bindings.

```bash
nix build .#default
nix build .#rooferpy
```

--------------------------------

### Download and Unzip Test Data

Source: https://innovation.3dbag.nl/roofer/getting_started.html

Download the sample dataset for testing Roofer. This command downloads a zip file and then extracts its contents.

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

```

--------------------------------

### Build Documentation with Conan

Source: https://innovation.3dbag.nl/roofer/developers.html

Compile roofer documentation using Conan. This requires building the documentation helper and Python bindings. The configuration disables applications and spdlog, but enables Python bindings and the documentation helper.

```bash
conan profile detect --force
conan install . \
  --output-folder=build \
  --build=missing \
  --settings=build_type=Release \
  --settings=compiler.cppstd=20 \
  --options="&:build_apps=False" \
  --options="&:use_spdlog=False" \
  --options="&:use_val3dity=False" \
  --options="&:build_bindings=True" \
  --options="&:build_testing=False"
# Conan forwards the package options above to the matching RF_* CMake options.
cmake -S . -B build \
  -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$PWD/install \
  -DRF_BUILD_DOC_HELPER=ON
cmake --build build --target rooferpy doc-helper
cmake --install build
cd docs
make html
```

--------------------------------

### Roofer CLI Usage

Source: https://innovation.3dbag.nl/roofer/cli_application.html

Displays the general usage instructions for the Roofer CLI application, including basic command structure and options.

```bash
Automatic LoD 2.2 building reconstruction from airborne lidar pointclouds

Usage:
  roofer [options] <pointcloud-path>... <polygon-source> <output-directory>
  roofer [options] (-c | --config) <config-file> [(<pointcloud-path>... <polygon-source>)] <output-directory>
  roofer -h | --help
  roofer -H | --help-all
  roofer -a | --attributes
  roofer -v | --version


```

--------------------------------

### Run Roofer with Test Data

Source: https://innovation.3dbag.nl/roofer/getting_started.html

Execute Roofer using the downloaded test dataset. This command processes the input LAS and GPKG files and specifies an output directory.

```bash
roofer wippolder/wippolder.las wippolder/wippolder.gpkg output

```

--------------------------------

### roofer::ReconstructionConfig

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Configuration parameters for the roofer building reconstruction algorithm.

```APIDOC
## ReconstructionConfig

### Description
Configuration parameters for the roofer building reconstruction algorithm. Coordinate units are assumed to be in meters.

### Members
* **complexity_factor** (float) - Complexity factor for building model geometry. A number between `0.0` and `1.0`. Higher values lead to more detailed building models, lower values to simpler models. Defaults to `0.888`.
* **clip_ground** (bool) - Set to true to activate the procedure that clips parts from the input footprint wherever patches of ground points are detected. May cause irregular outlines in reconstruction result. Defaults to `true`.
* **lod** (int) - Requested Level of Detail. `12`: LoD 1.2, `13`: LoD 1.3, `22`: LoD 2.2. Defaults to `22`.
* **lod13_step_height** (float) - Step height used for LoD13 generalisation, i.e. roofparts with a height discontinuity that is smaller than this value are merged. Only affects LoD 1.3 reconstructions. Unit: meters. Defaults to `3.0`.
* **floor_elevation** (float) - Floor elevation in case it is not provided by the footprint (API only). Defaults to `0.0`.
* **override_with_floor_elevation** (bool) - Force flat floor instead of using the elevation of the footprint (API only). Defaults to `false`.
* **plane_detect_k** (int) - Number of points used in nearest neighbour queries during plane detection. Defaults to `15`.
* **plane_detect_min_points** (int) - Minimum number of points required for detecting a plane. Defaults to `15`.
* **plane_detect_epsilon** (float) - Epsilon value for plane detection. Defaults to `0.300000`.
```

--------------------------------

### Add Roofer to PATH on Linux/macOS

Source: https://innovation.3dbag.nl/roofer/getting_started.html

If ~/.local/bin is not on your system's PATH, add this export command to your shell profile to make the 'roofer' command accessible.

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

```

--------------------------------

### Reconstruct Building without Ground Points

Source: https://innovation.3dbag.nl/roofer/api_py.html

Use this overload to reconstruct a building when only roof points are available. Ensure data is translated to the origin to prevent loss of precision.

```python
roofer.reconstruct(_points_roof_ , _footprint_ , _cfg =ReconstructionConfig())
```

--------------------------------

### Reconstruct Building with Roof and Ground Points

Source: https://innovation.3dbag.nl/roofer/api_py.html

Use this function to reconstruct a single building when both roof and ground points are available. Ensure data is translated to the origin to prevent loss of precision.

```python
roofer.reconstruct(_points_roof_ , _points_ground_ , _footprint_ , _cfg =ReconstructionConfig()_)
```

--------------------------------

### roofer::reconstruct (with ground points)

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Reconstructs a single building instance from roof and ground point clouds, along with a footprint and optional configuration.

```APIDOC
## reconstruct (with ground points)

### Description
Reconstructs a single instance of a building from a point cloud.

### Signature
```cpp
template<typename Footprint>
std::vector<Mesh> reconstruct(const PointCollection &points_roof, const PointCollection &points_ground, Footprint &footprint, ReconstructionConfig cfg = ReconstructionConfig())
```

### Parameters
* **points_roof** (PointCollection) - Point cloud representing the roof points
* **points_ground** (PointCollection) - Point cloud representing the ground points
* **footprint** (Footprint) - Footprint of the building. Type can be `LinearRing` or `CGAL::Polygon_with_holes_2<Epick>`.
* **cfg** (ReconstructionConfig) - Configuration parameters for reconstruction. Defaults to `ReconstructionConfig()`.
```

--------------------------------

### Check ReconstructionConfig Validity

Source: https://innovation.3dbag.nl/roofer/api_py.html

Use this method to check if the current `ReconstructionConfig` settings are valid. This is useful before initiating a reconstruction process.

```python
is_valid(_self : roofer.ReconstructionConfig_) -> bool
```

--------------------------------

### roofer.ReconstructionConfig

Source: https://innovation.3dbag.nl/roofer/api_py.html

Configuration object for reconstruction parameters.

```APIDOC
## roofer.ReconstructionConfig

### Description
Configuration object for reconstruction parameters.

### Properties
- **clip_ground** (bool) - Whether to clip ground points.
- **complexity_factor** (float) - Factor controlling reconstruction complexity.
- **floor_elevation** (float) - Elevation of the floor.
- **line_detect_epsilon** (float) - Epsilon for line detection.
- **lod** (int) - Level of detail.
- **lod13_step_height** (float) - Step height for LOD13.
- **override_with_floor_elevation** (bool) - Whether to override with floor elevation.
- **plane_detect_epsilon** (float) - Epsilon for plane detection.
- **plane_detect_k** (float) - K parameter for plane detection.
- **plane_detect_min_points** (int) - Minimum points for plane detection.
- **plane_detect_normal_angle** (float) - Normal angle for plane detection.
- **thres_alpha** (float) - Alpha threshold.
- **thres_reg_line_dist** (float) - Distance threshold for regular lines.
- **thres_reg_line_ext** (float) - Extension threshold for regular lines.

### Methods
#### is_valid
- **is_valid(_self : roofer.ReconstructionConfig_) → bool**
  Checks if the configuration is valid.
```

--------------------------------

### Convert CityJSONSeq to CityJSON

Source: https://innovation.3dbag.nl/roofer/getting_started.html

After Roofer generates a CityJSONSeq file, use 'cjseq collect' to convert it into a standard CityJSON file. This command pipes the output of 'cat' to 'cjseq'.

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

```

--------------------------------

### Reconstruct Building with Ground Points

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Use this function to reconstruct a building mesh when both roof and ground point clouds are available. Ensure data is translated to the origin to prevent precision loss.

```cpp
template<typename Footprint>
std::vector<Mesh> reconstruct(const PointCollection &points_roof, const PointCollection &points_ground, Footprint &footprint, ReconstructionConfig cfg = ReconstructionConfig())
```

--------------------------------

### ReconstructionConfig - Override with Floor Elevation

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Forces a flat floor by overriding the elevation from the footprint. This is an API-only setting.

```cpp
bool override_with_floor_elevation = false
```

--------------------------------

### ReconstructionConfig - Plane Detect Min Points

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Sets the minimum number of points required for detecting a plane during reconstruction.

```cpp
int plane_detect_min_points = 15
```

--------------------------------

### ReconstructionConfig - Plane Detect K

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Specifies the number of points used in nearest neighbor queries for plane detection.

```cpp
int plane_detect_k = 15
```

--------------------------------

### ReconstructionConfig - Floor Elevation

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Sets the floor elevation when it's not provided by the footprint. This is an API-only setting.

```cpp
float floor_elevation = 0.
```

--------------------------------

### roofer::reconstruct (without ground points)

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Reconstructs a single building instance from roof point cloud and footprint, when ground points are not available.

```APIDOC
## reconstruct (without ground points)

### Description
Reconstructs a single instance of a building from a point cloud. Overload for when the ground points are not available.

### Signature
```cpp
template<typename Footprint>
std::vector<Mesh> reconstruct(const PointCollection &points_roof, Footprint &footprint, ReconstructionConfig cfg = ReconstructionConfig())
```

### Parameters
* **points_roof** (PointCollection) - Point cloud representing the roof points
* **footprint** (Footprint) - Footprint of the building. Type can be `LinearRing` or `CGAL::Polygon_with_holes_2<Epick>`.
* **cfg** (ReconstructionConfig) - Configuration parameters for reconstruction. Defaults to `ReconstructionConfig()`.

### Returns
std::vector<Mesh> Building geometry meshes. The number of meshes is equal to the number of building parts. This number is equal to one if no ground points are available.
```

--------------------------------

### roofer::triangulate_mesh

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Triangulates a given mesh using the legacy mesh triangulator.

```APIDOC
## triangulate_mesh

### Description
Triangulates a mesh using `roofer::reconstruction::MeshTriangulatorLegacy`.

### Signature
```cpp
TriangleCollection triangulate_mesh(const Mesh &mesh)
```

### Parameters
* **mesh** (Mesh) - Mesh to triangulate.

### Returns
TriangleCollection Triangulated mesh.
```

--------------------------------

### ReconstructionConfig - LoD13 Step Height

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Defines the step height for LoD13 generalization. Roof parts with height discontinuities smaller than this value are merged. Units are in meters.

```cpp
float lod13_step_height = 3.
```

--------------------------------

### roofer.reconstruct

Source: https://innovation.3dbag.nl/roofer/api_py.html

Reconstructs a single building model from point cloud data and a footprint polygon. It can optionally use ground points.

```APIDOC
## roofer.reconstruct

### Description
Reconstruct a single building. The first overload uses both roof and ground points. The second overload reconstructs without ground points.

### Method
`reconstruct(_points_roof_, _points_ground_, _footprint_, _cfg = ReconstructionConfig()_)`
`reconstruct(_points_roof_, _footprint_, _cfg = ReconstructionConfig()_)

### Parameters
#### Path Parameters
- **points_roof** (PointCloud) - Required - Building or roof points.
- **points_ground** (PointCloud) - Optional - Ground points.
- **footprint** (Footprint) - Required - Building footprint.
- **cfg** (ReconstructionConfig) - Optional - Reconstruction parameters.

### Returns
#### Success Response
- **meshes** (list[Mesh]) - Reconstructed meshes.

### Return Type
list[Mesh]
```

--------------------------------

### ReconstructionConfig - Level of Detail (LoD)

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Specifies the requested Level of Detail for the reconstruction. Common values include 1.2, 1.3, and 2.2.

```cpp
int lod = 22
```

--------------------------------

### Reconstruct Building without Ground Points

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

This overload reconstructs a building mesh using only roof points when ground points are unavailable. The resulting mesh count is typically one.

```cpp
template<typename Footprint>
std::vector<Mesh> reconstruct(const PointCollection &points_roof, Footprint &footprint, ReconstructionConfig cfg = ReconstructionConfig())
```

--------------------------------

### roofer.triangulate_mesh

Source: https://innovation.3dbag.nl/roofer/api_py.html

Triangulates a given mesh into vertices and faces.

```APIDOC
## roofer.triangulate_mesh

### Description
Triangulate a mesh.

### Method
`triangulate_mesh(_mesh_)`

### Parameters
#### Path Parameters
- **mesh** (Mesh) - Required - Mesh to triangulate.

### Returns
#### Success Response
- **vertices** (list[Point]) - List of points.
- **faces** (list[list[int]]) - List of three vertex indices.

### Return Type
tuple[list[Point], list[list[int]]]
```

--------------------------------

### ReconstructionConfig - Clip Ground

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Enables or disables the clipping of footprint parts where ground points are detected. Setting this to true may result in irregular outlines.

```cpp
bool clip_ground = true
```

--------------------------------

### Triangulate Mesh

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Triangulates a given mesh using the legacy mesh triangulator. This is useful for preparing meshes for further processing or rendering.

```cpp
TriangleCollection triangulate_mesh(const Mesh &mesh)
```

--------------------------------

### Triangulate Mesh

Source: https://innovation.3dbag.nl/roofer/api_py.html

This function triangulates a given mesh. It returns the vertices and faces of the triangulated mesh.

```python
roofer.triangulate_mesh(_mesh_)
```

--------------------------------

### ReconstructionConfig - Complexity Factor

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Sets the complexity factor for building model geometry. Values range from 0.0 to 1.0, influencing the level of detail in the reconstruction.

```cpp
float complexity_factor = 0.888
```

--------------------------------

### ReconstructionConfig - Plane Detect Epsilon

Source: https://innovation.3dbag.nl/roofer/api_cpp.html

Defines the epsilon value used for plane detection, likely related to the tolerance for point-to-plane distance.

```cpp
float plane_detect_epsilon = 0.300000
```
Tokens:
Raw