doc/salome/tutorial/english/english_format_sinusx.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 Interpretation of the SinusX format: historic (for old files)
  21 #############################################################
  22
  23 File structure and line types
  24 =============================
  25 The ASCII file is structured in data blocks.
  26
  27 The lines that start with *B* are block limiters.
  28
  29 The lines starting with *CN* or *CP* complete the block definition.
  30
  31 The other lines starting with *C* are comments.
  32
  33 The lines that start with numbers are the block pointers.
  34
  35 It is possible to describe scatter plots, xyz curves, profiles and isocontours.
  36
  37 Depending on the format, the curves may or may not be connected and may be closed or open.
  38 In practice, a curve that is not connected is a type of scatter plot...
  39 The SALOME HYDRO module takes into account xyz points, curves in the XOY plane (z=0)
  40 and curves in the XOZ plane (profiles).
  41 Three types of processing can be used to handle curves in space (any Z, variable or not)
  42 during import in the HYDRO module:
  43
  44 * Projection at z=0 to have a connected curve in the XOY plane.
  45 * Creation of a line in the XOZ plane (curvilinear abscissa for the XOY curve, altitude).
  46 * Import of x,y,z points that are not connected as Bathymetry/altimetry
  47
  48 The first import is the most important and should be done systematically.
  49
  50 The second is useful for xyz curves, where Z is variable.
  51
  52 The third is not easy to use directly in the HYDRO module, beyond the simple visualisation
  53 of the Bathymetry/altimetry point fields in 3D. The contour of the Bathymetry/altimetry
  54 field in the XOY plane is needed for the nodal interpolation of the altitude; however,
  55 it makes no real linear sense. On the other, a Bathymetry/altimetry can be
  56 reconstituted by combining the points of several lines (for example, a series of isocontours)
  57 in a single point cloud.
  58
  59 Block delimiter
  60 ===============
  61
  62 ::
  63
  64   B type x1 y1 z1 dx dy dz scale
  65
  66 type
  67 ----
  68
  69 * type = S scatterplot
  70 * type = C xyz curve
  71 * type = P xyz profile
  72 * type = N isocontour
  73
  74 x1 y1 z1 dx dy dz scale
  75 -------------------------
  76
  77 Origin and deltas for conversion of measurements to metres in the table to be digitized.
  78
  79 This is ignored on import
  80
  81 examples of B-type lines
  82 ------------------------
  83
  84 ::
  85
  86   B S +4.290000E+05 +2.420000E+05 +0.000000E+00 +1.500000E+03 +2.000000E+03 +1.000
  87   B N +0.000000E+00 +0.000000E+00 +0.000000E+00 +1.000000E+00 +1.000000E+00 +1.000000E+00 1
  88   B C +0.000000E+00 +0.000000E+00 +0.000000E+00 +1.000000E+00 +1.000000E+00 +1.000000E+00 1
  89   B C +0.000000E+00 +0.000000E+00 +0.000000E+00 +3.200000E+04 +2.400000E+04 +1.000
  90   B C -3.333333E+03 +4.875000E+04 +0.000 A000E+00 +3.333330E+02 +1.666670E+02 +1.000000E+00 0.659154
  91   B C -3.333330E+03 +4.875000E+04 +0.000 A000E+00 +3.333330E+02 +1.666670E+02 +1.000000E+00 0.658869
  92
  93 export
  94 ------
  95
  96 ::
  97
  98   B type   0.0  0.0  0.0    1.0  1.0  1.0    1.0
  99
 100 or, preferably, just
 101
 102 ::
 103
 104   B type
 105
 106
 107 Data Block Name
 108 ===============
 109
 110 ::
 111
 112   CN the_block_name
 113
 114 Import
 115 ------
 116 Replace spaces by an underscore ‘_’ (example: curve 1 -> curve_1)
 117
 118 Export
 119 ------
 120
 121 Names of the objects in the HYDRO module.  Avoid the use of spaces and accented characters in the names.
 122
 123 Closure connection
 124 ==================
 125
 126 Historical definition
 127 ---------------------
 128
 129 ::
 130
 131   CP closed connection
 132
 133 Two booleans indicate whether the curve is closed or not and whether the points are connected
 134
 135 *example*: CP 0 1: open curve, linked points.
 136
 137 In practice, there should be no need for unconnected points, except for the scatter plots
 138
 139 Interpretation proposition and export
 140 -------------------------------------
 141
 142 ::
 143
 144   CP closed spline
 145
 146 Two booleans indicate whether the curve is closed and whether it is the spline or broken-line type.
 147 The existing data sets for the closed curves and the polygons have to be corrected manually.
 148
 149 Definition plane
 150 ================
 151
 152 ::
 153
 154   CP PlaneNumber
 155
 156 The plane number is entered as 0, 1 or 2 (0: XOY plane, 1: YOZ plane, 2: XOZ plane).
 157
 158 Most data blocks are in the XOY plane: CP 0
 159
 160 Plane numbers 1 or 2 serve to define profiles / sections in a normal plane to the hydraulic axis,
 161 with two useful coordinates. In practice, plane 2 will be used systematically.
 162
 163 Additional block-type related parameters
 164 ========================================
 165
 166 type = S scatterplot
 167 --------------------
 168
 169 Not applicable
 170
 171 type = C xyz curve
 172 ------------------
 173
 174 ::
 175
 176   CP (16 real indicators)
 177
 178 Not used – not interpreted on import.
 179
 180 Either a compatible export is made:
 181
 182 ::
 183
 184  CP 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
 185
 186 Or nothing is input here: preferable.
 187
 188 type = P xyz profile
 189 -------------------
 190
 191 Historical definition
 192 ~~~~~~~~~~~~~~~~~~~~~
 193
 194 ::
 195
 196   CP Zref Xref dz dx
 197
 198 TO BE COMPLETED
 199
 200 Proposed interpretation for a profile in the *XOZ* plan
 201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 202 In practice, this is a profile in the vertical plane with the georeferenced
 203 positions of the two extremities given. It is assumed that the third coordinate of the points is 0.
 204
 205 ::
 206
 207   CP Xorig Yorig Xend Yend
 208
 209 (Xorig, Yorig) and (Xend, Yend) are the georeferenced positions of the profile endpoints.
 210
 211 We go from a point (x, z) to the georeferenced point (ref +x*dx, yref +x*dy, z), with (dx, dy)
 212 the normalized horizontal vector calculated from the two georeferenced end-points.
 213
 214 Proposed interpretation for a profile in the XOY plan
 215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 216 The points are assumed to be already georeferenced, each with three valid coordinates.
 217
 218 Several profiles can be grouped together in SALOME HYDRO to create a river object ('stream').
 219
 220 type = N isocontour
 221 -------------------
 222
 223 ::
 224
 225   CP altitude
 226
 227 Altitude of the isocontour. This is the Z-coordinate value of each point.
 228
 229 Import: take this value as reference, ignoring the Z coordinate of individual points (FIXME: always the same value in the examples?)
 230
 231 Comment lines
 232 =============
 233
 234 ::
 235
 236   C any text
 237
 238 Ignored on import
 239
 240 Export information that needs to be defined can be put in the file header, for example:
 241
 242 C SALOME HYDRO version xxx
 243
 244 C name of the SALOME study
 245
 246 C date
 247
 248 Point lines
 249 ===========
 250
 251 ::
 252
 253   X Y Z text key
 254
 255 key
 256 ---
 257
 258 Not used, ignore
 259
 260 text
 261 ----
 262
 263 A label associated with the point: not used, ignore
 264
 265 import
 266 ------
 267 For isocontours, the Z value can be ignored, as it is defined at block level.
 268
 269 When two consecutive points have the same coordinates (which may occur with
 270 some data sets), the second point should be ignored.
 271
 272 export
 273 ------
 274 Depending on the nature of the curves, the unnecessary coordinate is set to zero.
 275 Note: imported isocontours are converted to curves in the Z=0 plane and grouped together in scatter
 276 plots. The isocontour information is lost in SALOME and it is not possible to export them as isocontours with the altitude entered.
 277
 278 For curves projected in the XOY plane::
 279
 280   X Y 0.0
 281
 282 For curves projected in the XOZ plane::
 283
 284   X 0.0 Z
 285
 286 For the XOY georeferenced profiles::
 287
 288   X Y Z
 289
 290 XYZ curve example
 291 =================
 292
 293 This is actually an isocontour with Z=9.0, though not defined as such.
 294
 295 import
 296 ------
 297
 298 ::
 299
 300   B C -3.333330E+03 +4.875000E+04 +0.000000E+00 +3.333330E+02 +1.666670E+02 +1.000000E+00 0.658992
 301   CN island_shore_line
 302   CP 1 1
 303   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
 304   CP 0
 305   C
 306      211563.340     133489.165      9.000 A
 307      211604.013     133517.519      9.000 A
 308      211645.047     133544.734      9.000 A
 309      211684.597     133585.430      9.000 A
 310      211716.859     133584.277      9.000 A
 311      211777.488     133597.853      9.000 A
 312      211828.211     133609.896      9.000 A
 313      211896.886     133618.448      9.000 A
 314      211945.422     133633.990      9.000 A
 315      211996.891     133649.326      9.000 A
 316      212044.447     133622.576      9.000 A
 317      212067.681     133584.157      9.000 A
 318      212056.937     133521.369      9.000 A
 319      212007.716     133482.464      9.000 A
 320      211959.462     133428.999      9.000 A
 321      211925.576     133392.362      9.000 A
 322      211885.762     133376.207      9.000 A
 323      211817.310     133404.427      9.000 A
 324      211783.848     133416.811      9.000 A
 325      211742.545     133413.025      9.000 A
 326      211681.493     133421.775      9.000 A
 327      211644.814     133436.616      9.000 A
 328      211597.633     133447.736      9.000 A
 329      211569.826     133461.954      9.000 A
 330
 331
 332 ``B C -3.3...``
 333   block type C (xyz curve), digitization parameters ignored
 334
 335 ``CN ...``
 336   block name = island_shore_line
 337
 338 ``CP 1 1``
 339   closed curve, spline
 340
 341 ``CP +0.0...``
 342   ignored``CP 0``
 343
 344 ``CP 0``
 345   plan XoY (ça doit toujours être le plan 0)
 346
 347 ``C ...``
 348   the comments are ignored
 349
 350 ``211563.340     133489.165      9.000 A``
 351   x, y, z point data. The additional information is ignored.
 352
 353 If all the Z values of the block are zero, they are ignored.
 354 If at least one Z coordinate of the block has a non-zero value, then
 355 the points supply a scatter plot containing the data points of the different file curves.
 356
 357 export
 358 ------
 359 A curve projected in the XOY plane in the form of an isocontour at Z = 0.
 360 It is a closed, spline curve.
 361
 362 ::
 363
 364   B N
 365   CN island_shore_line
 366   CP 1 1
 367   CP 0.0
 368   CP 0
 369   C
 370      211563.340     133489.165     0.000
 371      211604.013     133517.519     0.000
 372      211645.047     133544.734     0.000
 373      211684.597     133585.430     0.000
 374      211716.859     133584.277     0.000
 375      211777.488     133597.853     0.000
 376      211828.211     133609.896     0.000
 377      211896.886     133618.448     0.000
 378      211945.422     133633.990     0.000
 379      211996.891     133649.326     0.000
 380      212044.447     133622.576     0.000
 381      212067.681     133584.157     0.000
 382      212056.937     133521.369     0.000
 383      212007.716     133482.464     0.000
 384      211959.462     133428.999     0.000
 385      211925.576     133392.362     0.000
 386      211885.762     133376.207     0.000
 387      211817.310     133404.427     0.000
 388      211783.848     133416.811     0.000
 389      211742.545     133413.025     0.000
 390      211681.493     133421.775     0.000
 391      211644.814     133436.616     0.000
 392      211597.633     133447.736     0.000
 393      211569.826     133461.954     0.000
 394
 395
 396 Isocontour example
 397 ==================
 398
 399 Using the data from the example above, the curve type is changed: B N instead of B C
 400 and the altitude is indicated in the header: CP 9.0.
 401
 402 import
 403 ------
 404
 405 ::
 406
 407   B N -3.333330E+03 +4.875000E+04 +0.000000E+00 +3.333330E+02 +1.666670E+02 +1.000000E+00 0.658992
 408   CN island_shore_line
 409   CP 1 1
 410   CP 9.0
 411   CP 0
 412   C
 413      211563.340     133489.165      9.000 A
 414      211604.013     133517.519      9.000 A
 415      211645.047     133544.734      9.000 A
 416      211684.597     133585.430      9.000 A
 417      211716.859     133584.277      9.000 A
 418      211777.488     133597.853      9.000 A
 419      211828.211     133609.896      9.000 A
 420      211896.886     133618.448      9.000 A
 421      211945.422     133633.990      9.000 A
 422      211996.891     133649.326      9.000 A
 423      212044.447     133622.576      9.000 A
 424      212067.681     133584.157      9.000 A
 425      212056.937     133521.369      9.000 A
 426      212007.716     133482.464      9.000 A
 427      211959.462     133428.999      9.000 A
 428      211925.576     133392.362      9.000 A
 429      211885.762     133376.207      9.000 A
 430      211817.310     133404.427      9.000 A
 431      211783.848     133416.811      9.000 A
 432      211742.545     133413.025      9.000 A
 433      211681.493     133421.775      9.000 A
 434      211644.814     133436.616      9.000 A
 435      211597.633     133447.736      9.000 A
 436      211569.826     133461.954      9.000 A
 437
 438
 439 ``B N -3.3...``
 440   block type N (isocontour), digitization parameters ignored
 441
 442 ``CN ...``
 443   block name = island_shore_line
 444
 445 ``CP 1 1``
 446   closed curve, spline
 447
 448 ``CP 9.0``
 449   curve altitude
 450
 451 ``CP 0``
 452   XoY plane
 453
 454 ``C ...``
 455   the comments are ignored
 456
 457 ``211563.340     133489.165      9.000 A``
 458   x, y, z point data. The additional information is ignored.
 459
 460 The Z point values are ignored. The scatter plots are supplied with the
 461 curve points, with z forced to 9.0.
 462
 463 export
 464 ------
 465
 466 A curve, projected in the XOY plane in the form of a curve at Z = 0.
 467 It is a closed, spline curve.
 468
 469 ::
 470
 471   B N
 472   CN island_shore_line
 473   CP 1 1
 474   CP 0.0
 475   CP 0
 476   C
 477      211563.340     133489.165     0.000
 478      211604.013     133517.519     0.000
 479      211645.047     133544.734     0.000
 480      211684.597     133585.430     0.000
 481      211716.859     133584.277     0.000
 482      211777.488     133597.853     0.000
 483      211828.211     133609.896     0.000
 484      211896.886     133618.448     0.000
 485      211945.422     133633.990     0.000
 486      211996.891     133649.326     0.000
 487      212044.447     133622.576     0.000
 488      212067.681     133584.157     0.000
 489      212056.937     133521.369     0.000
 490      212007.716     133482.464     0.000
 491      211959.462     133428.999     0.000
 492      211925.576     133392.362     0.000
 493      211885.762     133376.207     0.000
 494      211817.310     133404.427     0.000
 495      211783.848     133416.811     0.000
 496      211742.545     133413.025     0.000
 497      211681.493     133421.775     0.000
 498      211644.814     133436.616     0.000
 499      211597.633     133447.736     0.000
 500      211569.826     133461.954     0.000
 501
 502 Curve projected in the XOZ plane along the curvilinear abscissa.
 503 This is an open, spline-type curve, defined by convention in the XOZ plane.
 504
 505 ::
 506
 507   B P
 508   CN altitude_island_shore_line
 509   CP 0 1
 510   CP 0.0 0.0 0.0 0.0
 511   CP 2
 512   C
 513     0.0 9.0
 514     ...
 515     x   9.0
 516
 517 *The ends are not georeferenced; they are defined with respect to another XOY curve.*
 518 To distinguish the XOZ profiles that are not georeferenced from those that
 519 are (by endpoints), a specific value with null coordinates is used for the CP field::
 520
 521   CP 0.0 0.0 0.0 0.0
 522
 523 The x values of the curvilinear abscissae are expressed in metres along
 524 the curve or normalized between 0 and 1. **To be reviewed**.
 525
 526 Summary
 527 =======
 528
 529 In the SALOME HYDRO module, when existing SinusX files are imported:
 530
 531 - scatter plots are imported as Bathymetries.
 532 - isocontours are converted to curves at Z=0 and non-georeferenced profiles
 533   profiles in the XOZ plane (curvilinear abscissa, z).
 534 - XYZ curves are converted to curves at Z=0 and profiles that are not
 535   georeferenced in the XOZ plane (curvilinear abscissa, z).
 536 - XOZ profiles georeferenced by endpoint coordinates are converted into
 537   profiles whose points are all defined by their X, Y, Z coordinates (XOY profiles).
 538 - XOZ profiles that are not georeferenced are imported as is (used as a line
 539   of altitude for another line in the XOY plane or as a section for a channel, embankment, etc.)
 540 - the XOY profiles are kept as such (all points are defined by their respective
 541   X, Y, Z coordinates).
 542 - All the point data of the isocontours (with non-zero Z values) and xyz
 543   curves are used to create a Bathymetry field.
 544
 545 During file export,
 546
 547 - the polylines are exported as zero-level isocontours, open or closed, spline
 548   or broken line. (What is done with the sections? Use a beginning of section comment on the point?)
 549 - the profiles are exported as such (to be developed)
 550 - Should bathymetries be exported in SinusX format or in xyz format?
 551   (only differs by the presence of a header line)
 552 - Dans le module HYDRO de SALOME, lors de l'importation des fichiers SinusX existant,
 553
 554
 555 .. only:: html
 556
 557    :ref:`ref_formatsSpecs`