MapGuide RFC 109 # - RenderMapLegend? API enhancement

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.


RFC Template Version(1.0)
Submission Date3rd September 2010
Last ModifiedJackie Ng 3rd September 2010
AuthorJackie Ng
RFC Statusretracted
Implementation Statuspending
Proposed Milestone2.3
Assigned PSC guide(s)(when determined)
Voting History(vote date)
no vote


This RFC proposes to add an enhanced RenderMapLegend() API to the rendering service. This enhanced API allows the option to omit empty layer groups from being rendered into the resulting image.


Under the current RenderMapLegend() API, all layer groups are rendered regardless of whether it has any visible layers or not. For maps with lots of layer groups, this can produce unnecessary clutter in the overall legend image.

Proposed Solution

Introduce a new overload of RenderMapLegend() to the MgRenderingService class:

    /// \brief
    /// Renders the legend for the specified MgMap to the requested size and format
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param width
    /// Input
    /// width of legend image in pixels
    /// \param height
    /// Input
    /// height of legend image in pixels
    /// \param backgroundColor
    /// Input
    /// background color. Specifies the map legend background color
    /// \param format
    /// Input
    /// image format. Defines the format of the resulting image
    /// \param omitEmptyLayerGroups
    /// Input
    /// indicates whether layer groups with no visible layers should be drawn in the resulting image. If true, these groups will not be drawn. If false, these groups will be drawn
    /// \return
    /// A byte reader containing the rendered image
    virtual MgByteReader* RenderMapLegend(
        MgMap* map,
        INT32 width,
        INT32 height,
        MgColor* backgroundColor,
        CREFSTRING format,
        bool omitEmptyLayerGroups) = 0;

When omitEmptyLayerGroups is false, this will function like the original API. When omitEmptyLayerGroups is true, this will skip rendering the names of any layer groups that have no visible layers at the current map scale.

Because this API has a HTTP counterpart, we will also introduce a new version of the GETMAPLEGENDIMAGE operation:


Name Value Required Description
VERSION 2.3.0 Yes Operation version
CLIENTAGENT text Optional Descriptive text for client
SESSION session identifier Yes MapGuide session identifier containing map to display
MAPNAME text Yes Name of the map to display.
This corresponds to the GetName() value for the resource identifier.
FORMAT JPG/PNG/PNG8 Yes Image format for rendered image
WIDTH integer Yes Width of legend image
HEIGHT integer Yes Height of legend image
OMITEMPTYLAYERGROUPS boolean Optional Indicates whether to omit layer groups from the rendered image. Default is false.


This is an API addition. The existing API will still be available and function as before.

Test Plan

Add new test case for Rendering Service unit test:

  • Create a map of Sheboygan which is the same as the existing rendering test map, but includes a visible Layer Group containing a Parcels layer (visible at 12000)
  • Set view scale of this map to > 12000
  • Render the legend of this map with omitEmptyLayerGroups = true and omitEmptyLayerGroups = false
  • When omitEmptyLayerGroups = false, verify the resulting image is as though the original API was called (layer group is drawn to the resulting image)
  • When omitEmptyLayerGroups = true, verify the empty layer group is not drawn to the resulting image.

Funding / Resources


Last modified 7 years ago Last modified on Sep 5, 2010 10:09:55 PM