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 filename matching <legend_images_path>/<service_name>/<layername>_<style>_<suffix>.png
• A filename matching <legend_images_path>/<service_name>/<layername>_<suffix>.png
• A filename matching <legend_images_path>/<service_name>/default_<suffix>.png
• A filename matching <legend_images_path>/<service_name>/<layername>_<style>.png
• A filename matching <legend_images_path>/<service_name>/<layername>.png
• A filename matching <legend_images_path>/<resource_entry[legend_image]>
• A filename matching <legend_images_path>/<service_name>/default.png
• As base64, as set in <resource_entry[legend_image_base64]>

Where

• service_name is the name of the WMS service
• layername is the WMS layer name
• suffix: empty, or one of _thumbnail, _tooltip. The suffix is passed by QWC to the legend service depending on the requested image type
• resource_entry[legend_image] and resource_entry[legend_image_base64] are the legend_image resp. legend_image_base64 settings of a layer as configured in the legend service resource 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
• File location: $CONFIG_PATH/<tenant>/legendConfig.json

Example:

{
  "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-legend-service/v2/schemas/qwc-legend-service.json",
  "service": "legend",
  "config": {
    "default_qgis_server_url": "http://localhost:8001/ows/",
    "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"
            }
          ]
        }
      }
    ]
  }
}

See the schema definition for the full set of supported config variables.

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

Environment variables¶

Config options in the config file can be overridden by equivalent uppercase environment variables.

Permissions¶

• JSON schema
• File location: $CONFIG_PATH/<tenant>/permissions.json

Example:

{
  "$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"
              }
            ]
          }
        ]
      }
    }
  ]
}

Basic Auth¶

The legend service be configured to accept password authentication using Basic authentication.

Example:

  "config": {
    "basic_auth_login_url": ["http://qwc-auth-service:9090/verify_login"]
  }

Run locally¶

Install dependencies and run:

export CONFIG_PATH=<CONFIG_PATH>
uv run src/server.py

To use configs from a qwc-docker setup, set CONFIG_PATH=<...>/qwc-docker/volumes/config.

Set FLASK_DEBUG=1 for additional debug output.

Set FLASK_RUN_PORT=<port> to change the default port (default: 5000).

Docker usage¶

The Docker image is published on Dockerhub.

See sample docker-compose.yml of qwc-docker.