wiki:HttpApi/RenderingService

Version 46 (modified by trevorwekel, 15 years ago) ( diff )

--

Rendering Service HTTP APIs

Revision History

RevisionDateAuthorComment
0.1April 19, 2010Trevor WekelInitial pass at documentation
0.2April 28, 2010Trevor WekelComplete documentation for GetDynamicMapOverlayImage and GetMapImage

Table of Contents

  1. Overview
  2. MapGuide 2.1 APIs
    1. GetDynamicMapOverlayImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    2. GetMapImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    3. GetMapLegendImage
      1. Overview
      2. Parameters
    4. GetVisibleMapExtent
      1. Overview
      2. Parameters
    5. QueryMapFeatures
      1. Overview
      2. Parameters
      3. Usage
  3. MapGuide 2.0 APIs
    1. GetDynamicMapOverlayImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    2. GetMapImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    3. GetMapLegendImage
      1. Overview
      2. Parameters
    4. GetVisibleMapExtent
      1. Overview
      2. Parameters
      3. Usage
    5. QueryMapFeatures
      1. Overview
      2. Parameters
  4. MapGuide 1.2 APIs
    1. GetDynamicMapOverlayImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    2. GetMapImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    3. GetMapLegendImage
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    4. GetVisibleMapExtent
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes
    5. QueryMapFeatures
      1. Overview
      2. Parameters
      3. Usage
      4. Technical Notes

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/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/mapagent.fcgi?OPERATION=GETMAPIMAGE
    &VERSION=2.1.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

Generates a legend image for the the currently displayed scale of the map identified by SESSION and MAPNAME. GetMapLegendImage in MapGuide 2.1 is identical to GetMapLegendImage in MapGuide 2.0 with the addition of a CLIENTAGENT parameter.

Parameters

Name Value Required Description
OPERATION GETMAPLEGENDIMAGE 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
WIDTH integer Yes Width of legend image
HEIGHT integer Yes Height of legend image

GetVisibleMapExtent

Overview

Returns the visible map extent in map coordinate system units for the map specified by SESSION and MAPNAME. GetVisibleMapExtent in MapGuide 2.1 is identical to GetVisibleMapExtent in MapGuide 2.0 with the addition of a CLIENTAGENT parameter.

Parameters

Name Value Required Description
OPERATION GETVISIBLEMAPEXTENT Yes Operation to execute
VERSION 2.0.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.
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.
FORMAT text Optional Desired output format.

QueryMapFeatures

Overview

QueryMapFeatures for MapGuide 2.1 is nearly identical to QueryMapFeatures for MapGuide 1.2. The only changes to the API were the addition of "ENVELOPEINTERSECTS" for the SELECTIONVARIANT parameter and the CLIENTAGENT parameter.

Parameters

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

Usage

http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=QUERYMAPFEATURES
    &VERSION=2.1.0
    &CLIENTAGENT=Ajax Viewer
    &PERSIST=0
    &MAPNAME=Sheboygan
    &SESSION=20ef251c-53bb-11df-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
    &LAYERNAMES=Islands,Hydrography,Parcels
    &GEOMETRY=POLYGON((10 10, 10 20, 20 20, 20 15, 10 10))
    &SELECTIONVARIANT=INTERSECTS
    &MAXFEATURES=1
    &LAYERATTRIBUTEFILTER=5
    &CLIENTAGENT=Ajax Viewer

Queries the first feature from the Islands,Hydrography, or Parcels layers intersecting the given polygon. The feature must have a tooltip and be visible. The queried feature is not selected on the map.

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/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/mapagent.fcgi?OPERATION=GETMAPIMAGE
    &VERSION=2.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

GetMapLegendImage

Overview

Generates a legend image for the the currently displayed scale of the map identified by SESSION and MAPNAME. GetMapLegendImage in MapGuide 2.0 is identical to GetMapLegendImage in MapGuide 1.2 with the addition of PNG8 as an output format.

Parameters

Name Value Required Description
OPERATION GETMAPLEGENDIMAGE 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
WIDTH integer Yes Width of legend image
HEIGHT integer Yes Height of legend image

GetVisibleMapExtent

Overview

Returns the visible map extent in map coordinate system units for the map specified by SESSION and MAPNAME. GetVisibleMapExtent in MapGuide 2.0 is identical to GetVisibleMapExtent in MapGuide 1.2 with the addition of a parameter to select either XML or JSON output for the result. The XML output has the following form: 

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<Envelope>
  <LowerLeftCoordinate>
    <X>-87.8</X>
    <Y>43.6</Y>
  </LowerLeftCoordinate>
  <UpperRightCoordinate>
    <X>-87.6</X>
    <Y>43.8</Y>
  </UpperRightCoordinate>
</Envelope>

And the JSON output has the following form: 

{
"Envelope":
  {
  "LowerLeftCoordinate":[{"X":["-87.8"],"Y":["43.6"]}],
  "UpperRightCoordinate":[{"X":["-87.6"],"Y":["43.8"]}]
  }
}

Parameters

Name Value Required Description
OPERATION GETVISIBLEMAPEXTENT 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.
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.
FORMAT text Optional Desired output format.

FORMAT Parameter

Selects the output format for the result:

  • "text/xml" - Output is given in XML format
  • "application/json" - Output is given in JSON format

Usage

http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=GETVISIBLEMAPEXTENT
    &VERSION=1.0.0
    &SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
    &MAPNAME=WorldElevation
    &SETVIEWCENTERX=-114.0
    &SETVIEWCENTERY=51.0
    &SETVIEWSCALE=50000
    &SETDISPLAYHEIGHT=500
    &SETDISPLAYWIDTH=500
    &FORMAT=application/json

Sets the center point of the WorldElevation map to (-114,51) and the scale to 1:50000. The visible map extent is returned as JSON. The display height and width for a subsequent GetDynamicMapOverlay are set to 500 by 500.

QueryMapFeatures

Overview

QueryMapFeatures for MapGuide 2.0 is identical to QueryMapFeatures for MapGuide 1.2.

Parameters

Name Value Required Description
OPERATION GETMAPIMAGE 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.
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.

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/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/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/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

GetMapLegendImage

Overview

Generates a legend image for the the currently displayed scale of the map identified by SESSION and MAPNAME. The legend image can be used for display purposes or as part of a bitmap plot for the current map view.

Parameters

Name Value Required Description
OPERATION GETMAPLEGENDIMAGE 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
WIDTH integer Yes Width of legend image
HEIGHT integer Yes Height of legend image

WIDTH Parmaeter

Width of generated legend image in pixels

HEIGHT Parmaeter

Height of generated legend image in pixels

Usage

http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=GETMAPLEGENDIMAGE
    &VERSION=1.0.0
    &SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
    &MAPNAME=WorldElevation
    &FORMAT=PNG
    &WIDTH=200
    &HEIGHT=500

Generates a 200 by 500 32 bit PNG legend image for the current view of the WorldElevation map.

Technical Notes

GetVisibleMapExtent

Overview

Returns the visible map extent in map coordinate system units for the map specified by SESSION and MAPNAME. During the call, the map state can be modified by additional parameters such as SETVIEWCENTERX and SETVIEWSCALE. This API is typically called before GetDynamicMapOverlay to set map state. The returned XML document has the following format: 

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<Envelope>
  <LowerLeftCoordinate>
    <X>10</X>
    <Y>10</Y>
  </LowerLeftCoordinate>
  <UpperRightCoordinate>
    <X>20</X>
    <Y>20</Y>
  </UpperRightCoordinate>
</Envelope>

Parameters

Name Value Required Description
OPERATION GETVISIBLEMAPEXTENT 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.
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.

Usage

http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=GETVISIBLEMAPEXTENT
    &VERSION=1.0.0
    &SESSION=Session:d5d05422-5f75-102c-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
    &MAPNAME=WorldElevation
    &SETVIEWCENTERX=-114.0
    &SETVIEWCENTERY=51.0
    &SETVIEWSCALE=50000
    &SETDISPLAYHEIGHT=500
    &SETDISPLAYWIDTH=500

Sets the center point of the WorldElevation map to (-114,51) and the scale to 1:50000. The visible map extent is returned as an XML document. The display height and width for a subsequent GetDynamicMapOverlay are set to 500 by 500.

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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FeatureSet-1.0.0.xsd">
    <Layer id="84777002-53bc-11df-8004-02004c4f4f50">
      <Class id="SHP_Schema:Parcels">
        <ID>BCAAAA==</ID>
      </Class>
    </Layer>
  </FeatureSet>
  <Tooltip>Some tooltip text</Tooltip>
  <Hyperlink>http://www.website.com</Hyperlink>
  <Property name="Owner" value="John Doe"/>
  <Property name="Lot Size" value=".50"/>
</FeatureInformation>

Parameters

Name Value Required Description
OPERATION GETMAPIMAGE 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.
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().

Usage

http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=QUERYMAPFEATURES
    &VERSION=1.0.0
    &PERSIST=0
    &MAPNAME=Sheboygan
    &SESSION=20ef251c-53bb-11df-8000-02004c4f4f50_en_7F0000010AFC0AFB0AFA
    &LAYERNAMES=Islands,Hydrography,Parcels
    &GEOMETRY=POLYGON((10 10, 10 20, 20 20, 20 15, 10 10))
    &SELECTIONVARIANT=INTERSECTS
    &MAXFEATURES=1
    &LAYERATTRIBUTEFILTER=5
    &CLIENTAGENT=Ajax Viewer

Queries the first feature from the Islands,Hydrography, or Parcels layers intersecting the given polygon. The feature must have a tooltip and be visible. The queried feature is not selected on the map.

Technical Notes

Note: See TracWiki for help on using the wiki.