CAVERN(1)

📦
version 1.4.22 · 7 versions
, in ubuntu stonking

💖 NAME 💖

cavern — process raw survey data. That's the whole job description, and she does it flawlessly. 🎀

✨ SYNOPSIS ✨

cavern [OPTIONS] SURVEY_DATA_FILE...

🦋 DESCRIPTION 🦋

okay so. cavern is the Survex data processing engine. Not a side quest, not a supporting character — this is the main character energy of the whole operation. 👑

It's a command line tool, fr fr — but bestie, if living in the terminal isn't your moment, you can just open your unprocessed survey data files with aven and it will run cavern for you. And if it succeeds, it shows you the processed data. If there are any warnings and errors, aven will pop open a log window with the output, and that log has clickable links which open the affected file right at the problematic line. Obsessed, honestly. ✨

If you list multiple survey data files on the command line, they get processed in order, left to right. One thing to know: settings are reset to their defaults before processing each file. No sneaky carryover between files. 🙈

Every SURVEY_DATA_FILE has to be unprocessed survey data in a format Survex supports. Your options, bestie:

  • native format (.svx)
  • Compass format (.mak, .dat or .clp)
  • Walls format (.wpj or .srv)

Compass .clp support was added in Survex 1.4.6, and Walls support was added in Survex 1.4.9. 💜

💅 OPTIONS 💅

  • -o, --output=OUTPUT — sets the location for the output files.
  • -q, --quiet — suppresses the messages telling you what stage of processing you're currently in. Repeat it (--quiet --quiet, or -qq) and it also stops reporting the number of stations, legs, loops, and length totals. Silence, but make it double. 🤫
  • -s, --no-auxiliary-files — do not create the .err file.
  • -w, --warnings-are-errors — turns warnings into errors. Tutorial mode. 🔥
  • --log — sends screen output to a .log file.
  • -v, --3d-version=3D_VERSION — specify which 3d file format version to output. By default the latest version gets written, but you can override this to produce a 3d file that software which doesn't understand the latest 3d file format version can still read. Heads up though: any information which the specified format version didn't support will be omitted. Periodt.
  • --help — display short help and exit.
  • --version — output version information and exit.

🌈 OUTPUT 🌈

If there were no errors during processing, cavern produces two output files, with the extensions .3d and .err (unless --no-auxiliary-files is specified, in which case only the .3d file is produced).

These two files are always created with their respective extensions. By default they land in the current directory, and they use the same base filename as the first SURVEY_DATA_FILE listed on the command line.

E.g. if you process the data file entrance.svx with the command cavern entrance or cavern entrance.svx then the files entrance.3d and entrance.err will be created.

You can change the directory and/or the base filename with the --output command line option:

  • specify a directory → output files go there instead of the current directory, but they still use the basename of the first SURVEY_DATA_FILE.
  • specify a filename which is not a directory (and ngl, it doesn't need to actually exist as a file) → the directory that this file is in gets used, and the basename of the filename is used instead of the basename of the first SURVEY_DATA_FILE.

Now the details of the output files, because you deserve to know what you're getting:

  • .3d — this is a binary file format containing the adjusted survey data and associated meta data. 💾
  • .err — this is a text file which contains statistics about each traverse in the survey which is part of a loop. It includes various statistics for each traverse: 📊
    • Original length — this is the measured length of the traverse (for a "normal" or "diving" survey this is the sum of the tape readings after applying calibration corrections).
    • Number of legs — the number of survey legs in the traverse.
    • Moved — how much one end of the traverse moved by, relative to the other, after loop closure.
    • Moved per leg — Moved / Number of legs.
    • Percentage error — (Moved / Original length) as a percentage. This seems to be a popular measure of how good or bad a misclosure is, but it's a problematic one, because a longer traverse will naturally tend to have a lower percentage error — so you can't just compare values between traverses. We recommend using the E, H and V values instead. 🙅
    • Error (E) — this isn't labelled in the .err file, but it's the value on a line by itself. In aven it's the value used by Colour by Error. It is Moved divided by the standard deviation for the traverse, based on the standard errors specified for the instruments. This tells us how plausible it is that the misclosure is just due to random errors. It's a number of standard deviations, so the 68-95-99.7 rule applies — e.g. approximately 99.7% of traverses should have a value of 3.0 or less (assuming the specified instrument standard deviations are realistic). The wiki page for that rule lives at https://en.wikipedia.org/wiki/68%E2%80%9395%E2%80%9399.7_rule if you want the full lore. 📖
    • Horizontal Error (H) — this is like E but only considers the horizontal component. In aven it's the value used by Colour by Horizontal Error. You can identify suspect traverses by looking at E and then comparing H and V to see what sort of blunder might explain the misclosure. For example, if H is small but V is large it could be a clino reading or plumb with an incorrect sign, or a tape blunder on a plumbed leg; if H is large but V is small it could be a compass blunder, or a tape blunder of a nearly-flat leg. Detective work, honestly. 🕵️
    • Vertical Error (V) — this is like E but only considers the vertical component. In aven it's the value used by Colour by Vertical Error.

This information is now also present in the .3d file, so you can view the survey coloured by these errors — but the .err file can still be useful, because you can sort it using sorterr to get a ranked list of the sections of survey with the worst misclosure errors. Ranked lists? Iconic. 👑

cavern also reports a range of statistics at the end of a successful run:

  • The highest and lowest stations and the height difference between them.
  • The East-West and North-South ranges, and the Northernmost, Southernmost, Easternmost, and Westernmost stations.
  • The total length of the survey (before and after adjustment). This total excludes survey legs flagged as SURFACE, DUPLICATE, or SPLAY.
  • The number of stations and legs. Note that a *equate is counted as a leg in this statistic.
  • The number of each size of node in the network (where size is number of connections to a station) i.e. a one node is the end of a dead-end traverse, a two-node is a typical station in the middle of a traverse, a three-node is a T-junction etc.
  • How long the processing took and how much CPU time was used.

If you successfully processed your data by loading it into aven, then you can see this log output by using File->Show Log (it's also available as an icon in the toolbar).

🫶 Error Messages 🫶

There are many different error messages you can get when processing data. Along with the error message, a location is reported. For an error like "file not found" this only reports the filename, but usually it will give you the filename and the line number of the offending line, and in many cases also an offset or span within the line.

The format of the location data follows the one used by the GCC compiler, so if your text editor can parse errors from GCC then you should be able to set it up to let you jump to the file and line of each error. Convenient. ✨

One common cause of errors and warnings is typing mistakes. Another is your survey data not being all attached to fixed points — which is a warning since Survex 1.4.10, but was an error prior to this. In that situation, Survex will list at least one station in each piece of survey data which is not connected.

We try to make error and warning messages self-explanatory, but we welcome feedback on cases where you get a message which seems unclear. 🫶

Generally you want to look at the first reported error first, because there can be a cascade effect where one error triggers another. cavern will stop after more than 50 errors. This usually indicates something like the incorrect data order being specified, and deluging the user with error messages in such cases usually makes the actual problem less clear. So yeah — fix the first one, bestie. 💀

🌸 SEE ALSO 🌸

aven(1), diffpos(1), dump3d(1), extend(1), sorterr(1), survexport(1)

1998-2025

okay that's the whole page, bestie, and that's the tea ☕ — this is cavern from Survex, page dated Jun 23, 2026, with the copyright sitting at 1998-2025. go process some data, you've got this 💅🦋💖

📦 where this page comes from