mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-25 16:52:00 +00:00
257 lines
19 KiB
HTML
257 lines
19 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>CUCC Expedition Handbook: Your laptop</title>
|
|
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
|
</head>
|
|
<body>
|
|
<h2 id="tophead">CUCC Expedition Handbook - Your laptop</h2>
|
|
|
|
<h1>Cave survey software - beyond the basics</h1>
|
|
|
|
<h2>Phones and laptops</h2>
|
|
|
|
|
|
<h3>Your Android phone</h3>
|
|
<p>Everyone has a phone pretty much, and everyone should have GPS enabled for safety. See <a href="../essentials.html">the expo GPS configuration pages</a>.
|
|
<p>There are several cave survey apps which run on a phone. We don't yet have a well documented way of using these
|
|
with the expo survey data workflow.
|
|
<ul>
|
|
<li><a href="https://osmand.net/">OsmAnd</a> - a GPS app.
|
|
<li><a href="http://www.gpsessentials.com/">GPSessentials</a> - another GPS app.
|
|
<li><a href="http://apemap.com/">Ape@Map</a> - another GPS app, compatible with Kompass commerical map sand used by Austrian cavers
|
|
|
|
<li><a href="https://sites.google.com/site/speleoapps/home">TopoDroid</a> makes cave surveys with the DistoX.
|
|
<li><a href="https://sites.google.com/site/speleoapps/home">Cave3D</a> is a Therion 3D viewer.
|
|
<li><a href="https://sites.google.com/site/speleoapps/home">ThManager</a> organizes single surveys, exported by TopoDroid, into Therion projects encoded by Therion "thconfig" files.
|
|
</ul>
|
|
|
|
<p>You can also use a phone to upload files and manage version control on the server. This is not the place to start, but if you are already doing this on your own laptop then these can be useful:
|
|
<ul>
|
|
<li><a href="https://www.termius.com/">Termius</a> - command line to create a registratkey for your phone, to ssh (and mosh) login to the expo server. To get sftp you have to buy it.
|
|
<li><a href="uploading.html#android">andftp</a> FTP app - needs an <a href="keyexchange.html">ssh key</a> installed on your phone
|
|
<li><a href="ftpusage.html">FTP using Cx_File_Explorer</a> (this is probably out of date)
|
|
</ul>
|
|
|
|
<h3>Your laptop</h3>
|
|
|
|
<p>You will already have configured your laptop to do all the basic stuff using the
|
|
<a href="basiclaptop.html">basic Expo laptop</a> guide.
|
|
|
|
|
|
<p><code>This is an attempt at a <em>complete set of optional software</em> for using survex, tunnel, therion, photos and GPS tracks to document our caves: using the existing data archive and processing new survey data.
|
|
<p>If you want to do software development instead, go to <a href="../troggle/troglaptop.html">configuring a troggle development machine</a>.
|
|
|
|
</code></p>
|
|
|
|
<p>This page documents what else you might find useful if the basic laptop setup does not do what you need.
|
|
|
|
<h2>Windows, Macs, Chromebooks and Linux</h2>
|
|
<ul>
|
|
<li>You should be able to use any OS (Linux, Windows, Mac) to interact with expo, but it's a bit simpler to get set up using Linux. You can't
|
|
yet do everything on a phone, but you can do some things.</li>
|
|
|
|
<li>The <i>expo laptop</i> uses <a href="https://www.debian.org/intro/about">Debian</a> with the <a
|
|
href="https://computingforgeeks.com/how-to-install-cinnamon-desktop-environment-on-debian/">Cinnamon</a> interface, but pretty much any Linux
|
|
system works fine. Old, slow machines without much memory can be very effective with <a href="https://xubuntu.org/">Xubuntu/xfce</a>.
|
|
|
|
<li>If using a Mac or Red-Hat-based linux you'll need to work it all out for yourself.</li>
|
|
|
|
<li>Chromebooks, since 2019, allow you to enable the underlying debian system in a container
|
|
using a tool called <a href="https://chromeos.dev/en/linux">Crostini</a>. This should work just fine, but no one has tried it yet.
|
|
It should be even better than <a href="../troggle/troglaptop.html#os">WSL on Windows</a> as you can run GUI applications on Debian. Or you could install a full Ubuntu system with chroot using
|
|
<a href="https://uk.pcmag.com/linux/135719/how-to-install-linux-on-your-chromebook">Crouton</a>.
|
|
|
|
<li>Windows machines can do almost everything needed directly in Windows itself, but some useful software has no Windows version and you will
|
|
need to find your own equivalents. There are also some 'gotchas' to look out for due to filesystem differences (e.g letter case). If you have
|
|
the choice, use Linux. Windows/Linux WSL is fine.</li>
|
|
|
|
<li><a href="winlaptop.html">A Windows laptop for expo</a> - a page of more detailed instructions for those who are definitely going to be
|
|
using a Windows PC or laptop.</li>
|
|
</ul>
|
|
|
|
<h2><a name="software">Software</a></h2>
|
|
<a href="https://survex.com/screenshots.html"><img src="https://survex.com/img/aven-1.2.37-by-date.png" hspace="20" align="right" width="300"></a>
|
|
<p></a>Long-standing Expo policy is to use open tools and protocols so we can retain control of our own data over the long term. And not to require expo-goers to sign up to external services or spend money on software.
|
|
So we use <a href="https://en.wikipedia.org/wiki/Free_and_open-source_software">FOSS software</a>.
|
|
You can use other software on your own machine if it is format-compatible and exports data in the formats we want,
|
|
but all the recommended software here is open source (and please don't install proprietary software on the '<em>expo laptop</em>').</p>
|
|
|
|
|
|
|
|
<p>The list of software:
|
|
<ul>
|
|
|
|
<li><a href="https://survex.com/download.html">Survex</a>, including the Aven visualisation tool.
|
|
<li><a href="https://survex.com/related.html">Survex related tools</a> Carto, CaveScript (used by CaveView the 3D browser visualiser).
|
|
<li><a href="https://github.com/CaveSurveying/tunnelx">Tunnel</a>: 2.5D cave drawing program based on Survex-compatible data which can also read PocketTopo files. (Generally called 'tunnel' even though the project and executable is actually 'tunnelx'.)
|
|
<li><a href="https://therion.speleo.sk/">Therion</a> - Therion processes survey data and generates maps or 3D models of caves.
|
|
<li><a href="https://bitbucket.org/AndrewA/topparser/src/default/">TopParser</a> - to convert PocketTopo .top files from a DistoX into Therion.
|
|
<li><a href="http://wscc.darkgem.com/caveconverter/">Footleg Cave Converter</a> - to convert PocketTopo .top files from a DistoX into survex (Java)
|
|
<li><a href="https://www.qgis.org/en/site/">QGIS</a> - A Geographic Information System
|
|
<li><a href="https://activityworkshop.net/software/gpsprune/development.html">GPSprune</a> - to edit GPS tracks in GPX files (Java).
|
|
<li><a href="https://sourceforge.net/projects/viking/">Viking</a> - an alternative to GPSprune. The <a href="https://github.com/viking-gps/viking">code</a> is on github.
|
|
|
|
<li><a href="https://github.com/patrickbwarren/qgis3-survex-import">qgis3-survex-import</a> - Patrick's plugin to import/export survex .3d files</li>
|
|
<li><a href="https://vectr.com/user-guide/">Vectr svg</a> - quick and easy sketcher (browser-based, Chrome only) for making rigging topo diagrams: "free forever" committment, but not open source. Please export as svg not jpg or png.
|
|
<li><a href="https://github.com/patrickbwarren/inkscape-survex-export">inkscape-survex</a> - Patrick's plugin to export a traced inkscape line drawing to a survex file.
|
|
<li><a href="http://www.thomas-holder.de/projects/inkscape-speleo/extensions/">inkscape-speleo</a> - plugin to import/export survex, therion and pockettopo files to the drawing package inkscape.
|
|
<li><a href="https://imagemagick.org/script/">Imagemagick convert</a> for re-scaling photographs and scanned images and converting from PDF to JPG. (NB you may need to fix this <a href="https://stackoverflow.com/questions/52998331/imagemagick-security-policy-pdf-blocking-conversion">security issue</a>)
|
|
<li><a href="https://git-scm.com/">git</a> - distributed version control system - already installed on Linux probably</li>
|
|
<li><a href="fzconfig.html">Filezilla</a> - ftp GUI software with a configuration file to get to the expo server (since October 2021 you can't use ftp:// in a Chrome browser anymore)</li>
|
|
<li>python, if you are working on the <a href="../troggle/scriptsother.html">scripts in expoweb/noinfo/</a> such as <var>make-folklist.py</var> or <var>wallets.py</var>- but not on troggle itself - then please use the as close to the same setup as you can to <a href="../troggle/troglaptop.html">the setup we use for troggle</a>. <img src="https://www.python.org/favicon.ico" width=64 hspace="20" align="right">
|
|
</ul>
|
|
<p>Nearly all our Austrian surveys have beeen produced using Tunnel (or were hand-drawn) but many smaller caves and some areas of SMKsystem are done with Therion because Therion does elevations and Tunnel doesn't. Expo has a policy decision on which to use: if it is an entirely new disconnected cave, then use Therion. If it is a passage in a cave where previously we used Tunnel, then use Tunnel. See also <a href="/expofiles/tunnelwiki/wiki/pages/Other_Cave_Software.html">Comparison of Tunnel to Other Cave Software</a>.</p>
|
|
|
|
<a href="https://therion.speleo.sk/2D.php"><img src="https://therion.speleo.sk/img/head.jpg" hspace="20"></a>
|
|
|
|
|
|
|
|
<h4>For Linux users only:</h4>
|
|
<ul>
|
|
<li><a href="https://git-scm.com/download/gui/linux">GUI for git</a> - There is a choice on Linux but many people just use the command line.
|
|
<li>Your favourite text editor. gedit is installed on the <em>expo laptop</em> and has syntax highlighting for .svx files too. This works with <a href="https://survex.com/changes.html">all GtkSourceView-based editors</a> (thanks to Phil Withnall). Download a local copy of the syntax colourizer <a download href="/site_media/survex.lang">survex.lang</a>.
|
|
</ul>
|
|
|
|
<p>Note that on a Debian/Ubuntu machine you should normally install the versions that come with the distro (i.e. install using 'apt install xxx', not be downloading things from the above sites. So installing everything you need should be as simple as:
|
|
<ul>
|
|
<li><tt>apt install openssh-client survex-aven tunnelx therion git sftp</tt></li>
|
|
<li><tt>ssh-keygen</tt> (to generate a key if you haven't already)</li>
|
|
<li><tt>apt install gpsprune qgis firefox-esr gedit tig gitg meld rsync</tt> (you may prefer other tools - e.g: elpa-magit is amazing but only if you know how to drive emacs)</li>
|
|
</ul>
|
|
</p>
|
|
|
|
|
|
<h4 id="win">For Windows users only:</h4>
|
|
<p></p>None of this works until you set up the key-pair setup using PuTty/Pageant.
|
|
|
|
<ul>
|
|
<li><a href="../putty/putty.html">PuTTY</a>.You need this to generate and to use ssh keys on Windows. Otherwise none of git, scp, ftp or rsync will work. It includes command line tools ssh, scp
|
|
(pscp) and sFTP (psftp). The <a href="https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html">PuTTY</a> installation includes puttygen and pagent which you also need. Version 0.77 was released on 2022-05-27.
|
|
<li><a href="https://desktop.github.com/">GitHub Desktop for Windows</a> - yes this works with the expo server git even though we don't use GitHub itself.
|
|
<li><a href="https://code.visualstudio.com/">VS Code</a> is a free (but not FOSS) editor with in-built git capability and plug-ins ("Git History",
|
|
"GitLens")which render git branches graphically. Also available for Linux.
|
|
<li><a href="https://gitforwindows.org/">Git for Windows</a> - not as simple to use as it looks
|
|
<li><a href="https://www.gitkraken.com/">GitKraken</a> - Very pretty GUI interface to git, also Linux version.
|
|
Times-out for our server unless you buy it but free for university people.
|
|
<li><a href="https://winscp.net/eng/download.php">WinScp</a> can be used as an alternative to Filezilla if you like (like Filezilla, it uses PuTTY ssh keys)
|
|
<li><a href="https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview">OpenSSH for Windows</a> is new since 2018. It is a
|
|
set of command line tools which are an alternative to PuTTY. It also includes scp and sftp. It integrates well with Github for Windows and enables you to
|
|
use rsync over ssh.
|
|
<li><a href="https://www.java.com/en/">java</a> - needed for GPSprune and CaveConverter. Has to be installed separately on a Windows machine.
|
|
<li><a href="https://notepad-plus-plus.org/">Notepad++</a> or any other syntax-highlighting code editor for HTML and python. We have a syntax-highlighter
|
|
to colourize .svx files, download it: <a href="/site_media/survex.xml">survex.xml</a>.
|
|
|
|
</ul>
|
|
|
|
<h4>Visual Studio Code editor</h4>
|
|
<p>If you use VS Code here are some relevant extras.
|
|
Not really for beginners but here are <a href="https://docs.microsoft.com/en-gb/learn/modules/python-install-vscode/">instructions for
|
|
configuring it for python</a>.
|
|
On Windows you run VS Code as a Windows app but it communicates directly ("remotely") with the WSL Linux environment.
|
|
<p>You will definitely want the
|
|
<a href="https://marketplace.visualstudio.com/items?itemName=donjayamanne.githistory">"Git History" extension</a>
|
|
and probably the "GitLens" extension too.
|
|
|
|
|
|
|
|
|
|
<h2><a name="configuration">Configuration</a></h2>
|
|
<p>You will already have configured your machine as a 'basic laptop'.
|
|
If you have not yet done this, <a href="basiclaptop.html#configuration">do that now</a>, before continuing with these instructions.
|
|
|
|
<p>If you are using a Windows machine, go and skim read the <a href="winlaptop.html">Windows advanced configuration</a> section before you actually start
|
|
any of this simpler stuff.
|
|
|
|
<p><a href="../../documents/Idiots guide to accessing expo git.pdf">Idiots guide to setting up git for expo</a>
|
|
- PDF - Brendan's guide. Uses PuTTy and GitKraken.
|
|
|
|
<p>You need to <a href="keyexchange.html">register a key with the expo server</a> to get upload (i.e. read/write) access. Do this first, Without it none of git, scp, ftp or rsync will work.
|
|
You can do this entirely on your own if you have access to the <i>expo laptop</i> to upload and install the public key generated by your laptop.</p>
|
|
|
|
<p>On a Windows machine you will need to configure pageant (the putty authentication agent)
|
|
to <a href="https://blog.shvetsov.com/2010/03/making-pageant-automatically-load-keys.html">run at startup to load your key</a>. Note that you are loading your <em>private</em> key, the .ppk file, into pageant and that this key never leaves your laptop.</p>
|
|
|
|
|
|
|
|
|
|
|
|
<p>Full illustrated instructions:<img src="https://wiki.filezilla-project.org/favicon.ico" width=64 hspace="20" align="right"></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="../putty/putty.html">Installing PuTTy on Windows</a>.</li>
|
|
|
|
<li><a href="fzconfig.html">Installing Filezilla</a>.</li>
|
|
|
|
</ul>
|
|
<p>The above gets the command-line PuTTY tools (ssd, sftp, pscp) running, but doesn't get rsync working. You might like to try <a href="https://stackoverflow.com/questions/23517023/rsync-from-windows-to-linux-using-puttys-pagent-authentication">this</a> (untested).</p>
|
|
|
|
<p>When using Windows please, please be <a href="http://expo.survex.com/handbook/survey/getin.htm#filenames">excessively careful when naming files and survex names</a> and be <a href="manual.html#quickstart">exceptionally careful when using rsync</a>.
|
|
|
|
|
|
<h3>Learning how to use this software</h3>
|
|
|
|
<ul>
|
|
<li>Using Survex, Tunnel and Therion, see the <a href="http://expo.survex.com/handbook/survey/">Expo Handbook - Surveying section</a>.
|
|
|
|
<li><p><a href="/expofiles/documents/therion/therion-cp33.pdf"><em>Drawing Surveys with Therion</em></a> (Wookey, Compass Points, March 2004)
|
|
<li><p><a href="/expofiles/documents/therion/tharticle-vercors-2008.pdf"><em>Therion - Digital Cave Maps </em></a> Martin Budaj, Stacho Mudrák, 2008)
|
|
<li><p><a href="/expofiles/documents/therion/thbook-v6.0.4.pdf"><em>The Therion Book</em></a> v6.0.4 (2012-11-28)
|
|
|
|
<li><em>For installing Survex, Tunnel etc. see <a href="getsurvex.html">this page</a> which may be merged in here eventually.</em>
|
|
|
|
<li><a href="../../documents/tunnel-loefflerCP35-only.pdf">Introduction to using Tunnel</a> - article by Dave Loeffler. This is really good and should be read first.
|
|
|
|
<li><a href="http://expo.survex.com/expofiles/tunnelwiki/wiki/pages/Tunnel.html">The Tunnel tutorial</a> - installation notes and a wiki of examples and tutorials
|
|
<li><a href="https://github.com/CaveSurveying/tunnelx">Tunnel - master copy since August 2019</a>. This is where the software is actively developed and is the most up to date copy, but the documentation is not as complete as in the other locations.
|
|
|
|
</ul>
|
|
<img src="tunnelbanner204.jpg" > <br />
|
|
|
|
<h3>Cheat lists and quick reminders</h3>
|
|
<ul>
|
|
<li>Quick <a href="qstart-git.html">reminders for using git</a> at the command line.
|
|
<li>Quick <a href="qstart-rsync.html">reminders for using rsync</a> at the command line.
|
|
</ul>
|
|
|
|
<h3>Logins to external systems</h3>
|
|
|
|
<p>
|
|
<a href="https://web.libera.chat/#expo">#expo</a> - public. An open-access <a href="https://en.wikipedia.org/wiki/Internet_Relay_Chat">
|
|
open-access IRC channel</a>
|
|
(ephemeral, not archived) for real-time discussions about everything but mostly software people. If you are having trouble using the software try here first.
|
|
</p>
|
|
<ul>
|
|
<li><a href="https://github.com/join">Github</a> - You'll need an account if you want to use this.
|
|
<li><a href="https://github.com/CaveSurveying/CUCCexposurveyissues/issues">Expo issues list</a> - Issues with data reduction for recent expos and software updates for tunnel
|
|
<li><a href="https://bitbucket.org/product/">Bitbucket</a> - create an account to help develop tunnel. <img src="https://tortoisehg.bitbucket.io/img/bitbucket-icon.png" width=64 hspace="20" align="right">
|
|
<li><a href="https://trac.survex.com/wiki">Trac issue tracker and wiki</a> for developing survex. You'll need a login to file bugs there.
|
|
</ul>
|
|
|
|
<p>Some expo survey stuff is tracked externally:
|
|
<ul>
|
|
<li><a href="https://github.com/CaveSurveying/CUCCexposurveyissues/issues">CUCC CaveSurveying Bug lists and open issues discussed on github</a> -
|
|
issue list so you will need to subscribe to the Cave Surveying Group on github to participate.
|
|
|
|
<li><a href="https://github.com/CaveSurveying/CUCCexposurveyissues/wiki/Expo-tunnel-workflows">Expo-tunnel-workflows</a> -
|
|
a wiki on github discussing workflows to generate centerlines, GEOTIFF and QGIS integration.
|
|
</ul>
|
|
|
|
|
|
<h3>Complementary tools</h3>
|
|
<p>When maintaining the HTML files in the expo handbook a link-checker is useful to report bad URLs (links to external sites go bad regularly) and to find orphaned pages with no in-links. The website has <a href="https://www.klebos.net/subdomains/keldos/LinkScans/TUNNEL-wiki-link-report.html">about 2,000 internal URLs</a> in just the Tunnel wiki section alone.
|
|
<ul>
|
|
<li><a href="https://www.brokenlinkcheck.com/">Online brokenlinkcheck tool</a> - does not install on your laptop. Limited to 3,000 pages.
|
|
<li><a href="https://www.deadlinkchecker.com/website-dead-link-checker.asp">Another online brokenlinkcheck tool</a> - does not install on your laptop. Limited to 2,000 pages but breadth-first rather than depth-first, so it covers a different chunk of the expo website.
|
|
<li><a href="https://www.drlinkcheck.com/account/subscriptions/1/projects/1/overview">Yet another link-checker</a>, only 1,500 pages checked but oh-so-stylish results presentation. Very informative.
|
|
<li><a href="http://home.snafu.de/tilman/xenulink.html">Xenu Link Sleuth</a> - install on Windows to do comprehensive link check.
|
|
<li><a href="https://www.digitalocean.com/community/tutorials/how-to-find-broken-links-on-your-website-using-wget-on-debian-7">Linkchecking with wget</a> - command line methods on Linux
|
|
</ul>
|
|
|
|
<a href="http://wscc.darkgem.com/caveconverter/"><img src="CaveConverterWorkflow.png" width=600 hspace="20"></a>
|
|
|
|
<hr /></body>
|
|
</html>
|