Export Image
- URL:https://<imageservice-url>/exportImage
- Required Capability:Image
- Version Introduced:9.3
Description
License:As of 10.5, 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. The result of this operation is 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.
10.3
Support for the compressionTolerance and adjustAspectRatio parameters was added at 10.3, as well as the bip, bsq, and lerc format values.
10.2
Support for the compression parameter (for the TIFF format only) and the png32 format value was added at 10.2.
10.0
The mosaicProperties and viewpointProperties parameters were deprecated at 10.0 and are no longer supported at version 10.1 or later. The mosaicRule parameter was added at 10.0 and should be used in place of both mosaicProperties and viewpointProperties.
At 10.0, support for the time and renderingRule parameters was added, as well as the jpgpng value format, which is the new default output format for the image service export operation.
Request parameters
|
Parameter |
Details |
|---|---|
| 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 Example |
| 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 Example |
| adjustAspectRatio |
Added at 10.3. 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 Example |
| 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 |
| noDataInterpretation |
Added at 10.1. 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 |
| 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 |
Added at 10.2. 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 |
| 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 |
| compressionTolerance |
Added at 10.3. 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 |
| 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 |
| 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
Below 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.
bbox=
bbox=[[-141.19530416221985,-62.217823180545146]-[139.27427961579508,84.15317625109763]]
Example two
Below 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.
Example three
Below 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.
Example four
Below is a sample request URL that demonstrates how to export an image by specifying a rendering rule supported by the image service.
JSON Response syntax
{
"href": "<href>",
"width": <width>,
"height": <height>,
"extent": {<envelope>}
}
JSON Response example
{
"href": "https://sampleserver3.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
}