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 16 characters of the current label, then |
---|
56 | trim back N (i.e. 1-14) dots ("."), everything after that particular dot. |
---|
57 | It's incorrect if the label ends up empty, or you attempt to trim more |
---|
58 | label than there is. The rationale for removing 16 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> |
---|