Map service ExportMapImage method

Generates a dynamic map image from a data frame (map) in an ArcGIS Server map service.

ExportMapImage (MapDescription MapDescription, ImageDescription ImageDescription)

Parameter

Description

MapDescription

Used to define the contents and extent of the map image, such as layer visibility and extent.

ImageDescription

Used to define the physical properties of the map image, such as height and width in pixels and image output type.

Return Value

A MapImage referencing the properties of the generated map image such as image width and height, map extent, map scale, and dpi. The MapImage also maintains a set of properties to store the URL of the generated map image or the MIME data stream of the image contents.

Remarks

ExportMapImage is designed to maintain aspect ratio, so the map extent provided as part of the MapDescription may be different than the map extent in the generated map image. To get the map extent of the generated image, use the MapImage. Extent property. Further modifications to the MapDescription and ImageDescription input parameters to alter map image content are discussed below:

MapDescription

The default MapDescription for a data frame contains the default description properties for a map it will generate. This can be retrieved via the MapServerInfo. DefaultMapDescription property. This object can be modified to change contents and properties of the generated map image. A number of modifications can be implemented:

Define map extent

Set the MapDescription.MapArea. Extent property to an instance of EnvelopeN. This envelope can be created from scratch and define minimum and maximum x and y values. Note that the aspect ratio of the generated map image will be maintained so the extent of the output MapImage may differ from the extent defined as part of the input MapDescription.

Change layer visibility

The LayerDescriptions property of the MapDescription returns an array or LayerDescription objects, one for each layer in the data frame in a map service. The LayerDescription. Visible property can be set to true or false to change layer visibility. Note that LayerDescription includes a reference to the unique layer id (via the LayerID property), but not layer name. Use the MapLayerInfo array from the MapServerInfo's MapLayerInfos property to associated layer id and name.

Define spatial reference

Data frame contents can be projected on the fly. The spatial reference of two items must be known: the map and the extent envelope. The MapDescription's SpatialReference property defines the coordinate system of the output map image. The EnvelopeN. SpatialReference property on the extent envelope defines the coordinate system of the requested extent. They do not need to match. The extent envelope will be projected from its coordinate system into the map coordinate system by the map service.

The ProjectedCoordinateSystem and GeographicCoordinateSystem classes both implement SpatialReference. To define a spatial reference you can use a well-known id or a projection string. The well-known id is defined using the SpatialReference.WKID property. Note, to use a well-known id, the SpatialReference.WKIDSpecified property must be set to true. A projection string can be defined via the SpatialReference. WKT property.

Set transparent background color

To overlay multiple maps, it may be beneficial to generate a map image in which the background color is transparent. MapDescription maintains two properties of interest for this situation. MapDescription. TransparentColor defines the single color to render transparent. MapDescription. BackgroundSymbol. Color stores a reference to the current background color. If they are the same, the background in the map image will be transparent. The image type must also support transparency. For example, PNG and GIF support transparency but JPEG does not.

Add graphics

Custom graphics can be added to a map image via the MapDescription. CustomGraphics property which stores an array of GraphicElement objects. A GraphicElement consists of geometry and a symbol. The symbol type should be valid for the geometry type. For example, geometry of type PointN must be rendered using a type of MarkerSymbol.

dynamicLayers

NoteNote:
The following functionalities are only supported when a mapservice is published with dynamicLayer enabled. SupportsDynamicLayers returns True when a mapservice is dynamicLayer enabled. It is important to know that all changes made to the MapServer are stateless and only valid for the duration of the call. One the call is process, MapServer is reverted back to the original state.

Reordering layers

When HonorLayerReordering is set to True, the position of a LayerDescription in the LayerDescriptions array of the MapDescription becomes important. The LayerDescription of the top of the array draws on top of any other layer in a mapervice, the last one in the array is drawn at the bottom.

Modify layer symbol

Set DrawingDescription to an existing LayerDescription to modify how a layer will be drawn. Setting this to Null on an existing LayerDescription makes the layer draw with the renderer set in the source map document. MapServer supports Simple, ClassBreaks and UniqueValue renderers. GenerateDataClasses is a helper method that can be used to ask a mapservice to generate ClassBreaks or UniqueValue renderer.

Add new layer

A new layer can only be added when a workspace (of type ArcSDE, FileGeodatabase or folder) is registered with a mapservice. One needs to consult with the publisher to find out whether any workspace is registered to a mapervice and what is identifier for that workspace. A mapservice does not advertise what are the workspace registered with itself.

In order add a new layer dynamically, create a LayerDescription, set the Source and DrawingDescription properties, set Visible to True, LayerID should be set to a positive integer that is not used by any other LayerDescription and add it to the LayerDescriptions property of the MapDescription. HonorLayerReordering property must be set to True.

Exporting from a cached map service

By default Exporting a map from a cached service does not generate map dynamically, instead it creates map using pre-cooked cache tiles and return one single image instead of multiple tiles. What that also means that any changes made to the LayerDescription of any of the map layers, such as applying a definition expression, applying a selection buffer, toggling the visibility of labels or changing the visibility of the layer itself are ignored. Also, any changes made to the database does not get relected since tiles are all precooked. In addition, custom graphics, the rendering of selected features etc. cannot be applied to the MapDescription.

By contrast, when a cached mapservice is enabled with dynamicLayers, an ExportMapImage call generates map dynamically by reading database instead of using pre-cooked tiles. As a result, any changes made to the LayerDescription or the source database are reflected in the output image.

ImageDescription

ImageDescription is used to define raw image properties. It is composed to two properties: ImageType and ImageDisplay.

ImageType defines the image type and method for returning the image content. Supported image types are 'png32', 'png24', 'png'/'png8', 'jpg', 'tif', ', 'emf', 'ps', 'pdf', 'gif', 'svg' and 'svgz'. PNG32 carries over transparency set to feature or layer in its alpha channel. Image content can be returned as a URL or as a MIME data stream.

ImageDisplay defines the height, width and DPI of the image. Note that the DPI is merely used by the map service to determine map scale on the server, it does not define the resolution of the map image. In this case, map scale is used to determine how to render scale dependent symbols and layers. For example, both map images included below were generated using the same size (250x250) but a different DPI. The map image on the left was created with a DPI of 96 and the one on the right 200. Note that although the physical resolution is the same, the symbology is different. Symbology size is defined using points (1 point = 1/72 inch). To determine symbology size in a map, DPI is used to convert from points to pixels with the following equation:

Symbol Size in Points * (DPI/Number of Points in 1 inch)

In the map image with 96 DPI, a symbol size of 1 point will use 1.33 pixels (rounded down to 1 pixel) to render. In the map image with 200 DPI, a symbol size of 1 point will use 2.78 (rounded up to 3 pixels) to render. As a result, the symbology appears larger in the map image created using a DPI of 200.

map image at 96 DPImap image at 200 DPI

Examples

C#

MapService_MapServer mapservice = new MapService_MapServer();

mapservice.Url = "http://localhost:6080/arcgis/services/MapService/MapServer";

 

MapServerInfo mapinfo = mapservice.GetServerInfo(mapservice.GetDefaultMapName());

MapDescription mapdesc = mapinfo.DefaultMapDescription;

 

ImageType imgtype = new ImageType();

imgtype.ImageFormat = esriImageFormat.esriImagePNG;

imgtype.ImageReturnType = esriImageReturnType.esriImageReturnURL;

 

ImageDisplay imgdisp = new ImageDisplay();

imgdisp.ImageHeight = 500; //pixels

imgdisp.ImageWidth = 500; //pixels

imgdisp.ImageDPI = 96;

 

ImageDescription imgdesc = new ImageDescription();

imgdesc.ImageDisplay = imgdisp;

imgdesc.ImageType = imgtype;

 

MapImage mapimg = mapservice.ExportMapImage(mapdesc, imgdesc);

VB.NET

Dim mapservice As MapService_MapServer = New MapService_MapServer()

mapservice.Url = "http://localhost:6080/arcgis/services/MapService/MapServer"

 

Dim mapinfo As MapServerInfo = mapservice.GetServerInfo(mapservice.GetDefaultMapName())

Dim mapdesc As MapDescription = mapinfo.DefaultMapDescription

 

Dim imgtype As ImageType = New ImageType()

imgtype.ImageFormat = esriImageFormat.esriImagePNG

imgtype.ImageReturnType = esriImageReturnType.esriImageReturnURL

 

Dim imgdisp As ImageDisplay = New ImageDisplay()

imgdisp.ImageHeight = 500 'pixels

imgdisp.ImageWidth = 500 'pixels

imgdisp.ImageDPI = 96

 

Dim imgdesc As ImageDescription = New ImageDescription()

imgdesc.ImageDisplay = imgdisp

imgdesc.ImageType = imgtype

 

Dim mapimg As MapImage = mapservice.ExportMapImage(mapdesc, imgdesc)

Java

String serviceURL = "http://localhost:6080/arcgis/services/MapService/MapServer";

MapServerBindingStub mapService = new MapServerBindingStub(serviceURL);

 

String mapName = mapService.getDefaultMapName();

MapServerInfo mapInfo= mapService.getServerInfo(mapName);

MapDescription mapDesc = mapInfo.getDefaultMapDescription();

 

ImageType imgType = new ImageType();

imgType.setImageFormat(EsriImageFormat.esriImagePNG);

imgType.setImageReturnType(EsriImageReturnType.esriImageReturnURL);

 

ImageDisplay imgDisp = new ImageDisplay();

imgDisp.setImageHeight(500); //Height of the image in pixels

imgDisp.setImageWidth(500); //Width of the image in pixels

imgDisp.setImageDPI(96);

 

ImageDescription imgDesc = new ImageDescription();

imgDesc.setImageDisplay(imgDisp);

imgDesc.setImageType(imgType);

 

MapImage mapImg = mapService.exportMapImage(mapDesc, imgDesc);

System.out.println("Image URL: " + mapImg.getImageURL());

2/28/2020