wiki:MapGuideRfc148

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 Date20 Oct 2014
Last Modified1 Nov 2014
AuthorJackie Ng
RFC Statusadopted
Implementation Statusimplemented
Proposed Milestone3.0
Assigned PSC guide(s)(when determined)
Voting History(vote date)
+1Jackie,Gordon
+0
-0
-1
no voteTrevor,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

Last modified 3 years ago Last modified on Oct 31, 2014 6:00:52 AM