Installation¶

To work with flusstools, a couple of dependencies have to be installed and depending on what platform you are working (Window or Linux), it might be preferable to use either a PIP3 or a CONDA environment. We have made good experience with conda environments in Windows and with pip environments in Linux (Ubuntu). However, both pip and conda both work fine on both platforms (and also with macOS). Since Python 3.4 (and Python 2.7.9), pip is installed with the basic Python installation (download and install Python if you do not want to use conda). Find the instructions for installing Anaconda tailored for your ooperating system (Linux, Windows, or macOS) in the Anaconda docs. The following paragraphs guide through setting up your system for the best experience with flusstools (and basically any geo-spatial Python application).

Get ready on Windows¶

On Windows, a convenient option for working with flusstools is to use a conda environment. In addition, GitBash is necessary to clone (download) flusstools (and to keep posted on updates). In detail:

Install Anaconda, for example, as described on hydro-informatics.github.io (IDEs).
Alternatively, download and install Python, open Windows Command Prompt, and make sure to upgrade pip with your basic Python installer by typing: python -m pip install -U pip.
Download and install GitBash.
We recommend to work with an IDE, such as PyCharm or Spyder, which is natively implemented in the Anaconda installation.
Download and install QGIS to visualize and draw geospatial data.

Get ready on Linux¶

Optional: Use a Virtual Machine (VM)¶

Either download a net-installer ISO of Debian Linux, Ubuntu, or one of its light-weight spin-offs such as the Lubuntu, and install one of theses images as a Virtual Machine (VM). To get started with VMs read the introduction to VMs on hydro-informatics.github.io (about VMs). Installing any other the Linux VM works similar, as described on hydro-informatics.github.io (VirtualBox) for Debian Linux. Just use the ISO image in lieu of the Debian Linux ISO. After installing Linux as a VM, make sure to:

Install Guest Additions for Linux VMs in VirtualBox.
Enable folder sharing between the host and guest (Debian, Ubuntu, or Lubuntu image).

Other system setups described on hydro-informatics.github.io (VM) (e.g., Wine) are not required in the following.

Prepare your system¶

Open Terminal and update the system:

sudo apt update && sudo apt full-upgrade -y

Update Python references¶

Some (basic) Linux distributions still have Python2 implemented as base interpreter to be used when python is called in Terminal. However, Python2 usage is deprecated, and therefore, we want to make sure to robustly use Python3 for running any Python script. Check out the installed Python3 versions:

ls /usr/bin/python*

/usr/bin/python  /usr/bin/python2  /usr/bin/python2.7  /usr/bin/python3  /usr/bin/python3.8  /usr/bin/python3.8m  /usr/bin/python3m

In this example, Python2.7 and Python3.8 are installed. To overwrite Python2 usage, set the python environment variable so that it points at Python3:

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.6 2
alias python=python3

PIP3 and additional libraries for geospatial analyses¶

Make sure that PyGeos and tkinter are available for use with geopandas:

sudo apt install python3-pip
sudo apt-get install python3-tk
sudo apt install tk8.6-dev
sudo apt install libgeos-dev

Then install QGIS and GDAL for Linux (this should work with any Debian architecture):

sudo add-apt-repository ppa:ubuntugis/ppa && sudo apt-get update
sudo apt-get update
sudo apt-get install gdal-bin
sudo apt-get install libgdal-dev
export CPLUS_INCLUDE_PATH=/usr/include/gdal
export C_INCLUDE_PATH=/usr/include/gdal
pip3 install GDAL

Note

Check on the latest GDAL release on the GDAL website.

More guidance for installing GDAL (also on other platforms) is available at gdal.org.

Install an IDE (PyCharm)¶

Note

IDE - your choice Any other Python IDE is also OK for working with hylas. Setting up PyCharm is explained here as just one option for working with flusstools.

Install PyCharm with snap (requires snap):

sudo apt install snapd
sudo snap install pycharm-community --classic

Install flusstools¶

conda¶

Download our environment.yml file and save it in a temporary folder (e.g., C:temp* or *USER/Downloads/).
Open Anaconda Prompt (on Windows) or Terminal (on Linux).
Navigate to your download directory (e.g., cd C:\temp or cd Downloads/).
Install the flusstools environment:
- conda env create -f environment.yml
- Geospatial libraries and other dependencies (see below) are being installed in a new environment called flusstools - this may take a while …
- Read more about installing, managing, or removing conda environments on hydro-informatics.github.io (install).
Activate the flusstools environment:
- conda activate flusstools
Install flusstools in the new environments (yes, use pip in conda):
- pip install flusstools

pip / venv¶

Consider to create and activate a new virtual environment before installing flusstools requirements (read more at python.org). Then, download our requirements.txt file and save it in a temporary folder (e.g., C:temp* or *USER/Downloads/). In Terminal (Linux / macOS) or Windows Command Prompt type:

cd C:\temp # or cd Downloads/
pip install -r requirements.txt
pip install flusstools

Setup IDE environment¶

Depending on the IDE you are using, create a new project and define the above created environment (either conda or pip) as project interpreter.

PyCharm users get help at jetbrains.com
Spyder users find help at spyder-ide.org
Notebook users are served at jupyter.org

Basic Usage¶

Run Python and add the download directory of flusstools to the system path:

import os, sys
sys.path.append("D:/Target/Directory/flusstools/")  # Of course: replace "D:/Target/Directory/", e.g., with  r'' + os.path.abspath('')

Import flusstools:

import flusstools as ft

from flusstools import geotools as gt
raster, array, geo_transform = gt.raster2array("/sample-data/froude.tif")
type(raster)
<class 'osgeo.gdal.Dataset'>
type(array)
<class 'numpy.ndarray'>
type(geo_transform)
<class 'tuple'>
print(geo_transform)
(6748604.7742, 3.0, 0.0, 2207317.1771, 0.0, -3.0)

Requirements¶

FlussTools requires geo-spatial processing libraries, which cannot be directly resolved by running setup.py. For this reason, we recommend to either install a virtual environment (pip / venv) with requirements.txt (pip / venv) or a conda environment (conda) with environment.yml (conda) to check out the following dependencies:

pip
tabulate
numpy
platform
pandas
matplotlib
plotly
alphashape
earthpy
gdal
geopandas
geojson
laspy
mapclassify
pyshp
rasterio
rasterstats
shapely
tk

FlussTools 0.1