summaryrefslogtreecommitdiff log msg author committer range
path: root/doc/manual/en/ch12_data_files.tex
blob: 367dd7ef17209a3b3733a79182c3c6cb14dfc5e0 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371  \chapter{Data Files}\label{cha:data-files} Data files used by XCSoar fall into two categories: \begin{description} \item[Flight data files] These files contain data relating to the aircraft type, airspace and maps, waypoints etc. These are the files that are most likely to be modified or set by normal users. \item[Program data files] These files contain data relating to the look and feel' of the program, button assignments, input events. \end{description} This chapter focuses on flight data files; see the {\em XCSoar Advanced Configuration Guide} for details on program data files. \section{File management} File names must correspond to the name extensions specified below. It is good practice to make sure that the file names are recognisable so that when making configuration changes there is less risk of confusion between different files and different file types. Regarding older Pocket PC devices it is a good idea to have data files located in nonvolatile memory, the use of SD cards and other removable media in PDAs can cause performance issues; for smaller files, and files that are only accessed at start-up (waypoints, airspace, glide polars, configuration files), this is acceptable. However, terrain and topography files are accessed continuously while XCSoar is running, so these should be located in faster storage memory. For newer Windows Mobile or Android devices this is not an issue any more. The access to modern memory cards usually meets the required performance. Many PDAs provide a 'file store' which is nonvolatile; the same arguments above apply regarding their use and performance. All data files should be copied into the directory: \begin{verbatim} My Documents/XCSoarData \end{verbatim} On PDAs data can also be stored on the operating system file store, on Compact Flash cards or SD cards under the directory \verb|XCSoarData|. For example: \begin{verbatim} SD Card/XCSoarData IPAQ File Store/XCSoarData \end{verbatim} If unsure, just start the newly installed XCSoar and it creates the \verb|XCSoarData| directory at the right place. \section{Map Database}\label{sec:map} A map database (extension \verb|.xcm|) contains terrain, topography and optional contents like waypoints and airspaces. Terrain is a raster digital elevation model represented as an array of elevations in meters on a latitude/longitude grid. The internal file format is GeoJPEG2000. The topography is vector data such as roads, railway lines, large built-up areas (cities), miscellaneous populated areas (towns and villages), lakes and rivers. The topography is stored in ESRI Shape files which are generated from OpenStreetMap. Map files can be downloaded from the XCSoar web site: \url{http://www.xcsoar.org/download/maps/} To generate a custom map database with different settings and bounds, you may use the map generator: \url{http://mapgen.xcsoar.org/} As far as waypoints or airspaces are included in the map database CXSoar defaults to them. An e.g. separately configured waypoint file will replace all the waypoints given by the map database. \section{Waypoints} XCSoar understands the following waypoint file formats: \begin{itemize} \item WinPilot/Cambridge (\verb|.dat|) \item SeeYou (\verb|.cup|) \item Zander (\verb|.wpz|) \item OziExplorer (\verb|.wpt|) \item GPSDump/FS, GEO and UTM (\verb|.wpt|) \end{itemize} Files are available from the Soaring Turn-points section of the Soaring Server\footnote{Mirrors to this website exist, google search for worldwide soaring turnpoint exchange'' if the main server is inaccessible.}: \url{http://soaringweb.org/TP} Several commercial and freely distributable programs exist for converting between different waypoint formats. If the elevation of any waypoints is set to zero in the waypoint file, then XCSoar estimates the waypoint elevation from the terrain database if available. \section{Airspace} XCSoar supports airspace files (extension \verb|.txt|) using a sub set of the widely distributed OpenAir format, as well as the Tim Newport-Pearce file format (extension \verb|.sua|). Files are available from the Special Use Airspace section of the soaring web site: \url{http://soaringweb.org/Airspace} The following is the list of supported airspace types: Class A-G, Prohibited, Danger Areas, Restricted, Task Area, CTR, No Gliders, Wave, Transponder Mandatory, and Other. All other airspace types will be drawn as type `Other''. In addition to the OpenAir standard the AR command is recognized as the airspace radio frequency. \section{Airfield details}\label{sec:airfield-details} The airfield details file (extension \verb|.txt|) is a simple text format file containing entries for each airfield, marked in square brackets, followed by the text to be displayed on the Waypoint Details Dialogue for that particular waypoint. The text should have a narrow margin because the waypoint details dialogue cannot currently handle word wrapping. The text may also specify images for airfields or waypoints. To show an image directly in XCSoar use \verb|image=| followed by the file name (this is currently not supported on PC/Windows). Be sure to avoid any additional whitespaces around the equal sign or in front of the keyword. Which files are supported depends on your operating system and the applications that are installed. Android supports JPEG files and other file types, others mostly BMP images. The names of airfields used in the file must correspond exactly to the names in the waypoints file, with the exception that converting to uppercase is allowed. The XCSoar website provides airfield details files for several countries and includes tools to convert from various Enroute Supplement sources to this file format. Users are free to edit these files to add their own notes for airfields that may not otherwise be included in the Enroute Supplement sources. An example (extract from the Australian airfields file): \begin{verbatim} [BENALLA] RUNWAYS: 08 (RL1,7) 17 (RL53) 26 (R) 35 (R) COMMUNICATIONS: CTAF - 122.5 REMARKS: Nstd 10 NM rad to 5000' REMARKS: CAUTION - Animal haz. Rwy 08L-26R and 17L-35R for glider ops and tailskidacft only, SR-SS. TFC PAT - Rgt circuits Rwy 08R-26L. NS ABTMT - Rwy 17R-35L fly wide ICAO: YBLA image=Benalla_sat.bmp [GROOTE EYLANDT] Blah blah blah blah ... \end{verbatim} \section{Glide polar} \label{sec:glide-polar} Many polars of common gliders are built into XCSoar. If your glider model is not listed, you can use a polar file in the WinPilot polar format (extension \verb|.plr|). The WinPilot and XCSoar websites provide several glide polar files. Files for other gliders may be created upon request to the XCSoar team. The format of the file is simple. Lines beginning with \verb|*| are ignored and so may be used to document how the polar was calculated or if there are restrictions on its use. Other than comments, the file must contain a single row of numbers separated with commas: \begin{itemize} \item Mass dry gross weight in kg: this is the weight of the glider plus a 'standard' pilot without ballast. \item Max water ballast in liters (kg). \item Speed in km/h for first measurement point, (usually minimum sink speed). \item Sink rate in m/s for first measurement point. \item Speed in km/h for second measurement point, (usually best glide speed). \item Sink rate in m/s for second measurement point. \item Speed in km/h for third measurement point, (usually max manoeuvring speed). \item Sink rate in m/s for third measurement point. \end{itemize} The following is an extension to the existing polare file format and thus optional. \begin{itemize} \item The wing area in m$^2$ to allow the wing load computation (could be zero if unknown). \item The max. manoeuvering speed in km/h to enable simple checks for the cruise speed command. \end{itemize} An example, for the LS-3 glider, is given below: \begin{verbatim} *LS-3 WinPilot POLAR file: MassDryGross[kg], * MaxWaterBallast[liters], Speed1[km/h], Sink1[m/s], * Speed2, Sink2, Speed3, Sink3 373, 121, 74.1, -0.65, 102.0, -0.67, 167.0, -1.85 \end{verbatim} \tip Don't be too optimistic when entering your polar data. It is all too easy to set your LD too high and you will rapidly see yourself undershooting on final glide. \section{Profiles} Profile files (extension \verb|.prf|) can be used to store configuration settings used by XCSoar. The format is a simple text file containing \verb|