Using GET_LAYOUT and LAYOUT with ArcMap Image Services

Introduction
GET_LAYOUT Request and LAYOUT Response
Using ENVELOPE
Using SCALE
Using LAYERLIST and LAYERDEF
Changing the Layout Format and Output Size using OUTPUT, LAYOUT, and GET_LAYOUT autoresize
- BMP, GIF, JPG, PNG8, PNG24, and TIF formats
- AI, EMF, EPS, PDF, and SVG formats
Using OUTPUT to Control Layout Names and Locations
Using Projections with GET_LAYOUT

Introduction

The purpose of GET_LAYOUT and its response LAYOUT is to generate an ArcMap layout and provide the location and filename of the layout.

ArcMap documents contain one or more data frames, which can be viewed as a map or in a layout. Most of the sample requests that follow are based on an ArcMap document consisting of two data frames. The Layers data frame has five layers from the ESRIDATA dataset. The following table summarizes the layer names, shapefile name, and layer ID number.

Layers data frame Layer Name	Shapefile Name	Layer ID
Cities	CITIES	0
Provinces	PROVINCE	1
States	STATES	2
Countries	CNTRY94	3
Ocean	WORLD30	4

The second data frame is used in some examples. This data frame is named States and contains the following layers:

States data frame Layer Name	Shapefile Name	Layer ID
Cities	CITIES	0
Roads	ROADS	1
States	STATES	2

GET_LAYOUT Request and LAYOUT Response

ArcMap layouts can be viewed using GET_LAYOUT. The layout format and size are determined by the ArcMap document and cannot be changed using GET_LAYOUT. However, GET_LAYOUT can request data in a data frame at different envelopes and projections. This request is for display only and can be used to generate a layout in one of several formats. The simplest GET_LAYOUT request requires no child elements. With this request, a layout is generated exactly as established in the ArcMap Image Service.

Simple GET_LAYOUT request

<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

The LAYOUT response is similar to an IMAGE response and includes a default envelope and the name and location of the layout. One significant difference is that the ENVELOPE coordinates are in the page units of a layout and not in map units.

LAYOUT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <LAYOUT>
      <ENVELOPE minx="-3.08333333333333" miny="0" maxx="11.5833333333333" maxy="11" />
      <OUTPUT url="http://mycomputer.domain.com/output/world_MYCOMPUTER2102209.png" file="c:\arcims\output\world_MYCOMPUTER2102209.png" />
    </LAYOUT>
  </RESPONSE>
</ARCXML>

The layout is returned using the formatting defined in the ArcMap document. This format cannot be altered. The layout always contains at least the active data frame. It can also contain multiple data frames and other margin information such as text, north arrows, scale bars, and legends. None of these features can be generated in the GET_LAYOUT request.

GET_LAYOUT has two child elements: PROPERTIES and DATAFRAME. PROPERTIES defines general characteristics of the layout as a whole, such as the extent of the layout in page units, a default projection for all data frames, and the output format of the layout. DATAFRAME provides information on an individual data frame, such as the map extent to show and what projection to use. The following example shows the framework of a GET_LAYOUT request when these child elements are included.

GET_LAYOUT request with PROPERTIES and DATAFRAME

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT>
      <PROPERTIES>
      </PROPERTIES>
      <DATAFRAME id="Layers" >
      </DATAFRAME>
      <DATAFRAME id="States" >
      </DATAFRAME>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

Using ENVELOPE

ENVELOPE can be used in both PROPERTIES and DATAFRAME.

When ENVELOPE is used in PROPERTIES, the envelope coordinates are referencing the layout as a whole in page units. When a user pans or zooms on a layout, what really happens is that the extent of the layout changes, not the extent of any data frames. When ENVELOPE is used in DATAFRAME, the extent of the data in the data frame changes. These units are in map units.

In the following example, ENVELOPE is included in both PROPERTIES and in both DATAFRAMEs. In the PROPERTIES section, the extent is unchanged from the service. However, if a user were to pan or zoom the layout, these envelope coordinates would be the ones to change. In the DATAFRAME section, the map in the Layers data frame has a new extent covering North America. The map in the States data frame has a new extent showing the eastern United States.

Using ENVELOPE in PROPERTIES and DATAFRAME

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT>
      <PROPERTIES>
        <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
      </PROPERTIES>
      <DATAFRAME id="Layers" >
        <ENVELOPE minx="-144" miny="19" maxx="-52" maxy="81" />
      </DATAFRAME>
      <DATAFRAME id="States" >
        <ENVELOPE minx="-94" miny="32" maxx="-73" maxy="46" />
      </DATAFRAME>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

The ENVELOPE in the response is in layout page units.

LAYOUT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <LAYOUT>
      <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11"/>
      <OUTPUT url="http://mycomputer.domain.com/output/world_MYCOMPUTER2102209.png" file="c:\arcims\output\world_MYCOMPUTER2102209.png" />
    </LAYOUT>
  </RESPONSE>
</ARCXML>

The layout is generated with new extents for the Layers and States data frames.

Using SCALE

Inside DATAFRAME, SCALE can be used instead of ENVELOPE. SCALE defines a relative scale and the center point of the map. In the next example, the scale factor for the Layers data frame is set to 1:15000000 and is centered on Berlin, Germany. Note that in the attribute rf, the value is "15000000" and not "1:15000000".

Using SCALE in DATAFRAME

The layout is generated with a new scale for the Layers data frame.

Using LAYERLIST and LAYERDEF

Layers inside a data frame can be turned on and off using LAYERLIST and LAYERDEF as illustrated in the example below. Note that unlike with a GET_IMAGE request, no child elements to LAYERDEF are valid. This includes SPATIALQUERY, SPATIALFILTER, and QUERY.

In the Layers data frame, LAYERLIST includes the order attribute. When order is set to "true", only LAYERDEF layers listed inside LAYERLIST are included. In this example, only the Ocean (id="4") and Countries (id="3") layers are displayed. All other layers in the service are ignored. Although the visible attribute is not required, the layer does not draw unless it is included.

In the States data frame, LAYERLIST has no attributes. All the visible layers from the service are drawn unless they are explicitely turned off using LAYERDEF. In this example, the Roads layer (id="1") is set to "false" and is not displayed.

Using LAYERLIST and LAYERDEF in DATAFRAME

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
<REQUEST>
  <GET_LAYOUT>
    <PROPERTIES>
        <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
      </PROPERTIES>
      <DATAFRAME id="Layers">
        <LAYERLIST order="true">
          <LAYERDEF id="4" visible="true" />
          <LAYERDEF id="3" visible="true" />
        </LAYERLIST>
      </DATAFRAME>
      <DATAFRAME id="States">
        <LAYERLIST>
          <LAYERDEF id="1" visible="false" />
        </LAYERLIST>
      </DATAFRAME>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

The layout includes only the layers specified using LAYERLIST and LAYERDEF.

Changing the Layout Format and Output Size using OUTPUT, LAYOUT, GET_LAYOUT autoresize

A layout can be requested in one of the following formats: ai, bmp, emf, eps, gif, jpg, pdf, png8, png24, svg, or tif. The format is specified using OUTPUT inside PROPERTIES. If OUTPUT is not included, the default output format for the service is used.

BMP, GIF, JPG, PNG8, PNG24, and TIF formats

During a request, IMAGESIZE in PROPERTIES sets the size of layouts in bmp, gif, jpg, png8, png24, and tif formats. If IMAGESIZE is not used, the default layout size is the size defined in the map document. The output size can be controlled using IMAGESIZE width and height. The maximum size of an image can be no greater than the image memory limit set when an ArcMap Image Service is started. For example, an image memory limit of 1 MB allows a layout image no larger than 262,144 pixels (512 x 512) to be generated. By default, a layout image is limited in size to 4 MB, which corresponds to 1,048,576 pixels. Changes can be made to the image size and pixel count using the ArcIMS Administrator. For more information, see ArcIMS Help.

A requested layout greater than the maximum pixel count can be reduced in size to within the maximum pixel count by using GET_LAYOUT autoresize. If autoresize is set to "true", a requested layout is reduced in size to always be within the maximum pixel count. If autoresize is not included, and the requested image is too big, an ERROR message is returned.

In the next example, a layout is requested in PNG8 format: OUTPUT type="PNG8". The requested layout size is 1600 x 1200 pixels: IMAGESIZE width="1600" height="1200". In order to trap for image requests that are too large, GET_LAYOUT autoresize is set to "true".

GET_LAYOUT request with OUTPUT, IMAGESIZE, and autoresize="true"

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT autoresize="true">
      <PROPERTIES>
        <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
        <IMAGESIZE width="1600" height="1200" />
        <OUTPUT type="PNG8" />
      </PROPERTIES>
      <DATAFRAME id="Layers" >
        <ENVELOPE minx="-144" miny="19" maxx="-52" maxy="81" />
      </DATAFRAME>
      <DATAFRAME id="States" >
        <ENVELOPE minx="-94" miny="32" maxx="-73" maxy="46" />
      </DATAFRAME>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

The LAYOUT response includes a resized image, since the requested image size was greater than allowed. In OUTPUT, the attributes height and width show the new image size. The generated layout is in PNG format.

LAYOUT response with resized output image information

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <LAYOUT>
      <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
      <OUTPUT url="http://mycomputer.domain.com/output/world_MYCOMPUTER3633699.png width="1182" height="886" file="c:\arcims\output\world_MYCOMPUTER3633699.png" />
    </LAYOUT>
  </RESPONSE>
</ARCXML>

AI, EMF, EPS, PDF, and SVG formats

Ai, emf, eps, pdf, and svg formats do not have the same image size restrictions. When these formats are requested, the output size matches the actual layout size in page units. Therefore, a layout in an ArcMap document set as "C" size is generated as "C" size during the GET_LAYOUT request. However, if IMAGESIZE is used in a request, the height and width are still used to calculate the image memory limit. To get around this problem, remove IMAGESIZE from the request or set GET_LAYOUT autoresize to "true".

Using OUTPUT to Control Layout Names and Locations

OUTPUT, in addition to setting the output format, provides a way to define the location and filename of the output layout. By default, the output directory and URL location are determined at the time the service is started. When a request is made, the ArcIMS Spatial Server assigns a filename. The name includes the service name, the computer name the layout was generated on, and a randomly generated number. If the service is named "world" and the computer is "MYCOMPUTER", then an example filename is world_MYCOMPUTER1248849.png.

OUTPUT works with paired attributes for defining a file output location and/or filename. If one of the attributes is used, its pair is required. Determining which pair to use depends on whether the ArcIMS Spatial Server defines the output filename or you do. In all cases, you specify the output directory and URL.

Attribute	Paired Attribute	Filename assignment	Example: http://mycomputer/arcims/...
path	baseurl	ArcIMS assigns random filename.	world_MYCOMPUTER1248849.png
name	url	You assign a filename.	myfilename.png

When starting a service or including OUTPUT in the request, UNC pathnames are valid. For example, instead of using "c:\arcims\output", "\\myComputer\arcims\output" can be used.

ArcIMS Spatial Server assigns filename

In the following example, the ArcIMS Spatial Server assigns a filename, but the user assigns the directory and URL. The attribute pair in this scenario is path-baseurl.

OUTPUT when ArcIMS Spatial Server defines filename

<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT>
      <PROPERTIES>
        <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
        <OUTPUT type="pdf" path="c:\arcims\layout_output" baseurl="http://mycomputer.domain.com/layout_output" />
      </PROPERTIES>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

LAYOUT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <LAYOUT>
      <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
      <OUTPUT url="http://mycomputer.domain.com/layout_output/world_MYCOMPUTER2983738.pdf" file="c:\arcims\layout_output\world_MYCOMPUTER2983738.pdf" />
    </LAYOUT>
  </RESPONSE>
</ARCXML>

User assigns filename

In the next example, the user assigns a filename, directory, and URL. The attribute pair in this scenario is name-url.

OUTPUT when user defines filename

<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT>
      <PROPERTIES>
        <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
        <OUTPUT type="pdf" name="c:\arcims\layout_output\layoutimage.pdf" url="http://mycomputer.domain.com/layout_output/layoutimage.pdf" />
      </PROPERTIES>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

LAYOUT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <LAYOUT>
      <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
      <OUTPUT url="http://mycomputer.domain.com/layout_output/layoutimage.pdf" file="c:\arcims\layout_output\layoutimage.pdf" />
    </LAYOUT>
  </RESPONSE>
</ARCXML>

Restricting OUTPUT

When using an ArcIMS HTML Viewer, ArcIMS Java Viewer, ArcExplorer-Java Edition, or any other client using the ArcIMS Servlet Connector, the OUTPUT element is restricted by default.

In a GET_LAYOUT request, all OUTPUT attributes are ignored with the exception of type.

The filename restrictions can be lifted by setting the properties spatialServer.AllowRequestOutput to true in Esrimap_prop. This property file is found in the same directory as the ArcIMS Servlet Connector. For more information on the location of Esrimap_prop and its properties, see ArcIMS Help.

The output file types permitted for use with GET_LAYOUT can be restricted in Esrimap_prop using the property spatialServer.ForbiddenLayoutTypes. When a request is made that includes a forbidden type, the layout is returned in the format of the service when it was started. Any of the layout format output types can be included in the list.
In an LAYOUT response, the attribute file is not returned. The OUTPUT location is the default location specified when the ArcIMS Image Service was started. The ArcIMS Spatial Server assigns the filename. OUTPUT includes only url.

This restriction on the output file location can be lifted by setting the property spatialServer.AllowResponsePath to true in Esrimap_prop.

These restrictions apply only when the ArcIMS Servlet Connector is used. They do not apply to the ActiveX, ColdFusion, or Java Connectors, or to the .NET Link. The OUTPUT filename extensions are limited to *.ai, *.bmp, *.emf, *.eps, gif, *.jpg, *.pdf, *.png, *.svg, and *.tif regardless of whether OUTPUT is restricted or not.

Using Projections with GET_LAYOUT

The projection of data in data frames can be changed using the projection elements:

For a complete discussion on the different elements, refer to Using Projection Elements.

FILTERCOORDSYS is used to specify the coordinate system of the requesting client or the coordinates in ENVELOPE in a DATAFRAME. FEATURECOORDSYS is used to specify to which coordinate system the data in the data frames should be transformed. All the examples so far for have been in geographic coordinates (decimal degrees), which have an ID of "4326".

FILTERCOORDSYS and FEATURECOORDSYS can be used inside PROPERTIES and DATAFRAME. When used inside PROPERTIES, all data frames are transformed to the same projection. In the next example, all data frames in the layout are requested in Robinson, which has an ID of "54030". FILTERCOORDSYS and FEATURECOORDSYS are included only in the PROPERTIES section.

Using FILTERCOORDSYS and FEATURECOORDSYS inside PROPERTIES

In the response, the ENVELOPE coordinates are still in layout page units.

LAYOUT response

<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <LAYOUT>
      <ENVELOPE minx="0" miny="-0.45" maxx="8.5" maxy="11.45" />
      <OUTPUT url="http://mycomputer.domain.com/output/world_MYCOMPUTER2102209.jpg" file="c:\arcims\output\world_MYCOMPUTER2102209.jpg" />
    </LAYOUT>
  </RESPONSE>
</ARCXML>

The returned map image shows both the Layers and States data frames in the Robinson coordinate system.

Using the Robinson coordinate system with the "States" data frame does not produce the best results. In order to set the projection for individual data frames, FILTERCOORDSYS and FEATURECOORDSYS can be used inside DATAFRAME in addition to PROPERTIES. When used in a DATAFRAME, projection information in the PROPERTIES section is ignored for that data frame.

In the next example, FILTERCOORDSYS and FEATURECOORDSYS are used in the "States" data frame and are set to North America Albers Equal Area Conic (102008). To summarize this request, FILTERCOORDSYS and FEATURECOORDSYS in the PROPERTIES section are set to Robinson (54030). All data frames use this projection information unless FILTERCOORDSYS and FEATURECOORDSYS are also used in DATAFRAME. The "Layers" data frame has no projection information, and the data is transformed to Robinson. The "States" data frame does have projection information, and the data is transformed to North America Albers rather than to Robinson.

ENVELOPE should also be included in DATAFRAME when using projection elements. The ENVELOPE coordinates should be in the same projection as FILTERCOORDSYS. If ENVELOPE is not included, the coordinates are assumed to be in the projection of the service.

Using FILTERCOORDSYS and FEATURECOORDSYS inside PROPERTIES and DATAFRAME

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_LAYOUT>
      <PROPERTIES>
        <ENVELOPE minx="0" miny="0" maxx="8.5" maxy="11" />
        <FEATURECOORDSYS id="54030" />
        <FILTERCOORDSYS id="54030" />
      </PROPERTIES>
      <DATAFRAME id="Layers" >
      </DATAFRAME>
      <DATAFRAME id="States" >
        <ENVELOPE minx="-8260377.77928749" miny="-3192427.8093698" maxx="3697151.36816421" maxy="5775719.05121898" />
        <FEATURECOORDSYS id="102008" />
        <FILTERCOORDSYS id="102008" />
      </DATAFRAME>
    </GET_LAYOUT>
  </REQUEST>
</ARCXML>

The returned image shows the "Layers" data frame in Robinson and the "States" data frame in North America Albers.