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
    }
  ],
  "import_geometries" : [
    "path": "import_buildings/TUD_geometries.json",*
    "advantage":   true,
    "true_height": true,
    "lod": "1.3",
    "refine": false                          // Optional - refine surface
  ]

  //-- Domain dimensions 
  "point_of_interest": [85376, 446125],
  "influence_region": 300,             // Radius, Polygon points, imported polygon, or null for BPG
  "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

  "lod": "1.2",
  "building_percentile": 90,
  "min_height": 2,                     // Optional - define the minimum allowed height 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,

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

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

(back to top)

Polygons

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

Building

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) building surfaces. It might introduce self-intersections

SurfaceLayer

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

(back to top)

Imported geometries

  "import_geometries" : [
    "path": "import_buildings/TUD_geometries.json",
    "advantage":   true,
    "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.

advantage: default: true; whether imported buildings take precedence over reconstructed ones

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

(back to top)

Domain dimensions

  "point_of_interest": [85376, 446125],
  "influence_region": 300,            // Radius, Polygon points, imported polygon, or null for BPG
  "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

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]]
• BPG: type: null; Using best practice guidelines to define influence region. Activate by setting to null, e.g. "influence_region": null

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]

(back to top)

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

  "lod": "1.2",
  "building_percentile": 90,
  "min_height": 2,                       // Optional - define the minimum allowed height 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

lod: Level-of-detail of buildings. For now, only 1.2 is possible

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]

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

(back to top)

Output and log

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

(back to top)