Roofer CLI App¶

roofer is a command line application for generating LoD1.2, LoD1.3 and LoD2 building models from pointclouds.

With the roofer CLI application you can:

Generate of 3D building models for very 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 if it is already in a supported format.
Obtain detailed information per building object about the reconstruction process and the quality of the generated models and the input point cloud.

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 -v | --version

Options¶

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

-h, --help¶: Show help message.

-v, --version¶: Show version.

-l, --loglevel <level>¶: Specify loglevel. Can be trace, debug, info, warning [default: info]

--trace-interval <s>¶: Trace interval in seconds. Implies --loglevel trace [default: 10].

-c <file>, --config <file>¶: TOML configuration file.

-j <n>, --jobs <n>¶: Number of threads to use. [default: number of cores]

--crop-output¶: Output cropped building pointclouds.

--crop-output-all¶: Output files for each candidate pointcloud instead of only the optimal candidate. Implies --crop-output.

--crop-rasters¶: Output rasterised crop pointclouds. Implies --crop-output.

--index¶: Output index.gpkg file with crop analytics.

--split-cjseq¶: Output CityJSONSequence file for each building [default: one file per output tile]

--cj-translate¶: Specify manually the translation applied to CityJSON output vertices

--cj-scale¶: Specify manually the scaling applied to CityJSON output vertices

--omit-metadata¶: Omit metadata from output CityJSON

--filter <str>¶: Specify WHERE clause in OGR SQL to select specfic features from <polygon-source>

--polygon-source-layer <str>¶: Load this layer from <polygon-source> [default: first layer]

--force-lod11-attribute <str>¶: Building attribute for forcing lod11.

--srs <str>¶: Override SRS for both inputs and outputs

--box <xmin ymin xmax ymax>¶: Region of interest. Data outside of this region will be ignored

--ceil_point_density <float>¶: Enfore this point density ceiling on each building pointcloud.

--tilesize <x y>¶: Tilesize used for output tiles

--cellsize <float>¶: Cellsize used for quick pointcloud analysis

--id-attribute <str>¶: Building ID attribute

-Rplane-detect-epsilon <float>¶: See roofer::ReconstructionConfig::plane_detect_epsilon.

-Rplane-detect-k <int>¶: See roofer::ReconstructionConfig::plane_detect_k.

-Rplane-detect-min-points <int>¶: See roofer::ReconstructionConfig::plane_detect_min_points.

-Rlod13-step-height <float>¶: See roofer::ReconstructionConfig::lod13_step_height.

-Rcomplexity-factor <float>¶: See roofer::ReconstructionConfig::complexity_factor.

-Rlod <int>¶: See roofer::ReconstructionConfig::lod. Default is to reconstruct all LoDs.

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.

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 many of these options are also available as command line arguments, incase one option is provided both in the configuration file and as a command line argument, the command line argument takes precedence.

# Vector source with polygon roofprints. Any OGR supported format is supported.
polygon-source = "data/roofprints.gpkg"
# Load this layer from <polygon-source> [default: first layer]
polygon-source-layer = "SomeLayer"
# Building ID attribute
id-attribute = "id_attribute"
# Boolean building attribute for forcing LoD 1.1 (simple roofprint extrustion) and skipping reconstruction in a higher LoD for this building.
force-lod11-attribute = "SomeAttribute"
# Specify WHERE clause in OGR SQL to select specfic features from <polygon-source>
filter = "id_attribute='SomeID'"


# Override SRS for both inputs and outputs
srs = "EPSG:7415"
# Region of interest. Data outside of this region will be ignored. Format: [x_min, y_min, x_max, y_max].
box = [0,0,1000,1000]
# Enfore this point density ceiling on each building pointcloud.
ceil-point-density = 20
# Tilesize used for output tiles. Format: [size_x, size_y].
tilesize = [1000, 1000]
# Cellsize used for quick pointcloud analysis
cellsize = 0.5

## Reconstruction options
# Plane detect epsilon
plane-detect-epsilon = 0.3
# Plane detect k
plane-detect-k = 15
# Plane detect min points
plane-detect-min-points = 15
# Step height used for LoD1.3 generation
lod13-step-height = 3
# Complexity factor building reconstruction
complexity-factor = 0.7
# Which LoDs to generate, possible values: 12, 13, 22 [if omitted: all LoDs are generated]
lod = 22

## Output options
# Output CityJSONSequence file for each building [default: one file per output tile]
split-cjseq = false
# Omit metadata from output CityJSON
omit-metadata = true
# Manually override CityJSON transform translation
cj-translate = [171800.0,472700.0,0.0]
# Manually override CityJSON transform scale
cj-scale = [0.01,0.01,0.01]

output-directory = 'output-directory'

[[pointclouds]]
# name of the pointcloud
name = "AHN3"
# source can be a list of files and/or directories with pointcloud files. If a directory is given
# roofer recursively looks for files with the extensions `.laz`, `.las`, `.LAZ`, and `.LAS`.
source = ["data/AHN3-pointcloud.laz"]

[output-attributes]
# Rename the attributes that are added to the output by roofer. Shown are the default names (prefix: `rf_`)
status = "rf_status"
reconstruction_time = "rf_reconstruction_time"
val3dity_lod12 = "rf_val3dity_lod12"
val3dity_lod13 = "rf_val3dity_lod13"
val3dity_lod22 = "rf_val3dity_lod22"
is_glass_roof = "rf_is_glass_roof"
nodata_frac = "rf_nodata_frac"
nodata_r = "rf_nodata_r"
pt_density = "rf_pt_density"
is_mutated = "rf_is_mutated"
pc_select = "rf_pc_select"
pc_source = "rf_pc_source"
pc_year = "rf_pc_year"
force_lod11 = "rf_force_lod11"
roof_type = "rf_roof_type"
h_roof_50p = "rf_roof_elevation_50p"
h_roof_70p = "rf_roof_elevation_70p"
h_roof_min = "rf_roof_elevation_min"
h_roof_max = "rf_roof_elevation_max"
roof_n_planes = "rf_roof_n_planes"
rmse_lod12 = "rf_rmse_lod12"
rmse_lod13 = "rf_rmse_lod13"
rmse_lod22 = "rf_rmse_lod22"
h_ground = "rf_h_ground"
slope = "rf_slope"
azimuth = "rf_azimuth"