doc/3dformat-old.htm

   1 <!DOCTYPE HTML PUBLIC "-//W4C//DTD HTML 4.0 Transitional//EN">
   2 <HTML><HEAD>
   3 <TITLE>Survex 3d Format Specification (v3-v7)</TITLE>
   4 <STYLE type="text/css"><!--
   5 BODY, TD, TH, CENTER, UL, OL {font-family: sans-serif;}
   6 TD, TH {font-size: 11pt; vertical-align: top;}
   7 TH {white-space: nowrap; background-color: #ffc;}
   8 .code {text-align: center; white-space: nowrap;}
   9 .type {text-align: center; white-space: nowrap;}
  10 .data {text-align: left; white-space: nowrap;}
  11 .desc {text-align: left; white-space: wrap;}
  12 .version {text-align: center; white-space: wrap;}
  13 TH.data, TH.desc {text-align: center;}
  14 .reserved {background-color: #ddd;}
  15 -->
  16 </STYLE>
  17 </HEAD><BODY BGCOLOR=white TEXT=black>
  18 <H1>Survex 3d Format Specification (v3-v7)</H1>
  19
  20 <P>If you're writing in C or C++ it's <b>strongly</b> recommended
  21 that you use the img routine provided with Survex to read and write
  22 3d files.  Doing so means that you can take advantage of any revisions
  23 to the 3d format by simply rebuilding your software with the updated
  24 img routines, rather than having to update your own code.  It also
  25 allows you to read a sub-set of the data in the file, restricted by
  26 Survey prefix.</P>
  27
  28 <P>This document only describes 3d format revisions 3 to 7 (inclusive).
  29 Newer versions are described in a <a href="3dformat.htm">separate document</a>.
  30 Older format versions are only documented by the code to read them in img.c -
  31 they had version strings "v0.01", "Bv0.01", "bv0.01", and "v2").
  32 </P>
  33
  34 <P>The following table document which Survex versions generate which 3d file
  35 format versions.  A version is able to read the format it generates and any
  36 older versions, but in addition Survex 1.0.40 has support for reading all
  37 versions up to v7 (but writes v3).
  38
  39 <table border="1" cellpadding="1" cellspacing="0" width="*">
  40 <tr>
  41     <th class="version">Format</th>
  42     <th class="version" colspan=2>Survex versions</th>
  43 </tr>
  44 <tr>
  45     <td class="version">v3</td>
  46     <td class="version">0.97</td>
  47     <td class="version">1.0.40</td>
  48 </tr>
  49 <tr>
  50     <td class="version">v4</td>
  51     <td class="version">1.1.0</td>
  52     <td class="version">1.1.3</td>
  53 </tr>
  54 <tr>
  55     <td class="version">v5</td>
  56     <td class="version">1.1.4</td>
  57     <td class="version">1.1.10</td>
  58 </tr>
  59 <tr>
  60     <td class="version">v6</td>
  61     <td class="version">1.1.11</td>
  62     <td class="version">1.1.14</td>
  63 </tr>
  64 <tr>
  65     <td class="version">v7</td>
  66     <td class="version">1.1.15</td>
  67     <td class="version">1.2.6</td>
  68 </tr>
  69 </table>
  70
  71 <P>If you try to use this specification and find details which aren't
  72 spelled out clearly enough (or at all!) or any errors, please let us know.
  73 At least two people have successfully written code to read 3d files
  74 using this document, but that doesn't mean it can't be improved.
  75 </P>
  76
  77 <H2>File Header</H2>
  78
  79 <P>This consists of:</P>
  80
  81 <ul>
  82 <li>File ID: the string "Survex 3D Image File" followed by a linefeed
  83 (decimal 10, hex 0a). [Note: v0.01 files can have a carriage return
  84 before this and other linefeeds - this is a file format error in any
  85 other format version].
  86 <li>File format version: "v3", "v4", "v5", "v6", "v7" followed by a linefeed.
  87 Any future versions will be "v8", "v9", "v10", "v11", etc.
  88 <li> Survey title: A string followed by a linefeed.  There's no length limit on this string.
  89 <li> Timestamp: A string followed by a linefeed.  This is intended to be the
  90 time the file was generated, rather than the time the survey data was
  91 collected.  The easiest way to generate this is with the strftime() format
  92 "%a,%Y.%m.%d %H:%M:%S %Z" if you have access to strftime().  An example
  93 timestamp is "Sun,2002.03.17 14:01:07 GMT".
  94 </ul>
  95
  96 <H2>Items</H2>
  97
  98 <P>Following the header are a number of items.  The last item must be a 0x00
  99 byte when the current label is empty, which marks the end of the data.  The
 100 first byte of an item is a code identifying what the item is:</P>
 101
 102 <table border="1" cellpadding="1" cellspacing="0" width="100%">
 103 <tr>
 104     <th class="code">Code</th>
 105     <th class="code">Type</th>
 106     <th class="data">Data</th>
 107     <th class="desc" colspan="2">Meaning</th>
 108     <th class="version">Version</th>
 109 </tr>
 110 <tr>
 111     <td class="code">0x00</td>
 112     <td class="type">STOP</td>
 113     <td class="data">&nbsp;</td>
 114     <td class="desc" colspan="2">
 115     If the current label is empty, signifies the end of the data in the 3d
 116     file; if the current label isn't empty, make it empty.</td>
 117     <td class="version">&ge;3</td>
 118 </tr>
 119 <tr>
 120     <td class="code">0x01 - 0x0e</td>
 121     <td class="type">TRIM</td>
 122     <td class="data">&nbsp;</td>
 123     <td class="desc" colspan="2">
 124     Trim the last 16 characters of the current label, then trim back N (i.e.
 125     1-14) dots ("."), everything after that particular dot.
 126     It's incorrect if the label ends up empty, or you attempt to trim more
 127     label than there is. The rationale for removing 16 characters first is
 128     that removal of 1-16 characters can be encoded by 0x10-0x1f (see below)
 129     and we can make this encoding more powerful by not
 130     overlapping what can be encoded.</td>
 131     <td class="version">&ge;3</td>
 132 </tr>
 133 <tr>
 134     <td class="code">0x0f</td>
 135     <td class="type">MOVE</td>
 136     <td class="data">&lt;x&gt; &lt;y&gt; &lt;z&gt;</td>
 137     <td class="desc" colspan="2">
 138     Set current position to the coordinates given. Coordinates
 139     are 4 byte little-endian signed integers representing
 140     values in centimetres (0.01 metres).</td>
 141     <td class="version">&ge;3</td>
 142 </tr>
 143 <tr>
 144     <td class="code">0x10 - 0x1f</td>
 145     <td class="type">TRIM</td>
 146     <td class="data">&nbsp;</td>
 147     <td colspan="2">
 148     Remove N-15 (i.e. 1-16) characters from the current label. It's
 149     incorrect if the label ends up empty, or you attempt to trim more label
 150     than there is.</td>
 151     <td class="version">&ge;3</td>
 152 </tr>
 153 <tr>
 154     <td class="code">0x20</td>
 155     <td class="type">DATE (old version)</td>
 156     <td class="data">&lt;date&gt;</td>
 157     <td colspan="2">
 158     Set survey date of legs: date is 4 byte little-endian unsigned integer
 159     counting seconds since 1970.</td>
 160     <td class="version">&ge;4 and &le;6</td>
 161 </tr>
 162 <tr>
 163     <td class="code">0x20</td>
 164     <td class="type">DATE</td>
 165     <td class="data">&lt;date&gt;</td>
 166     <td colspan="2">
 167     Set survey date of legs: date is a 2 byte little-endian unsigned integer
 168     counting days from the
 169     start of 1900.</td>
 170     <td class="version">&ge;7</td>
 171 </tr>
 172 <tr>
 173     <td class="code">0x21</td>
 174     <td class="type">DATE (old version)</td>
 175     <td class="data">&lt;date1&gt;&lt;date2&gt;</td>
 176     <td colspan="2">
 177     Set survey date of legs to a range: date1, date2 are 4 byte little-endian
 178     unsigned integer counting seconds since 1970.</td>
 179     <td class="version">&ge;4 and &le;6</td>
 180 </tr>
 181 <tr>
 182     <td class="code">0x21</td>
 183     <td class="type">DATE</td>
 184     <td class="data">&lt;date1&gt;&lt;datespan&gt;</td>
 185     <td colspan="2">
 186     Set survey date of legs to a range: date1 is a
 187     2 byte little-endian unsigned integer counting days since the start of
 188     1900, and datespan is an unsigned byte counting days from date1.</td>
 189     <td class="version">&ge;7</td>
 190 </tr>
 191 <tr>
 192     <td class="code">0x22</td>
 193     <td class="type">ERROR</td>
 194     <td class="data">&lt;legs&gt;&lt;length&gt;&lt;E&gt;&lt;H&gt;&lt;V&gt;</td>
 195     <td colspan="2">
 196     Error information for the current traverse.  &lt;legs&gt; is the number of
 197     legs. &lt;length&gt; is the total length of the
 198     traverse in cm (0.01m). E, H and V are the error and the horizontal and
 199     vertical components in cm. (All values are 4 byte little-endian signed integers) </td>
 200     <td class="version">&ge;6</td>
 201 </tr>
 202 <tr>
 203     <td class="code">0x23</td>
 204     <td class="type">DATE</td>
 205     <td class="data">&lt;date1&gt;&lt;date2&gt;</td>
 206     <td colspan="2">
 207     Set survey date of legs to a range: date1, date2 are
 208     2 byte little-endian unsigned integers counting days since the
 209     start of 1900.</td>
 210     <td class="version">&ge;7</td>
 211 </tr>
 212 <tr>
 213     <td class="code">0x24</td>
 214     <td class="type">DATE</td>
 215     <td class="data">&nbsp;</td>
 216     <td colspan="2">
 217     No survey date information was specified.</td>
 218     <td class="version">&ge;7</td>
 219 </tr>
 220 <tr class="reserved">
 221     <td class="code">0x25 - 0x2f</td>
 222     <td class="type">&nbsp;</td>
 223     <td class="data">&nbsp;</td>
 224     <td colspan="3">Reserved</td>
 225 </tr>
 226 <tr>
 227     <td class="code" rowspan="3">0x30 - 0x31</td>
 228     <td class="type" rowspan="3">XSECT</td>
 229     <td class="data" rowspan="3">&lt;len&gt; &lt;label&gt; &lt;L&gt; &lt;R&gt; &lt;U&gt; &lt;D&gt;</td>
 230     <td colspan="2">
 231     Dimensions are 2 byte little-endian signed integers representing values
 232     in centimetres (0.01 metres). Omitted dimensions are encoded as 0xffff.
 233     Station flags are (N &amp; 0x01): </td>
 234     <td class="version" rowspan="3">&ge;5</td>
 235 </tr>
 236 <tr>
 237     <th>Flag (N &amp; 0x01)</th>
 238     <th>Meaning</th>
 239 </tr>
 240 <tr>
 241     <td>0x01</td>
 242     <td>Station is last one in this passage</td>
 243 </tr>
 244 <tr>
 245     <td class="code" rowspan="3">0x32 - 0x33</td>
 246     <td class="type" rowspan="3">XSECT</td>
 247     <td class="data" rowspan="3">&lt;len&gt; &lt;label&gt; &lt;L&gt; &lt;R&gt; &lt;U&gt; &lt;D&gt;</td>
 248     <td colspan="2">
 249     Dimensions are 4 byte little-endian signed integers representing values
 250     in centimetres (0.01 metres). Omitted dimensions are encoded as
 251     0xffffffff.</td>
 252     <td class="version" rowspan="3">&ge;5</td>
 253 </tr>
 254 <tr>
 255     <th>Flag (N &amp; 0x01)</th>
 256     <th>Meaning</th>
 257 </tr>
 258 <tr>
 259     <td>0x01</td>
 260     <td>Station is last one in this passage</td>
 261 </tr>
 262 <tr class="reserved">
 263     <td class="code">0x34 - 0x3f</td>
 264     <td class="type">&nbsp;</td>
 265     <td class="data">&nbsp;</td>
 266     <td colspan="3">Reserved</td>
 267 </tr>
 268 <!-- Checked to here! -->
 269 <tr>
 270     <td class="code" rowspan="13">0x40 - 0x7f</td>
 271     <td class="type" rowspan="13">LABEL</td>
 272     <td class="data" rowspan="13">&lt;len&gt; &lt;label&gt; &lt;x&gt; &lt;y&gt; &lt;z&gt;</td>
 273     <td colspan="2">
 274     Append label to the current label buffer. The updated contents of the
 275     label buffer give the survey stations full name. The length of label is
 276     given by length, which is encoded as follows:</td>
 277     <td class="version" rowspan="12">&ge;3</td>
 278 </tr>
 279 <tr>
 280     <th>Length</th>
 281     <th>Encoding</th>
 282 </tr>
 283 <tr>
 284     <td>0 - 253</td>
 285     <td>byte 0x00 - 0xfd</td>
 286 </tr>
 287 <tr>
 288     <td>254-65789</td>
 289     <td>byte 0xfe 2 byte little-endian unsigned integer len-254 0x0000-0xffff</td>
 290 </tr>
 291 <tr>
 292     <td>65790 and greater</td>
 293     <td>byte 0xff 4 byte little-endian unsigned integer len
 294     0x000100fd-0xffffffff</td>
 295 </tr>
 296 <tr>
 297     <td colspan="2">
 298     The station flags are encoded in the bottom 6 bits of the item code:</td>
 299 </tr>
 300 <tr>
 301     <th>Flag (N &amp; 0x3f)</th>
 302     <th>Meaning</th>
 303 </tr>
 304 <tr>
 305     <td>0x01</td>
 306     <td>Station is on leg above ground</td>
 307 </tr>
 308 <tr>
 309     <td>0x02</td>
 310     <td>Station is on an underground leg (both may be true at an entrance)</td>
 311 </tr>
 312 <tr>
 313     <td>0x04</td>
 314     <td>Station is marked as an entrance (with *entrance)</td>
 315 </tr>
 316 <tr>
 317     <td>0x08</td>
 318     <td>Station is exported (i.e. may be used as a connection point to other
 319     surveys)</td>
 320 </tr>
 321 <tr>
 322     <td>0x10</td>
 323     <td>Station is a fixed point (control point)</td>
 324 </tr>
 325 <tr class="reserved">
 326     <td>0x20</td>
 327     <td colspan="2">Reserved</td>
 328 </tr>
 329 <tr>
 330     <td class="code" rowspan="8">0x80 - 0xbf</td>
 331     <td class="type" rowspan="8">LINE</td>
 332     <td class="data" rowspan="8">&lt;len&gt; &lt;label&gt; &lt;x&gt; &lt;y&gt; &lt;z&gt;</td>
 333     <td colspan="2">
 334     Append label to the current label buffer. The length of the label is
 335     encoded as for a station label above. Return leg from current position
 336     to coordinates given, and update current position to coordinates given.
 337     The updated contents of the label buffer give the survey that the leg is
 338     in.</td>
 339     <td class="version" rowspan="5">&ge;3</td>
 340 </tr>
 341 <tr>
 342     <th>Flag (N &amp; 0x3f)</th>
 343     <th>Meaning</th>
 344 </tr>
 345 <tr>
 346     <td>0x01</td>
 347     <td>Leg is above ground</td>
 348 </tr>
 349 <tr>
 350     <td>0x02</td>
 351     <td>Leg duplicates data in another leg (e.g. resurvey along a passage to
 352     tie into a known station)</td>
 353 </tr>
 354 <tr>
 355     <td>0x04</td>
 356     <td>Leg is a splay shot in a chamber (radial shots from a central point)</td>
 357 </tr>
 358 <tr class="reserved">
 359     <td>0x08</td>
 360     <td colspan="2">Reserved</td>
 361 </tr>
 362 <tr class="reserved">
 363     <td>0x10</td>
 364     <td colspan="2">Reserved</td>
 365 </tr>
 366 <tr class="reserved">
 367     <td>0x20</td>
 368     <td colspan="2">Reserved</td>
 369 </tr>
 370 <tr class="reserved">
 371     <td class="code">0xc0 - 0xff</td>
 372     <td class="type">&nbsp;</td>
 373     <td class="data">&nbsp;</td>
 374     <td colspan="3">Reserved</td>
 375 </tr>
 376 </table>
 377
 378 <H2>Item order</H2>
 379 <ul>
 380 <li>A continuous section of centreline is defined by a &lt;MOVE&gt; item, followed
 381 by one or more &lt;LINE&gt; items.</li>
 382 <li>&lt;LABEL&gt; items may appear anywhere in the file after the header,
 383 including within a &lt;MOVE&gt;&lt;LINE&gt;... sequence.</li>
 384 <li>Duplicate &lt;LABEL&gt; items are permitted provided they also have identical
 385 coordinate values. (The same coordinate values may also be shared by any
 386 number of different &lt;LABEL&gt; items).</li>
 387 <li>Stations must be defined in a &lt;LABEL&gt; item <u>before</u> being
 388 referenced (e.g. in &lt;XSECT&gt; items)</li>
 389 </ul>
 390
 391 <P>Authors: Olly Betts and Mike McCombe, last updated: 2013-07-05</P>
 392 </BODY></HTML>