Warning - Provisional

This specification is reverse engineered from the code. At least one person has written code to successfully written code to read 3d files using it, but it may be incorrect in minor details, and it's possible that there are points which aren't fully spelled out. If you encounter any problems, please mail us so we can improve this document.

Survex 3d Format Specification

If you're writing in C or C++ it's strongly recommended that you use the img routine provided with Survex to read and write 3d files. Doing so means that you can take advantage of any revisions to the 3d format by simply rebuilding your software with the updated img routines, rather than having to update your own code. It also allows you to read a sub-set of the data in the file, restricted by Survey prefix.

This document only describes the most recent revision of the 3d format (version 3), which is produced by Survex versions 0.97 and later.

File Header

This consists of:

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 other linefeeds - this is a file format error in any other format version].
File format version: "v3" followed by a linefeed. Valid values for older format versions are ("v0.01", "Bv0.01", "bv0.01", "v2"). Newer versions will be "v4", "v5", ..., "v10", "v11", etc.
Survey title: A string followed by a linefeed. There's no length limit on this string.
Timestamp: A string followed by a linefeed. This is intended to be the time the file was generated, rather than the time the survey data was collected. The easiest way to generate this is with the strftime() format "%a,%Y.%m.%d %H:%M:%S %Z" if you have access to strftime(). An example timestamp is "Sun,2002.03.17 14:01:07 GMT".

Items

Following the header are a number of items. The last item must be a 0x00 byte when the current label is empty, which marks the end of the data. The first byte of an item identifies what it is:

0x00 : if the current label is empty, signifies the end of the data in the 3d file; if the current label isn't empty, make it empty.
0x01-0x0e : trim the last 16 characters of the current label, then trim back N (i.e. 1-14) dots ("."), everything after that particular dot. It's incorrect if the label ends up empty, or you attempt to trim more label than there is. The rationale for removing 16 characters first is that removal of 1-16 characters can be encoded by 0x10-0x1f (see below) and we can make this encoding more powerful by not overlapping what can be encoded.
0x0f <x coord> <y coord> <z coord> : set current position to the coordinates given. Coordinates are 4 bytes little-endian signed integers representing values in centimetres (0.01 metres).
0x10-0x1f : remove N-15 (i.e. 1-16) characters from the current label. It's incorrect if the label ends up empty, or you attempt to trim more label than there is.
0x20-0x3f : Reserved
0x40-0x7f <length> <label> <x coord> <y coord> <z coord> : station flags are (N & 0x1f):
- 0x01 : Station is on an above ground leg
- 0x02 : Station is on an underground leg (both may be true at an entrance)
- 0x04 : Station is marked as an entrance (with *entrance)
- 0x08 : Station is exported (i.e. may be used as a connection point to other surveys)
- 0x10 : Station is a fixed point (control point)
- 0x20 : Reserved
Append label to the current label buffer. The length of label is given by length, which is encoded as follows:
- 0-253 - byte 0x00-0xfd
- 254-65789 - byte 0xfe 2 byte little-endian unsigned integer len-254 0x0000-0xffff
- 65790 and greater - byte 0xff 4 byte little-endian unsigned integer len 0x000100fd-0xffffffff
The rationale for this encoding is that station and survey names are usually much less than 253 characters. However, the Survex philosophy is not to impose arbitrary limits. By using a variable length encoding, we get the compactness benefits of encoding the length in a single byte, but avoid the need to impose a hard limit of the length of station and survey names.
Return station at the coordinates given, and update current position to coordinates given (FIXME: check this). The updated contents of the label buffer give the survey stations full name.
0x80-0xbf <length> <label> <x coord> <y coord> <z coord> : leg flags are (N & 0x1f):
- 0x01 : Leg is above ground
- 0x02 : Leg duplicates data in another leg (e.g. resurvey along a passage to tie into a known station)
- 0x04 : Leg is a splay shot in a chamber (radial shots from a central point)
- 0x08 : Reserved
- 0x10 : Reserved
- 0x20 : Reserved
Append label to the current label buffer. The length of the label is encoded as for a station label above. Return leg from current position to coordinates given, and update current position to coordinates given. The updated contents of the label buffer give the survey that the leg is in.
0xc0-0xff : Reserved

Olly Betts 2002-03-17, 2002-03-21, 2002-09-30, 2002-11-25