# Beaver Processor

A QGIS plugin that turns an area of interest into a clean, briefing-ready map graphic, ready to drop into documents and slides from a guided window. The plugin works on its own project file: it never reads, clears, or modifies the project you have open in QGIS.

## Features

- **Guided workflow**: pick an area of interest, build, export. One window.
- **Bundled framing data**: Natural Earth admin-0 (countries) and admin-1
  (provinces/states) are included for selecting and framing the map.
- **Open-licensed basemaps**: optional XYZ tile layers: OpenStreetMap,
  OpenTopoMap, CARTO Positron, CARTO Dark Matter (internet required only when a
  basemap is enabled).
- **Geoprocessing & symbology**: built-in processing, projection control,
  print-layout formatting, and manual symbol / flag / text insertion.
- **Export**: PNG, JPG, or PDF at print resolution.

## Requirements

- QGIS 3.34 or newer.
- No external Python dependencies: only libraries shipped with QGIS are
  used.
- Internet connection only if you enable a tile basemap.

Runtime output (the built-map cache and the analytics CSV) is written to a
per-user folder under your QGIS profile directory, not into the plugin
install directory.

## Installation

**From the QGIS Plugin Manager** (once published): Plugins → Manage and
Install Plugins → search "Beaver Processor" → Install.

**From a ZIP:** Plugins → Manage and Install Plugins → Install from ZIP →
select `beaver_processor.zip`.

Launch it from the toolbar icon or Plugins → Beaver Processor.

## Quick start

1. Open the plugin (toolbar icon or Plugins menu).
2. Set a map width/height, then choose a focus country and/or province
   (or enter coordinates, or tick Global map).
3. Optionally enable a basemap.
4. Click BUILD, adjust overlays if desired, then EXPORT.

## Standalone use (development)

The same code also runs as a standalone desktop app for development, outside
QGIS, via `Beaver_processor.bat` (Windows), which invokes `code/standalone.py`
through the QGIS Python launcher.

## Platform support

Pure-Python / PyQt5 / PyQGIS with no OS-specific code paths; fonts are
registered per-process via Qt (`QFontDatabase`) rather than installed into the
operating system. Developed and tested on Windows; expected to run on Linux and
macOS.

## License

GNU General Public License v2 or later (GPL-2.0-or-later). See [LICENSE](LICENSE).
