Roofer CLI App

roofer is a command line application for generating LoD 1.2, LoD 1.3 and LoD 2.2 building models from pointclouds in the CityJSONSeq format.

With the roofer CLI application you can:

• Generate 3D building models for large areas with a reasonably small memory footprint. This is achieved by processing the input data in square tiles. No pre-tiling is needed.

• Benefit from multi-threading for faster processing.

• Read common vector input sources and filter them based on attributes or spatial extent. This means you do not need to crop the input data beforehand.

• Obtain detailed information per building object about the reconstruction process and the quality of the generated models and the input point cloud.

Usage

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 -a | --attributes
  roofer -v | --version

Positional arguments

<pointcloud-path>

Path to pointcloud file (.LAS or .LAZ) or folder that contains pointcloud files.

<polygon-source>

Path to roofprint polygon source. Can be an OGR supported file (eg. GPKG) or database connection string.

<output-directory>

Output directory. The building models will be written to a CityJSONSequence file in this directory.

General options

-h, --help  (default: false)

Show help message

-a, --attributes  (default: false)

List output attributes

-v, --version  (default: false)

Show version

-j, --jobs <int> (default: 0)

Number of threads to use

-c, --config <string> (default: <no value>)

Configuration file

--trace-interval <int> (default: 10)

Interval for tracing in seconds

--loglevel (trace|debug|info) (default: info)

Specify loglevel

Input options

--id-attribute <string> (default: <no value>)

Building ID attribute to be used as identifier in CityJSONSeq output.

--force-lod11-attribute <string> (default: <no value>)

Input attribute (boolean) to force individual buildings to always be reconstructed using simple extrusion (LoD 1.1).

--yoc-attribute <string> (default: <no value>)

Input attribute (integer) containing the building’s year of construction. Only relevant when multiple pointclouds are provided.

--h-terrain-attribute <string> (default: <no value>)

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-roof-attribute <string> (default: <no value>)

Input attribute (float) containing fallback roof height for buildings in case no roof height can be derived from the pointcloud.

--polygon-source-layer <string> (default: <no value>)

Select this layer name from <polygon-source>. By default the first layer is used.

--filter <string> (default: <no value>)

Specify WHERE clause in OGR SQL to select specfic features from <polygon-source>.

--box (xmin ymin xmax ymax) (default: <no value>)

Axis aligned bounding box specifying the region of interest. Data outside of this region will be ignored.

--srs <string> (default: <no value>)

Manually set or override Spatial Reference System for input data.

--bld-class <int> (default: 6)

LAS classification code that contains the building points.

--grnd-class <int> (default: 2)

LAS classification code that constains the ground points.

--[no-]skip-pc-check  (default: false)

Disable/enable check if all supplied pointcloud files exist.

Crop options

--ceil-point-density <float> (default: 20)

Enforce this point density ceiling on each building pointcloud.

--cellsize <float> (default: 0.5)

Cellsize used for quick pointcloud analysis (eg. point density and nodata regions).

--lod11-fallback-area <int> (default: 69000)

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.

--[no-]clear-insufficient  (default: true)

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.

--[no-]compute-pc-98p  (default: false)

Compute and output the 98th percentile of pointcloud height for each building.

--[no-]crop-only  (default: false)

Only perform the crop phase, do not perform reconstruction,

--[no-]crop-output  (default: false)

Output building pointclouds from crop phase as LAS files.

--[no-]crop-output-all  (default: false)

Output building pointclouds for each pointcloud. Only relevant when multiple pointclouds are provided.Implies --crop-output

--[no-]crop-rasters  (default: false)

Output rasterised pointcloud analytics from crop phase as GeoTIFF files. Implies --crop-output

--[no-]index  (default: false)

Output index.gpkg file with quick pointcloud analystics from crop phase.

Reconstruction options

--[no-]lod12  (default: false)

Generate LoD 1.2 geometries in CityJSONSeq output.

--[no-]lod13  (default: false)

Generate LoD 1.3 geometries in CityJSONSeq output.

--[no-]lod22  (default: true)

Generate LoD 2.2 geometries in CityJSONSeq output.

--complexity-factor <float> (default: 0.888)

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.

--[no-]clip-terrain  (default: true)

Set to true to activate the procedure that clips parts from the input roofprint wherever patches of ground points are detected.May cause irregular outlines in reconstruction result.

--lod13-step-height <float> (default: 3)

Step height in meters, used for LoD 1.3 generalisation.Adjacent roofparts with a height discontinuity that is smaller than this value are merged. Only affects LoD 1.3 geometry.

--plane-detect-k <int> (default: 15)

Number of points used in nearest neighbour queries for plane detection. Higher values will lead to longer processing times, but may help with growing plane regions through areas with a poor point distribution.

--plane-detect-min-points <int> (default: 15)

Minimum number of points required for detecting a plane in the pointcloud.

--plane-detect-epsilon <float> (default: 0.3)

Maximum distance (in meters) from inliers to plane during plane fitting procedure. Higher values offer more robustness against oversegmentation, but may result in less accurate plane detection.

--h-terrain-strategy (buffer_tile|buffer_user|user) (default: buffer_tile)

Strategy to determine terrain elevation that is used to set the height of building floors. buffer_tile: use the 5th percentile lowest elevation point in a 3 meter buffer around the roofprint. If no points are found, we fall back to the lowest elevation point in the current tile. This may give undesired results for hilly areas. buffer_user: same as buffer_tile, but with now with a fallback to the elevation provided via --h-terrain-attribute. user: always use the elevation provided via --h-terrain-attribute.

--lod11-fallback-planes <int> (default: 900)

Number of planes required for LoD 1.1 fallback. When more than this number of planes is detected, abort the reconstruction process and fallback to LoD 1.1 extrusion. Primarily used to limit the reconstruction time per building.

--lod11-fallback-time <int> (default: 1800000)

Time for LOD 1.1 fallback in milliseconds. When more than this time is spent on expensive parts of the reconstruction algorithm, abort and fallback to LoD 1.1 extrusion.

Output options

--[no-]tiling  (default: false)

Enable or disable output tiling.

--tilesize (x y) (default: [1000,1000])

Tilesize for rectangular output tiles in meters.

--[no-]split-cjseq  (default: false)

Output CityJSONSequence file for each building instead of one file per tile.

--[no-]omit-metadata  (default: false)

Omit metadata line in CityJSONSequence output.

--cj-scale (x y z) (default: [0.001,0.001,0.001])

Scaling applied to CityJSON output vertices

--cj-translate (x y z) (default: <no value>)

Translation applied to CityJSON output vertices. Uses dataset center by default.

--attribute-rename key=value[,...] (default: azimuth=rf_azimuth,extrusion_mode=rf_extrusion_mode,force_lod11=rf_force_lod11,h_ground=rf_h_ground,h_pc_98p=rf_h_pc_98p,h_roof_50p=rf_h_roof_50p,h_roof_70p=rf_h_roof_70p,h_roof_max=rf_h_roof_max,h_roof_min=rf_h_roof_min,h_roof_ridge=rf_h_roof_ridge,is_glass_roof=rf_is_glass_roof,is_mutated=rf_is_mutated,nodata_frac=rf_nodata_frac,nodata_r=rf_nodata_r,pc_select=rf_pc_select,pc_source=rf_pc_source,pc_year=rf_pc_year,pointcloud_unusable=rf_pointcloud_unusable,pt_density=rf_pt_density,reconstruction_time=rf_t_run,rmse_lod12=rf_rmse_lod12,rmse_lod13=rf_rmse_lod13,rmse_lod22=rf_rmse_lod22,roof_n_planes=rf_roof_planes,roof_n_ridgelines=rf_ridgelines,roof_type=rf_roof_type,slope=rf_slope,success=rf_success,val3dity_lod12=rf_val3dity_lod12,val3dity_lod13=rf_val3dity_lod13,val3dity_lod22=rf_val3dity_lod22,volume_lod12=rf_volume_lod12,volume_lod13=rf_volume_lod13,volume_lod22=rf_volume_lod22)

Rename output attributes. If no value is provided, the attribute will not be written. See the list of available attributes with --attributes. By default attribute names are prefixed with rf_.

Output format

The output of the roofer CLI application are CityJSONSequence files. These are a JSON Lines files that contain a sequence of CityJSON features, each feature represents all the information for one building.

Tip

In the near future we expect to introduce a converter program to convert the CityJSONSequence files to other formats like GPKG, OBJ and others.

Output attributes

azimuth (default name: rf_azimuth)

The azimuth of a roofpart in degrees

extrusion_mode (default name: rf_extrusion_mode)

Indicates what extrusion mode was used for the building. standard: the regular LoD 1.2, 1.3 or 2.2 extrusion. lod11_fallback: all geometry was substituted with an LoD 1.1 extrusion. skip: no 3D geometry was generated

force_lod11 (default name: rf_force_lod11)

Indicates if LoD 1.1 extrusion was forced for the building

h_ground (default name: rf_h_ground)

The elevation of the floor of the building

h_pc_98p (default name: rf_h_pc_98p)

The 98th percentile elevation of the building pointcloud

h_roof_50p (default name: rf_h_roof_50p)

The 50th percentile roof elevation

h_roof_70p (default name: rf_h_roof_70p)

The 70th percentile roof elevation

h_roof_max (default name: rf_h_roof_max)

The maximum roof elevation

h_roof_min (default name: rf_h_roof_min)

The minimum roof elevation

h_roof_ridge (default name: rf_h_roof_ridge)

The main ridge elevation

is_glass_roof (default name: rf_is_glass_roof)

Indicates if a glass roof was detected

is_mutated (default name: rf_is_mutated)

Indicates if the building was mutated between multiple input pointclouds (if multiple input pointclouds were provided)

nodata_frac (default name: rf_nodata_frac)

Indicates fraction (in the range [0,1]) of the roofprint area that is not covered by pointcloud data

nodata_r (default name: rf_nodata_r)

Indicates the radius of the largest circle in the roofprint that is not covered by pointcloud data

pc_select (default name: rf_pc_select)

Indicates why the input pointcloud was selected for reconstruction. Only relevant if multiple input pointclouds were provided

pc_source (default name: rf_pc_source)

Indicates which input pointcloud was used for reconstruction

pc_year (default name: rf_pc_year)

Indicates the acquisition year of the selected input pointcloud

pointcloud_unusable (default name: rf_pointcloud_unusable)

Indicates if the pointcloud was found to be insufficient for reconstruction

pt_density (default name: rf_pt_density)

Indicates the point density inside the roofprint

reconstruction_time (default name: rf_t_run)

Reconstruction time in milliseconds

rmse_lod12 (default name: rf_rmse_lod12)

The Root Mean Square Erorr of the LOD12 geometry

rmse_lod13 (default name: rf_rmse_lod13)

The Root Mean Square Erorr of the LOD13 geometry

rmse_lod22 (default name: rf_rmse_lod22)

The Root Mean Square Erorr of the LOD22 geometry

roof_n_planes (default name: rf_roof_planes)

The number of roofplanes detected in the pointcloud (could be different from the generated mesh model)

roof_n_ridgelines (default name: rf_ridgelines)

The number of ridgelines detected in the pointcloud (could be different from the generated mesh model)

roof_type (default name: rf_roof_type)

Roof type. Can be no points, no planes, horizontal, multiple horizontal, or slanted

slope (default name: rf_slope)

The slope of a roofpart in degrees

success (default name: rf_success)

Indicates if processing completed without unexpected errors

val3dity_lod12 (default name: rf_val3dity_lod12)

Lists val3dity codes for LoD 1.2 geometry

val3dity_lod13 (default name: rf_val3dity_lod13)

Lists val3dity codes for LoD 1.3 geometry

val3dity_lod22 (default name: rf_val3dity_lod22)

Lists val3dity codes for LoD 2.2 geometry

volume_lod12 (default name: rf_volume_lod12)

The volume in cubic meters of the LoD 1.2 geometry

volume_lod13 (default name: rf_volume_lod13)

The volume in cubic meters of the LoD 1.3 geometry

volume_lod22 (default name: rf_volume_lod22)

The volume in cubic meters of the LoD 2.2 geometry

Example config file

Below is an example of a TOML configuration file for the roofer CLI application. It shows all the available options. Noticed that these options are also available as command line arguments, in case one option is provided both in the configuration file and as a command line argument, the command line argument takes precedence.

## 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>`.
# 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
## 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
## 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

### Reconstruction options
## Generate LoD 1.2 geometries in CityJSONSeq output.
lod12 = false
## Generate LoD 1.3 geometries in CityJSONSeq output.
lod13 = false
## Generate LoD 2.2 geometries in CityJSONSeq output.
lod22 = true
## 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.
complexity-factor = 0.888
## Set to true to activate the procedure that clips parts from the input roofprint wherever patches of ground points are detected.May cause irregular outlines in reconstruction result.
clip-terrain = true
## Step height in meters, used for LoD 1.3 generalisation.Adjacent roofparts with a height discontinuity that is smaller than this value are merged. Only affects LoD 1.3 geometry.
lod13-step-height = 3
## Number of points used in nearest neighbour queries for plane detection. Higher values will lead to longer processing times, but may help with growing plane regions through areas with a poor point distribution.
plane-detect-k = 15
## Minimum number of points required for detecting a plane in the pointcloud.
plane-detect-min-points = 15
## Maximum distance (in meters) from inliers to plane during plane fitting procedure. Higher values offer more robustness against oversegmentation, but may result in less accurate plane detection.
plane-detect-epsilon = 0.3
## Strategy to determine terrain elevation that is used to set the height of building floors. `buffer_tile`: use the 5th percentile lowest elevation point in a 3 meter buffer around the roofprint. If no points are found, we fall back to the lowest elevation point in the current tile. This may give undesired results for hilly areas. `buffer_user`: same as `buffer_tile`, but with now with a fallback to the elevation provided via `--h-terrain-attribute`. `user`: always use the elevation provided via `--h-terrain-attribute`.
# h-terrain-strategy = "buffer_tile"
## Number of planes required for LoD 1.1 fallback. When more than this number of planes is detected, abort the reconstruction process and fallback to LoD 1.1 extrusion. Primarily used to limit the reconstruction time per building.
lod11-fallback-planes = 900
## Time for LOD 1.1 fallback in milliseconds. When more than this time is spent on expensive parts of the reconstruction algorithm, abort and fallback to LoD 1.1 extrusion.
lod11-fallback-time = 1800000

### Output options
## Enable or disable output tiling.
tiling = false
## Tilesize for rectangular output tiles in meters.
tilesize = [1000,1000]
## Output CityJSONSequence file for each building instead of one file per tile.
split-cjseq = false
## Omit metadata line in CityJSONSequence output.
omit-metadata = false
## Scaling applied to CityJSON output vertices
cj-scale = [0.001,0.001,0.001]
## Translation applied to CityJSON output vertices. Uses dataset center by default.
# cj-translate = [100000, 200000, 0]
## Rename output attributes. If no value is provided, the attribute will not be written. See the list of available attributes with `--attributes`. By default attribute names are prefixed with `rf_`.

[output-attributes]
## The azimuth of a roofpart in degrees
azimuth = "rf_azimuth"
## Indicates what extrusion mode was used for the building. `standard`: the regular LoD 1.2, 1.3 or 2.2 extrusion. `lod11_fallback`: all geometry was substituted with an LoD 1.1 extrusion. `skip`: no 3D geometry was generated
extrusion_mode = "rf_extrusion_mode"
## Indicates if LoD 1.1 extrusion was forced for the building
force_lod11 = "rf_force_lod11"
## The elevation of the floor of the building
h_ground = "rf_h_ground"
## The 98th percentile elevation of the building pointcloud
h_pc_98p = "rf_h_pc_98p"
## The 50th percentile roof elevation
h_roof_50p = "rf_h_roof_50p"
## The 70th percentile roof elevation
h_roof_70p = "rf_h_roof_70p"
## The maximum roof elevation
h_roof_max = "rf_h_roof_max"
## The minimum roof elevation
h_roof_min = "rf_h_roof_min"
## The main ridge elevation
h_roof_ridge = "rf_h_roof_ridge"
## Indicates if a glass roof was detected
is_glass_roof = "rf_is_glass_roof"
## Indicates if the building was mutated between multiple input pointclouds (if multiple input pointclouds were provided)
is_mutated = "rf_is_mutated"
## Indicates fraction (in the range [0,1]) of the roofprint area that is not covered by pointcloud data
nodata_frac = "rf_nodata_frac"
## Indicates the radius of the largest circle in the roofprint that is not covered by pointcloud data
nodata_r = "rf_nodata_r"
## Indicates why the input pointcloud was selected for reconstruction. Only relevant if multiple input pointclouds were provided
pc_select = "rf_pc_select"
## Indicates which input pointcloud was used for reconstruction
pc_source = "rf_pc_source"
## Indicates the acquisition year of the selected input pointcloud
pc_year = "rf_pc_year"
## Indicates if the pointcloud was found to be insufficient for reconstruction
pointcloud_unusable = "rf_pointcloud_unusable"
## Indicates the point density inside the roofprint
pt_density = "rf_pt_density"
## Reconstruction time in milliseconds
reconstruction_time = "rf_t_run"
## The Root Mean Square Erorr of the LOD12 geometry
rmse_lod12 = "rf_rmse_lod12"
## The Root Mean Square Erorr of the LOD13 geometry
rmse_lod13 = "rf_rmse_lod13"
## The Root Mean Square Erorr of the LOD22 geometry
rmse_lod22 = "rf_rmse_lod22"
## The number of roofplanes detected in the pointcloud (could be different from the generated mesh model)
roof_n_planes = "rf_roof_planes"
## The number of ridgelines detected in the pointcloud (could be different from the generated mesh model)
roof_n_ridgelines = "rf_ridgelines"
## Roof type. Can be `no points`, `no planes`, `horizontal`, `multiple horizontal`, or `slanted`
roof_type = "rf_roof_type"
## The slope of a roofpart in degrees
slope = "rf_slope"
## Indicates if processing completed without unexpected errors
success = "rf_success"
## Lists val3dity codes for LoD 1.2 geometry
val3dity_lod12 = "rf_val3dity_lod12"
## Lists val3dity codes for LoD 1.3 geometry
val3dity_lod13 = "rf_val3dity_lod13"
## Lists val3dity codes for LoD 2.2 geometry
val3dity_lod22 = "rf_val3dity_lod22"
## The volume in cubic meters of the LoD 1.2 geometry
volume_lod12 = "rf_volume_lod12"
## The volume in cubic meters of the LoD 1.3 geometry
volume_lod13 = "rf_volume_lod13"
## The volume in cubic meters of the LoD 2.2 geometry
volume_lod22 = "rf_volume_lod22"

[[pointclouds]]
## Name of the pointcloud
name = ""
## Path to the pointcloud
source = ""
## Ground class
ground_class = 0
## building class
building_class = 0
## Quality
quality = 0
## Date
date = 0
## Force LoD11
force_lod11 = false
## Select only for date
select_only_for_date = false