IMapServer3.ExportMapImage Method

Generates an image of the map, based on the given map description, and writes the image to a specified file on disk. Supported file types are: 'bmp', 'jpg', 'tif', 'png'/'png8', 'png24', 'emf', 'ps', 'pdf', 'ai', 'gif', and 'svg'/'svgz'.

[Visual Basic .NET]
Public Function ExportMapImage ( _
    ByVal mapDesc As IMapDescription, _
    ByVal imageDesc As IImageDescription _
) As IMapImage

[C#]
public IMapImage ExportMapImage (
    IMapDescription mapDesc,
    IImageDescription imageDesc
);

[C++]
HRESULT ExportMapImage(
  IMapDescription* mapDesc,
  IImageDescription* imageDesc,
  IMapImage** MapImage
);

[C++]

Parameters
mapDesc [in]

  mapDesc is a parameter of type IMapDescription
imageDesc [in]

  imageDesc is a parameter of type IImageDescription
MapImage [out, retval]

  MapImage is a parameter of type IMapImage

Product Availability

Remarks

Use ExportMapImage to retrieve a file (image or vector format) of the map.

The input parameter MapDescription contains properties describing the map (also known as the data frame). These include the map's Name, the MapArea, the SpatialReference , as well as collections of LayerDescription objects. Size, resolution and file format are determined by the ImageDescription, which includes ImageDisplay and ImageType objects.

ExportMapImage returns a MapImage object. MapExtent, MapScale and an array of VisibleLayers can be retrieved from the MapImage.

You can export the map to either a vector or an image type. This is specified by the ReturnType property of IImageType.

Setting the size and resolution of the output

Size and resolution are set in the ImageDisplay. Both Height and Width are required. The Height and Width properties of IImageResult are read-only and are not used to make changes. In order to control the size of an exported image, IMapServerInit2 contains two properties: MaxImageHeight and MaxImageWidth. The default value for these properties is 1024 pixels.

You should be careful when specifying a DeviceResolution to the ImageDisplay. This is merely used by the map service to determine map scale on the server, it does not define the resolution of the map image. Changing the DeviceResolution may lead to unintended changes in the map scale. For example, you export a map image to JPG. You specify an image of 400 pixels by 600 pixels with the DeviceResolution set at 96. The relative MapScale of the resulting image is around 54,000,000. Next, you increase the DeviceResolution to 300 while keeping the size constant. The MapScale of this result is about 205,000,000. The result may not be want you wanted if the map contains layers or labels that are scale-dependent. In order to to maintain the MapScale at around 1:54,000,000 you would need to export a larger image.

If you are exporting to PDF you will need to keep in mind that PDF exits in page space. Setting the Height and Width sets the dimensions of the PDF page. For example, you export a map image to PDF where the ImageDisplay Height is 400 and the Width is 500. The DeviceResolution is 100. The resulting PDF is 4 inches by 5 inches. Holding the Height and Width settings constant, as you increase the DeviceResolution the actual size of the PDF will get smaller. As you decrease the DeviceResolution the size of the PDF gets larger. This will also affect MapScale. If you wish the MapScale to stay constant you will need to increase (or decrease) the ImageDisplay Height and Width values as you increase (or decrease) the DeviceResolution.

DeviceResolution also affects the symbols is rendered. For example, two map images were generated using the same size (250x250), same extent but a different DeviceResolution. The first map image was created with a DeviceResolution of 96 and the second one with 200. You will notice the symbols size differences between those two images. Symbology size is defined using points (1 point=1/72 inch) in the source map. To determine symbology size in a map, DeviceResolution is used to convert from points to pixels with the following equation:

Symbol Size in Points * (DeviceResolution/Number of Points in 1 inch)
 
In the map image with 96 DeviceResolution, a symbol size of 1 point will use 1.33 pixels (rounded down to 1 pixel) to render. In the map image with 200 DeviceResolution, 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 DeviceResolution of 200.

Image quality and image type of MapServer

• MapServices allow the author of the MapService to set general anti-aliasing options and text anti-aliasing options in the source document (.msd), resulting in a better quality image.  A user may use the DocumentInfo property to find out whether the map has anti-aliasing enabled.
• Output images may contain artifacts if a client requests a png8 image and the MapService has anti-aliasing enabled, especially when the map�s content uses more than 256 colors. The artifacts can occur because anti-aliasing effectively increases the number of colors in the map.  If the number of colors in the map increases beyond 256 colors (the limit of a png8 image) then dithering may occur, resulting in a �grainy� appearance in areas of solid color.  When anti-aliasing is enabled on the map, use png24 or png32 image formats to obtain higher quality images. 
• MapServices have support for the image type PNG32 which allows the use of an alpha band (in addition to RGB bands) to support pixel level transparency. When using the PNG32 format, transparency set on layers in the map gets carried over to the output image.  This means that the client application does not need to set any client side transparency when draping the service on top of another map service.
• Image formats supported by MapServices are �PNG32, PNG24, PNG, JPG, DIB, TIFF , EMF, PS, PDF, GIF, SVG, SVGZ�

dynamicLayers

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

Exporting image from a cached map service may be useful for getting the image in a different coordinate system other than the mapservice's.

Miscellaneous

Use IMapServerGeoTransformation when the image output from a map service is to be displayed in a coordinate system where the underlying geographic coordinate system is different than the underlying geographic coordinate system of the DefaultMapDescription.

See Also