[![](https://github.com/qwc-services/qwc-legend-service/workflows/build/badge.svg)](https://github.com/qwc-services/qwc-legend-service/actions)
[![docker](https://img.shields.io/docker/v/sourcepole/qwc-legend-service?label=Docker%20image&sort=semver)](https://hub.docker.com/r/sourcepole/qwc-legend-service)

QWC Legend Service
==================

Acts as a proxy between the client and QGIS server for GetLegendGraphic request,
allowing to return custom legend graphics instead of the ones generated by the WMS server.

**Note:** Requires a QGIS server running on `default_qgis_server_url`.


### Usage

Configure `legend_images_path` in the service configuration (see below). Then, legend images will be searched for in this order (the first one found is used):

 * A `<legend_images_path>/<service_name>/<layername><suffix>.png` file, where
   * `service_name` is the name of the WMS service
   * `layername` is the WMS layer name
   * `suffix`: empty, or one of `_thumbnail`, `_tooltip`, see `type` query-parameter below.
 * A `<legend_images_path>/default<suffix>.png` file.
 * According to the `legend_image` paths set in the layer resource configurations of the legend service configuration.

Configuration
-------------

The static config and permission files are stored as JSON files in `$CONFIG_PATH` with subdirectories for each tenant,
e.g. `$CONFIG_PATH/default/*.json`. The default tenant name is `default`.


### Legend Service config

* [JSON schema](schemas/qwc-legend-service.json)
* File location: `$CONFIG_PATH/<tenant>/legendConfig.json`

Example:
```jsonc
{
  "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-legend-service/v2/schemas/qwc-legend-service.json",
  "service": "legend",
  "config": {
    // QGIS Server URL
    "default_qgis_server_url": "http://localhost:8001/ows/",
    // base path to legend images (required if using 'legend_image')
    "legend_images_path": "/PATH/TO/LEGENDS/"
  },
  "resources": {
    "wms_services": [
      {
        "name": "qwc_demo",
        "root_layer": {
          "name": "qwc_demo",
          "layers": [
            {
              "name": "edit_demo",
              "layers": [
                {
                  "name": "edit_points",
                  // using custom legend image
                  "legend_image": "edit_points.png"
                },
                {
                  "name": "edit_lines",
                  // using custom legend image in Base64 encoding
                  "legend_image_base64": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAHUlEQVQI12NgwAEYGRgY/tdjiDYyMOHSQQ8JnAAAUUoCDCaibn8AAAAASUVORK5CYII="
                },
                {
                  // using WMS GetLegendGraphics by default
                  "name": "edit_polygons"
                }
              ]
            },
            {
              "name": "geographic_lines"
            },
            {
              "name": "country_names"
            },
            {
              "name": "states_provinces"
            },
            {
              "name": "countries"
            }
          ]
        }
      }
    ]
  }
}
```

**Note**: the `legend_image` path for custom legend graphics is relative to `legend_images_path` and may contain subdirectories


### Permissions

* [JSON schema](https://github.com/qwc-services/qwc-services-core/blob/master/schemas/qwc-services-permissions.json)
* File location: `$CONFIG_PATH/<tenant>/permissions.json`

Example:
```json
{
  "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-services-core/master/schemas/qwc-services-permissions.json",
  "users": [
    {
      "name": "demo",
      "groups": ["demo"],
      "roles": []
    }
  ],
  "groups": [
    {
      "name": "demo",
      "roles": ["demo"]
    }
  ],
  "roles": [
    {
      "role": "public",
      "permissions": {
        "wms_services": [
          {
            "name": "qwc_demo",
            "layers": [
              {
                "name": "qwc_demo"
              },
              {
                "name": "edit_demo"
              },
              {
                "name": "edit_points"
              },
              {
                "name": "edit_lines"
              },
              {
                "name": "edit_polygons"
              },
              {
                "name": "geographic_lines"
              },
              {
                "name": "country_names"
              },
              {
                "name": "states_provinces"
              },
              {
                "name": "countries"
              }
            ]
          }
        ]
      }
    }
  ]
}
```

Usage
-----

Set the `CONFIG_PATH` environment variable to the path containing the service config and permission files when starting this service (default: `config`).

Set the `QWC2_PATH` environment variable to the path containing your QWC2 production build.


Base URL:

    http://localhost:5014/

API documentation:

    http://localhost:5014/api/

Sample request:

    http://localhost:5014/qwc_demo?SERVICE=WMS&REQUEST=GetLegendGraphic&LAYER=qwc_demo&format=image/png


Development
-----------

Create a virtual environment:

    virtualenv --python=/usr/bin/python3 --system-site-packages .venv

Without system packages:

    python3 -m venv .venv

Activate virtual environment:

    source .venv/bin/activate

Install requirements:

    pip install -r requirements.txt
    pip install flask_cors

Start local service:

    CONFIG_PATH=/PATH/TO/CONFIGS/ python src/server.py
