| Version 31 (modified by , 15 years ago) ( diff ) |
|---|
Rendering Service HTTP APIs
Revision History
| Revision | Date | Author | Comment |
| 0.1 | April 19, 2010 | Trevor Wekel | Initial pass at documentation |
| 0.2 | April 28, 2010 | Trevor Wekel | Complete documentation for GetDynamicMapOverlayImage and GetMapImage |
Table of Contents
- Overview
- MapGuide 2.1 APIs
- MapGuide 2.0 APIs
- MapGuide 1.2 APIs
Overview
This document describes the Rendering Service HTTP APIs supported by the MapGuide mapagent. The Rendering Service APIs are used to render a map into a bitmapped image. In addition to bitmap rendering, the APIs support basic updates to the underlying MgMap object state including changes to center, scale, and layer visibility.
MapGuide 2.1 APIs
GetDynamicMapOverlayImage
Overview
GetDynamicMapOverlayImage returns a rendered raster image containing all visbile layers at the current center and scale for the map. This API is used in conjuction with the GetVisibleMapExtent HTTP API to provide dynamic map updates for end user interactions.
Parameters
| Name | Value | Required | Description |
| OPERATION | GETDYNAMICMAPOVERLAYIMAGE | Yes | Operation to execute |
| VERSION | 2.1.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 |
| SELECTIONCOLOR | RGBA hex color | Yes | Selection color encoded in hexadecimal RGBA format 0xRRGGBBAA. |
| BEHAVIOR | bitmask | Yes | Bitmask representing rendering behavior. See below for more details. |
| 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. |
CLIENTAGENT Parameter
Descriptive text describing the client of the HTTP operation. Currently used values include "Ajax Viewer", "Fusion Viewer" "MapGuide Developer" and "MapGuide Maestro".
Usage
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETDYNAMICMAPOVERLAYIMAGE
&VERSION=2.1.0
&CLIENTAGENT=Ajax Viewer
&SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
&MAPNAME=WorldElevation
&FORMAT=PNG8
&BEHAVIOR=7
&SELECTIONCOLOR=0xFF000080
&SETVIEWCENTERX=-114.0
&SETVIEWCENTERY=51.0
&SETVIEWSCALE=50000
&SETDISPLAYHEIGHT=500
&SETDISPLAYWIDTH=500
&SHOWLAYERS=d5d01111-5f75-102c-8000-02004c4f4f50,d5d01118-5f75-102c-8000-02004c4f4f50
Sets center of map to (-114,51) and scale to 1:50000. Turns on layers d5d01111 and d5d01118. The visible layers and any selection are then rendered as a 500 by 500 eight bit PNG image. The selection is drawn in partially transparent red.
Technical Notes
GetMapImage
Overview
GetMapImage returns a rendered raster image containing all visible layers for the map. This API can be used to generate a raster image for a currently displayed map in the session repository or to display an arbitrary view of a map defined by a map definition.
Parameters
| Name | Value | Required | Description |
| OPERATION | GETMAPIMAGE | Yes | Operation to execute |
| VERSION | 2.1.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. |
Usage
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETMAPIMAGE
&VERSION=1.0.0
&CLIENTAGENT=Fusion Viewer
&SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
&MAPNAME=WorldElevation
&FORMAT=PNG
&SETVIEWCENTERX=-114.0
&SETVIEWCENTERY=51.0
&SETVIEWSCALE=50000
&SETDISPLAYHEIGHT=500
&SETDISPLAYWIDTH=500
&KEEPSELECTION=1
&SHOWLAYERS=d5d01111-5f75-102c-8000-02004c4f4f50,d5d01118-5f75-102c-8000-02004c4f4f50
&CLIP=1
Sets center of map to (-114,51) and scale to 1:50000. Turns on layers d5d01111 and d5d01118. The visible layers are rendered as a 500 by 500 PNG image. Any selection already defined by web extensions API calls will be drawn in blue regardless of scale. Changes to center, scale and layer visibility are retained. Features and labels will be clipped to the bounds of the image.
Technical Notes
GetMapLegendImage
Overview
Parameters
Usage
Technical Notes
GetVisibleMapExtent
Overview
Parameters
Usage
Technical Notes
QueryMapFeatures
Overview
Parameters
Usage
Technical Notes
MapGuide 2.0 APIs
GetDynamicMapOverlayImage
Overview
GetDynamicMapOverlayImage returns a rendered raster image containing all visbile layers at the current center and scale for the map. This API is used in conjuction with the GetVisibleMapExtent HTTP API to provide dynamic map updates for end user interactions.
Parameters
| Name | Value | Required | Description |
| OPERATION | GETDYNAMICMAPOVERLAYIMAGE | Yes | Operation to execute |
| VERSION | 2.0.0 | Yes | Operation version |
| 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 |
| BEHAVIOR | bitmask | Yes | Bitmask representing rendering behavior. See below for more details. |
| SELECTIONCOLOR | RGBA hex color | Yes | Selection color encoded in hexadecimal RGBA format 0xRRGGBBAA. |
BEHAVIOR Parameter
The behavior parameter specifies how the rendering is performed. The value is encoded as a bitmask to facilitate future enhancements to the API. One or more bits may be combined to determine overall rendering behavior.
| Value | Description |
| 1 (RenderSelection) | Renders the selected feature(s) |
| 2 (RenderLayers) | Renders the features on the map |
| 4 (KeepSelection) | Renders the selected feature(s) even if they are outside the current scale |
Examples:
- BEHAVIOR=3 (RenderSelection|RenderLayers) will render selection and layers within the current scale
- BEHAVIOR=5 (RenderSelection|KeepSelection) will render only the selection regardless of scale
SELECTIONCOLOR Parameter
Color for selected objects expressed in hexadecimal RGBA format 0xRRGGBBAA.
Usage
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETDYNAMICMAPOVERLAYIMAGE
&VERSION=2.0.0
&SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
&MAPNAME=WorldElevation
&FORMAT=PNG
&BEHAVIOR=5
&SELECTIONCOLOR=0xFF000080
Renders the selection regardless of current scale for the WorldElevation map from session Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA as a 32 bit PNG image. The selection is drawn in partially transparent red.
Technical Notes
GetMapImage
Overview
GetMapImage returns a rendered raster image containing all visible layers for the map. This API can be used to generate a raster image for a currently displayed map in the session repository or to display an arbitrary view of a map defined by a map definition.
Parameters
| Name | Value | Required | Description |
| OPERATION | GETMAPIMAGE | Yes | Operation to execute |
| VERSION | 2.0.0 | Yes | Operation version |
| 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. |
CLIP Parameter
If set to true, all features and labels will be clipped to the extents of the rendered image. This can improve rendering speed but may cause dense labels to shift slightly during pans.
Usage
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETMAPIMAGE
&VERSION=1.0.0
&SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
&MAPNAME=WorldElevation
&FORMAT=PNG
&SETVIEWCENTERX=-114.0
&SETVIEWCENTERY=51.0
&SETVIEWSCALE=50000
&SETDISPLAYHEIGHT=500
&SETDISPLAYWIDTH=500
&KEEPSELECTION=1
&SHOWLAYERS=d5d01111-5f75-102c-8000-02004c4f4f50,d5d01118-5f75-102c-8000-02004c4f4f50
&CLIP=1
Sets center of map to (-114,51) and scale to 1:50000. Turns on layers d5d01111 and d5d01118. The visible layers are rendered as a 500 by 500 PNG image. Any selection already defined by web extensions API calls will be drawn in blue regardless of scale. Changes to center, scale and layer visibility are retained. Features and labels will be clipped to the bounds of the image.
Technical Notes
MapGuide 1.2 APIs
GetDynamicMapOverlayImage
Overview
GetDynamicMapOverlayImage returns a rendered raster image containing all visible layers at the current center and scale for the map. This API is used in conjuction with the GetVisibleMapExtent HTTP API to provide dynamic map updates for end user interactions.
Parameters
| Name | Value | Required | Description |
| OPERATION | GETDYNAMICMAPOVERLAYIMAGE | Yes | Operation to execute |
| VERSION | 1.0.0 | Yes | Operation version |
| 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 | Yes | Image format for rendered image |
| KEEPSELECTION | 0/1 | Optional | If true, render selected feature(s) even if they are outside the current scale. |
Usage
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETDYNAMICMAPOVERLAYIMAGE
&VERSION=1.0.0
&SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
&MAPNAME=WorldElevation
&FORMAT=PNG
Renders the WorldElevation map from session Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA as a 32 bit PNG image.
Technical Notes
GetMapImage
Overview
GetMapImage returns a rendered raster image containing all visible layers for the map. This API can be used to generate a raster image for a currently displayed map in the session repository or to display an arbitrary view of a map defined by a map definition.
Parameters
| Name | Value | Required | Description |
| OPERATION | GETMAPIMAGE | Yes | Operation to execute |
| VERSION | 1.0.0 | Yes | Operation version |
| 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 | 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. |
OPERATION Parameter
Name of HTTP operation to execute. This parameter is case sensitive. Operation names should be all uppercase.
VERSION Parameter
Version of operation to execute. This version number corresponds to the version of MapGuide where the operation was changed or introduced.
SESSION Parameter
Session identifier for the map. The session identifier is typically created using MgSite::CreateSession() or the CREATESESSION HTTP operation.
USERNAME Parameter
MapGuide user id with permission to access the map definition and related resources.
PASSWORD Parameter
Password for MapGuide user.
MAPNAME Parameter
The map name is the resource name of the map. For example "WorldElevation" is the resource name for "Library://Maps/World/WorldElevation.MapDefinition".
MAPDEFINITION Parameter
Resource identifier for the map definition, eg. "Library://Maps/World/WorldElevation.MapDefinition".
FORMAT Parameter
Image format for the rendered image. Legal values are:
- "JPG" for 24 bit JPEG
- "PNG" for 32 bit PNG
- "PNG8" for 8 bit PNG Note: This was added in MapGuide 2.0.
KEEPSELECTION Parameter
Determines whether the selection is visible outside of the scale range for the selected feature(s). If "1", the selection will be visible even when the feature scale range is outside of the current map scale.
SETVIEWCENTERX Parameter
Sets the X coordinate for the center of the map. The coordinate is given in map coordinate system units.
SETVIEWCENTERY Parameter
Sets the Y coordinate for the center of the map. The coordinate is given in map coordinate system units.
SETVIEWSCALE Parameter
Sets the currently viewed scale for the map. This number should be greater than zero.
SETDISPLAYDPI Parameter
Sets the display resolution for the device. Typically 96 or 120 DPI.
SETDISPLAYWIDTH Parameter
Sets the width of the resulting image in pixels.
SETDISPLAYHEIGHT Parameter
Sets the height of the resulting image in pixels.
SHOWLAYERS Parameter
Comma separated list of the MgLayer::GetObjectId() values for layers to show. Previously shown layers will continue to be shown.
HIDELAYERS Parameter
Comma separated list of the MgLayer::GetObjectId() values for layers to hide. Previously hidden layers will remain hidden.
SHOWGROUPS Parameter
Comma separated list of the MgGroup::GetObjectId() values for groups to show. Previously shown groups will continue to be shown. Layers within the groups will retain their current hide/show status.
HIDEGROUPS Parameter
Comma separated list of the MgGroup::GetObjectId() values for groups to hide. Previously hidden groups will remain hidden. Layers within the groups will retain their current hide/show status.
Usage
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETMAPIMAGE
&VERSION=1.0.0
&SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
&MAPNAME=WorldElevation
&FORMAT=PNG
&SETVIEWCENTERX=-114.0
&SETVIEWCENTERY=51.0
&SETVIEWSCALE=50000
&SETDISPLAYHEIGHT=500
&SETDISPLAYWIDTH=500
&KEEPSELECTION=1
&SHOWLAYERS=d5d01111-5f75-102c-8000-02004c4f4f50,d5d01118-5f75-102c-8000-02004c4f4f50
Sets center of map to (-114,51) and scale to 1:50000. Turns on layers d5d01111 and d5d01118. The visible layers are rendered as a 500 by 500 PNG image. Any selection already defined by web extensions API calls will be drawn in blue regardless of scale. Changes to center, scale and layer visibility are retained.
http://localhost/mapguide/mapagent.fcgi?OPERATION=GETMAPIMAGE
&VERSION=1.0.0
&USERNAME=Anonymous
&PASSWORD=
&MAPDEFINITION=Library://Maps/World/WorldElevation.MapDefinition
&FORMAT=PNG
&SETVIEWCENTERX=-114.0
&SETVIEWCENTERY=51.0
&SETVIEWSCALE=50000
&SETDISPLAYHEIGHT=500
&SETDISPLAYWIDTH=500
&SHOWLAYERS=d5d01111-5f75-102c-8000-02004c4f4f50,d5d01118-5f75-102c-8000-02004c4f4f50
Creates a temporary map. Sets center of map to (-114,51) and scale to 1:50000. Turns on layers d5d01111 and d5d01118. The visible layers are rendered as a 500 by 500 PNG image. No selection is defined or drawn.
Technical Notes
QueryMapFeatures
Overview
QueryMapFeatures operation identifies features that meet the specified spatial selection criteria. These features can be persisted as selected features in a map. QueryMapFeatures returns an XML document describing the set of selected features. If a single feature is selected, the XML contains the tooltip, hyperlink, and properties of the feature.
<?xml version="1.0" encoding="UTF-8"?>
<FeatureInformation>
<FeatureSet>
<Layer>
<id></id>
<Class>
<id></id>
<ID></ID>
</Class>
</Layer>
</FeatureSet>
<Tooltip>Some tooltip text</Tooltip>
<Hyperlink>http://www.website.com</Hyperlink>
<Property name="Owner" value="John Doe"/>
<Property name="MarketAssessment" value="700000"/>
</FeatureInformation>
Parameters
| Name | Value | Required | Description |
| OPERATION | GETMAPIMAGE | Yes | Operation to execute |
| VERSION | 1.2.0 | Yes | Operation version |
| 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. |
| LAYERNAMES | text | Optional | Comma separated list of layer names. |
| MAXFEATURES | integer | Yes | Maximum number of features to select. |
| GEOMETRY | text | Yes | WKT string representing the selection geometry. |
| SELECTIONVARIANT | text | Yes | Geometric operation to use while selecting. |
| PERSIST | 0/1 | Yes | If true, selection is saved to map. |
| LAYERATTRIBUTEFILTER | integer | Optional | Filter based on layer attributes. |
| FEATUREFILTER | text | Optional | Filter based on previous selected features. |
LAYERNAMES Parameter
Comma separated list of layer names to restrict the selection to. Names can be obtained from MgLayer.GetName()
MAXFEATURES Parameter
Maximum number of features to select. If this value is set to "-1", all matching features will be selected.
GEOMETRY Parameter
WKT string representing the selection geometry, eg. "POLYGON((10 10, 10 20, 20 20, 20 15, 10 10))"
SELECTIONVARIANT Parameter
Geometric operation to use for testing features against the supplied geometry. The following operations are supported:
- "TOUCHES" - Feature geometry touches supplied geometry
- "INTERSECTS" - Feature geometry intersects supplied geometry
- "WITHIN" - Feature geometry lies within supplied goemetry
- "ENVELOPEINTERSECTS" - Envelopes of feature and supplied geometry intersect. Note: This was added in MapGuide 2.1.0
PERSIST Parameter
If set to "1", the resulting selection from QueryMapFeatures will be persisted to the map and visible on the next call to GetDynamicMapOverlayImage or GetMapImage.
LAYERATTRIBUTEFILTER Parameter
Bitmask specifying the attributes a layer must have to be considered in the selection process. The following attributes are supported:
- 1 - Layer is visible
- 2 - Layer is selectable
- 4 - Layer has a tooltip defined
Combinations of one or more attributes are allowed.
FEATUREFILTER Parameter
XML filter describing a set of previously selected features. This paramter is useful for obtaining the attribute values of a previously selected feature. The XML text can be retrieved from MgSelection.ToXml().
