MapGuide RFC 148 - Support user-defined selection color in RenderMap

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	20 Oct 2014
Last Modified	1 Nov 2014
Author	Jackie Ng
RFC Status	adopted
Implementation Status	implemented
Proposed Milestone	3.0
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Jackie,Gordon
+0
-0
-1
no vote	Trevor,Kevin,Crispin,Haris

Overview

This RFC proposes to extend the RenderMap API to support user-defined selection colors

Motivation

Currently, the RenderMap API does not offer the ability to pass in a custom selection color. As a result, any selections rendered via the RenderMap API will always be blue, which may not be suitable for particular maps.

Proposed Solution

Add 2 new overloads of RenderMap that accepts a selection color to MgRenderingService.

The first overload is based on the existing overload with the most parameters.

The other overload is to support invocation from the mapagent.

class MgRenderingService
{
PUBLISHED_API:
...
    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Renders the specified MgMap to the requested image format.
    ///
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param selection
    /// Input
    /// map feature selection. Specifies the selected features on the map
    /// \param center
    /// Input
    /// map center point. Specifies the center point for the map
    /// \param scale
    /// Input
    /// map scale. Specifies the scale for the map
    /// \param width
    /// Input
    /// image width. Specifies the image width in pixels
    /// \param height
    /// Input
    /// image height. Specifies the image height in pixels
    /// \param backgroundColor
    /// Input
    /// background color. Specifies the map background color
    /// \param format
    /// Input
    /// image format. Defines the format of the resulting image
    /// \param bKeepSelection
    /// Input
    /// true if you want to keep the selection
    /// \param selectionColor
    /// Input
    /// The color to use for rendered selections
    ///
    /// \return
    /// A byte reader containing the rendered image
    ///
    virtual MgByteReader* RenderMap(
        MgMap* map,
        MgSelection* selection,
        MgCoordinate* center,
        double scale,
        INT32 width,
        INT32 height,
        MgColor* backgroundColor,
        CREFSTRING format,
        bool bKeepSelection,
        MgColor* selectionColor) = 0;

    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Renders the specified MgMap to the requested image format.
    ///
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param selection
    /// Input
    /// map feature selection. Specifies the selected features on the map
    /// \param format
    /// Input
    /// image format. Defines the format of the resulting image
    /// \param bKeepSelection
    /// Input
    /// true if you want to keep the selection
    /// \param bClip
    /// Input
    /// true if you want to clip feature geometry
    /// \param selectionColor
    /// Input
    /// The color to use for rendered selections
    ///
    /// \return
    /// A byte reader containing the rendered image
    ///
    virtual MgByteReader* RenderMap(
        MgMap* map,
        MgSelection* selection,
        CREFSTRING format,
        bool bKeepSelection,
        bool bClip,
        MgColor* selectionColor) = 0;
};

In the mapagent, we'll introduce a version 3.0.0 GETMAPIMAGE that supports a user-defined selection color.

Name	Value	Required	Description
OPERATION	GETMAPIMAGE	Yes	Operation to execute
VERSION	3.0.0	Yes	Operation version
CLIENTAGENT	text	Optional	Descriptive text for client
SESSION	session identifier	Optional	MapGuide session identifier containing map to display. SESSION or USERNAME and PASSWORD must be specified.
USERNAME	text	Optional	MapGuide user id. SESSION or USERNAME and PASSWORD must be specified.
PASSWORD	text	Optional	Password for MapGuide user. SESSION or USERNAME and PASSWORD must be specified.
MAPNAME	text	Optional	Name of the map to display. This corresponds to the GetName() value for the resource identifier. MAPNAME or MAPDEFINITION must be specified.
MAPDEFINITION	text	Optional	Resource identifier for the map definition. MAPNAME or MAPDEFINITION must be specified.
FORMAT	JPG/PNG/PNG8	Yes	Image format for rendered image
KEEPSELECTION	0/1	Optional	If true, render selected feature(s) even if they are outside the current scale.
SETVIEWCENTERX	double	Optional	Set X coordinate for center of map.
SETVIEWCENTERY	double	Optional	Set Y coordinate for center of map.
SETVIEWSCALE	double	Optional	Set scale for map.
SETDISPLAYDPI	integer	Optional	Set DPI for map.
SETDISPLAYWIDTH	integer	Optional	Set width of image in pixels.
SETDISPLAYHEIGHT	integer	Optional	Set height of image in pixels.
SHOWLAYERS	text	Optional	List of layers to display.
HIDELAYERS	text	Optional	List of layers to hide.
SHOWGROUPS	text	Optional	List of groups to display.
HIDEGROUPS	text	Optional	List of groups to hide.
CLIP	0/1	Optional	If true, additional clipping will be performed on image.
SELECTIONCOLOR	RGBA hex color	Optional	If specified, any selections rendered will use the specified color. Defaults to blue if not specified

Implications

None. This is a new API.

Test Plan

Add new rendering tests that pass in specific colors. Verify image output results.

Funding / Resources

Community

References

• #2399