Skip to content

Getting Started

Jump to bottom
Lukas edited this page May 22, 2024 · 9 revisions

Welcome to the installation guide for the GeoRoughness Tool. This page will walk you through the steps required to install and set up the software on your system. The GeoRoughness Tool supports Windows, macOS, and Linux operating systems.

Prerequisites

Before you begin, ensure that your system meets the following requirements:

  • Python 3.12 or later: The software is built to run with Python 3.12 and above.
  • pip: Python's package installer, used to install the DEM Roughness Calculator.

Step-by-Step Installation

Windows

Windows

  1. Install Python:

    • Visit the official Python website.
    • Download the installer for Python 3.12 or later.
    • Run the installer. Ensure to check the box that says "Add Python 3.12 to PATH" at the beginning of the installation process.
    • Complete the installation.

  2. Verify Installation:

    • Open Command Prompt and type: 
      python3 --version
      This should display the Python version installed.
    • Check pip is installed: 
      pip3 --version

  3. Install GeoRoughness Tool:

    • In the Command Prompt, run: 
      pip3 install geo-roughness-tool
      This command downloads and installs the GeoRoughness Tool along with its dependencies. If you encounter any permission issues, try running the Command Prompt as Administrator on Windows.
macOS

macOS

  1. Install Python:

    • You can install Python using Homebrew (a package manager for macOS). If you do not have Homebrew installed, you can install it by pasting the following command in a Terminal window: 
      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    • Once Homebrew is installed, install Python by running: 
      brew install python@3.12

  2. Verify Installation:

    • In the Terminal, run: 
      python3 --version
      • This should return the version of Python installed.
    • Ensure pip is working: 
      pip3 --version

  3. Install GeoRoughness Tool:

    • In the Terminal, run: 
      pip3 install geo-roughness-tool
      This command downloads and installs the GeoRoughness Tool along with its dependencies. If you encounter any permission issues, try adding sudo before the command.
Linux

Linux

  1. Install Python:

    • Most Linux distributions come with Python pre-installed. If not, you can install it using your distribution’s package manager. For Ubuntu, use: 
      sudo apt update
sudo apt install python3.12 python3-pip

  2. Verify Installation:

    • Check Python installation: 
      python3 --version
    • Check pip installation: 
      pip3 --version

  3. Install GeoRoughness Tool:

    • Use pip to install: 
      pip3 install geo-roughness-tool
      This command downloads and installs the GeoRoughness Tool along with its dependencies. If you encounter any permission issues, try adding sudo before the command.

Running the Software

To start the programm, simply run:

georough

This command launches the GUI where you can interactively load DEM files, set parameters, and view the roughness calculations. The GUI version also allows to use more tools, like the use of training data to calculate optimized thresholds.

CLI Application

Note

Command Line Interface (CLI)

The CLI version is not maintained anymore. It should still support basic roughness calculations, but for newer features and optimizations, please use the GUI version.

This package also provides a basic command line interface (CLI) for batch processing of DEM files.

To use the CLI tool, run the following command in your terminal:

georough --input_path "path/to/input.tif" --output_dir "path/to/output"

Additional Parameters

The CLI tool supports the following additional parameters:

  • --window_size: The size of the window in meters for calculating roughness.
    • Default is 1.0 meter.
    • Accepts float values.
    • Example: --window_size 2.5 for a 2.5-meter window.
  • --categorical_thresholds: Set of thresholds to categorize the roughness data.
    • Default is None.
    • Accepts a list of float values separated by commas.
    • Example: --categorical_thresholds 0.01,0.1,0.3 for thresholds at 0.01, 0.1, and 0.3.
    • Creates a category 0 for values below the first threshold, 1 for values between the first and second threshold, and so on.
  • --band_number: The specific band of the DEM to process. Only applicable for multi-band DEMs.
    • Default is 1.
    • Accepts integer values.
    • Example: --band_number 2 for the second band.
  • --high_value_threshold: Threshold to filter out high roughness values that can be calculated at the borders of the DEM.
    • Default is 10.0.
    • Accepts a float value.
    • Example: --high_value_threshold 50.0 to filter out values above 50.

For information about the parameters and their usage, visit Parameter Explanation

Updating the Software

To update the GeoRoughness Tool to the latest version when released, use:

pip3 install --upgrade geo-roughness-tool

Uninstalling the Software

If you need to uninstall the GeoRoughness Tool, execute:

pip3 uninstall geo-roughness-tool

Troubleshooting

If you run into any issues during the installation or running of the DEM Roughness Calculator, please refer to the Troubleshooting section of the wiki. If your issue is not listed there, do not hesitate to contact support or submit an issue.

Clone this wiki locally