# Basemap Loader

A QGIS plugin that adds all Swiss (swisstopo) and World basemap layers in a
single click or keyboard shortcut, organized in a `Basemaps` group at the
bottom of the layer tree.

Repository: https://github.com/fdenzinger/basemap-loader-qgis

## Features

- Loads swisstopo WMTS layers (relief shading, Landeskarte, SWISSIMAGE, etc.)
  in `EPSG:2056` / `EPSG:21781`.
- Loads World layers from EOX, CartoDB, OpenStreetMap, OpenTopoMap, ESRI and
  Google.
- Organizes layers into `Basemaps > Switzerland` and `Basemaps > World`
  groups. The `Basemaps` group is expanded by default; the `Switzerland` and
  `World` (or custom) subgroups and their individual layers are collapsed,
  and layers stay unchecked unless marked `Active` (see below).
- Toolbar button and menu entry (`Plugins > Basemap Loader`), plus the
  `Ctrl+Shift+B` shortcut.
- Prompts before replacing an existing `Basemaps` group.
- Reports any layers that failed to load (e.g. due to no internet
  connection).

## Installation

### From a built zip

1. Build the plugin zip (see [Building](#building) below), or download a zip
   from the [Releases](https://github.com/fdenzinger/basemap-loader-qgis/releases)
   page.
2. In QGIS, go to `Plugins > Manage and Install Plugins > Install from ZIP`.
3. Select `dists/basemap_loader.zip` and click `Install Plugin`.

### Manual install

Copy this folder into your QGIS plugins directory as `basemap_loader`, e.g.:

- macOS: `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/basemap_loader`
- Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/basemap_loader`
- Windows: `%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\basemap_loader`

Then enable it in `Plugins > Manage and Install Plugins`.

## Usage

Click the toolbar icon, use `Plugins > Basemap Loader > Load Basemaps`, or
press `Ctrl+Shift+B`. A `Basemaps` group is added at the bottom of the layer
tree containing `Switzerland` and `World` subgroups. The `Basemaps` group is
expanded by default; the `Switzerland`/`World` subgroups and the individual
layers inside them are collapsed, and layers are only checked on if marked
`Active` in the sources list.

## Editing basemap sources

The list of sources is not hard-coded: it lives in a `basemaps.json` file in
your QGIS profile folder (e.g. on macOS:
`~/Library/Application Support/QGIS/QGIS3/profiles/default/basemap_loader/basemaps.json`).
It is created automatically (copied from the plugin's built-in defaults) the
first time you load basemaps or open the editor.

To add, edit, or remove sources without touching any code:

1. Go to `Plugins > Basemap Loader > Edit Basemap Sources...`.
2. Use `Add Row` to add a new source, filling in:
   - **Group** — e.g. `Switzerland`, `World`, or a new group name of your choice.
   - **Name** — the display name shown in the layer tree.
   - **URL** — the QGIS raster layer source string (the same value you'd get
     from QGIS's `Data Source Manager > WMS/WMTS` or `XYZ Tiles` connections).
   - **Active** — check this box to have that layer turned on (checked)
     automatically every time `Load Basemaps` runs, instead of being added
     unchecked.
3. Select a row and click `Remove Selected Row(s)` to delete it.
4. Click `Reset to Defaults` to reload the plugin's built-in sources into the
   table (only applied once you click `Save`).
5. Click `Validate` to test every complete row by attempting to load it as a
   raster layer. Rows are highlighted green (loaded OK) or red (failed), and
   a summary lists any failures — handy for catching typos or dead URLs
   before saving.
6. Click `Export...` to save the current table as a JSON file anywhere on
   disk (e.g. to share a team-standard basemap list with colleagues).
7. Click `Save` to write your changes to `basemaps.json`. The next time you
   click `Load Basemaps`, your updated list (including any new groups) is
   used.

Because the file lives in your profile folder rather than the plugin
folder, your edits survive plugin reinstalls/updates.

## Building

Run `./build.sh` to package the plugin into `dists/basemap_loader.zip`,
ready for distribution or `Install from ZIP`.

## Requirements

- QGIS `3.0` – `4.99`

## License

[MIT](LICENSE)

## Author

Florian Denzinger — florian.denzinger@slf.ch
