TauDEM

TauDEM (Terrain Analysis Using Digital Elevation Models) is a suite of Digital Elevation Model (DEM) tools for the extraction and analysis of hydrologic information from topography as represented by a DEM.

📋 Table of Contents

• What's TauDEM
• Setup Visual Studio Code for TauDEM Development
• Building/Compiling TauDEM
  • Using Command Line
  • Using VS Code Tasks
• Dependencies
• Project Structure
• Testing
• Contributing
• Resources
• Support
• License

🌍 What's TauDEM

TauDEM is a comprehensive suite of tools designed for terrain analysis using Digital Elevation Models. It provides algorithms for:

• Flow Direction Analysis: D8 and D-Infinity flow direction algorithms
• Contributing Area Calculation: Watershed delineation and catchment area computation
• Stream Network Extraction: Automatic identification and characterization of stream networks
• Topographic Analysis: Slope, aspect, curvature, and wetness index calculations
• Hydrologic Modeling: Tools for runoff analysis and watershed characterization

Key Features

• Parallel Processing: Built with MPI support for high-performance computing
• Multiple Algorithms: Supports both D8 and D-Infinity flow routing methods
• ArcGIS Integration: Python toolbox for seamless integration with ArcGIS
• Cross-Platform: Runs on Windows, Linux, and macOS
• Open Source: Licensed under GPL v3

For more information, visit the official website and the project wiki.

Setup VS Code for TauDEM Development

Clone the TauDEM Github Repository

Installing Git

Before cloning the repository, you'll need to install Git if you don't have it already:

macOS:

# Using Homebrew
brew install git

# Or download the installer from
# https://git-scm.com/download/mac

Windows:

# Download and run the installer from
# https://git-scm.com/download/win

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install git

Verify your installation:

git --version

Cloning the Repository

After installing Git, clone the TauDEM repository at a location of your choice:

git clone https://github.com/dtarb/TauDEM.git
cd TauDEM
git status
# Should show 'On branch Develop'
# You can then checkout the branch you want to work on or create a new branch

Install Visual Studio Code (VS Code)

Download and install Visual Studio Code for your operating system using this link: https://code.visualstudio.com/download

Prerequisites

Before setting up VS Code, ensure you have the required dependencies installed (see Dependencies section).

VS Code Extensions

Install the following essential extensions for TauDEM development:

# Core C++ development
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cpptools-extension-pack

# CMake integration
code --install-extension ms-vscode.cmake-tools

# Git integration
code --install-extension eamodio.gitlens

# Additional helpful extensions (better C++ syntax highlighting)
code --install-extension jeff-hykin.better-cpp-syntax

# Optional extensions for specialized tasks
code --install-extension ms-vscode.hexeditor  # For examining binary DEM files (optional)

Platform-Specific Setup

macOS Setup

1. Copy VS Code settings template:

   cp .vscode/settings-macos.json.template .vscode/settings.json

2. Install dependencies via Homebrew:

   # Core dependencies
   brew install gdal
   brew install open-mpi
   brew install cmake

3. Configure IntelliSense: The .vscode/c_cpp_properties.json is already configured for macOS with proper include paths.

Windows Setup

1. Copy VS Code settings template:

   copy .vscode\settings-windows.json.template .vscode\settings.json

2. Install vcpkg dependencies: See section for detailed instructions.

3. Configure paths: Update the include paths in .vscode/c_cpp_properties.json if your vcpkg installation is in a different location.

4. Install CMake: Download and install CMake for Windows (look for the binary distribution for platform 'Windows x64 Installer') from the following link:

   https://cmake.org/download/

Linux Setup

1. Install dependencies:

   sudo apt update
   sudo apt install -y build-essential cmake openmpi-bin libopenmpi-dev \
                        gdal-bin libgdal-dev libproj-dev libtiff-dev libgeotiff-dev

2. Configure VS Code: Create .vscode/settings.json with appropriate Linux-specific settings.

VS Code Configuration

The project includes pre-configured settings for:

• IntelliSense: Proper C++ standard (C++17) and include paths
• CMake Integration: Source directory set to src/
• Code Formatting: C++ formatting with ms-vscode.cpptools
• Compiler Configuration: Platform-specific compiler settings

Debugging Setup

Configure Launch Configuration (for debugging TauDEM tools)

NOTE: Here is an example of a launch.json configuration for debugging shown to explain the configuration. You do not need to create this file. The launch-*.json.template files are already configured for each platform.

Example .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug TauDEM Tool",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/bin/pitremove",
            "args": ["-z", "input.tif", "-fel", "output.tif"],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

Understanding launch.json Configuration

The launch.json file configures VS Code's debugging system for TauDEM development. Here's what each setting does:

🔧 Core Configuration

• "version": "0.2.0" - VS Code debugging configuration format version
• "configurations": [] - Array containing different debug configurations (you can have multiple)

🎯 Debug Target Settings

• "name": "Debug TauDEM Tool" - Display name in VS Code's debug dropdown menu
• "type": "cppdbg" - Specifies C++ debugger type
• "request": "launch" - Launch a new process (alternative: "attach" to running process)

📂 Program and Arguments

• "program": "${workspaceFolder}/bin/pitremove" - Path to executable to debug
  • ${workspaceFolder} = path/to/TauDEM local repository
  • Targets the pitremove tool (pit removal algorithm)
• "args": ["-z", "input.tif", "-fel", "output.tif"] - Command line arguments
  • Simulates running: ./bin/pitremove -z input.tif -fel output.tif
  • -z input.tif: Input DEM file with pits
  • -fel output.tif: Output filled DEM file

🔍 Execution Environment

• "stopAtEntry": false - Don't automatically break at main() function
• "cwd": "${workspaceFolder}" - Working directory for the debugged program
• "environment": [] - Environment variables (empty array = inherit from VS Code)
• "externalConsole": false - Use VS Code's integrated terminal instead of external console

🛠️ Debugger Configuration

• "MIMode": "gdb" - Use GDB debugger (GNU Debugger for macOS/Linux)
  • On Windows, this would be "vsdbg" for Visual Studio debugger
• "setupCommands" - GDB initialization commands
  • "-enable-pretty-printing" makes variable display more readable during debugging

🚀 How to Use the Above Example Configuration

1. Place test files: Ensure input.tif exists in your workspace root

2. Set breakpoints: Click in the margin next to line numbers in C++ source files

3. Start debugging: Press F5 or Run → Start Debugging to debug the first configuration. To debug a different target, first press cmd+shift+d (macos) or ctrl+shift+d (Windows/Linux) to open the Debug panel, or click on the Run and Debug icon (icon with a bug symbol) in VS Code's activity bar (vertical toolbar on the left side of vscode). Then select a configuration from the debug dropdown and press F5 to start debugging.

4. Debug controls available:

   • Step Over (F10): Execute current line, don't enter function calls
   • Step Into (F11): Enter function calls to debug inside them
   • Step Out (Shift+F11): Exit current function
   • Continue (F5): Run until next breakpoint
   • Variables panel: Inspect variable values and memory
   • Call stack: See function call hierarchy
   • Watch expressions: Monitor specific variables/expressions

🔄 Customizing for Other Tools

To debug different TauDEM tools, create additional configurations:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug PitRemove",
            "program": "${workspaceFolder}/bin/pitremove",
            "args": ["-z", "dem.tif", "-fel", "filled.tif"]
        },
        {
            "name": "Debug AreaD8",
            "program": "${workspaceFolder}/bin/aread8",
            "args": ["-p", "flowdir.tif", "-ad8", "area.tif"]
        },
        {
            "name": "Debug D8FlowDir",
            "program": "${workspaceFolder}/bin/d8flowdir",
            "args": ["-fel", "filled.tif", "-p", "