# Viewshed Calculator

A QGIS plugin for calculating viewshed (visibility analysis) from Digital Surface Models (DSM) using project layers, file inputs, or generated viewpoint grids.

## Features

- Calculate visibility analysis using GDAL's ViewshedGenerate algorithm
- Process multiple viewpoint locations from a shapefile
- Generate viewpoint grids from an extent or a polygon shapefile/layer with configurable spacing
- Optional Canopy Height Model (CHM) validation to exclude locations within vegetation
- Aggregate results as a GeoTIFF raster showing maximum visible area per grid cell
- Configurable parameters:
  - Observer height (default: 1.6 m)
  - Maximum distance (default: 1200 m)
  - Raster resolution (default: 25 m)

## Installation

### Prerequisites

Before installing the plugin, ensure you have:

1. **QGIS** 3.0 or later (https://www.qgis.org)
2. **GDAL/OGR** libraries with Python bindings (usually installed with QGIS)
3. **NumPy** (usually installed with QGIS)

### Installing the Plugin

1. Copy the `viewshed_calculator_plugin` folder to your QGIS plugins directory:
   
   **Windows:**
   ```
   C:\Users\<YourUsername>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\
   ```
   
   **Linux:**
   ```
   ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
   ```
   
   **macOS:**
   ```
   ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/
   ```

2. Restart QGIS

3. Enable the plugin:
   - Go to **Plugins** → **Manage and Install Plugins**
   - Search for "Viewshed Calculator"
   - Check the box next to the plugin name
   - Click **Close**

The plugin should now appear in the **Analysis** menu.

## Usage

### Basic Workflow

1. **Prepare your data:**
   - **DSM (Digital Surface Model)**: A GeoTIFF raster file with elevation data
   - **Viewpoints**: A shapefile with point geometries (observer locations)
   - **CHM (Canopy Height Model)** (optional): A GeoTIFF raster with vegetation height

2. **Open the plugin:**
   - Go to **Analysis** → **Viewshed Calculator**

3. **Configure parameters:**
   - **DSM**: Select your Digital Surface Model raster file, or pick a raster layer already loaded in the QGIS project
   - **CHM** (optional): Enable and select a CHM file, or pick a raster layer already loaded in the QGIS project
   - **Viewpoints**: Use either an existing point shapefile/layer, or generate a point grid from extent/polygon with a chosen spacing
   - **Raster Resolution**:
     - In **Existing Layer** mode: set explicitly in the Viewpoints section
     - In **Generate Grid** mode: automatically uses the viewpoint spacing value
   - **Observer Height**: Height of the observer above ground (default: 1.6 m for human eye level)
   - **Max Distance**: Maximum distance to calculate visibility (default: 1200 m)
   - **Output**: Optional GeoTIFF file path. If left empty, the plugin creates a temporary output file automatically

4. **Run the calculation:**
   - Click **Run Viewshed Calculation**
   - Monitor progress in the status window
   - The output layer is automatically added to the QGIS project when complete

### Output

The plugin generates a GeoTIFF raster where:
- Each cell contains the maximum visible area (in hectares) from all observer points that can see that cell
- Cells with no visibility are marked as NoData (-9999)
- The raster uses the same projection as your DSM

## Parameters Explained

| Parameter | Default | Range | Description |
|-----------|---------|-------|-------------|
| **Observer Height** | 1.6 m | 0-100 m | Eye height above ground level |
| **Max Distance** | 1200 m | 100-100,000 m | Maximum viewshed radius |
| **Raster Resolution** | 25 m | 1-1,000 m | Output grid cell size (set in Existing Layer mode; in Generate Grid mode it equals spacing) |

### CHM Validation

If enabled, the plugin:
- Checks the CHM value at each observer point's location
- Skips viewshed calculation if CHM > 0 (observer is inside vegetation)
- Useful to exclude viewpoints that fall within trees or buildings

## Performance Considerations

- Processing time depends on:
  - Number of viewpoints
  - Max distance (larger = slower)
  - DSM resolution and extent
  - Output raster resolution
- For large datasets, consider:
  - Reducing max distance
  - Increasing output raster resolution
  - Dividing viewpoints into smaller batches

## Troubleshooting

### Plugin doesn't appear in QGIS

1. Ensure the plugin folder is in the correct location
2. Check QGIS log for errors (Help → Log Panel or View → Panels → Log)
3. Restart QGIS

### "Cannot open DSM" or file not found errors

1. Verify file paths are correct and files exist
2. Ensure files are in a supported format (GeoTIFF recommended)
3. Check file permissions

### "No viewpoints found" error

1. Verify the shapefile contains point geometries
2. Ensure the shapefile has more than 0 features
3. Check that the coordinate system matches your DSM

### Slow performance

1. Reduce the Max Distance parameter
2. Increase the Raster Resolution (larger cell size = faster)
3. Split viewpoints into batches and process separately
4. Use a coarser DSM resolution if appropriate

## Development/Modification

To modify the plugin:

1. Edit the relevant Python files:
   - `dialog.py` - UI and worker thread logic
   - `viewshed_calculator.py` - Plugin main class
   
2. Restart QGIS or reload the plugin to see changes

## License

Use and modify as needed for your projects.

## Support

For issues or questions, refer to the QGIS documentation or GDAL/OGR documentation.
