Export Image
- URL:http://<imageservice-url>/exportImage
- Required Capability:Image
- Version Introduced:9.3
Description
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.
The mosaicProperties and viewpointProperties parameters were deprecated at 10.0 and are no longer supported at 10.1 and later. The mosaicRule parameter was added at 10.0. Use this new parameter instead of mosaicProperties and viewpointProperties.
Support for the time and renderingRule parameters was added at 10.0.
Support for the jpgpng format was also added at 10.0. jpgpng, is the new default output format for the 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.
Support for the bip, bsq, lerc formats was added at 10.3.
Support for the compressionTolerance, adjustAspectRatio parameters was added at 10.3.
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 following parameters table:
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 bbox coordinates 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 size is not specified, an image with a default size of 400 * 400 will be exported. Syntax: <width>, <height> Example: size=600,550 |
|
adjustAspectRatio |
Added at 10.3. Description: This parameter indicates whether to adjust the aspect ratio or not. By default adjustAspectRatio is true, that means the actual bbox will be adjusted to match the width/height ratio of size paramter, and the response image has square pixels. Values: true | false |
| 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:
Time extent (For time extents one of <startTime> or <endTime> could be 'null'):
|
| format |
Description: The format of the exported image. The default format is jpgpng. Values: jpgpng | png | png8 | png24 | jpg | bmp | gif | tiff | png32 | bip | bsq | lerc Support for the jpgpng format was added at 10.0. 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. bip, bsq, and lerc were added at 10.3. bip and bsq are uncompressed data using bip and bsq respectively. All three formats are pixel data followed by nodata mask (1 bit per pixel). |
| 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. 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 such 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 could be the same as the source data, or different. For example, an image service that serves floating point elevation data may 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 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—Added at 10.0 SP2. When a pixel matches a nodata value, the pixel will be rendered transparent. |
| noDataInterpretation |
Added at 10.1. Description: Interpretation of the noData setting. The 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 at 10.2. Controls how to compress the image when exporting to TIFF format: None, JPEG, LZ77. It does not control compression on other formats. Example: compression=LZ77 For other output image formats (such as JPEG, PNG, PNG24, PNG32, and GIF), compressions are automatically set by the format. |
| 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 The compression quality works for the JPEG format, JPGPNG (if the result is a JPG), and TIFF with JPEG compression. |
| compressionTolerance |
Added at 10.3. Description: 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. Example: compressionTolerance=0.5 is loselss for 8 and 16 bit images, but has an accuracy of +-0.5 for floating point data. The compression tolerance works for the LERC format only. |
| 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.
Example 2: Export the image similar to Example 1 but request the image in Web Mercator (3857). Response format is JSON.
Example 3: Export an image by specifying a mosaic rule supported by the image service. (Shows world temperature using the 8th raster only: August of 1950.)
Example 4: 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" : "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
}