grd2stream – QGIS Plugin
Table of Contents
Overview
The grd2stream QGIS plugin allows users to comfortably generate multiple flowlines from velocity grids by selecting seed points.
This plugin utilizes GMT6 (Generic Mapping Tools) to ensure compatibility with all GDAL file formats.
The core functionality is based on the grd2stream command-line utility, which calculates streamlines from gridded velocity
fields using Runge-Kutta integration methods.
Key Features
- Generate flowlines from any GDAL-compatible X and Y velocity component rasters
- Interactive seed point selection via map clicks or manual coordinate entry
- Configurable integration parameters (step size, max steps, etc.)
- Save and load parameter presets for repeated use
- Isolated GMT6 environment that doesn't interfere with existing installations
Installation & Requirements
QGIS Plugin Installation
- Open QGIS
- Go to Plugins → Manage and Install Plugins
- Search for "grd2stream"
- Click "Install Plugin"
Dependencies
The plugin requires:
- QGIS 3.0 or higher
- GMT6 (Generic Mapping Tools version 6)
- grd2stream command-line utility
Note: On Linux and macOS, the plugin can automatically install these dependencies in an isolated Miniconda environment.
Current Status
| Platform |
Status |
Notes |
| Linux |
✅ Fully Supported |
Automatic installation of dependencies via Miniconda |
| macOS |
✅ Fully Supported |
Automatic installation of dependencies via Miniconda |
| Windows |
🚧 In Development |
Currently only planning/parameter configuration available. Command execution not yet supported. |
Windows Limitations
On Windows, the plugin currently cannot execute the grd2stream command. However, you can still:
- Configure all parameters and settings
- Save and manage presets
- View the command that would be executed (for reference)
Full Windows support is being developed and will be available in a future update.
Technical Architecture
Component Overview
The plugin consists of several key components:
- QGIS Plugin Interface - The UI components that integrate with QGIS
- Flowline Module - Core functionality for generating flowlines
- Preset Manager - Handles saving and loading of parameter configurations
- Conda Environment Management - Handles installation and management of GMT6 and grd2stream
Dependency Management
On Linux and macOS, the plugin:
- Installs Miniconda3 to
~/miniconda3 (if not already installed)
- Creates a "GMT6" Conda environment with GMT6 and required dependencies
- Installs the grd2stream utility in the Conda environment
This approach ensures that:
- The plugin works without requiring system-wide installation of GMT6
- The plugin's dependencies don't interfere with existing installations
- No administrator privileges are required for installation
Using the Plugin
Basic Workflow
- Click the grd2stream icon in the QGIS toolbar
- If this is your first time using the plugin on Linux or macOS, you may be prompted to install dependencies
- Select input rasters:
- Raster 1: X-component of velocity
- Raster 2: Y-component of velocity
- For multi-band rasters, select the appropriate band for each component
- Configure parameters or load a preset
- Click OK to proceed to seed point selection
- Choose a method to select the seed point:
- Click on the map
- Enter coordinates manually
- The plugin will calculate the flowline and add it to your project as a vector layer
Parameter Configuration
Required Parameters
- Raster 1 & Raster 2: The X and Y component rasters
- Seed Point: The starting location for the flowline
Optional Parameters
- Backward Steps: Enable to trace the flowline in both upstream and downstream directions
- Step Size: Distance increment for integration steps (default is min(x_inc, y_inc) / 5)
- Max Integration Time: Maximum time for the integration process
- Max Steps: Maximum number of steps to calculate (default is 10,000)
- Output Format: Choose what data columns to include in the output layer
Output Formats
- Default (no option): x y dist
- X and Y coordinates
- Distance along the flowline
- Extended (-l): x y dist v_x v_y
- All default columns
- X and Y velocity components at each point
- Full (-t): x y dist v_x v_y time
- All extended columns
- Integration time for each point
Working with Presets
Saving Presets
To save your current configuration as a preset:
- Configure parameters in the main dialog
- Click "Save as Preset"
- Enter a name for your preset
- Confirm to save
Loading Presets
To load a saved preset:
- Click "Load Preset" in the main dialog
- Select a preset from the list
- Click "Select"
Managing Presets
The preset management dialog allows you to:
- View: See detailed settings for each preset
- Edit: Modify parameters for existing presets
- Delete: Remove presets that are no longer needed
Using Last Settings
The "Use Last Settings" button quickly reapplies:
- The last manually configured settings, or
- The last preset that was used
Note: Presets are stored in a presets.json file in the plugin directory and persist between QGIS sessions.
Technical Details
Integration Method
The plugin uses the grd2stream utility, which implements:
- 4th-order Runge-Kutta integration method
- Adaptive step size control (optional)
- Bi-linear interpolation between grid points
Supported File Formats
The plugin can work with any raster format supported by GDAL, including:
- GeoTIFF
- NetCDF
- HDF5
- GRIB
- ASCII Grid
- Many others
Tip: For NetCDF and similar multi-dimensional formats, you can select the specific variable by choosing the appropriate band in the input dialog.
Output Processing
The plugin:
- Executes the grd2stream command with the specified parameters
- Captures the command output (a text stream of coordinates and attributes)
- Parses the output and converts it to a QGIS vector layer
- Adds the vector layer to the current project
Troubleshooting
Common Issues
No Flowline Generated
- Issue: Plugin runs but no flowline appears
- Possible causes:
- Seed point placed in an area with zero or undefined velocity
- Input rasters don't represent valid velocity components
- Step size too large for the data resolution
- Solutions:
- Try a different seed point location
- Verify raster data represents X and Y velocity components
- Reduce step size
Installation Problems
- Issue: Dependency installation fails
- Possible causes:
- Network connectivity issues
- Insufficient disk space
- Permission issues in home directory
- Solutions:
- Check internet connection
- Ensure at least 1GB free disk space
- Check QGIS Python console for detailed error messages
Windows Support
- Issue: Plugin shows command but doesn't execute it
- Cause: Windows execution support is still under development
- Solution: Currently not available; Windows support will be added in a future update
Checking Logs
For detailed troubleshooting:
- Open the QGIS Python Console (Plugins → Python Console)
- Look for messages related to grd2stream
- Check detailed execution logs and error messages
Development Information
Plugin Structure
The plugin code is organized as follows:
- __init__.py - Plugin initialization
- grd_2_stream.py - Main plugin class and QGIS integration
- flowline_module.py - Core functionality
- dialog_selection.py - UI for parameter selection
- dialog_preset.py - UI for preset management
- help_widget.py - Help documentation display
Contributing
Contributions to the plugin are welcome! Priority areas include:
- Windows support implementation
License Information
Plugin License
The grd2stream QGIS plugin is licensed under the GNU General Public License v3.0 (GPL-3.0).
Third-Party Components
The plugin includes:
- grd2stream command-line tool by Thomas Kleiner:
- Licensed under the BSD 3-Clause License
- See the full license text in
lib/LICENSE.txt
Copyright
© 2013-2025 Thomas Kleiner & ScienceFlightPlanner-Team