Installing LSDTopoTools

If you are in a Linux or MacOS all you really need is Miniconda. You should use the python 3.8 version.

In windows don’t install conda for windows! Create an Ubuntu subsystem using these instructions and install conda there.

Once you have conda you can install the command line tools like this:

$ conda -c conda-forge install lsdtopotools

Now you can use the command line tools!

You install lsdtopytools using conda

$ conda -c conda-forge install lsdtopytools

You install lsdviztools using pip:

$ pip install lsdviztools

These both have a bunch of dependencies so it is easier to use our docker container that has everything pre-installed. You can read about that below.

Download and install Docker Community Edition. Instructions on different operating systems are in the Docker documentation.

We will henceforth assume that you actually have a functioning version of Docker on your host machine. If you want more details about how to use docker, or getting it set up (particularly in Windows, in Linux and MacOS this is more straightforward), see our section on docker notes.

lsdtt-alpine: This is the stripped-down, lightweight LSDTopoTools container. It uses a linux distrubution called the alpine linux distribution. For many users, this is the only container you will need. It is an 88 Mb download and when built, it is a bit under 300 Mb.

lsdtt-pcl: A few of our routines (notably the terrace extraction routines and any routines using swath profiling) require something called the point cloud library (PCL). This library is ENORMOUS and a massive pain to install. It does everything the lsdtt-alpine container does, and more. It is big: the download is 644 Mb and built it is over 2 Gb. However, if you need this one you can use it instead of the lsdtt-alpine container.

lsdtt-viz: This container installs all the python routines you need if you want to use our visualisation tools. Our tools require multiple python packages, meaning that this container is also quite large. If you use a GIS to look at our data, you won’t need this. However we do all our visualisation in python and have written lots of automation scripts, so if you think you will used LSDTopoTools routinely you might want to grab this dockerfile.

lsdtt-docs: Our documentation is all written in asciidoc format, and processed with the extremely awesome asciidoctor. It runs in the Ruby programming language, and requires some stuff to be installed. We have a container for building the documentation so you don’t need to worry about installing the correct stuff. It is very unlikely you will need this unless you are an LSDTopoTools developer.

First, make a directory in your host operating system where you will put all the files associated with LSDTopoTools. I put mine in C:\LSDTopoTools\

To share a directory in docker you use the -v flag.

When you run docker (see below) you will need to ensure that the host directory name is the same as the directory you just created for LSDTopoTools.

Okay, this should be fairly easy.

If you want to run the full docker installation from the get go, simply run:

$ docker run --rm -it -v C:/LSDTopoTools:/LSDTopoTools lsdtopotools/lsdtt_pcl_docker

If you want the lightweight version (but it can’t do floodplains and terraces) use:

$ docker run --rm -it -v C:/LSDTopoTools:/LSDTopoTools lsdtopotools/lsdtt_alpine_docker

Either one of these commands will result in your command line terminating in the # symbol. This indicates that you are insida a docker container.

Once you are in one of the two docker containers, run the install script:

# Start_LSDTT.sh

If you want to follow our examples later in this documentation, you should also grab the example data:

# Get_LSDTT_example_data.sh

You can now navigate to your data and start using LSDTopoTools. See our section on first analyses in LSDTopoTools.

Create a folder where you are going to put files associated with docker. In the examples I will assume these are in C:\LSDTopoTools\ (this is a windows path, since the majority of organisations use the Windows operating system).

If you are only running LSDTopoTools for routine analysis and looking at the results in GIS software, you will only need one docker container.

We are only going to work with the lsdtt-alpine container. But the steps are basically the same for all the other containers.

Start a terminal (MacOS or Linux) or powershell (Windows) with docker enabled.

Go into the directory inside you docker directory (in my case C:\Docker\LSDTopoTools\) and go into the lsdtt_alpine directory. In windows, if your directory is called the same thing as my directory, you can get there with:

PS> cd C:\Docker\LSDTopoTools\lsdtt_alpine_docker

Build the docker container:

PS> docker build -t lsdtt-alpine .

The -t flag in docker stands for "tag". It is the name of the container. You could call it anything you want but all documentation henceforth assumes you have called it lsdtt-alpine.

Now you need to run this container:

$ docker run -it -v C:/LSDTopoTools:/LSDTopoTools lsdtt_alpine_docker

After that, run the install script:

# Start_LSDTT.sh

If you want to follow our examples later in this documentation, you should also grab the example data:

# Get_LSDTT_example_data.sh

You can now navigate to your data and start using LSDTopoTools. See our section on first analyses in LSDTopoTools.

Start a terminal session.

Install some essential softare (we will use Ubuntu installation, you need to modify these if you are on another version of Linux). This assumes you have the GNU c++ tools:

$ sudo apt-get install -y git
$ sudo apt-get install -y gdal-bin
$ sudo apt-get install -y python-gdal
$ sudo apt-get install -y libfftw3-dev
$ sudo apt-get install -y cmake

Grab the script

$ wget https://raw.githubusercontent.com/LSDtopotools/LSDTT_Edinburgh_scripts/master/LSDTT_native_linux_setup.sh

Run the script

$ sh LSDTT_native_linux_setup.sh

You will need to tell this script where you want to install LSDTopoTools.

The first time you run this it will take a while to compile and get all the files. But you can run it thereafter for any terminal session and it will add the actually LSDTopoTools programs to your $PATH for that session.

If you don’t want to bother with the script each time, we suggest adding the location of the LSDTopoTools prgrams to your $PATH in your .bashrc file. If you don’t know what that previous sentence means, just use the script.

Firstly, download the Ubuntu app from Microsoft Store. If you can’t find it, then you can also get it from this link. You might need to restart your computer as prompted following this step.

Launch the Ubuntu app by clicking on it from the Start menu. You will then be prompted to create a new user account and password - you can choose whatever you want for this, but make sure you remember it! The password is important for installing packages in the next steps.

The first time you launch, make sure you update and upgrade your standard packages by typing:

$ sudo apt update && sudo apt upgrade

Now install the dependencies for LSDTopoTools:

$ sudo apt install -y build-essential git gdal-bin python-gdal libfftw3-dev cmake

Then make a new directory for the LSDTopoTools code and download it from GitHub:

$ mkdir LSDTopoTools && cd LSDTopoTools
$ git clone https://github.com/LSDtopotools/LSDTopoTools2.git

This will create a directory called ~/LSDTopoTools/LSDTopoTools2 in your home. Navigate to this directory and run the start up script:

$ cd LSDTopoTools2
$ bash lsdtt2_setup.sh

This script will set up the code: we then need one more command to add the binary to your local path. First run:

$ cd bin
$ pwd

This will print out a directory path. Copy this directory path, let’s call it /path/to/your/bin for the sake of this example, and run:

$ export PATH=/path/to/your/bin:$PATH

This will link the bin folder to the system path and make the code executable from anywhere in the Linux subsystem.

Open a file explorer window and under computer select the "University drive":

Figure 1. The university drive

Then go into the Science and Engineering folder ("SCE"):

Figure 2. The science and engineering folder

Then into the GeoSciences folder ("GEOS"):

Figure 3. The geosciences folder

Then into the Drive Mapping folder ("drive_mapping"):

Figure 4. The drive mapping folder

And finally double click the shortcut "Access Netdata":

Figure 5. The access netdata shortcut

In the windows search bar, type "powershell" and start a windows powershell.

Figure 6. Start powershell

Type ssh UUN@ssh.geos.ed.ac.uk.

Figure 7. Go onto a server using the ssh command. You must use your own university username (UUN)!

It will ask you a yes/no question about adding a key. Type yes.

Enter your EASE password. and enter your password. UUN is your university user name.

This puts you into the university ssh server, which is slow. Move into a better one by typing ssh burn.

Figure 8. Go onto burn. You could also try achray

Navigate to your home directory

$ cd ~

Get the setup script from the internet

$ wget https://raw.githubusercontent.com/LSDtopotools/LSDTT_Edinburgh_scripts/master/LSDTT_UEdin_setup.sh

Figure 9. Grab the startup script from the internet using wget. Brief note: for downloading large files, wget is much faster than downloading files through a browser.

Now run the script:

$ sh LSDTT_UEdin_setup.sh

Figure 10. Run the script.

Follow the prompts.