Getting started

Prerequisites

Guitares requires Python 3.10 or higher. The following packages are installed automatically as dependencies:

PySide6 — Qt6 bindings for Python
PySide6-WebEngine — web engine for the map widget and webpage element
PyYAML — YAML configuration file parsing
geopandas, numpy, pandas, pyproj, shapely — geospatial and numerical support

Install the latest release from PyPI:

pip install guitares

For an editable installation from source (useful during development):

git clone https://github.com/deltares-research/guitares.git
cd guitares
pip install -e .

After installation, run the included hello example to verify everything works:

cd examples/hello
python hello.py

You should see a small window with an edit box that greets you by name.

A Guitares application consists of four files:

File	Purpose
`myapp.yml`	YAML configuration file describing the window and all UI elements
`app.py`	Creates the `Application` class, initializes variables, and builds the GUI
`callbacks.py`	Contains callback functions that run when the user interacts with the GUI
`myapp.py`	Entry point that imports `app` and calls `app.gui.build()`

See A Very Simple Example for a complete walkthrough.

Guitares supports two map engines for the interactive map widget. The engine is selected when creating the GUI object:

from guitares.gui import GUI
gui = GUI(app, config_file="myapp.yml", map_engine="maplibre")

Engine	Notes
`"maplibre"`	Open-source, no API token required, works offline. Recommended default.
`"mapbox"`	Requires a Mapbox API token stored in a file called `mapbox_token.txt` next to your config file.

See The Map Widget for full documentation of the map widget.