# EMDS Plugin Quick Start Guide

## 5-Minute Setup

Requires **QGIS 4.0.2 or later**.

### 1. Install the plugin from ZIP

1. Download the EMDS plugin ZIP for your platform from
   <https://emds.mountain-viewgroup.com>.
2. In QGIS: **Plugins** → **Manage and Install Plugins** → **Install from
   ZIP** → pick the downloaded file.

### 2. Let the plugin finish its own setup

On first load a setup dialog offers to install the Python packages the plugin
needs (pandas / pyarrow) into the Python that QGIS bundles. Click **Install
now**, then restart QGIS when prompted. If you dismissed the dialog, it is
available under **Plugins → EMDS → Finish EMDS Setup…**. (Offline or
locked-down machine? On macOS/Linux use the scripts at the root of the
`-setup` download; on Windows download `install-deps.ps1` from the EMDS
website.)

### 3. Open the panel

A dock panel appears on the left; if not, use the EMDS toolbar icon or
**View** → **Panels**.

## First Steps

### Create a Demo Project

1. Click **[+ Create Project]** button
2. Enter: `My First Project`
3. Select all available layers
4. Click **[OK]**

### Add an Assessment

1. Click on "My First Project" in the tree
2. Click **[+ Create Assessment]**
3. Enter: `Forest Cover Assessment`
4. Click **[OK]**

### Create a Provenance

1. Click on the assessment
2. Click **[+ Create Provenance]**
3. Enter: `Initial Analysis`
4. Click **[OK]**

### Add a Workflow Step

1. Click on the provenance
2. Click **[+ Create Workflow Step]**
3. Select: `NetWeaver Engine`
4. Enter step name: `Intersection Calculation`
5. Set model file: `model.nw2`
6. Click **[OK]**

## Understanding the Tree

The tree shows your hierarchy:

```
📁 My First Project
├─ 📊 Forest Cover Assessment
│  └─ 🔄 Initial Analysis
│     ├─ ⚙️ Intersection Calculation
│     │  └─ 📍 output_layer.shp (500 features)
│     └─ ⚙️ Union Calculation
```

- **📁 Projects**: Top-level container
- **📊 Assessments**: Spatial analyses
- **🔄 Provenances**: Workflow groupings
- **⚙️ Workflow Steps**: Individual processing steps
- **📍 Results**: Output layers with feature counts

## Key Actions

### Right-Click Menu

Right-click any item to see context menu:

```
Project
├─ Create Assessment
├─ Edit Project
└─ Delete Project

Assessment
├─ Create Provenance
├─ Edit Assessment
└─ Delete Assessment

Provenance
├─ Create Workflow Step
├─ Edit Provenance
└─ Delete Provenance

Workflow Step
├─ Create Sub-Workflow Step  (nested up to 6 levels)
├─ View Result               (open in external viewer)
├─ Edit Step
└─ Delete Step

Results
├─ View                      (open external viewer)
└─ Toggle Visibility         (show/hide on map)
```

### Smart Collapsing

When you select an item, the tree automatically collapses unrelated branches:

```
BEFORE (cluttered):
📁 Project A
├─ 📊 Assessment 1
│  ├─ 🔄 Provenance 1
│  │  ├─ ⚙️ Step 1
│  │  └─ ⚙️ Step 2
│  └─ 🔄 Provenance 2
│     └─ ⚙️ Step 3
├─ 📊 Assessment 2
└─ 📊 Assessment 3

AFTER (selecting Step 1):
📁 Project A
├─ 📊 Assessment 1
│  └─ 🔄 Provenance 1
│     └─ ⚙️ Step 1  ← SELECTED AND EXPANDED
└─ [other items collapsed]
```

## Working with Layers

### View Results

1. Click on a workflow step
2. Click **[View]** button next to results
3. External viewer opens (integration needed)

### NetWeaver Hotlink Viewer

Opening a NetWeaver result launches the hotlink viewer: a topic tree with a
filter box, per-feature recoloring, an embedded map, exports (CSV/XLSX/PNG/
print), and a class-distribution node inspector.

The embedded map has its own toolbar:

- **Pan / Identify** — exclusive mode toggles (one is always active; Pan is
  the default). In Identify mode, clicking a feature selects it, syncs the
  results table, and opens a one-row **Field/Value** dialog with the
  feature's attributes and topic scores (geometry columns omitted).
- **+ / −** — zoom in / out.
- **Zoom to Selection** — zooms to the currently selected feature(s).
- **Full Extent** — zooms to the full extent of all layers.
- **Refresh / Fit** — re-sync the preview and fit the active topic layer.

### NetWeaver Network Viewer

Right-click any topic in the hotlink's topic tree → **Open Model Graph** to
open the node-NETWORK viewer for the selected feature:

- **Network tab** — the topic's full dependency network (operators, functions,
  fuzzy curves, variables), colored by the canonical truth-value ramp for the
  clicked feature. Single-click inspects a node (detail panel); double-click
  drills into it (breadcrumb bar, Back button, Esc). Zoom with the −/+/Fit
  buttons, Ctrl+mouse-wheel, or Ctrl+0.
- **Outline tab** — the whole knowledge base as a tree with per-feature value
  swatches; topics expand lazily into their networks.
- **Goals & Calculations tab** — every goal and calculated node with its
  current value; double-click opens it in the Network tab.
- **Data Assignments tab** — each model variable, the feature column it
  resolved to, and the row value fed into the engine (shows the task's
  persisted mappings before any feature is selected).
- **Documents tab** — the knowledge base's authored documentation: topic
  hints, explanation documents, and hyperlinks, browsed master–detail.
- **What-ifs** — tick *Ignore (conditional/persistent)* on a selected node to
  re-evaluate the feature with that node ignored. What-ifs are session-only
  (the model file is never modified); *Reset what-ifs* restores the persisted
  state. Selecting a different feature row in the hotlink recolors the open
  graph automatically.

The viewer needs the NetWeaver engine (`netweaver-cli`). Without it, the
dialog falls back to a read-only topic-hierarchy graph.

### Toggle Visibility

1. Click on a results item
2. Right-click → "Toggle Visibility"
3. Layer appears/disappears on the map
4. Eye icon changes: **👁** (visible) → **⊙** (hidden)

## Advanced: Nesting Workflow Steps

You can nest workflow steps up to 6 levels deep:

```
⚙️ Step 1
├─ ⚙️ Step 1.1
│  ├─ ⚙️ Step 1.1.1
│  │  └─ ⚙️ Step 1.1.1.1 (4 levels deep)
│  └─ ⚙️ Step 1.1.2
└─ ⚙️ Step 1.2
```

To create nested steps:
1. Click on a workflow step (not just a provenance)
2. Right-click → "Create Sub-Workflow Step"
3. Follow the same workflow as regular steps

## Rich Comments

Every wizard comment/description box (workspace, study area, analysis, and
the NetWeaver/CDP/Portfolio task wizards, plus Edit Workspace/Study Area) is
a rich-text editor: bold/italic/underline, bullet and numbered lists, text
color, links, undo/redo. The area grows with the dialog. Plain text is stored
in the shared database columns (so the ArcGIS product and older views keep
working); the formatted version is kept alongside it and restored when you
reopen the dialog. Legacy comments that contain old RTF formatting are shown
as readable plain text.

## Engine Types

When creating a workflow step, choose your engine:

### NetWeaver
- Real engine integration
- Requires `.nw2` model file
- Best for complex analyses

### CDP
- Custom engine support
- Requires configuration file
- Good for domain-specific tasks

### Templates
- Predefined workflows
- Fast execution
- Good for quick analyses

## Configuration Parameters

Each engine type has different parameters:

### NetWeaver
- **Model File**: Path to `.nw2` model
- **Timeout**: Max execution time (seconds)

### CDP
- **Configuration**: Path to config file

### Templates
- **Option**: Template-specific option

## Keyboard Shortcuts (Future)

Currently not implemented, but planned:

- `Ctrl+N`: New project
- `Delete`: Delete selected item
- `F2`: Edit selected item
- `Space`: Toggle visibility

## Troubleshooting

### Plugin doesn't appear
- Check plugin folder location
- Verify `metadata.txt` exists
- Check QGIS Log Messages panel

### Dialogs won't open
- Finish the first-run setup (Plugins → EMDS → Finish EMDS Setup…)
- Review QGIS error messages (View → Panels → Log Messages)

### Tree won't update
- Try selecting different item and back
- Click [+ Create] button again
- Restart QGIS if issues persist

### Map layers not visible
- Right-click results → "Toggle Visibility"
- Check layer properties in QGIS
- Verify layer has valid geometry

## Next Steps

1. **Explore the demo project**: Click around the demo data
2. **Create your own project**: Add your layers and analyses
3. **Integrate engines**: See `example_integration.py` for engine bridge
4. **Extend functionality**: Modify dialogs and add custom engines

## Getting Help

### Documentation Files
- `README.md` - Full documentation
- `PLUGIN_STRUCTURE.md` - Architecture details
- `example_integration.py` - Engine integration example

### Common Issues

**Q: Can I edit a project name?**
A: Yes, right-click → "Edit Project" (future version)

**Q: Can I move items between projects?**
A: Not yet, but planned for future releases

**Q: How do I delete the demo data?**
A: Right-click project → "Delete Project"

**Q: Can I export my workflow?**
A: Yes, use Project → "Export to JSON" (future version)

## Tips and Tricks

1. **Organize by Assessment**: Create separate assessments for different analysis types
2. **Use Provenances for Versions**: Different provenances = different workflow versions
3. **Nest Steps Logically**: Group related steps as sub-steps
4. **Name Clearly**: Use descriptive names for easy identification
5. **Document Parameters**: Add parameter descriptions in your names

## What's Next?

The plugin is actively developed. Upcoming features include:

- ✅ Hierarchical project management (DONE)
- ✅ Tree view with smart collapsing (DONE)
- ✅ Creation dialogs (DONE)
- ⏳ Workflow execution with progress
- ⏳ Engine bridge integration
- ⏳ Layer export formats
- ⏳ Project templates
- ⏳ Collaboration features

## Join the Community

Have ideas or found bugs? Let us know:
- GitHub Issues: [EMDS QGIS Plugin Issues]
- Email: support@emds.org
- Discussions: [EMDS Community Forum]

Happy analyzing! 🚀
