doc/salome/tutorial/english/english_sinusX_Format.rst

   1 ..
   2    Copyright (C) 2015-2016 EDF
   3
   4    This file is part of SALOME HYDRO module.
   5
   6    SALOME HYDRO module is free software: you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation, either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    SALOME HYDRO module is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with SALOME HYDRO module.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 ##############################################
  20 SinusX format for SALOME HYDRO: specifications
  21 ##############################################
  22
  23 Introduction
  24 ============
  25
  26 SinuxX is an ASCII format used at EDF for for free surface flow studies with Telemac.
  27 SinusX format as been defined a long time ago for a digitizing software used for maps, isocontours...
  28 The sofware is not used any more, but there are still parameters related to the software
  29 in the format specification and the data files.
  30 The goal of this specification is provide an editable ASCII format for import and export of SALOME HYDRO module data,
  31 and allow import of existing SinusX data files.
  32 The parameters related to the old SinusX software will be ignored on import in SALOME HYDRO module,
  33 and default values will be provided on export from SALOME HYDRO module, to keep a consistent format between
  34 old and new data.
  35 Some existing files does not follow correctly the format and must be manually corrected. For instance,
  36 closed parameter is not handled correctly in a lot of files.
  37
  38 Contents and general structure of SinusX format, correspondance with HYDRO data types
  39 =====================================================================================
  40
  41 HYDRO data types to import and export
  42 -------------------------------------
  43
  44 HYDRO module data contains Bathymetry fields and 2D or 3D polylines. 2D polylines are either polylines in the XoY plane (Z=0)
  45 or profiles in a vertical plane.
  46
  47 The bathymetry fields are a list of x,y,z points.
  48
  49 The polylines, in the XoY plane, are defined by an ordered list of x,y points. the polylines are either closed or open,
  50 spline or not. Sections are not yet taken into account here.
  51
  52 The profiles are defined in a vertical plane, by an ordered list of u,z points. The profiles are georeferenced or not,
  53 are used to describe variables sections of a river (stream object), constant sections of channel or enbankments,
  54 or altitude lines to be combined with XoY lines in order to build 3D lines.
  55
  56 All the HYDRO module objects are named.
  57
  58 general structure of SinusX format
  59 ----------------------------------
  60
  61 The file is structured in blocs of data.
  62 There are several types of blocs:
  63
  64 * Scatter plot: field of Bathymetry or Altimetry, contains a list of x,y,z points
  65 * XYZ profile: for instance a vertical profile on river, defined by a list of x,y,z points (in a vertical plane)
  66 * isocontour: a line at a constant altitude, defined by a list of x,y,z points (with z constant)
  67 * XYZ curve : a line in 3D, defined by a list of x,y,z points
  68
  69 All Blocs begin with a line starting by 'B type ...'.
  70
  71 A bloc contains several parameter lines starting with 'CN name' or 'CP parameters...'.
  72
  73 Comments are lines starting with 'C ...' and are ignored.
  74
  75 A bloc contains several point lines (one x,y,z point per line) after the bloc start and parameter lines.
  76
  77 SinusX lines format
  78 -------------------
  79
  80 Bloc Delimiter
  81 ~~~~~~~~~~~~~~
  82
  83 ::
  84
  85   B type several ignored parameters
  86
  87 **type:**
  88
  89 * type = S: Scatter plot
  90 * type = C: XYZ curve
  91 * type = P: XYZ profile
  92 * type = N: isocontour
  93
  94 There are other types in some old files. These blocs are ignored.
  95 The parameters after the type are ignored.
  96
  97 Bloc name
  98 ~~~~~~~~~
  99
 100 ::
 101
 102   CN le_nom_du_bloc
 103
 104 Avoid spaces and special characters (for instance accents) in name.
 105
 106 Closed and spline parameters
 107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 108
 109 ::
 110
 111   CP closed spline
 112
 113 Closed and spline are two booleans (0 or 1).
 114 for instance,
 115 ::
 116
 117   CP 1 1
 118
 119 means a closed line of type spline.
 120
 121 This parameter is significant only for curves, profiles and isocontour (types C, P, N)
 122 and is present but not interpreted for Scatter plot.
 123
 124 specific curve parameters, depending on curve type
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 Following the type of curve (C, P, N), this parameter is different:
 128
 129 **type = C: XYZ curve**
 130
 131 ::
 132
 133   CP real1 real2... real16
 134
 135 These 16 real parameters are ignored at import, and can be set to 0.0 at export.
 136
 137 **type = P: XYZ profile**
 138
 139 ::
 140
 141   CP x1 y1 x2 y2
 142
 143 Folowing the plane definition parameter (see below), the values define the start and end points
 144 or are ignored.
 145
 146 If the plane definition is XoY (horizontal), all the point of the profile are fully defined with their 3 coordinates x,y,z.
 147 All the points are supposed to be in the same vertical plane.
 148 The x1,y1 and x2,y2 values are ignored (and set to 0.0 at export).
 149
 150 If the plane definition is XoZ (vertical), the points of the profile are defined with 2 coordinates x,z (or u,z).
 151 The y coordinate of the profile points are set to 0.0.
 152 The two extremities are defined by origin: p1(x1,y1,0) and end: p2(x2,y2,0).
 153 The Points of the profile are in the plane defined by the line p1,p2 and the vertical.
 154 The x or u coordinate represents the abcissa in meters on the line p1,p2 counted from origin p1.
 155
 156 If the plane definition is XoZ (vertical) and x1, y1, x2, y2 are all null, the profile is not georeferenced.
 157
 158 **type = N: isocontour**
 159
 160 ::
 161
 162   CP altitude
 163
 164 Altitude value for isocontour. This value is also in the Z coordinate of each point of the bloc,
 165 but the Z coordinates are ignored, only the altitude parameter is taken into account.
 166
 167 plane definition parameter
 168 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 169
 170 ::
 171
 172   CP plane
 173
 174 Plane parameter is an integer value: 0 1 ou 2.
 175
 176 * 0: plane XoY
 177 * 1: plane YoZ
 178 * 2: plane XoZ
 179
 180 Plane 0 is used for XYZ curve, XYZ profile and isocontour.
 181
 182 Plane 1 is not used.
 183
 184 Plane 2 is used for XYZ profile.
 185
 186 Plane parameter is present but not interpreted for Scatter plots.
 187
 188 Point line
 189 ~~~~~~~~~~
 190
 191 ::
 192
 193   x y z ignored comments
 194
 195 There are always 3 coordinates.
 196 Everything after the coordinates is ignored.
 197
 198 At export, the real values must be with a fixed format with 3 decimals. For instance::
 199
 200   275982.120   128441.000      -7.500
 201
 202 Coordinates are in meter, in Lambert 93 projection: x, y absolutes values are less then 10000000.000.
 203 Z abolute values are less than 10000.000.
 204
 205 SinusX blocs description and format
 206 ===================================
 207
 208 Scatter plot bloc
 209 =================
 210
 211 example of scatter plot bloc
 212 ----------------------------
 213
 214 *import from existing data file:*
 215 ::
 216
 217   C
 218   B S +0.000000E+00 +0.000000E+00 +0.000000E+00 +1.000000E+00 +1.000000E+00 +1.000000E+00 1
 219   CN semis_de_points
 220   CP 0 1
 221   CP 0
 222   C an ignored comment
 223   +2.759820E05 +1.284410E05 -7.500000E00 A
 224   +2.759970E05 +1.284470E05 -7.500000E00 A
 225   +2.760120E05 +1.284530E05 -7.500000E00 A
 226   +2.759760E05 +1.283920E05 +3.000000E00 A
 227   +2.759900E05 +1.283970E05 -2.450000E00 A
 228   +2.760030E05 +1.284030E05 -4.000000E00 A
 229   +2.760160E05 +1.284080E05 -5.450000E00 A
 230   +2.760300E05 +1.284130E05 -4.250000E00 A
 231   +2.760440E05 +1.284190E05 -7.500000E-01 A
 232   +2.760570E05 +1.284240E05 +3.250000E00 A
 233
 234 The only parameters used are the type of bloc and the name. Closed, spline parameter and plane parameter are ignored.
 235 For each point, only the x y z value are used.
 236
 237 *export:*
 238 ::
 239
 240   C
 241   B S
 242   CN semis_de_points
 243   CP 0 0
 244   CP 0
 245   275982.000    128441.000   -7.500
 246   275997.000    128447.000   -7.500
 247   276012.000    128453.000   -7.500
 248   275976.000    128392.000    3.000
 249   275990.000    128397.000   -2.450
 250   276003.000    128403.000   -4.000
 251   276016.000    128408.000   -5.450
 252   276030.000    128413.000   -4.250
 253   276044.000    128419.000   -7.500
 254   276057.000    128424.000    3.250
 255
 256 example of XYZ profile
 257 ----------------------
 258
 259 profile defined by two georeferenced extremities
 260 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 261
 262 *import from existing data file:*
 263 ::
 264
 265   B P
 266   CN profil_with_extremities
 267   CP 0 1
 268   CP +2.759820E05 +1.284410E05 +2.760570E05 +1.284240E05
 269   CP 2
 270     1.120  0.000 -1.250
 271     x y z values lines with y=0.0
 272     ...
 273
 274 The profile of name *profil_with_extremties* is vertical, is an open line of type spline.
 275 The two extremities are (+2.759820E05 +1.284410E05 0.0) and (+2.760570E05 +1.284240E05 0.0)
 276
 277 *export:*
 278 ::
 279
 280   B P
 281   CN profil_with_extremities
 282   CP 0 1
 283   CP   275982.000  128441.000    276057.000    128424.000
 284   CP 2
 285     1.120  0.000 -1.250
 286     x y z values lines with y=0.0
 287     ...
 288
 289 profile not georeferenced
 290 ~~~~~~~~~~~~~~~~~~~~~~~~~
 291
 292 *import from existing data file:*
 293 ::
 294
 295   B P
 296   CN profil_not_georeferenced
 297   CP 0 0
 298   CP 0.0 0.0 0.0 0.0
 299   CP 2
 300     -10.0  0.0  0.0
 301      -8.0  0.0 -5.0
 302       8.0  0.0 -5.0
 303      10.0  0.0  0.0
 304
 305 The profile of name *profil_not_georeferenced* is vertical, is an open line of type polyline.
 306 The 4 real parameters are null, meaning there are no georeferenced extremities.
 307
 308 *export:*
 309 ::
 310
 311   B P
 312   CN profil_not_georeferenced
 313   CP 0 0
 314   CP 0.0 0.0 0.0 0.0
 315   CP 2
 316     -10.0  0.0  0.0
 317      -8.0  0.0 -5.0
 318       8.0  0.0  5.0
 319      10.0  0.0  0.0
 320
 321 profile with fully georeferenced points
 322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 323
 324 *import from existing data file:*
 325 ::
 326
 327   B P
 328   CN profil_fully_georeferenced
 329   CP 0 1
 330   CP +1.00000E+02 +2.00000E+02  +1.00000E+01  +2.00000E+01
 331   CP 0
 332     275982.000    128441.000   -7.500
 333     x y z values lines
 334     ...
 335
 336 The profile of name *profil_fully_georeferenced* is defined in plane 0 (XoY),
 337 meaning all the points are fully georeferenced (x y z significants).
 338 The 4 real parameters are not used.
 339
 340 *export:*
 341 ::
 342
 343   B P
 344   CN profil_fully_georeferenced
 345   CP 0 1
 346   CP 0.0 0.0 0.0 0.0
 347   CP 0
 348     275982.000    128441.000   -7.500
 349     x y z values lines
 350     ...
 351
 352 example of XYZ curve
 353 --------------------
 354
 355 *import from existing data file:*
 356 ::
 357
 358   B C -3.333330E+03 +4.875000E+04 +0.000000E+00 +3.333330E+02 +1.666670E+02 +1.000000E+00 0.658992
 359   CN trait_cote_ile
 360   CP 1 1
 361   CP  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00  +0.000000E+00
 362   CP 0
 363   C
 364      211563.340     133489.165      8.750 A
 365      211604.013     133517.519      9.000 A
 366      211645.047     133544.734      9.100 A
 367      211684.597     133585.430      9.150 A
 368      211716.859     133584.277      9.050 A
 369      211777.488     133597.853      8.950 A
 370      211828.211     133609.896      9.000 A
 371      211896.886     133618.448      9.200 A
 372      211945.422     133633.990      9.250 A
 373      211996.891     133649.326      9.150 A
 374      212044.447     133622.576      9.050 A
 375      212067.681     133584.157      9.000 A
 376      212056.937     133521.369      9.000 A
 377      212007.716     133482.464      9.000 A
 378      211959.462     133428.999      9.000 A
 379      211925.576     133392.362      9.000 A
 380      211885.762     133376.207      9.000 A
 381      211817.310     133404.427      9.000 A
 382      211783.848     133416.811      9.000 A
 383      211742.545     133413.025      9.000 A
 384      211681.493     133421.775      9.000 A
 385      211644.814     133436.616      9.000 A
 386      211597.633     133447.736      9.000 A
 387      211569.826     133461.954      9.000 A
 388
 389 The curve of name *trait_cote_ile* is closed, of type spline, defined in plane XoY (XoY is the only possible value here).
 390 Other parameters are not used.
 391
 392 This 3D curve is converted in a polyline and a profile in HYDRO module:
 393
 394 * One polyline (with z=0).
 395 * One vertical profile (u,z) representing the altitude along the polyline defined above.
 396
 397 The u parameter of the vertical profile is the curvilign abcissa (in meters) along the isocontour.
 398
 399
 400 *export*
 401
 402 See isocontour and XYZ profile not georeferenced
 403
 404 example of isocontour
 405 ---------------------
 406
 407 *import from existing data file:*
 408 ::
 409
 410   B N -3.333330E+03 +4.875000E+04 +0.000000E+00 +3.333330E+02 +1.666670E+02 +1.000000E+00 0.658992
 411   CN trait_cote_ile
 412   CP 1 1
 413   CP 9.0
 414   CP 0
 415   C
 416      211563.340     133489.165      9.000 A
 417      211604.013     133517.519      9.000 A
 418      211645.047     133544.734      9.000 A
 419      211684.597     133585.430      9.000 A
 420      211716.859     133584.277      9.000 A
 421      211777.488     133597.853      9.000 A
 422      211828.211     133609.896      9.000 A
 423      211896.886     133618.448      9.000 A
 424      211945.422     133633.990      9.000 A
 425      211996.891     133649.326      9.000 A
 426      212044.447     133622.576      9.000 A
 427      212067.681     133584.157      9.000 A
 428      212056.937     133521.369      9.000 A
 429      212007.716     133482.464      9.000 A
 430      211959.462     133428.999      9.000 A
 431      211925.576     133392.362      9.000 A
 432      211885.762     133376.207      9.000 A
 433      211817.310     133404.427      9.000 A
 434      211783.848     133416.811      9.000 A
 435      211742.545     133413.025      9.000 A
 436      211681.493     133421.775      9.000 A
 437      211644.814     133436.616      9.000 A
 438      211597.633     133447.736      9.000 A
 439      211569.826     133461.954      9.000 A
 440
 441
 442 The isocontour of name *trait_cote_ile* is closed, of type spline, defined in plane XoY
 443 (XoY is the only possible value here).
 444 The constant altitude is 9.0. the Z values of the points are ignored.
 445
 446 This 3D curve is converted in a polyline and a profile in HYDRO module:
 447
 448 * One polyline (with z=0).
 449 * One vertical profile (u,z) representing the altitude along the polyline defined above, with a constant Z.
 450
 451 The u parameter of the vertical profile is the curvilign abcissa (in meters) along the isocontour.
 452
 453 *export of an isocontour with z=0:*
 454 ::
 455
 456   B N
 457   CN trait_cote_ile
 458   CP 1 1
 459   CP 0.0
 460   CP 0
 461   C
 462      211563.340     133489.165     0.000
 463      211604.013     133517.519     0.000
 464      211645.047     133544.734     0.000
 465      211684.597     133585.430     0.000
 466      211716.859     133584.277     0.000
 467      211777.488     133597.853     0.000
 468      211828.211     133609.896     0.000
 469      211896.886     133618.448     0.000
 470      211945.422     133633.990     0.000
 471      211996.891     133649.326     0.000
 472      212044.447     133622.576     0.000
 473      212067.681     133584.157     0.000
 474      212056.937     133521.369     0.000
 475      212007.716     133482.464     0.000
 476      211959.462     133428.999     0.000
 477      211925.576     133392.362     0.000
 478      211885.762     133376.207     0.000
 479      211817.310     133404.427     0.000
 480      211783.848     133416.811     0.000
 481      211742.545     133413.025     0.000
 482      211681.493     133421.775     0.000
 483      211644.814     133436.616     0.000
 484      211597.633     133447.736     0.000
 485      211569.826     133461.954     0.000
 486
 487
 488 See also XYZ profile not georeferenced
 489
 490
 491 Synthesis
 492 =========
 493
 494 In SALOME HYDRO module, when importing SinusX files,
 495
 496 - scatter plots are imported as Bathymetries,
 497 - isocontours are converted as polylines (z=0) and profiles not georeferenced (lines with z=constant),
 498 - XYZ curves are converted as polylines (z=0) and profiles not georeferenced (curvilign abcissa, z),
 499 - XYZ profiles with georeferenced extremities are imported as is (stream profiles for instance),
 500 - XYZ profiles with with fully georeferenced points are converted in profiles with georeferenced extremities (see stream profiles),
 501 - XYZ profiles not georeferenced are imported as is (used for section of a channel or embankment, or altitude line...),
 502 - **all points of XYZ curves and isocontour with z different of 0 are regrouped to build a Bathymetry field**,
 503   (Isocontour with z=0 are not significant in that case,
 504 - when 2 successive points have the same coordinates, the second point must be removed (there are some old data files with this problem).
 505
 506 When exporting SinusX files, all the polylines and profiles can be exported in a single file:
 507
 508 - polylines are exported as isocontour with z=0, (open or closed, spline or not),
 509   *(what about sections ? add a comment after the first point of a section?)*
 510 - profiles are exported as is, georeferenced or not...
 511 - **bathymetries are exported on demand (volume may be huge).**
 512
 513
 514 .. only:: html
 515
 516    :ref:`ref_english_formatsSpecs`