source: git/doc/3dformat.htm @ 1bcecc8

RELEASE/1.0RELEASE/1.2debug-cidebug-ci-sanitisersfaster-cavernloglog-selectstereowalls-datawalls-data-hanging-as-warning
Last change on this file since 1bcecc8 was 6fef9bc, checked in by Olly Betts <olly@…>, 22 years ago

added 3dformat.htm

git-svn-id: ​file:///home/survex-svn/survex/trunk@2198 4b37db11-9a0c-4f06-9ece-9ab7cdaee568
  • Property mode set to 100644
File size: 5.2 KB
Line 
1<HTML><HEAD>
2<TITLE>Survex 3d Format Specification</TITLE>
3<STYLE type="text/css"><!--
4BODY, TD, CENTER, UL, OL {font-family: sans-serif;}
5-->
6</STYLE>
7</HEAD><BODY BGCOLOR=white TEXT=black>
8<H1>Warning - Provisional</H1>
9
10This specification is reverse engineered from the code.  At least one person
11has written code to successfully written code to read 3d files using it, but
12it may be incorrect in minor details, and it's possible that there are points
13which aren't fully spelled out.  If you encounter any problems, please mail
14us 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
19the img routine provided with Survex to read and write 3d files.  Doing so
20means that you can take advantage of any revisions to the 3d format by simply
21rebuilding your software with the updated img routines, rather than having to
22update your own code.  It also allows you to read a sub-set of the data in
23the 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
34other 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
36older format versions are ("v0.01", "Bv0.01", "bv0.01", "v2").  Newer versions
37will 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
40time the file was generated, rather than the time the survey data was
41collected.  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
43timestamp 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
49byte when the current label is empty, which marks the end of the data.  The
50first 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
54in 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
56trim back N-1 (i.e. 0-13) dots ("."), removing "." and everything after
57it.  It's incorrect if the label ends up empty, or you attempt to trim more
58label than there is.
59<li> 0x0f &lt;x coord&gt; &lt;y coord&gt; &lt;z coord&gt; : set current
60position to the coordinates given.  Coordinates are 4 bytes little-endian
61signed integers representing values in centimetres (0.01 metres).
62<li> 0x10-0x1f : remove N-15 (i.e. 1-16) characters from the current label.
63It's incorrect if the label ends up empty, or you attempt to trim more
64label than there is.
65<li> 0x20-0x3f : Reserved
66<li> 0x40-0x7f &lt;length&gt; &lt;label&gt; &lt;x coord&gt; &lt;y coord&gt;
67&lt;z coord&gt; : station flags are (N &amp; 0x1f):
68<ul>
69<li> 0x01 : Station is on an above ground leg
70<li> 0x02 : Station is on an underground leg (both may be true at an entrance)
71<li> 0x04 : Station is marked as an entrance (with *entrance)
72<li> 0x08 : Station is exported (i.e. may be used as a connection point to
73other surveys)
74<li> 0x10 : Station is a fixed point (control point)
75<li> 0x20 : Reserved
76</ul>
77
78Append label to the current label buffer.  The length of label is given by
79length, which is encoded as follows:
80<ul>
81<li> 0-253 - byte 0x00-0xfd
82<li> 254-65789 - byte 0xfe 2 byte little-endian unsigned integer len-254
830x0000-0xffff
84<li> 65790 and greater - byte 0xff 4 byte little-endian unsigned integer len
850x000100fd-0xffffffff
86</ul>
87
88The rationale for this encoding is that station and survey names are usually
89much less than 253 characters.  However, the Survex philosophy is not to impose
90arbitrary limits.  By using a variable length encoding, we get the
91compactness benefits of encoding the length in a single byte, but avoid the
92need to impose a hard limit of the length of station and survey names.<P>
93
94Return station at the coordinates given, and update current position to
95coordinates given (FIXME: check this).  The updated contents of the label
96buffer give the survey stations full name.
97
98<li> 0x80-0xbf &lt;length&gt; &lt;label&gt; &lt;x coord&gt; &lt;y coord&gt;
99&lt;z coord&gt; : leg flags are (N &amp; 0x1f):
100<ul>
101<li> 0x01 : Leg is above ground
102<li> 0x02 : Leg duplicates data in another leg (e.g. resurvey along a passage to tie into a known station)
103<li> 0x04 : Leg is a splay shot in a chamber (radial shots from a central point)
104<li> 0x08 : Reserved
105<li> 0x10 : Reserved
106<li> 0x20 : Reserved
107</ul>
108Append label to the current label buffer.  The length of the label is encoded
109as for a station label above.  Return leg from current position to coordinates
110given, and update current position to coordinates given.  The updated contents
111of the label buffer give the survey that the leg is in.
112<li> 0xc0-0xff : Reserved
113</ul>
114
115<P>Olly Betts 2002-03-17, 2002-03-21, 2002-09-30</P>
116</BODY></HTML>
Note: See TracBrowser for help on using the repository browser.