city_generator2-input.5 (8742B)
1 .\" Copyright (C) 2022-2023 Université de Pau et des Pays de l'Adour UPPA 2 .\" Copyright (C) 2022-2023 CNRS 3 .\" Copyright (C) 2022-2023 Sorbonne Université 4 .\" Copyright (C) 2022-2023 Université Paul Sabatier 5 .\" Copyright (C) 2022-2023 |Meso|Star>. 6 .\" 7 .\" This program is free software: you can redistribute it and/or modify 8 .\" it under the terms of the GNU General Public License as published by 9 .\" the Free Software Foundation, either version 3 of the License, or 10 .\" (at your option) any later version. 11 .\" 12 .\" This program is distributed in the hope that it will be useful, 13 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 14 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 .\" GNU General Public License for more details. 16 .\" 17 .\" You should have received a copy of the GNU General Public License 18 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 19 .Dd June 10, 2024 20 .Dt CITY_GENERATOR2-INTPUT 5 21 .Os 22 .Sh NAME 23 .Nm city_generator2-input 24 .Nd description of input file formats for 25 .Xr city_generator2 1 26 .Sh DESCRIPTION 27 .Nm 28 are the formats used by the 29 .Xr city_generator2 1 30 program to describe a city. 31 They all rely on the yaml 1.1 syntax. 32 .Xr city_generator2 1 33 reads two different types of files: a single map file, and at least one catalog 34 file. 35 The next two sections describe their formats. 36 .Pp 37 Because these files are yaml files, they must comply with yaml syntax rules, 38 including the hard part that is spacing. The following grammar rules that 39 begin with a verbatim text must all start at column 1. 40 From here, the amount of whitespace characters in verbatim text must be strictly 41 observed. 42 Also, text appearing between quote marks has to be used verbatim in the input, 43 without the quote characters. 44 Finally, text introduced by the # character in descriptions, 45 when not verbatim, is a comment and is not part of the description. 46 .Pp 47 Note however that yaml syntax admits multiple equivalent expressions. 48 Thus, the rules given thereafter could have been written differently. 49 Experienced yaml users can use any equivalent syntax instead of the one 50 introduced here. 51 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 52 .\" Grammar in Backus-Naur form 53 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 54 .Sh GRAMMAR 55 .Ss CITY MAP FILE FORMAT 56 The city map file aims to describe the ground, that is currently limited to a 57 single layer, with a depth, and the list of buildings on the ground. 58 Each building is described in the same way, regardless of its construction mode, 59 that is part of the description. 60 .Pp 61 The city map file format is as follows: 62 .Bl -column (descr-line) (::) () 63 .It Ao Va city-map-file Ac Ta ::= Ta Ao Va ground-desc Ac 64 .It Ta Ta Ao Va building-list Ac 65 .It Ao Va ground-desc Ac Ta ::= Ta Qo ground: Qc 66 .It Ta Ta Qo \ \ extend: \& Qc Ao Va extend Ac 67 .It Ta Ta Qo \ \ depth: \& Qc Ao Va depth Ac 68 .It Ao Va building-list Ac Ta ::= Ta Qo buildings: Qc 69 .It Ta Ta Ao Va buildings Ac 70 .It Ao Va extent Ac Ta ::= Ta Qo \&[ Qc Ao Va Xmin Ac Qo , Qc\ 71 Ao Va Ymin Ac Qo , Qc Ao Va Xsize Ac Qo , Qc Ao Va Ysize Ac Qo ] Qc 72 .It Ao Va depth Ac Ta ::= Ta Vt REAL No # > 0, in m 73 .It Ao Va buildings Ac Ta ::= Ta Ao Va building Ac 74 .It Ta Ta [ \& Ao Va buildings Ac \& ] 75 .It Ao Va Xmin Ac Ta ::= Ta Vt REAL No # in m 76 .It Ao Va Ymin Ac Ta ::= Ta Vt REAL No # in m 77 .It Ao Va Xsize Ac Ta ::= Ta Vt REAL No # > 0, in m 78 .It Ao Va Ysize Ac Ta ::= Ta Vt REAL No # > 0, in m 79 .It Ao Va building Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac 80 .It Ta Ta Qo \ \ \ construction_mode: \& Qc Ao Va cmode-name Ac 81 .It Ta Ta Qo \ \ \ dataset: \& Qc Ao Va dataset-name Ac 82 .It Ta Ta Qo \ \ \ footprint: [ Qc Ao Va vertices Ac Qo ] Qc 83 .It Ta Ta Ao Va height-spec Ac 84 .It Ao Va name Ac Ta ::= Ta Vt STRING 85 .It Ao Va cmode-name Ac Ta ::= Ta Qo Construction_Mode_0 Qc | Qo Construction_Mode_1 Qc 86 .It Ao Va dataset-name Ac Ta ::= Ta Vt STRING 87 .It Ta Ta # The name must be found in a catalog file 88 .It Ta Ta # with the same construction mode 89 .It Ao Va height-spec Ac Ta ::= Ta Qo \ \ \ height: \& Qc Ao Va height Ac 90 .It Ta | Ta Qo \ \ \ levels_height: [ Qc Ao Va height-list Ac Qo ] Qc 91 .It Ao Va vertices Ac Ta ::= Ta Ao Va vertex Ac Bo \& Qo , Qc Ao Va vertices Ac \& Bc 92 .It Ta Ta # \&At least 3 vertices 93 .It Ao Va vertex Ac Ta ::= Ta Qo \&[ Qc Ao Va X Ac Qo , Qc Ao Va Y Ac Qo ] Qc 94 .It Ao Va X Ac Ta ::= Ta Vt REAL No # in m 95 .It Ao Va Y Ac Ta ::= Ta Vt REAL No # in m 96 .It Ao Va height-list Ac Ta ::= Ta Ao Va height Ac Bo \& Qo , Qc Ao Va height-list Ac \& Bc 97 .It Ao Va height Ac Ta ::= Ta Vt REAL No # > 0, in m 98 .El 99 100 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 101 .Ss CATALOG FILE FORMAT 102 There are currently two different catalog file formats, identified by name, 103 and the way 104 .Xr city_generator2 1 105 is designed allows for additional catalog formats to be implemented. 106 .Pp 107 All catalog files contain the name of the construction mode to which they add 108 datasets, and a list of datasets. 109 What differs between catalog file formats is the format of the datasets. 110 It is obviously expected that datasets use the format associated with the named 111 construction mode. 112 .Pp 113 The catalog file format is as follows: 114 .Bl -column (descri-line) (::) () 115 .It Ao Va catalog-file Ac Ta ::= Ta Ao Va catalog-file-0 Ac 116 .It Ta | Ta Ao Va catalog-file-1 Ac 117 .It Ta | Ta Ao Va catalog-file-2 Ac 118 .It Ao Va catalog-file-0 Ac Ta ::= Ta Qo construction_mode: Construction_Mode_0 Qc 119 .It Ta Ta Qo datasets: \& Qc 120 .It Ta Ta Ao Va datasets-0 Ac 121 .It Ao Va catalog-file-1 Ac Ta ::= Ta Qo construction_mode: Construction_Mode_1 Qc 122 .It Ta Ta Qo datasets: \& Qc 123 .It Ta Ta Ao Va datasets-1 Ac 124 .It Ao Va catalog-file-2 Ac Ta ::= Ta Qo construction_mode: Construction_Mode_2 Qc 125 .It Ta Ta Qo datasets: \& Qc 126 .It Ta Ta Ao Va datasets-2 Ac 127 .It Ao Va datasets-0 Ac Ta ::= Ta Ao Va dataset-0 Ac 128 .It Ta Ta [ \& Ao Va datasets-0 Ac \& ] 129 .It Ao Va datasets-1 Ac Ta ::= Ta Ao Va dataset-1 Ac 130 .It Ta Ta [ \& Ao Va datasets-1 Ac \& ] 131 .It Ao Va dataset-0 Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac 132 .It Ta Ta Qo \ \ \ wall_thickness: \& Qc Vt REAL No # > 0, in m 133 .It Ta Ta Qo \ \ \ floor_thickness: \& Qc Vt REAL No # > 0, in m 134 .It Ao Va dataset-1 Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac 135 .It Ta Ta Qo \ \ \ wall_thickness: \& Qc Vt REAL No # > 0, in m 136 .It Ta Ta Qo \ \ \ floor_thickness: \& Qc Vt REAL No # > 0, in m 137 .It Ta Ta Qo \ \ \ inter_floor_count: \& Qc Vt INTEGER No # >= 0 138 .It Ta Ta Qo \ \ \ inter_floor_thickness: \& Qc Vt REAL No # > 0, in m 139 .It Ta Ta Qo \ \ \ roof_thickness: \& Qc Vt REAL No # > 0, in m 140 .It Ta Ta Qo \ \ \ crawl_height: \& Qc Vt REAL No # >= 0, in m 141 .It Ta Ta Qo \ \ \ attic_height: \& Qc Vt REAL No # >= 0, in m 142 .It Ta Ta Qo \ \ \ glass_ratio: \& Qc Vt REAL No # >= 0 and <= 1 143 .It Ta Ta Qo \ \ \ floor_insulation_thickness: \& Qc Vt REAL 144 .It Ta Ta No # >= 0, in m 145 .It Ta Ta Qo \ \ \ roof_insulation_thickness: \& Qc Vt REAL 146 .It Ta Ta No # >= 0, in m 147 .It Ta Ta Qo \ \ \ internal_insulation_thickness: \& Qc Vt REAL 148 .It Ta Ta No # >= 0, in m 149 .It Ta Ta Qo \ \ \ external_insulation_thickness: \& Qc Vt REAL 150 .It Ta Ta No # >= 0, in m 151 .It Ta Ta Qo \ \ \ foundation_depth: \& Qc Vt REAL No # >= 0, in m 152 .It Ao Va dataset-2 Ac Ta ::= Ta Qo \ \ -name: \& Qc Ao Va name Ac 153 .It Ta Ta Qo \ \ \ wall_thickness: \& Qc Vt REAL No # > 0, in m 154 .It Ta Ta Qo \ \ \ floor_thickness: \& Qc Vt REAL No # > 0, in m 155 .It Ta Ta Qo \ \ \ inter_floor_thickness: \& Qc Vt REAL No # > 0, in m 156 .It Ta Ta Qo \ \ \ roof_thickness: \& Qc Vt REAL No # > 0, in m 157 .It Ta Ta Qo \ \ \ crawl_height: \& Qc Vt REAL No # >= 0, in m 158 .It Ta Ta Qo \ \ \ foundation_depth: \& Qc Vt REAL No # >= 0, in m 159 .It Ta Ta Qo \ \ \ has_attic: \& Qc Vt 0 | 1 No 160 .It Ta Ta Qo \ \ \ glass_ratio: \& Qc Vt REAL No # >= 0 and <= 1 161 .It Ta Ta Qo \ \ \ windows_min_width: \& Qc Vt REAL No # >= 0 162 .It Ta Ta Qo \ \ \ windows_max_width: \& Qc Vt REAL No # >= 0 163 .It Ta Ta Qo \ \ \ windows_min_spacing: \& Qc Vt REAL No # >= 0 164 .It Ta Ta Qo \ \ \ windows_height_ratio: \& Qc Vt REAL No # >= 0 and <= 1 165 .It Ta Ta Qo \ \ \ floor_insulation_thickness: \& Qc Vt REAL 166 .It Ta Ta No # >= 0, in m 167 .It Ta Ta Qo \ \ \ roof_insulation_thickness: \& Qc Vt REAL 168 .It Ta Ta No # >= 0, in m 169 .It Ta Ta Qo \ \ \ internal_insulation_thickness: \& Qc Vt REAL 170 .It Ta Ta No # >= 0, in m 171 .It Ta Ta Qo \ \ \ external_insulation_thickness: \& Qc Vt REAL 172 .It Ta Ta No # >= 0, in m 173 .It Ao Va name Ac Ta ::= Ta Vt STRING 174 .El 175 .Sh SEE ALSO 176 .Xr city_generator2 1 177 .Sh STANDARDS 178 .Rs 179 .%T YAML Ain't Markup Language version 1.1 180 .%A Oren Ben-Kiki 181 .%A Clark Evans 182 .%A Ingy döt Net 183 .%D 2005 184 .%U https://yaml.org/spec/1.1 185 .Re 186 .Sh HISTORY 187 .Nm 188 has been initially developed as part of the 189 .Sy Readynov No funding program of the Occitanie / 190 Pyrénées-Méditerranée region.