# Viewshed Calculator QGIS Plugin - Structure

## Plugin Files

```
viewshed_calculator_plugin/
├── __init__.py              # Plugin entry point
├── metadata.txt             # Plugin metadata for QGIS
├── viewshed_calculator.py   # Main plugin class
├── dialog.py                # UI dialog and calculation worker
├── resources.qrc            # Qt resource file
├── resources_rc.py          # Generated resources (empty in this case)
├── README.md                # Installation and usage guide
└── icons/                   # Plugin icon folder
    └── (place icon.png here)
```

## Key Components

### 1. `__init__.py`
- Entry point for QGIS plugin loader
- Returns the plugin class for QGIS to instantiate

### 2. `metadata.txt`
- Plugin metadata (name, version, author, description)
- Used by QGIS plugin manager
- Defines minimum QGIS version and dependencies

### 3. `viewshed_calculator.py`
- Main plugin class (`ViewshedCalculatorPlugin`)
- Manages plugin lifecycle (initGui, unload)
- Creates menu items and toolbar buttons
- Instantiates and shows the dialog

### 4. `dialog.py`
- `ViewshedCalculatorDialog`: Main UI with input fields and buttons
- `ViewshedWorker`: Threaded worker for long-running calculations
  - Prevents UI freezing during processing
  - Emits progress signals back to UI
  - Core viewshed calculation logic adapted from original script

### 5. `resources.qrc` & `resources_rc.py`
- Qt resource files (currently empty)
- Can be used for icons and other resources later

## Installation Instructions

1. Copy the entire `viewshed_calculator_plugin` folder to:
   
   **Windows:** `%APPDATA%\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 in Plugins → Manage and Install Plugins

## Usage

1. Open the plugin from **Analysis → Viewshed Calculator**
2. Select input files (DSM, viewpoints, optional CHM)
3. Configure parameters
4. Click **Run Viewshed Calculation**
5. Output raster automatically loads into QGIS

## Key Improvements Over Original Script

- **Interactive UI**: File browser dialogs and parameter adjustment in GUI
- **Threading**: Non-blocking calculation with progress updates
- **Error Handling**: User-friendly error messages and validation
- **Integration**: Automatic output layer loading into QGIS
- **Progress Tracking**: Real-time progress bar and status updates
- **Optional CHM**: CHM validation is now optional (can be disabled)

## Customization

### Adding an Icon
1. Create a 32x32 or 64x64 PNG icon
2. Save as `icons/icon.png`
3. The plugin will automatically use it in the menu and toolbar

### Modifying Parameters
Edit the default values in `dialog.py` - look for lines like:
```python
self.observer_height_spin.setValue(1.6)
self.max_distance_spin.setValue(1200)
```

### Changing Output Format
Currently outputs GeoTIFF. To support other formats, modify the `_calculate_viewshed()` method in `dialog.py`.

## Dependencies

- QGIS 3.0+
- GDAL/OGR (included with QGIS)
- NumPy (included with QGIS)

All dependencies should already be available in your QGIS installation.

## Notes

- The plugin uses `gdal.ViewshedGenerate()` which is the same algorithm as the original script
- CHM validation is optional; if disabled or no CHM provided, all viewpoints are processed
- Results are aggregated using max visibility per cell (same as original)
- The plugin is compatible with projected coordinate systems (recommended for accurate area calculations)
