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 8) which is produced by versions from 1.2.7. A separate document describes older versions.

If you try to use this specification and find details which aren't spelled out clearly enough (or at all!) or any errors, please let us know. At least two people have successfully written code to read 3d files using this document, but that doesn't mean it can't be improved.

File Header

This consists of:

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 is a code identifying what the item is:

Code Type Data Meaning Version
0x00 STYLE_NORMAL / STOP   Set style for following legs to tape, compass and clino.

If the style is already set to STYLE_NORMAL, this code signifies the end of the data in the 3d file.

≥8
0x01 STYLE_DIVING   Set style for following legs to diving data ≥8
0x02 STYLE_CARTESIAN   Set style for following legs to cartesian data ≥8
0x03 STYLE_CYLPOLAR   Set style for following legs to cylindrical polar data ≥8
0x04 STYLE_NOSURVEY   Set style for following legs to unsurveyed ≥8
0x05 - 0x0e     Reserved
0x0f MOVE <x> <y> <z> Set current position to the coordinates given. Coordinates are 4 byte little-endian signed integers representing values in centimetres (0.01 metres). ≥8
0x10 DATE   No survey date information was specified. ≥8
0x11 DATE <date> Set survey date of legs: date is a 2 byte little-endian unsigned integer counting days from the start of 1900. ≥8
0x12 DATE <date1><datespan> Set survey date of legs to a range: date1 is a 2 byte little-endian unsigned integer counting days since the start of 1900, and datespan is an unsigned byte counting days from date1. ≥8
0x13 DATE <date1><date2> Set survey date of legs to a range: date1, date2 are 2 byte little-endian unsigned integers counting days since the start of 1900. ≥8
0x14 - 0x1e     Reserved
0x1f ERROR <legs><length><E><H><V> Error information for the current traverse. <legs> is the number of legs. <length> is the total length of the traverse in cm (0.01m). E, H and V are the error and the horizontal and vertical components in cm. (All values are 4 byte little-endian signed integers) ≥8
0x20 - 0x2f     Reserved
0x30 - 0x31 XSECT <label> <L> <R> <U> <D> Dimensions are 2 byte little-endian signed integers representing values in centimetres (0.01 metres). Omitted dimensions are encoded as 0xffff. Station flags are (N & 0x01): ≥8
Flag (N & 0x01) Meaning
0x01 Station is last one in this passage
0x32 - 0x33 XSECT <label> <L> <R> <U> <D> Dimensions are 4 byte little-endian signed integers representing values in centimetres (0.01 metres). Omitted dimensions are encoded as 0xffffffff. ≥8
Flag (N & 0x01) Meaning
0x01 Station is last one in this passage
0x34 - 0x3f     Reserved
0x40 - 0x7f LINE <label> <x> <y> <z> Append label to the current label buffer. The length of the label is encoded as for a station label below. 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. ≥8
Flag (N & 0x3f) Meaning
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 No change to label (<label> omitted entirely) ≥8
0x80 - 0xff LABEL <label> <x> <y> <z> Append label to the current label buffer. The updated contents of the label buffer give the survey stations full name. The length of label is given by length, which is encoded as follows: ≥8
Length Encoding
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 station flags are encoded in the bottom 7 bits of the item code:
Flag (N & 0x7f) Meaning
0x01 Station is on leg above ground
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 Station is anonymous
0x40 Station is on the passage wall

Item order

Authors: Olly Betts and Mike McCombe, last updated: 2014-07-02