| [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> |
|---|
| [27b8b59] | 8 | <H1>Warning - Provisional</H1> |
|---|
| [2d82f2a] | 9 | |
|---|
| [27b8b59] | 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 |
|---|
| [63dc4eb] | 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 |
|---|
| [27b8b59] | 14 | us so we can improve this document. |
|---|
| [2d82f2a] | 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 | |
|---|
| [32f05df] | 25 | <P>This document only describes the more recent revisions of the 3d format |
|---|
| 26 | (versions 3 and 4). Version 3 was produced by Survex versions 0.97 and later, |
|---|
| 27 | version 4 by Survex 1.1.0 and later.</P> |
|---|
| [2d82f2a] | 28 | |
|---|
| 29 | <H2>File Header</H2> |
|---|
| 30 | |
|---|
| 31 | <P>This consists of: |
|---|
| 32 | |
|---|
| 33 | <ul> |
|---|
| [27b8b59] | 34 | <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 |
|---|
| 35 | other linefeeds - this is a file format error in any other format version]. |
|---|
| [32f05df] | 36 | <li> File format version: "v3" or "v4" followed by a linefeed. Valid values for |
|---|
| 37 | older format versions are ("v0.01", "Bv0.01", "bv0.01", "v2"). Any future |
|---|
| 38 | versions will be "v5", "v6", ..., "v10", "v11", etc. |
|---|
| [2d82f2a] | 39 | <li> Survey title: A string followed by a linefeed. There's no length limit on this string. |
|---|
| [429121e] | 40 | <li> Timestamp: A string followed by a linefeed. This is intended to be the |
|---|
| 41 | time the file was generated, rather than the time the survey data was |
|---|
| 42 | collected. The easiest way to generate this is with the strftime() format |
|---|
| 43 | "%a,%Y.%m.%d %H:%M:%S %Z" if you have access to strftime(). An example |
|---|
| 44 | timestamp is "Sun,2002.03.17 14:01:07 GMT". |
|---|
| [2d82f2a] | 45 | </ul> |
|---|
| 46 | |
|---|
| 47 | <H2>Items</H2> |
|---|
| 48 | |
|---|
| 49 | <P>Following the header are a number of items. The last item must be a 0x00 |
|---|
| 50 | byte when the current label is empty, which marks the end of the data. The |
|---|
| [a0b43a6] | 51 | first byte of an item identifies what it is: |
|---|
| [2d82f2a] | 52 | |
|---|
| 53 | <ul> |
|---|
| 54 | <li> 0x00 : if the current label is empty, signifies the end of the data |
|---|
| 55 | in the 3d file; if the current label isn't empty, make it empty. |
|---|
| [26da572] | 56 | <li> 0x01-0x0e : trim the last 16 characters of the current label, then |
|---|
| 57 | trim back N (i.e. 1-14) dots ("."), everything after that particular dot. |
|---|
| 58 | It's incorrect if the label ends up empty, or you attempt to trim more |
|---|
| 59 | label than there is. The rationale for removing 16 characters first is |
|---|
| 60 | that removal of 1-16 characters can be encoded by 0x10-0x1f (see below) |
|---|
| 61 | and we can make this encoding more powerful by not overlapping what can |
|---|
| 62 | be encoded. |
|---|
| [2d82f2a] | 63 | <li> 0x0f <x coord> <y coord> <z coord> : set current |
|---|
| 64 | position to the coordinates given. Coordinates are 4 bytes little-endian |
|---|
| 65 | signed integers representing values in centimetres (0.01 metres). |
|---|
| 66 | <li> 0x10-0x1f : remove N-15 (i.e. 1-16) characters from the current label. |
|---|
| 67 | It's incorrect if the label ends up empty, or you attempt to trim more |
|---|
| 68 | label than there is. |
|---|
| [32f05df] | 69 | <li> <font color=red>0x20 <date>: set survey date of legs (date is 4 byte little endian unsigned integer counting seconds since 1970) [New in version 4]</font> |
|---|
| 70 | <li> <font color=red>0x21 <date1> <date2>: set survey date of legs |
|---|
| 71 | to a range (date1, date2 are 4 byte little endian unsigned integer counting seconds since 1970) [New in version 4]</font> |
|---|
| 72 | <li> 0x22-0x3f : Reserved |
|---|
| [67d60f3] | 73 | <li> 0x40-0x7f <length> <label> <x coord> <y coord> |
|---|
| [e77d6de] | 74 | <z coord> : station flags are (N & 0x1f): |
|---|
| 75 | <ul> |
|---|
| 76 | <li> 0x01 : Station is on an above ground leg |
|---|
| 77 | <li> 0x02 : Station is on an underground leg (both may be true at an entrance) |
|---|
| 78 | <li> 0x04 : Station is marked as an entrance (with *entrance) |
|---|
| 79 | <li> 0x08 : Station is exported (i.e. may be used as a connection point to |
|---|
| 80 | other surveys) |
|---|
| 81 | <li> 0x10 : Station is a fixed point (control point) |
|---|
| 82 | <li> 0x20 : Reserved |
|---|
| 83 | </ul> |
|---|
| 84 | |
|---|
| [a6907d1] | 85 | Append label to the current label buffer. The length of label is given by |
|---|
| 86 | length, which is encoded as follows: |
|---|
| 87 | <ul> |
|---|
| 88 | <li> 0-253 - byte 0x00-0xfd |
|---|
| 89 | <li> 254-65789 - byte 0xfe 2 byte little-endian unsigned integer len-254 |
|---|
| 90 | 0x0000-0xffff |
|---|
| 91 | <li> 65790 and greater - byte 0xff 4 byte little-endian unsigned integer len |
|---|
| 92 | 0x000100fd-0xffffffff |
|---|
| 93 | </ul> |
|---|
| 94 | |
|---|
| [760a6550] | 95 | The rationale for this encoding is that station and survey names are usually |
|---|
| 96 | much less than 253 characters. However, the Survex philosophy is not to impose |
|---|
| 97 | arbitrary limits. By using a variable length encoding, we get the |
|---|
| 98 | compactness benefits of encoding the length in a single byte, but avoid the |
|---|
| 99 | need to impose a hard limit of the length of station and survey names.<P> |
|---|
| 100 | |
|---|
| 101 | Return station at the coordinates given, and update current position to |
|---|
| 102 | coordinates given (FIXME: check this). The updated contents of the label |
|---|
| 103 | buffer give the survey stations full name. |
|---|
| [e77d6de] | 104 | |
|---|
| 105 | <li> 0x80-0xbf <length> <label> <x coord> <y coord> |
|---|
| [2d82f2a] | 106 | <z coord> : leg flags are (N & 0x1f): |
|---|
| 107 | <ul> |
|---|
| 108 | <li> 0x01 : Leg is above ground |
|---|
| 109 | <li> 0x02 : Leg duplicates data in another leg (e.g. resurvey along a passage to tie into a known station) |
|---|
| 110 | <li> 0x04 : Leg is a splay shot in a chamber (radial shots from a central point) |
|---|
| 111 | <li> 0x08 : Reserved |
|---|
| 112 | <li> 0x10 : Reserved |
|---|
| [e77d6de] | 113 | <li> 0x20 : Reserved |
|---|
| [2d82f2a] | 114 | </ul> |
|---|
| [a6907d1] | 115 | Append label to the current label buffer. The length of the label is encoded |
|---|
| 116 | as for a station label above. Return leg from current position to coordinates |
|---|
| 117 | given, and update current position to coordinates given. The updated contents |
|---|
| 118 | of the label buffer give the survey that the leg is in. |
|---|
| [e77d6de] | 119 | <li> 0xc0-0xff : Reserved |
|---|
| [2d82f2a] | 120 | </ul> |
|---|
| 121 | |
|---|
| [26da572] | 122 | <P>Olly Betts 2002-03-17, 2002-03-21, 2002-09-30, 2002-11-25</P> |
|---|
| [2d82f2a] | 123 | </BODY></HTML> |
|---|
