# Viewshed Calculator Quick Start Guide

## Installation (2 minutes)

### Step 1: Locate your QGIS plugins folder

**Windows:**
Open File Explorer and navigate to:
```
C:\Users\YOUR_USERNAME\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\
```

**Linux:**
```bash
~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
```

**macOS:**
```bash
~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/
```

### Step 2: Copy the plugin folder

Copy the entire `viewshed_calculator_plugin` folder into your plugins directory.

### Step 3: Restart QGIS

Close and reopen QGIS.

### Step 4: Enable the plugin

1. Go to **Plugins** → **Manage and Install Plugins**
2. Search for "Viewshed Calculator"
3. Check the checkbox to enable it
4. Click **Close**

The plugin is now installed! You should see **Viewshed Calculator** in the **Analysis** menu.

---

## First Run

### Prepare your data

You need:
1. **DSM**: A GeoTIFF file with elevation data (required)
2. **Viewpoints**: A shapefile with point features (required)
3. **CHM**: Optional vegetation height model

### Run the plugin

1. Click **Analysis** → **Viewshed Calculator** in the menu
2. Click **Browse...** next to DSM and select your elevation raster, or choose a raster from **DSM layer in project**
3. In **Viewpoints**, either:
   - Use **Existing Layer** and pick a point shapefile/layer, or
   - Use **Generate Grid** and create viewpoints from an extent or polygon source with spacing
4. (Optional) Check "Use CHM for validation" and select your vegetation model with **Browse...**, or choose a raster from **CHM layer in project**
5. Adjust parameters if needed:
   - Observer Height: 1.6 m (typical human eye level)
   - Max Distance: 1200 m (how far to calculate visibility)
   - If using **Existing Layer**: set Raster Resolution in the Viewpoints section
   - If using **Generate Grid**: Raster Resolution is automatically the same as viewpoint spacing
6. (Optional) Click **Browse...** next to Output and choose where to save the result. If you leave it empty, a temporary output file is created automatically
7. Click **Run Viewshed Calculation**
8. Wait for processing (progress updates shown in the status window)
9. When done, the output layer is automatically added to the QGIS project

---

## Output Interpretation

The output GeoTIFF contains:
- **Cell values**: Visible area in hectares (1 hectare = 10,000 m²)
- **NoData cells**: Areas with no visibility (-9999)
- **Legend**: Values range from 0 to the maximum visible area from any observer

Higher values = areas visible from more/larger viewpoints.

---

## Performance Tips

For faster processing:
- ✓ Increase **Raster Resolution** (e.g., 50 m instead of 25 m)
- ✓ Decrease **Max Distance** (e.g., 800 m instead of 1200 m)
- ✓ Process viewpoints in smaller batches
- ✓ Use coarser DSM if appropriate

---

## Troubleshooting

**Plugin doesn't appear in menu after restart?**
- Check the plugins folder path is correct
- Look at Help → Log Panel for error messages
- Try disabling and re-enabling the plugin

**"Cannot open DSM" error?**
- Verify the file path is correct
- Ensure it's a GeoTIFF (.tif) file
- Check file isn't corrupted

**"No viewpoints found" error?**
- Ensure shapefile contains point geometries
- Check it has at least 1 feature
- Verify shapefile has matching .shp, .shx, .dbf files

**Calculation is very slow?**
- Reduce Max Distance parameter
- Increase Raster Resolution to larger cell size
- Split viewpoints into multiple batches

---

## Need Help?

See the full README.md for detailed documentation and parameter descriptions.
