Skip to content

[Feature]: Raster legend labels from class names (colour table / RAT), and editable raster class labels #889

Open

Description

Before you start

  • I searched the existing issues and the roadmap and did not find a duplicate request.

What problem does this solve?

A classified raster with a colour table, such as slope classes or land cover, shows the right colours with the Colormap renderer. But the legend lists the raw values (1, 2, 3 …) instead of the class names. Neither the command line nor the project file offers a way to set them: layer.classStyle answers "this works on feature layers, not rasters".

Example: a slope map in 7 classes (0-5 %, 5-15 %, 15-30 %, 30-50 %, 50-70 %, 70-100 %, over 100 %) with its palette. The legend shows 1 to 7, so a reader cannot tell what each colour means.

Proposed solution

  1. Read the class names that GDAL writes for a band (GDAL_METADATA / .aux.xml category names, or the Class_Names / Value columns of a raster attribute table). Use them as legend labels in the Colormap and Unique Values renderers.
  2. Let layer.classStyle set label (and color) on raster Unique Values and Colormap classes, as it already does for feature layers.

In v0.4.0 the legend label comes from fmt_num(*v) in crates/map/src/raster.rs (RasterRenderer::Colormap).

Estimated scope

Small to medium: reading the names from the .aux.xml sidecar, which #438 already reads, plus a label field on raster classes in the project format.

Alternatives considered

Polygonising the classes to use vector Unique Values works, but it makes a large layer for a display-only need.

Activity

  1. GISspecialistAlejandraDuque commented on Oct 26, 2026

    @GISspecialistAlejandraDuque
    ContributorAuthor

    I'll take the first part of this. Plan: read the <CategoryNames> GDAL writes to a band's .aux.xml in pam.rs, keep them on the band next to its description, and use them as the labels of the Colormap and Unique Values legend rows in the Layers pane, falling back to the value where a class has no name. With tests, and checked on the slope-class raster from the issue.

    Out of scope for this PR, unless you'd rather have them in it: raster attribute tables, layer.classStyle on raster classes, the layout colour bar, and rasters converted through GDAL.

  2. elpidioassinaturas commented on Nov 14, 2026

    @elpidioassinaturas
    Contributor

    Another case for the second part of this issue (setting raster class labels without a sidecar), from a plugin. Checked on main at bf4884e2.

    The BrasilData plugin brings the Copernicus Global Land Cover 100 m (CLMS LC100, 23 classes) for the user's area. It reads a window of the COG with layer.addUrl {bbox}, then runs raster.process clip and raster.project onto the project grid. It styles the result with style.importQgis and a paletted QML in which every entry has a label:

    <rasterrenderer type="paletted" band="1"><colorPalette>
      <paletteEntry value="30" color="#ffff4c" alpha="255" label="Vegetação herbácea"/>
      <paletteEntry value="50" color="#fa0000" alpha="255" label="Área urbana e construída"/>
      …
    </colorPalette></rasterrenderer>

    The colours are right, but the Layers pane and the layout legend show 20, 30, 40… The .aux.xml category names (#971) and the attribute table (#1892) don't help here. The layer is the in-memory output of raster.project, so it has no sidecar, and a plugin can't write one.

    Today a command has no way to name the classes:

    • style.importQgis reads each paletteEntry's value, color and alpha, but drops label (crates/map/src/qgis/raster.rs, the "paletted" arm). QGIS keeps it as the class label, and so does a colorRampEntry label in a discrete singlebandpseudocolor.
    • layer.classStyle answers "this works on feature layers, not rasters".
    • raster.symbology has no labels parameter.

    Any one of these would do, in order of preference:

    1. Keep the label of paletteEntry (and of colorRampEntry) from a QML as the class label.
    2. layer.classStyle {value, label, color?} on raster Unique Values and Colormap classes, as this issue proposes.
    3. A labels map on raster.symbology {type: "unique"}, for example {"30": "Vegetação herbácea"}.

    The same need comes up in the plugin for the MapBiomas land-cover classes and the OPERA DIST-S1 disturbance status. Today the plugin polygonises the classes to get names into the legend, which is the workaround this issue already calls heavy.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions