Skip To Content

Export Image

Description

License:

You must license your ArcGIS Server as an ArcGIS Image Server site to use this resource with a mosaic dataset.

The exportImage operation is performed on an image service resource and results in an image resource. This resource provides information about the exported image, such as its URL, extent, width, and height.

In addition to the usual response formats of HTML and JSON, you can also request the image format while performing this operation. When you perform an export with the image format, 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 other than the image itself.

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

10.8.1

Support for the sliceId parameter was added at 10.8.1.

10.5

Support for the lercVersion parameter was added at 10.5.

Request parameters

ParameterDetails
bbox

The extent (bounding box) of the exported image. Unless the bboxSR parameter has been specified, the bbox parameter is assumed to be in the spatial reference of the image service. The bbox coordinates should always use a period as the decimal separator, even in countries where traditionally a comma is used.

Syntax

bbox=<xmin>,<ymin>,<xmax>,<ymax>

Example

bbox=-104,35.6,-94.32,41
size

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

Syntax

size=<width>,<height>

Example

size=600,550
adjustAspectRatio

This parameter indicates whether to adjust the aspect ratio or not. By default, adjustAspectRatio is true, which means that the actual bbox parameter will be adjusted to match the width/height ratio of the size parameter, and the response image has square pixels.

Values: true | false

imageSR

The spatial reference of the exported image. The spatial reference can be specified as either a well-known ID or a spatial reference JSON object. If the imageSR parameter is not specified, the image will be exported in the spatial reference of the image service.

bboxSR

The spatial reference of the bbox parameter. The spatial reference can be specified as either a well-known ID or a spatial reference JSON object. If the bboxSR parameter is not specified, the bbox parameter is assumed to be in the spatial reference of the image service.

time

The time instant or the time extent of the exported image. For time extents, either the startTime or endTime values can be null. A null value specified for start time or end time will represent infinity for start or end time, respectively.

Syntax


//Time instant
time=<timeInstant>

//Time extent
time=<startTime>,<endTime>

Example


//Time instant (1 Jan 2008 00:00:00 GMT)
time=1199145600000

//Time extent (1 Jan 2008 00:00:00 GMT to 1 Jan 2009 00:00:00 GMT)
time=1199145600000, 1230768000000
format

The format of the exported image. The default format is jpgpng. Support for the jpgpng format was added at 10.0. This format returns a JPG file if there are no transparent pixels in the requested extent; otherwise, it returns a PNG file (png32), which was added at 10.2. The bip, bsq, and lerc formats were added at 10.3. The bip and bsq formats are uncompressed data. All three formats are pixel data followed by a nodata mask (1 bit per pixel).

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

lercVersion

The version of the LERC format if the user sets the format as lerc. The default is 1. If a version is specified, the server returns the matching version; otherwise, it returns the highest version available.

Values: 1 | 2

pixelType

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.

The exportImage operation involves two major steps: getting the image (band selection, spatial resolution, mosaicking, processing raster functions, and so on) and converting to a specific format (for example, JPG, PNG, or 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 the pixel type (for example, JPG or PNG), the image service applies a default stretch in the second step so the final result can fit into an 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 can be the same as or different from the source data. For example, an image service that serves floating-point elevation data can produce an F32 image when no rendering rule is applied and a U8 image when a hillshade function is used. In the first case (F32), specifying pixelType=U8 can lead to truncation; in the second case (U8 with hillshade), specifying pixelType as F32 can 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

The pixel value representing no information.

Example


//Pixel is transparent when the pixel value of any band is 0
noData=0

//When a pixel matches a nodata value, the pixel will be rendered transparent
noData=58,128,187
noDataInterpretation

Interpretation of the noData setting. The default is esriNoDataMatchAny when noData is a number, and esriNoDataMatchAll when noData is a comma-delimited string.

Values: esriNoDataMatchAny | esriNoDataMatchAll.

Example


//A pixel is transparent only if the pixel value is 0 for all bands
noData=0&noDataInterpretation=esriNoDataMatchAll

//A pixel is transparent when the pixel value is 58,128,187.
noData=58,128,187&noDataInterpretation=esriNoDataMatchAll

//A pixel is transparent if any band is 0
noData=0&noDataInterpretation=esriNoDataMatchAny
interpolation

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

Controls how to compress the image when exporting to TIFF format: None, JPEG, or LZ77. It does not control compression on other formats. For other output image formats (such as JPEG, PNG, PNG24, PNG32, and GIF), compressions are automatically set by the format.

Example

compression=LZ77
compressionQuality

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. The compression quality works for the JPEG format, JPGPNG (if the result is a JPG), and TIFF with JPEG compression.

Example

compressionQuality=75
compressionTolerance

Controls the tolerance of the lerc compression algorithm. The tolerance defines the maximum possible error of pixel values in the compressed image. It's a double value. The compression tolerance works for the LERC format only.

Example


//Is lossless for 8 and 16 bit images, but has an accuracy of +0.5 for floating point data
compressionTolerance=0.5
bandIds

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

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

Specifies the rendering rule for how the requested image should be rendered. Refer to the raster function JSON objects for the syntax and examples.

sliceId

Added at 10.8.1 and available if the image service uses ArcObjects11 or ArcObjectsRasterRendering as the service provider.

This parameter is for image services of multidimensional datasets only. The image export operation will be processed for the selected dimensional slice. The sliceId parameter of a dimensional slice can be queried from the image service slices resource.

f

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

Example usage

Example one

The following is a sample request URL that demonstrates how to export an image with a bounding box (example below) in WGS 84 (4326) and an image response format:

https://machine.domain.com/webadaptor/rest/services/World/MODIS/ImageServer/exportImage?f=image&bbox=-141.19530416221985,-62.217823180545146,139.27427961579508,84.15317625109763&imageSR=4326&bboxSR=4326&size=937,489

Below is the example values used for the bbox parameter in the request above:

bbox=

bbox=[[-141.19530416221985,-62.217823180545146]-[139.27427961579508,84.15317625109763]]

Example two

The following is a sample request URL that demonstrates how to export an image, similar to Example 1, but instead requests the image in Web Mercator (3857) with a JSON response format:

https://machine.domain.com/webadaptor/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 three

The following is a sample request URL that demonstrates how to export an image by specifying a mosaic rule supported by the image service. The result of this request shows world temperatures during August of 1950 using only the eighth raster.

https://machine.domain.com/webadaptor/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 four

The following is a sample request URL that demonstrates how to export an image by specifying a rendering rule supported by the image service.

https://machine.domain.com/webadaptor/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": "https://machine.domain.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
}