CUCC Expo Surveying Handbook

From muddy book to survex plot

Tony Rooke entering data (1991)

Survex has its own documentation for the format of the data, though the template file and a look at someone else's data will quickly make this fairly clear.

Survex has some very flexible data entry options, so there are a few extra guidelines to try to get some consistency in the way everyone uses it within this project.

Survex (including the graphical software 'aven') is already installed on the expo laptop. These instructions assume that you are using the expo laptop.

Where to put your data

[These instructions pre-date the online form and describe typing using a text editor. Use the online form! But the content of the survex file is the same. This page will be edited to specifically describe using the form when time permits.]

Where to put your data: If in doubt, ask!. These instructions assume that you are typing it in on the expo laptop. (You can do it fom your own laptop if you have been initiated into the deep magic of the ":loser:" repository of the distributed version control system - see the list of repositories.

• If it is a surface survey, it goes in the :loser:/surface" directory;
• if it is a file of fixed points (like GPS fixes, or map coordinates), it goes in the ":loser:/fixedpts" directory;
• if it is a new cave on the near-plateau, put it in a new directory under ":loser:/caves-1623".
• Underground data for Steinbrückenhöhle goes in one of the subdirectories under :loser:/caves-1623/204/; it may well be clear which one from what it links to, but if not, ask.

Use a template

The beginner should start from the existing template file :loser:/template/template.svx as this has lines to remind you to add various details - make sure you don't leave any blanks! Copy and rename this to where you want to put your data before editing it. Too many people have overwritten the template in the past, try not to do this yourself.

Working by editing a .svx file from another bit of the same cave may seem like a short cut but whoever edited it may have deleted some of the helpful and useful hints that are in the template.svx file - so don't do this please, until you really know what you are doing.

Filename and data-entry conventions in svx files

• Use Unix line endings (i.e. \n not \r\n).
• Use UTF-8 character encoding.
• NO UMLAUTS. Use ¨ for u-umlaut and &oml; for o-umlaut in text. But don't use these in filenames.
• Cave numbers are written without any leading zeros at all (in filenames, survey names, or anything else!).
• Entrances have station names such as p204b. In the event of the tag location being different from the entrance location, the tag point should be named with a "t" instead, e.g. t204b.
• No full stop (.) characters in station names.
• All filenames to be in lower case. Capital letters in filenames can still (in 2022) cause hassle when moving between Linux and Windows. (This includes suffix letters for cave entrances: it is "87a" NOT "87A".)
• No filenames starting with "-" or "!".
• No colons in filenames.
• Caves with a provisional number consisting of a year and a serial number should be hyphenated, thus 2018-ad-01 not with underscore 2018_01 or any of the various other variants.

The name of your survey

File 2050-01.svx
*begin 2050-01
    *export pt1.1 pt2.5 [...]
    *begin pt1
        [survey data from first trip]
    *end pt1
    *begin pt2
        [survey data from second trip]
    *end pt2
*end 2050-01

There is no restriction on the length of these names, but as they can be displayed in aven, tunnel and other such programs, it helps not to have anything too elaborate. Older versions of survex required each prefix to be unique in its first eight characters, and this is not a bad guideline to follow.

Station names

Every station should have a number within your survey even if it is an existing station to which you have connected. Any survey stations which you think can reliably be found again should be listed at the start of your survey file. This includes the name (within your survey) of any existing points you linked into. I have used lines like ;*export mysurvey.pt1.0 ; 2nd bolt at head of new pitch – this may or may not catch on as a standard.

At this stage, you have done enough to get a centre line for drawing up. If you aren't completely confident about the structure of the Austria data, or the survex syntax of *equate and *export which can be rather cryptic for the uninitiated, it may be best not to try to link your survey to everything else so skip the next bit and read on from here.

Plumbing your survey into the rest of the cave

However, if you need to see your survey in relation to the rest of the dataset:

• Don't put any *equate directives to other surveys into your file (or any survey legs which quote station names from other survey files). Instead, go to the file which *includes the other files in the same area.
  
  For example, if you have created a file trivial.svx in the caves-1623/204/deepsouth directory, go to the file deepsouth/deepsouth.svx, where you will find *include lines for each of the files, together with the *equate lines to connect them together. Add an include for your file, and *equate lines for each of your survey stations which is the same as one in another survey. If your survey connects to points in surveys in files in more than one directory then the *equates should go in the /204/204.svx file, but at this stage it is probably worth enlisting the help of someone who knows the structure of the data inside-out!
  
  
• You should now find that if you run survex on one of the master files ( 1623-and-1626-no-schoenberg-hs.svx, 204.svx, smk-system.svx , etc.) which includes the area of your new survey, it is linked in and will show up when you use the resultant .3d file in aven.

Now you have been typing this on the expo laptop, and before you let someone else use the laptop you need to find a nerd to do the deep magic to add your file to the version control repository "loser". Watching the nerd do this is usually your first initiation into learning how to do it yourself.

Example svx file

To make that all a bit more concrete, here is a fictitious example of a survey off Swings & Roundabouts in 204. Let's say that you went to explore a lead from the QM list numbered 2002-99, that the nearest survey station was listed as 204.allswings.swings5.2 and you found it successfully, and numbered it within your own survey as station 0. Then you might create the following file: (note we don't use umlauts)

File wibble.svx
*begin wibble

; Locn:	Totes Gebirge, Austria - Loser/Augst-Eck Plateau (kataster group 1623)
; Cave:	Steinbruckenhohle
*title "Wibbled by Goesser"
*date 2004.08.32 ;date the survey was done
*team Insts John Doe
*team Notes Amalthea Jones
*team Tape Amalthea Jones
 
; ref.:	2004 #999 ; the #number is on the clear pocket containing the original notes.

; ====== stations refindable to link to other surveys: ======

*export 0 ; list all exported survey points.

*calibrate tape 0	; +ve if tape was too short, -ve if too long
;calibration data 148,+23,147,+23.5,148,+23,329,-23,328,-23.5,328.5,-23

;from	to	tape	compass	clino	; remarks
1	p5	5.48	181	-27
[and the rest of your survey data]
6	5	5.66	-	DOWN

;stn	L	R	U	D	Desc
;1	0.7	0.4	0.3	0.5	RP top of boulder
[and the rest of the station details]
*end wibble

That lot would be typed by copying :loser:/template/template.svx to :loser:/caves-1623/204/swings/wibble.svx and then filling in the blanks and adding your data. If you are linking to the rest of the survey then in the file :loser:/caves-1623/204/swings/allswings.svx add the lines:

*include wibble
*equate wibble.0 swings5.2

Split surface and underground files

Remember not to put surface data and underground data in the same file, even if they are part of one continuous survey. You need to create two files, with a defined station for the entrance, and a suitable equate in the file which includes both surface stuff and underground stuff.

*Team options

We have used a varied and peculiar range of roles in our survex files over the years. e.g.

*team nail_varnish_bitch Amalthea Jones

The list of approved roles (as of July 2023) is:
bitch|bodger|bolt|bolter|bolting|book|clino|comp| compass|consultant|disto|distox|distox2|dog| dogsbody|drawing|drill|gps|helper|inst|instr| instrument|monkey|nagging|nail|nail_polish| nail_polish_bitch|nail_polish_monkey|nail_varnish| nail_varnish_bitch|note|paint|photo|pic|point| polish|powerdrill|rig|rigger|rigging|sketch| slacker|something|tape|topodroid|unknown| useless|varnish|waiting_patiently

Postprocessing and Update

Once you have your data typed in and checked, it must be run through the survey software (which on expo will be survex) and a centre line printed, both for plan and for extended elevation. Measure the print out to check that it really has printed at the scale you wanted (typically 1:500), as this has sometimes caused problems in the past.

Return to "Survey handbook - survex format".