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.

Status

RFC Template Version	(1.0)
Submission Date	3rd September 2010
Last Modified	Jackie Ng 3rd September 2010
Author	Jackie Ng
RFC Status	draft
Implementation Status	pending
Proposed Milestone	2.3
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

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.

Motivation

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:

Parameters

Name	Value	Required	Description
OPERATION	GETMAPLEGENDIMAGE	Yes	Operation to execute
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.

Implications

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

Community