# EMDS Workbench (EMDS for QGIS)

A QGIS dock-panel plugin for EMDS (Ecosystem Management Decision Support):
organize workspaces, study areas, analyses, and task pipelines, run the
NetWeaver and CDP decision engines, and review results — all inside QGIS.

## Features

- **Guided Workbench and Advanced views**: a beginner-friendly guided panel
  plus a full hierarchy tree for experienced users
- **Workspace → Study Area → Analysis → Task hierarchy** with right-click
  actions for creating, editing, and deleting items
- **Engine integration**: NetWeaver and CDP engines ship inside the plugin as
  self-contained executables — no separate .NET install
- **Pipeline Builder**: create, save, and reuse task pipelines
- **Results review**: result tables, engine viewers, charts, and map layers
  scoped per analysis
- **Built-in updates**: Plugins → EMDS → Check for Updates, plus QGIS Plugin
  Manager support via the EMDS plugin repository

## Requirements

- **QGIS 4.0.2 or later** (Qt6 / PyQt6)
- Python packages `pandas` and `pyarrow` in the QGIS Python environment —
  **the plugin offers to install these itself on first load** (optional:
  `matplotlib` for result charts)
- For the Create Study Area overlay feature: the external GDAL CLI 3.12+
  (`gdal vector layer-algebra`), which ships with QGIS 4.0.2+ — detected at
  runtime with upgrade guidance if missing

## Installation

1. In QGIS, open **Plugins → Manage and Install Plugins → Install from ZIP**.
2. Select the EMDS plugin ZIP for your platform (downloaded from
   <https://emds.mountain-viewgroup.com>).
3. On first load, a setup dialog offers to install the missing Python
   packages into the Python that QGIS bundles. Click **Install now** and
   restart QGIS when prompted. (If you dismissed it, it is available under
   **Plugins → EMDS → Finish EMDS Setup…**.)

If the in-app setup cannot run — no internet access, or a locked-down
machine — use the fallback dependency scripts: on macOS and Linux they ship
at the root of the `-setup` download (next to the plugin ZIP, with a README);
on Windows download `install-deps.ps1` from
<https://emds.mountain-viewgroup.com>.

The plugin installs into the active QGIS profile:

- **Windows**: `%APPDATA%\QGIS\QGIS4\profiles\<profile>\python\plugins\emds_qgis_plugin`
- **macOS**: `~/Library/Application Support/QGIS/QGIS4/profiles/<profile>/python/plugins/emds_qgis_plugin`
- **Linux**: `~/.local/share/QGIS/QGIS4/profiles/<profile>/python/plugins/emds_qgis_plugin`

## Getting started

1. Open the EMDS panel (toolbar icon or **View → Panels**).
2. **Create Workspace** — workspaces live under `Documents/EmdsProjects`.
3. **Create Study Area** under the workspace by combining a target layer with
   overlay/include layers.
4. **Create Analysis** under the study area and configure its first task
   (NetWeaver or CDP model).
5. Run the task and review results in the results grid, engine viewer, chart
   view, or directly on the map.

## Architecture (for developers)

| File | Responsibility |
| --- | --- |
| `__init__.py` | Plugin entry; dependency preflight → first-run setup |
| `first_run_setup.py` | In-app dependency installer + engine payload repair |
| `emds_plugin.py` | Plugin lifecycle, menu/toolbar, update checks |
| `dock_widget.py` | Main dock panel and user interactions |
| `models.py`, `tree_model.py` | Data model and hierarchy tree |
| `python-bridge/engine_bridge.py` | Subprocess bridge to the .NET engines (JSON + Arrow IPC) |
| `engines/<rid>/…` | Self-contained NetWeaver/CDP engine executables |
| `update_checker.py` | Release manifest checks (EMDS → Check for Updates) |
| `translations/` | JSON i18n catalogs (en, es, de, pt) |

Qt imports go through `qt_compat.py` (QGIS 4 / PyQt6 only — native Qt6 enum
scopes, no PyQt5 aliases).

## Troubleshooting

- **Setup dialog didn't appear / was dismissed**: **Plugins → EMDS → Finish
  EMDS Setup…**, or run the fallback script for your platform (see
  Installation above), then restart QGIS.
- **Plugin not appearing**: confirm the plugin is enabled in the Plugin
  Manager and check **View → Panels → Log Messages** for errors.
- **Engine errors on macOS/Linux** (`Permission denied`, "killed"): the
  plugin repairs engine execute permissions and macOS quarantine flags
  automatically on every load; if an engine still fails, see the
  troubleshooting sections of the platform README included with the
  macOS/Linux `-setup` download.

## License

GPL-2.0-or-later — see `LICENSE`. The bundled NetWeaver and CDP engines are
separate self-contained executables with their own licensing.

## Support

- Website / downloads: <https://emds.mountain-viewgroup.com>
- Email: <support@emds.org>
