Configuration File

The configuration file is in JSON format. It is a necessary input and it is validated against a schema.

Examples of configuration files are in https://github.com/tudelft3d/City4CFD/tree/main/examples/TUDCampus

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 geojson file
      "height_attribute": "height",          // Optional - use height from geojson 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
    },
    {
      "type": "SurfaceLayer",
      "path": "polygons/Vegetation.geojson",
      "layer_name" : "Vegetation"            // Optional - choose a layer name
    },
    {
      "type": "SurfaceLayer",
      "path": "polygons/Water.geojson",
      "layer_name": "Water",
      "average_surface":    true,            // Optional - set all points of the surface layer to the same height
      "surface_percentile": 30               // Percentile of all points of the surface layer to set the height to, required if average_surface is true
    }
  ],
  "import_geometries" : [
    "path": "import_buildings/TUD_geometries.json",*
    "advantage":   true,
    "true_height": true,
    "lod": "1.3"
  ]

  //-- Domain dimensions 
  "point_of_interest": [85376, 446125],
  "influence_region": 300,            // Radius, Polygon points, GeoJSON 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": 90,             // Optional - percentage of randomly removed terrain points
  "smooth_terrain":   true,           // Optional - smoothing flag
  "flat_terrain":     false,          // Optional - make terrain flat

  "lod": "1.2",
  "building_percentile": 90,

  "edge_max_len": 2,

  //-- 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 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 geojson file
      "height_attribute": "height",          // Optional - use height from geojson 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
    },
    {
      "type": "SurfaceLayer",
      "path": "polygons/Vegetation.geojson",
      "layer_name" : "Vegetation"           // Optional - choose a layer name
    },
    {
      "type": "SurfaceLayer",
      "path": "polygons/Water.geojson",
      "layer_name": "Water",
      "average_surface":    true,            // Optional - set all points of the surface layer to the same height
      "surface_percentile": 30               // Percentile of all points of the surface layer to set the height to, required if average_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 GeoJSON file [optional]

The following options are used for reconstruction using height information stored in the GeoJSON 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 GeoJSON 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

SurfaceLayer

layer_name: Name that will be used in the output file [optional]. If missing, layers will be named SurfaceLayer_1, SurfaceLayer_2, etc.

average_surface: default: false; Sets all points of the surface layer to an averaged height [linklink describing more] [optional]

surface_percentile: Sets surface layer points to a defined percentile, required in case average_surface is true

(back to top)

Imported geometries

Information on imported buildings here

  "import_geometries" : [
    "path": "import_buildings/TUD_geometries.json",
    "advantage":   true,
    "true_height": true,
    "lod": "1.3"
  ]

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

(back to top)

Domain dimensions

  "point_of_interest": [85376, 446125],
  "influence_region": 300,            // Radius, Polygon points, GeoJSON 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 GeoJSON 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": 90,             // Optional - percentage of randomly removed terrain points
  "smooth_terrain":   true,           // Optional - smoothing flag
  "flat_terrain":     false,          // Optional - make terrain flat

  "lod": "1.2",
  "building_percentile": 90,

  "edge_max_len": 2,

terrain_thinning: Percentage of randomly removed points from the point cloud [optional]

smooth_terrain: default: false; Gaussian smoothing of terrain points

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

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)