| [2d82f2a] | 1 | <HTML><HEAD> |
|---|
| 2 | <TITLE>Survex 3d Format Specification</TITLE> |
|---|
| 3 | <STYLE type="text/css"><!-- |
|---|
| 4 | BODY, TD, CENTER, UL, OL {font-family: sans-serif;} |
|---|
| 5 | --> |
|---|
| 6 | </STYLE> |
|---|
| 7 | </HEAD><BODY BGCOLOR=white TEXT=black> |
|---|
| 8 | <H1>Warning - Very Provisional</H1> |
|---|
| 9 | |
|---|
| [a6907d1] | 10 | This is an <b>early draft</b> of this specification, and I've had to reverse |
|---|
| [2d82f2a] | 11 | engineer it from the code. It may be incorrect in places, and I certain |
|---|
| 12 | there's a lot of knowledge this document assumes, especially if you aren't |
|---|
| 13 | familiar with Survex. |
|---|
| 14 | |
|---|
| 15 | <H1>Survex 3d Format Specification</H1> |
|---|
| 16 | |
|---|
| 17 | <P>If you're writing in C or C++ it's <b>strongly</b> recommended that you use |
|---|
| 18 | the img routine provided with Survex to read and write 3d files. Doing so |
|---|
| 19 | means that you can take advantage of any revisions to the 3d format by simply |
|---|
| 20 | rebuilding your software with the updated img routines, rather than having to |
|---|
| 21 | update your own code. It also allows you to read a sub-set of the data in |
|---|
| 22 | the file, restricted by Survey prefix.</P> |
|---|
| 23 | |
|---|
| 24 | <P>This document only describes the most recent revision of the 3d format |
|---|
| 25 | (version 3), which is produced by Survex versions 0.97 and later.</P> |
|---|
| 26 | |
|---|
| 27 | <H2>File Header</H2> |
|---|
| 28 | |
|---|
| 29 | <P>This consists of: |
|---|
| 30 | |
|---|
| 31 | <ul> |
|---|
| 32 | <li> File ID: the string "Survex 3D Image File" followed by a linefeed (decimal 10, hex x0a) |
|---|
| 33 | <li> File format version: "v3" followed by a linefeed. Valid values for |
|---|
| 34 | older format versions are ("v0.01", "Bv0.01", "bv0.01", "v2"). Newer versions |
|---|
| 35 | will be "v4", "v5", ..., "v10", "v11", etc. |
|---|
| 36 | <li> Survey title: A string followed by a linefeed. There's no length limit on this string. |
|---|
| [429121e] | 37 | <li> Timestamp: A string followed by a linefeed. This is intended to be the |
|---|
| 38 | time the file was generated, rather than the time the survey data was |
|---|
| 39 | collected. The easiest way to generate this is with the strftime() format |
|---|
| 40 | "%a,%Y.%m.%d %H:%M:%S %Z" if you have access to strftime(). An example |
|---|
| 41 | timestamp is "Sun,2002.03.17 14:01:07 GMT". |
|---|
| [2d82f2a] | 42 | </ul> |
|---|
| 43 | |
|---|
| 44 | <H2>Items</H2> |
|---|
| 45 | |
|---|
| 46 | <P>Following the header are a number of items. The last item must be a 0x00 |
|---|
| 47 | byte when the current label is empty, which marks the end of the data. The |
|---|
| [a0b43a6] | 48 | first byte of an item identifies what it is: |
|---|
| [2d82f2a] | 49 | |
|---|
| 50 | <ul> |
|---|
| 51 | <li> 0x00 : if the current label is empty, signifies the end of the data |
|---|
| 52 | in the 3d file; if the current label isn't empty, make it empty. |
|---|
| 53 | <li> 0x01-0x0e : trim the last 17 characters of the current label, then |
|---|
| 54 | trim back N-1 (i.e. 0-13) dots ("."), removing "." and everything after |
|---|
| 55 | it. It's incorrect if the label ends up empty, or you attempt to trim more |
|---|
| 56 | label than there is. |
|---|
| 57 | <li> 0x0f <x coord> <y coord> <z coord> : set current |
|---|
| 58 | position to the coordinates given. Coordinates are 4 bytes little-endian |
|---|
| 59 | signed integers representing values in centimetres (0.01 metres). |
|---|
| 60 | <li> 0x10-0x1f : remove N-15 (i.e. 1-16) characters from the current label. |
|---|
| 61 | It's incorrect if the label ends up empty, or you attempt to trim more |
|---|
| 62 | label than there is. |
|---|
| [67d60f3] | 63 | <li> 0x20-0x3f : Reserved |
|---|
| 64 | <li> 0x40-0x7f <length> <label> <x coord> <y coord> |
|---|
| [e77d6de] | 65 | <z coord> : station flags are (N & 0x1f): |
|---|
| 66 | <ul> |
|---|
| 67 | <li> 0x01 : Station is on an above ground leg |
|---|
| 68 | <li> 0x02 : Station is on an underground leg (both may be true at an entrance) |
|---|
| 69 | <li> 0x04 : Station is marked as an entrance (with *entrance) |
|---|
| 70 | <li> 0x08 : Station is exported (i.e. may be used as a connection point to |
|---|
| 71 | other surveys) |
|---|
| 72 | <li> 0x10 : Station is a fixed point (control point) |
|---|
| 73 | <li> 0x20 : Reserved |
|---|
| 74 | </ul> |
|---|
| 75 | |
|---|
| [a6907d1] | 76 | Append label to the current label buffer. The length of label is given by |
|---|
| 77 | length, which is encoded as follows: |
|---|
| 78 | <ul> |
|---|
| 79 | <li> 0-253 - byte 0x00-0xfd |
|---|
| 80 | <li> 254-65789 - byte 0xfe 2 byte little-endian unsigned integer len-254 |
|---|
| 81 | 0x0000-0xffff |
|---|
| 82 | <li> 65790 and greater - byte 0xff 4 byte little-endian unsigned integer len |
|---|
| 83 | 0x000100fd-0xffffffff |
|---|
| 84 | </ul> |
|---|
| 85 | |
|---|
| [760a6550] | 86 | The rationale for this encoding is that station and survey names are usually |
|---|
| 87 | much less than 253 characters. However, the Survex philosophy is not to impose |
|---|
| 88 | arbitrary limits. By using a variable length encoding, we get the |
|---|
| 89 | compactness benefits of encoding the length in a single byte, but avoid the |
|---|
| 90 | need to impose a hard limit of the length of station and survey names.<P> |
|---|
| 91 | |
|---|
| 92 | Return station at the coordinates given, and update current position to |
|---|
| 93 | coordinates given (FIXME: check this). The updated contents of the label |
|---|
| 94 | buffer give the survey stations full name. |
|---|
| [e77d6de] | 95 | |
|---|
| 96 | <li> 0x80-0xbf <length> <label> <x coord> <y coord> |
|---|
| [2d82f2a] | 97 | <z coord> : leg flags are (N & 0x1f): |
|---|
| 98 | <ul> |
|---|
| 99 | <li> 0x01 : Leg is above ground |
|---|
| 100 | <li> 0x02 : Leg duplicates data in another leg (e.g. resurvey along a passage to tie into a known station) |
|---|
| 101 | <li> 0x04 : Leg is a splay shot in a chamber (radial shots from a central point) |
|---|
| 102 | <li> 0x08 : Reserved |
|---|
| 103 | <li> 0x10 : Reserved |
|---|
| [e77d6de] | 104 | <li> 0x20 : Reserved |
|---|
| [2d82f2a] | 105 | </ul> |
|---|
| [a6907d1] | 106 | Append label to the current label buffer. The length of the label is encoded |
|---|
| 107 | as for a station label above. Return leg from current position to coordinates |
|---|
| 108 | given, and update current position to coordinates given. The updated contents |
|---|
| 109 | of the label buffer give the survey that the leg is in. |
|---|
| [e77d6de] | 110 | <li> 0xc0-0xff : Reserved |
|---|
| [2d82f2a] | 111 | </ul> |
|---|
| 112 | |
|---|
| [67d60f3] | 113 | <P>Olly Betts 2002-03-17, 2002-03-21</P> |
|---|
| [2d82f2a] | 114 | </BODY></HTML> |
|---|
