-
Notifications
You must be signed in to change notification settings - Fork 18
Configuration File
The configuration file is in JSON format. It is a necessary input and it is validated against a schema.
A few examples of configuration files are in the demo folder.
This section of the documentation provides a walkthrough of the configuration file and available options for the reconstruction. An example of the configuration file containing all options is as follows:
//-- CITY4CFD CONFIGURATION FILE --//
{
"point_clouds":
{
"ground": "point_cloud/sampled_ground_1m.ply",
"buildings" : "point_cloud/sampled_buildings_1m.ply"
},
"polygons" : [
{
"type": "Building",
"path": "polygons/tudcampus.geojson",
"unique_id": "gid" // Optional - use building ID from the polygon file
"height_attribute": "height", // Optional - use height from the polygon file for reconstruction
"floor_attribute": "num_floors", // Optional - use number of floors for reconstruction
"floor_height": 3, // Floor height, required if 'floor_attribute' is defined
"height_attribute_advantage": false, // In case height attribute takes precedence over other reconstruction from point cloud
"avoid_bad_polys": false, // Optional - ignore or try to reconstruct problematic (non-simple) polygons
"refine": false // Optional - refine surface
},
{
"type": "SurfaceLayer",
"path": "polygons/Vegetation.geojson",
"layer_name" : "Vegetation" // Optional - choose a layer name
},
{
"type": "SurfaceLayer",
"path": "polygons/Water.geojson",
"layer_name": "Water",
"flatten_surface": true, // Optional - set all points of the surface layer to the same height
"flatten_vertical_border": true, // Optional - enforce vertical walls between terrain and flattened surface
"surface_percentile": 30 // Percentile of all points of the surface layer to set the height to, required if flatten_surface is true
}
],
"reconstruction_regions" : [
{
"influence_region": 300, // Radius, Polygon points, imported polygon, or null for BPG
"lod": "2.2", // LoD1.2, 1.3, or 2.2
"complexity_factor": 0.6, // Graph cut optimisation bias for LoD1.3 and LoD2.2, required if those LoDs are chosen
"lod13_step_height": 2, // Optional - choose LoD1.3 minimum step height between roof faces in m
"validate": false, // Optional - do the geometric validity check and report on invalid buildings
"enforce_validity": "lod1.2", // Optional - fall back to LoD1.2 reconstruction or surface wrap in case the geometric validity check fails
"relative_alpha": 500, // Required when "enforce_validity": "surface_wrap"
"relative_offset": 1200, // Required when "enforce_validity": "surface_wrap"
"skip_gap_closing": false, // Optional - skip open border check and simple gap closing in LoD1.3 and LoD2.2 reconstruction
"bpg_influence_region_extra": 0., // Optional - expand the influence region as 3*(max_dim + extra)
"import_advantage": false // Optional - whether imported or reconstructed take advantage in the region
}
]
"import_geometries" : {
"path": "import_buildings/TUD_geometries.json",*
"true_height": true,
"lod": "1.3",
"refine": false // Optional - refine surface
}
//-- Domain dimensions
"point_of_interest": [85376, 446125],
"domain_bnd": null, // Same as above
"top_height": 300, // Doesn't matter if BPG are used for domain size
"buffer_region": -20, // Optional - buffer region size in percentage of distance to bndpoly centroid
"reconstruct_boundaries: true // Optional - reconstruct sides and top of the domain, default: false
//- Arguments required only if using BPG
"bnd_type_bpg": "Rectangle", // Round, Rectangle, Oval. Matters only if using BPG
"bpg_blockage_ratio": false, // Optional - blockage ratio BPG. Can be set as 'true' for default, or as a number defining max allowed blockage ratio
"flow_direction": [1, 1], // Required for Rectangular and Oval domain, and Round with the blockage ratio
"bpg_domain_size": [5, 5, 15, 6], // Optional - overwrites bpg distances from tallest building
// [front, sides, back, top] Rectangle/Ellipse, [sides, top] for round
//- Terrain and building reconstruction
"terrain_thinning": 80, // Optional - percentage of randomly removed terrain points
"smooth_terrain": { // Optional - smoothing flag
"iterations": 1, // number of smoothing iterations. Typical numbers are 1-10
"max_pts": 250000 // number of points after optimized thinning for smoothing
},
"flat_terrain": false, // Optional - make terrain flat
"building_percentile": 90,
"min_height": 2, // Optional - define the minimum allowed height for buildilng reconstruction
"min_area": 50, // Optional - define the minimum allowed floorplan area for buildilng reconstruction
"reconstruct_failed": false, // Optional - reconstruct buildings at minimum height if the reconstruction fails
"intersect_buildings_terrain": false,// Optional - make buildings protrude through terrain
"edge_max_len": 5,
//-- Output and log
"output_file_name": "Mesh",
"output_format": "obj",
"output_separately": true,
"output_log": true, // Optional, also outputs GeoJSON file of building polygons that couldn't be reconstructed
"log_file": "logFile.log" // Optional, defaults to 'log'
}
"point_clouds" :
{
"ground": "point_cloud/sampled_ground_1m.ply",
"buildings" : "point_cloud/sampled_buildings_1m.ply"
}
This dictionary gives paths to two point clouds -- one used for ground points, and the other one used for buildings. Paths are set relative to the location of the configuration file. Accepted formats for point clouds are LAS/LAZ, PLY (both binary and ASCII) and XYZ.
"polygons" : [
{
"type": "Building",
"path": "polygons/tudcampus.geojson",
"unique_id": "gid" // Optional - use building ID from the polygon file
"height_attribute": "height", // Optional - use height from the polygon file for reconstruction
"floor_attribute": "num_floors", // Optional - use number of floors for reconstruction
"floor_height": 3, // Floor height, required if 'floor_attribute' is defined
"height_attribute_advantage": false, // In case height attribute takes precedence over other reconstruction from point cloud
"avoid_bad_polys": false, // Optional - ignore or try to reconstruct problematic (non-simple) polygons
"refine": false // Optional - refine surface
},
{
"type": "SurfaceLayer",
"path": "polygons/Vegetation.geojson",
"layer_name" : "Vegetation" // Optional - choose a layer name
},
{
"type": "SurfaceLayer",
"path": "polygons/Water.geojson",
"layer_name": "Water",
"flatten_surface": true, // Optional - set all points of the surface layer to the same height
"flatten_vertical_border": true, // Optional - enforce vertical walls between terrain and flattened surface
"surface_percentile": 30 // Percentile of all points of the surface layer to set the height to, required if flatten_surface is true
}
],
Two types of polygons can be set:
- Building
- SurfaceLayer
Polygons are imported in GeoJSON format. Path to polygons is given relative to the location of the configuration file.
unique_id: ID of polygons stored in the polygon file [optional]
The following options are used for reconstruction using height information stored in the polygon file. They are mandatory (height attribute or num floors + floor height) only if the buildings point cloud is missing:
height_attribute: Name of the height information stored in the polygon file for reconstruction
floor_attribute: Name of the parameter containing the number of floors
floor_height: Floor height in m, required if floor_attribute is defined
height_attribute_advantage: default: false; If true, reconstruction using attributes takes precedence
avoid_bad_polys: default: false; If true, non-simple polygons will not be imported. Otherwise, their import (and possible reconstruction) will be attempted. This could work, but it can also result in bad reconstructions and robustness issues
refine: default: false; If true, refines (isotropically remeshes) reconstructed building surfaces. It might introduce self-intersections
layer_name: Name that will be used in the output file [optional]. If missing, layers will be named SurfaceLayer_1, SurfaceLayer_2, etc.
flatten_surface: default: false; Sets all points of the surface layer to a certain height. Information here [optional]
flatten_vertical_border: default: false; Enforces vertical walls between surface layers and terrain. WARNING: it can be resource-intensive [optional]
surface_percentile: Sets surface layer points to a defined percentile, required in case flatten_surface is true
"reconstruction_regions" : [
{
"influence_region": 300, // Radius, Polygon points, imported polygon, or null for BPG
"lod": "2.2", // LoD1.2, 1.3, or 2.2
"complexity_factor": 0.6, // Graph cut optimisation bias for LoD1.3 and LoD2.2, required if those LoDs are chosen
"lod13_step_height": 2, // Optional - choose LoD1.3 minimum step height between roof faces in m
"validate": false, // Optional - do the geometric validity check and report on invalid buildings
"enforce_validity": "lod1.2", // Optional - fall back to LoD1.2 reconstruction or surface wrap in case the geometric validity check fails
"relative_alpha": 500, // Required when "enforce_validity": "surface_wrap"
"relative_offset": 1200, // Required when "enforce_validity": "surface_wrap"
"skip_gap_closing": false, // Optional - skip open border check and simple gap closing in LoD1.3 and LoD2.2 reconstruction
"bpg_influence_region_extra": 0., // Optional - expand the influence region as 3*(max_dim + extra)
"import_advantage": false // Optional - whether imported or reconstructed take advantage in the region
},
{
"influence_region": null,
"lod": "1.2"
...
}
]
influence_region: Dimensions of the influence region, can be defined in three ways:
- Radius: type: number; All buildings that are inside or on the border of a certain radius (in meters) from the point of interest are in the influence region
-
Polygon: it can be set in two ways:
-
type: string; path to the polygon manually defining the influence region, e.g.
"influence_region": "polygons/manualInflu.geojson" -
type: array; manually defining polygon coordinates, e.g.
"influence_region": [[88200, 123400], [88300, 123400], [88300, 123500] [88200, 123500]]
-
type: string; path to the polygon manually defining the influence region, e.g.
- BPG: type: null; Using best practice guidelines to define influence region. Activate by setting to null, e.g. "influence_region": null
lod: Level-of-detail of buildings. Option between LoD1.2 (polygon extrusion), LoD1.3 (multiple flat roof surfaces), LoD2.2 (slanted roofs)
complexity_factor: default: 0.5; Graph cut optimisation bias in case of LoD1.3 and LoD2.2 reconstruction that controls output geometry complexity. Values from 0 (least complex geometry) to 1 (most complex geometry)
lod13_step_height: default: 2; Controls the minimum allowed step height between two roof surfaces in LoD1.3 reconstruction
validate: default: false; Do the geometry validity check on LoD1.3 and LoD2.2 reconstruction and report invalid buildings to log. Check here for error codes.
enforce_validity: Fallbacks in case LoD1.3 and LoD2.2 reconstructions results in geometrically invalid buildings. Available fallbacks are "surface_wrap" (alpha wrapping) and "lod1.2" (reconstruction in valid LoD1.2) [optional]
relative_alpha: Surface wrapping parameter, required when "enforce_validity": "surface_wrap"
relative_offset: Surface wrapping parameter, required when "enforce_validity": "surface_wrap"
skip_gap_closing: default: false; Skip the simple open border check and closing at the end of LoD1.3 and LoD2.2 reconstruction
bpg_influence_region_extra: default: 0; BPG for influence region is 3*max_dim. This expands it with 3*(max_dim + extra). Can be useful when multiple reconstruction regions are used
import_advantage: default: true; Whether imported buildings take precedence over reconstructed ones in that specific region
"import_geometries" : [
"path": "import_buildings/TUD_geometries.json",
"true_height": true,
"lod": "1.3",
"refine": false // Optional - refine surface
]
Imported geometries should have one distinctive bottom surface that can be detected as footprint. CityJSON format should have GroundSurface semantic information. Accepted formats are CityJSON, OBJ, STL, PLY, VTP, and OFF.
true_height: default true; true if the height is set as a height above sea level, false if building height is relative to ground height
lod: choose level-of-detail from a CityJSON file
refine: default: false; If true, refines (isotropically remeshes) building surfaces. It might introduce self-intersections or affect robustness depending on the input quality
"point_of_interest": [85376, 446125],
"domain_bnd": null, // Same as above
"top_height": 300, // Doesn't matter if BPG are used for domain size
"buffer_region": -20, // Optional - buffer region size in percentage of distance to bndpoly centroid
"reconstruct_boundaries: true // Optional - reconstruct sides and top of the domain, default: false
//- Arguments required only if using BPG
"bnd_type_bpg": "Rectangle", // Round, Rectangle, Oval. Matters only if using BPG
"bpg_blockage_ratio": false, // Optional - blockage ratio BPG. Can be set as 'true' for default, or as a number defining max allowed blockage ratio
"flow_direction": [1, 1], // Required for Rectangular and Oval domain, and Round with the blockage ratio
"bpg_domain_size": [5, 5, 15, 6], // Optional - overwrites bpg distances from tallest building
// [front, sides, back, top] Rectangle/Ellipse, [sides, top] for round
point_of_interest: Central point of the simulation. All points are translated by these coordinates. It must fall in a building polygon if using BPGs for influence region/domain boundaries
domain_bnd: Domain dimensions, can be defined in the same three ways as the influence region
top_height: Top height in meters for a closed domain, overridden if BPGs are used
buffer_region: Creates mainly flat buffer around the edge domain to avoid perturbations close to boundary conditions. Can be extended inwards (less than 0) or outwards (more than 0) [optional]
reconstruct_boundaries: default: false; Reconstructs side and top boundaries, effectively closing the geometrical domain
The following arguments can/should be used in case BPGs are chosen for domain size:
bnd_type_bpg: Defines the type of domain that is created using BPGs; three types can be chosen:
- "Rectangle"
- "Round"
- "Oval"
bpg_blockage_ratio: default: false; Using blockage ratio for as a condition in BPGs. Setting it to true uses the default value of 3%, but any number can be set indicating targeted ercentage, eg. "bpg_blockage_ratio": 5
flow_direction: Required for Rectangular and Oval domain, and Round if the blockage ratio is activated.
bpg_domain_size: Overwrites BPG distances from the tallest building. Numbers represent the multiplier of the tallest building in the influence region. Depending on the type of domain, it can be defined as:
- Rectangular/Oval domain: [front, side, back, top]; default: [5, 5, 15, 6]
- Round domain: [radius, top]; default: [15, 6]
"terrain_thinning": 80, // Optional - percentage of randomly removed terrain points
"smooth_terrain": { // Optional - smoothing flag
"iterations": 1, // number of smoothing iterations. Typical numbers are 1-10
"max_pts": 250000 // number of points after optimized thinning for smoothing
},
"flat_terrain": false, // Optional - make terrain flat
"building_percentile": 90,
"min_height": 2, // Optional - define the minimum allowed height for buildilng reconstruction
"min_area": 50, // Optional - define the minimum allowed floorplan area for buildilng reconstruction
"reconstruct_failed": false, // Optional - reconstruct buildings at minimum height if the reconstruction fails for some reason
"intersect_buildings_terrain": false,// Optional - make buildings protrude through terrain
"edge_max_len": 5,
smooth_terrain: Terrain smoothing [optional]
-
iterations: Number of smoothing iterations. Typical number is 1-10 -
max_pts: Additional optimized thinning of terrain points for smoothing. Required due to increased computational effort of the smoothing. Suggested number is 200-250k, but can be higher with increased reconstruction times
terrain_thinning: Percentage of randomly removed points from the point cloud [optional]
flat_terrain: default: false; Make terrain flat at height 0
building_percentile: Percentile of building heights from the point cloud that is being used as building height
min_height: default: 2; Minimum height for building reconstruction. Lower buildings will reconstruct at that height [optional]
min_area": 50: Minimum allowed floorplan area for building reconstruction. Smaller buildings will be skipped [optional]
reconstruct_failed: If true, reconstruct buildings that failed reconstruction (e.g. missing points) at minimum height [optional]
intersect_buildings_terrain: If true, buildings will intersect terrain instead of being adjacent to it [optional]
edge_max_len: Polygon edges longer than the prescribed threshold are shortened. This avoids abrupt jumps in polygon-terrain interpolation
//-- Output and log
"output_file_name": "Mesh",
"output_format": "obj",
"output_separately": true,
"output_log": true, // Optional, also outputs GeoJSON file of building polygons that couldn't be reconstructed
"log_file": "logFile.log" // Optional, defaults to 'log'
output_file_name
output_format: "obj", "stl", or "cityjson"
output_separately: Defines whether features (buildings, terrain, surface layers) are being outputted as separate files (e.g. Mesh_Buildings.obj, Mesh_Terrain.obj, Mesh_Water.obj, etc.) or if they are being outputted as separate groups (OBJ) or solids (STL) in a single file.
output_log: default: false; Flag that defines whether the log file is being outputted
log_file: default: "log.log"; Log file name
Copyright (c) 2021-2024 3D Geoinformation, Delft University of Technology