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