IMapServerLayout.ExportLayout Method

Generates an image of the layout, based on the given page description object, 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 ExportLayout ( _
    ByVal pageDesc As IPageDescription, _
    ByVal imageDesc As IImageDescription _
) As ILayoutImage

[C#]
public ILayoutImage ExportLayout (
    IPageDescription pageDesc,
    IImageDescription imageDesc
);

[C++]
HRESULT ExportLayout(
  IPageDescription* pageDesc,
  IImageDescription* imageDesc,
  ILayoutImage** LayoutImage
);

[C++]

Parameters
pageDesc [in]

  pageDesc is a parameter of type IPageDescription
imageDesc [in]

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

  LayoutImage is a parameter of type ILayoutImage

Product Availability

Remarks

Use ExportLayout to retrieve a file (image or vector format) of the map's layout.

PageDescription refers to properties describing the actual map layout. These include the Height and Width of the layout in page Units , the layout page extent in page units, map descriptions for each map frame in the layout and any CustomGraphics to be placed in the layout. Size, resolution and file format are determined by the ImageDescription, which includes ImageDisplay and ImageType .

ExportLayout returns a LayoutImage object. The page Extent of the layout, an array of MapImages (data frames), can be gleaned from this object. In addition, the geographic MapExtent, MapScale and an array of VisibleLayers for each data frame in the layout can be retrieved from the MapImage object.

Do not use IMapServerLayout to create new layouts or to create layouts "on-the-fly". You cannot change the actual page size of the map layout, reposition map elements on the layout nor can you add or remove layout elements such as titles, text, graphics, scale bars, north arrows and legends. However, you can define the size and resolution of the output. How these parameters are defnied can affect the results. These effects are outlined below. You can also choose to export a clipped portion of the page layout.

Let's look at an example. An existing map layout has a portrait page orientation with a height of 11 inches and a width of 8.5 inches. The absolute scale for the map is 1:30,000,000. There are some layers within the map that are scale dependent. This scale is based on the page size of the layout and the relative size of the map's data frame.

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

Exporting to vector format (e.g. PDF)

If you are exporting to a vector format, such as PDF, and want to retain the original size of the layout as specified in the map document the dimensions need not be set. Not specifying a Height and Width for IImageDisplay2, or specifying 0 for both, will cause the export result to maintain the original size of the layout as specified in the source map document. The Height and Width properties of IImageResult are read-only and are not used to make changes.

The the best results it is recommended that you do not specify Height or Width in the ImageDisplay. Let the page size set in the source map determine the size of our output. 

If you have a raster layer in your map, or the map has transparency, you may want to increase the DeviceResolution set in IImageDisplay for better results. The map scale and layer visibility should not be affected. The size of ExportLayout result should be adjusted using the height and width properties of the ImageDisplay. You can increase or decrease the relative size of the map layout. Remember, you are not changing the size of the layout of the source map. You are changing the size of the exported result.

For example, you wish to reduce the image of the 11 inch by 8.5 inch layout described above by half. The DeviceResolution is set at 96. You will need to specify a height of 528 and a width of 408. Please note that the map scale does not change. The absolute scale of the map will be incorrect, though the scale bar should be correct since its size changes relative to the change in output size. This effect is similar to shrinking a printed map using a photocopying machine. The result will be 5.5 inches by 4.25 inches PDF.

Once you specify the height and width the value of the DeviceResolution will have an impact on the result. Think of 96 as a baseline for the layout's page (1 inch=96 pixels). Values different from 96 will require appropriate adjustments in height and width. Using the example above, if the DeviceResolution was 300, the height and width needed to reduce the resulting layout to a PDF of 5.5 inches by 4.25 inches would be 1650 pixels by 1275 pixels.

Changing the aspect ratio (height x width) of the ExportLayout output will not change the aspect ratio of the map layout. For example, again using the layout example above, a height of 816 and a width of 1056 pixels are specified. This will not change the orientation of the page layout from portrait to landscape. Instead, the original portrait orientation of the layout will be maintained and will be fitted into the 816 x 1056 space. This will result in white space on either side of the layout.

Exporting to image format (e.g. JPG)

You can change the size of results using the height and width properties of IImageDisplay. For example, you wish to reduce the image of the 11 by 8.5 layout described above by half.  You specify a height of 528 and a width of 408 for the image result. Please note that the map scale does not change. Remember, it is the output size of the image result that is being adjusted. Therefore, the absolute scale of the map will be incorrect, though the scale bar should be correct since its size changes relative to the change in output size. This effect is similar to shrinking or enlarging a printed map using a photocopying machine. When specifying a height and width for a raster format, the value set for DeviceResolution will have no affect on the result.

If you do not specify height or width (or use 0) the size of the image file will be a function of the DeviceResolution and the size of the layout page (where 1 inch=96 pixels). For example, you specify a DeviceResolution of 96 for the above layout the result will be an image of 1056 pixels by 816 pixels. Increasing the DeviceResolution will increase the size of the output. For example, setting the DeviceResolution to 300 will result in an image of 3300 pixels by 2550 pixels.

Changing the aspect ratio (height x width) of the ExportLayout output will not change the aspect ratio of the map layout. For example, again using the layout example above, a height of 816 and a width of 1056 pixels are specified. This will not change the orientation of the page layout from portrait to landscape. Instead, the original portrait orientation of the layout will be maintained and will be fitted into the 816 x 1056 space. This will result in white space on either side of the layout.

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.

Miscellaneous

If you wish to export a portion of the page layout use Extent on IPageDescription. The extent is in the page units of the map document.

Page space is an important component of ExportLayout. It exists for all map documents and the map services the documents are based on. This page space provides the default size of the exported layout (for best results you should use this default). Page space does not figure in ExportMapImage. Therefore, you will see differences in results when adjusting the Height, Width or DeviceResolution for a ExportLayout as compared to making similar adjustments for ExportMapImage.

Another important thing to consider when authoring a layout to be used with  IMapServerLayout is to uncheck the "Use Printer Paper Settings" checkbox on the Page and Print Setup dialog in ArcMap before saving the map. Otherwise, the page setup may be dependent on a printer unavailable to the server or users. This may result in a rescaling of the map and unexpected results.

See Also