Export Image

Description

The export image operation is performed on an image service resource. The result of this operation is an image resource. This resource provides information about the exported image, such as its URL, its width and height, and extent.

Apart from the usual response formats of html and json, users can also request a format called image while performing this operation. When users perform an export with the format of image, the server responds by directly streaming the image bytes to the client. With this approach you don't get any information associated with the exported image besides the actual image.

The mosaicProperties and viewpointProperties parameters were deprecated at 10 and not supported from 10.1 onwards. The mosaicRule parameter was added at 10. Users should use this new parameter instead of mosaicProperties and viewpointProperties.

Support for the time and renderingRule parameters was added at 10.

Support for a new jpgpng format was also added at 10. jpgpng is the new default output format for Image Service export operation.

Support for the compression parameter was added at 10.2 (for tiff format only).

Support for the png32 format was added at 10.2.

Users can provide arguments to the export image operation as query parameters. These parameters include the request extent, size information, interpolation, pixel type, and so on. The parameter details are provided in the parameters table below.

Request Parameters

Parameter

Details

f

Description: The response format. The default response format is html. If the format is image, the image bytes are directly streamed to the client.

Values: html | json | image | kmz

bbox

Description: The extent (bounding box) of the exported image. Unless the bboxSR parameter has been specified, the bbox is assumed to be in the spatial reference of the image service.

Syntax: <xmin>, <ymin>, <xmax>, <ymax>

Example: bbox=-104,35.6,-94.32,41

The bboxcoordinates should always use a period as the decimal separator even in countries where traditionally a comma is used.

size

Description: The size (width * height) of the exported image in pixels. If the size is not specified, an image with a default size of 400 * 400 will be exported.

Syntax: <width>, <height>

Example: size=600,550

imageSR

Description: The spatial reference of the exported image.

The spatial reference can be specified as either a well-known ID or as a spatial reference json object.

If the imageSR is not specified, the image will be exported in the spatial reference of the image service.

bboxSR

Description: The spatial reference of the bbox.

The spatial reference can be specified as either a well-known ID or as a spatial reference json object.

If the bboxSR is not specified, the bbox is assumed to be in the spatial reference of the image service.

time

Description: The time instant or the time extent of the exported image.

Time instant

Syntax: time=<timeInstant>

Example: time=1199145600000 (1 Jan 2008 00:00:00 GMT)

Time extent (For time extents one of <startTime> or <endTime> could be 'null').

Syntax: time=<startTime>, <endTime>

Example: time=1199145600000, 1230768000000 (1 Jan 2008 00:00:00 GMT to 1 Jan 2009 00:00:00 GMT

A null value specified for start time or end time will represent infinity for start or end time respectively.

format

Description: The format of the exported image. The default format is jpgpng.

Values: jpgpng | png | png8 | png24 | jpg | bmp | gif | tiff | png32

Note that support for the jpgpng format was added at 10. This format returns a JPG if there are no transparent pixels in the requested extent, otherwise it returns a PNG (png32).

png32 was added at 10.2.

pixelType

Description: The pixel type, also known as data type, pertains to the type of values stored in the raster, such as signed integer, unsigned integer, or floating point. Integers are whole numbers, whereas floating points have decimals.

ExportImage operation involves two major steps: getting the image (band selection, spatial resolution, mosaicking, processing raster functions etc.) and convert to a specific format (e.g. jpg, png, tiff). This pixelType parameter controls the output of the first step. When pixel values exceed the valid value range of the requested pixel type, pixel values are truncated to fit to the pixel type. When the pixel type is not 8 bit but the requested format does not support such pixel type (e.g. jpg or png), image service applies default stretch in the second step so the final result can fit into a 8 bit jpg or png. There is no default stretch applied when the request format is TIFF.

The processing result of the first step has a default pixelType, it could be the same as the source data, or different. For example, an image service that serves floating point elevation data may produce a F32 image when no rendering rule is applied, and a U8 image when a hillshade function is used. In the first case (F32), specify pixelType=U8 may lead to truncation; in the second case (U8 with hillshade), specifying pixelType=F32 may lead to a hillshaded image stored as F32 and cause unnecessary rendering when converting to jpg or png.

Leave pixelType as unspecified, or UNKNOWN, in most exportImage use cases, unless such pixelType is desired.

Values: C128 | C64 | F32 | F64 | S16 | S32 | S8 | U1 | U16 | U2 | U32 | U4 | U8 | UNKNOWN

noData

Description: The pixel value representing no information.

Example 1: noData=0 //a pixel is transparent when the pixel value of any band is 0.

Example 2: noData=58,128,187 //newly added at 10.0 SP2. when a pixel matches the nodata, the pixel will be rendered transparent.

noDataInterpretation

//Added in 10.1.

Description: Interpretation of noData setting.

Default is esriNoDataMatchAny when noData is a number, and esriNoDataMatchAll when noData is a comma delimited string: esriNoDataMatchAny | esriNoDataMatchAll

Example 1: noData=0&noDataInterpretation=esriNoDataMatchAll a pixel is transparent only if the pixel value is 0 for all bands.

Example 2: noData=58,128,187&noDataInterpretation=esriNoDataMatchAll //a pixel is transparent when the pixel value is 58,128,187. Equivalent of noData=58,128,187

Example 3: noData=0&noDataInterpretation=esriNoDataMatchAny a pixel is transparent if any band is 0.

interpolation

Description: The resampling process of extrapolating the pixel values while transforming the raster dataset when it undergoes warping or when it changes coordinate space.

Values: RSP_BilinearInterpolation | RSP_CubicConvolution | RSP_Majority | RSP_NearestNeighbor

compression

//Added in 10.2.

Controls how to compress the image when export to TIFF format: None, JPEG, LZ77. It does not control compression on other formats.

Example: compression=LZ77

compressionQuality

Description: Controls how much loss the image will be subjected to by the compression algorithm. Valid value ranges of compression quality are from 0 to 100.

Example: compressionQuality=75

bandIds

Description: If there are multiple bands, you can specify a single band to export, or you can change the band combination (red, green, blue) by specifying the band number. Band number is 0 based.

Example: bandIds=2,1,0

mosaicRule

Description: Specifies the mosaic rule when defining how individual images should be mosaicked. When a mosaic rule is not specified, the default mosaic rule of the image service will be used (as advertised in the root resource: defaultMosaicMethod, mosaicOperator, sortField, sortValue).

Refer to the mosaic rule json objects for the syntax and examples.

renderingRule

Description: Specifies the rendering rule for how the requested image should be rendered.

Refer to the raster function json objects for the syntax and examples.

Example Usage

Example 1: Export an image with the bounding box [[-141.19530416221985,-62.217823180545146] - [139.27427961579508,84.15317625109763]] in WGS 84 (4326). Response format is image.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/World/MODIS/ImageServer/exportImage?f=image&bbox=-141.19530416221985,-62.217823180545146,139.27427961579508,84.15317625109763&imageSR=4326&bboxSR=4326&size=937,489

Example 2: Export the image similar to Example 1 but request the image in Web Mercator (3857). Response format is json.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/World/MODIS/ImageServer/exportImage?f=json&bbox=-141.19530416221985,-62.217823180545146,139.27427961579508,84.15317625109763&imageSR=3857&bboxSR=4326&size=937,489

Example 3: Export an image by specifying a mosaic rule supported by the image service. (showing world temperature using the 8th raster only: August of 1950)

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/World/Temperature/ImageServer/exportImage?bbox=-180,-55.5,180,83.5&bboxSR=&size=&imageSR=&time=&format=jpgpng&pixelType=U8&noData=&interpolation=RSP_NearestNeighbor&compressionQuality=&bandIds=&mosaicRule={"mosaicMethod" : "esriMosaicLockRaster","lockRasterIds":[8]}&renderingRule=&f=image

Example 4: Export an image by specifying a rendering rule supported by the image service.

http://sampleserver6.arcgisonline.com/arcgis/rest/services/CharlotteLAS/ImageServer/exportImage?bbox=1440000.0,535000.0,1455000.0,550000.0&bboxSR=&size=400,400&imageSR=&format=jpgpng&pixelType=UNKNOWN&noData=&interpolation=RSP_BilinearInterpolation&mosaicRule=&renderingRule={"rasterFunction" : "RFTAspectColor"}&f=image

JSON Response Syntax

{"href" : "<href>","width" : <width>,"height" : <height>,"extent" : {<envelope>}}

JSON Response Example

{
"href" : "http://sampleserver3a.arcgisonline.com/arcgisoutput/_ags_321611040.jpg",
"width" : 937,
"height" : 489,
"extent" : { 
 "xmin" : -26821417.0684016, 
 "ymin" : -8910977.94571736, 
 "xmax" : 26607569.5940922, 
 "ymax" : 18972452.6604293, 
 "spatialReference" : {"wkid" : 3857}},
"scale":0
}