survex-dist

A command line utility for calculating the distance between two points in a Survex cave survey file. survex-dist is not associated with the Survex project, although I am very grateful for their hard work!

Features

Implemented

• Process Survex 3D files to create a graph of the cave system.
• Calculate the shortest walking distance between any two stations in the cave system using A* pathfinding.
• Force a specific route through the cave by specifying survey stations to go via or exclude.
• Output to different formats: plain text, table, JSON.

Planned

• Produce a graphical representation of the cave system and path.
• A web interface to allow the application to be used without installing it locally.
• Provide analysis of the cave system, such as the number of loops, number of entrances, etc.
• Provide analysis of various through trips in the cave system.

Example

> survex-dist tests/data/nottsii.3d nottsii.entrance entranceshaft.007

+-------------------+----------------------------+----------+------------+
| Station label     | Coords                     | Leg Dist | Total Dist |
+-------------------+----------------------------+----------+------------+
| entrance          | 66668.00, 78303.00, 319.00 | 0.00m    | 0.00m      |
| entranceshaft.002 | 66668.09, 78302.82, 319.00 | 0.20m    | 0.20m      |
| entranceshaft.003 | 66668.09, 78302.82, 317.93 | 1.07m    | 1.27m      |
| entranceshaft.004 | 66667.99, 78303.07, 317.93 | 0.27m    | 1.54m      |
| entranceshaft.005 | 66667.99, 78303.07, 306.40 | 11.53m   | 13.07m     |
| entranceshaft.006 | 66668.52, 78305.06, 305.16 | 2.40m    | 15.47m     |
| entranceshaft.007 | 66668.04, 78305.88, 304.03 | 1.48m    | 16.95m     |
+-------------------+----------------------------+----------+------------+

+------------------------+-----------------------------------------------+
| Metadata               | Value                                         |
+------------------------+-----------------------------------------------+
| Start station          | entrance                                      |
| End station            | committeepotentrance.entranceshaft.007        |
| Path length            | 7                                             |
| Path distance          | 16.95m                                        |
| Straight line distance | 15.24m                                        |
| Time taken             | 22.19ms                                       |
+------------------------+-----------------------------------------------+

Usage

Installation

survex-dist is not presently available as a binary. You can build and install it yourself using cargo, the Rust package manager. If you need to install cargo, see rustup.rs.

To build and install survex-dist in your cargo bin directory (usually ~/.cargo/bin), run the following command:

cargo install survex-dist

Via and avoid

survex-dist can ensure that a certain route is taken by specifying via stations. This is done using the --via flag. For example, to ensure that the route passes through the station entranceshaft.005, use the following command:

> survex-dist tests/data/nottsii.3d nottsii.entrance entranceshaft.007 --via entranceshaft.005

In exactly the same way, the --avoid flag can be used to ensure that a route does not pass through a certain station. Both --via and --avoid can be used multiple times. Note that --via stations are processed in the order that they are specified, and may cause a route to loop back.

Station matching

You can use partial station names whenever specifying a survey station.

For example, the station nottsii.committeepotentrance.entranceshaft.007 was specified as entranceshaft.007 above. The partial match will be accepted as long as it is unambiguous. If the partial match is ambiguous, survex-dist will print a list of possible matches and exit:

❯ survex-dist tests/data/nottsii.3d nottsii.entrance entranceshaft
There were 35 possible matches for the station name 'entranceshaft'.

The first 20 matches were:

  nottsii.committeepotentrance.entranceshaft_2.15
  nottsii.committeepotentrance.entranceshaft_2.14
  nottsii.committeepotentrance.entranceshaft_2.13
  nottsii.committeepotentrance.entranceshaft_2.12
  ... snip ...

Output format

The output format can be changed using the --format flag. The following formats are supported:

• table (default)
• text
• json

Survey analysis

survex-dist will, in the future, provide analysis of a survey using the --analyse flag. At the moment, this flag does nothing.

Further options

For a full list of options, run survex-dist --help.

Contributing

Pull requests and issues are more than welcome - do let me know if you find any bugs or have a suggestion for a feature.

See also

survex-dist makes use of the survex-rs library to read Survex 3D files, which in turn uses the Survex img.c library directly.