Raster Functions

Overview

The image service's export image operation supports a renderingRule parameter. This parameter has the following JSON syntax:

{
  "rasterFunction" : "<rasterFunctionName>",
  "rasterFunctionArguments" : {<rasterFunctionArguments>},
  "variableName" : "<variableName>"
}

Image service has a few well-known raster functions that does not need to be pre-configured with service. The structure of the rasterFunctionArguments object varies based on the rasterFunction name.

Image service REST supports Aspect, Colormap, Hillshade, NDVI, ShadedRelief, Slope, Statistics, Stretch functions in 10.0.

New at 10.1, Image service REST supports Convolution, Remap, BandArithmetic, Clip, Geometric functions.

New at 10.1, client can invoke a raster function template that is pre-configured on server-side along with the service. A raster function template defines a processing chain that is composed of one or more raster functions, including customized raster functions that're extended based on ArcObjects. Information of these raster function templates are available through RasterFunctionInfos property on image service root resource page. Client may omit rasterFunctionArguments to take default configuration in raster function template, or overwrite them by specifying argument parameters (argument names and value types are defined by the author of each raster function template and are not discoverable through REST).

ArcGIS supports a lot of raster functions. Not all raster functions in ArcGIS are directly exposed as well-known functions, but they can be used in raster function templates and invoked from REST. For a comprehensive list of raster functions supported by raster function templates, refer to ArcGIS Resource Center.

This document lists these well-known raster functions supported by the REST API, as well as an example of using raster function template defined by a service.

"rasterFunction" : "Aspect"

The Aspect raster function takes no arguments. Hence, specifying only the rasterFunction property suffices in this case.

{
  "rasterFunction" : "Aspect"
}

"rasterFunction" : "Colormap"

The arguments for the Colormap function are as shown below:

{
  "rasterFunction" : "Colormap",
  "rasterFunctionArguments" : {
    "ColormapName" : "<Random | NDVI | Elevation | Gray>",
    "Colormap" : [
      [<value1>, <red1>, <green1>, <blue1>], //[int, int, int, int]
      [<value2>, <red2>, <green2>, <blue2>]
    ]
  },
  "variableName" : "Raster"
}

Example 1:

{
  "rasterFunction" : "Colormap",
  "rasterFunctionArguments" : {
    "ColormapName" : "Random"
  },
  "variableName" : "Raster"
}

Example 2:

{
  "rasterFunction" : "Colormap",
  "rasterFunctionArguments" : {
    "Colormap" : [
      [0, 1, 2, 3],
      [2, 45, 52, 13]
    ]
  },
  "variableName" : "Raster"
}

"rasterFunction" : "Hillshade"

The arguments for the Hillshade function are as shown below:

{
  "rasterFunction" : "Hillshade",
  "rasterFunctionArguments" : {
    "Azimuth" : <Azimuth>, //double (e.g. 215.0)
    "Altitude" : <Altitude>, //double (e.g. 75.0)
    "ZFactor" : <ZFactor> //double (e.g. 0.3)
  },
  "variableName" : "DEM"
}

Example:

{
  "rasterFunction" : "Hillshade",
  "rasterFunctionArguments" : {
    "Azimuth" : 215.0,
    "Altitude" : 75.0,
    "ZFactor" : 0.3
  },
  "variableName" : "DEM"
}

"rasterFunction" : "NDVI"

The arguments for the NDVI function are as shown below:

{
  "rasterFunction" : "NDVI",
  "rasterFunctionArguments" : {
    "VisibleBandID" : <VisibleBandID>, //int (zero-based band id, e.g. 2)
    "InfraredBandID" : <InfraredBandID> //int (zero-based band id, e.g. 1)
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "NDVI",
  "rasterFunctionArguments" : {
    "VisibleBandID" : 2,
    "InfraredBandID" : 1
  },
  "variableName" : "Raster"
}

"rasterFunction" : "ShadedRelief"

The arguments for the ShadedRelief function are as shown below:

{
  "rasterFunction" : "ShadedRelief",
  "rasterFunctionArguments" : {
    "Azimuth" : <Azimuth>, //double (e.g. 215.0)
    "Altitude" : <Altitude>, //double (e.g. 75.0)
    "ZFactor" : <ZFactor>, //double (e.g. 0.3)
    "Colormap" : [
      [<value1>, <red1>, <green1>, <blue1>], //[int, int, int, int]
      [<value2>, <red2>, <green2>, <blue2>]
    ]
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "ShadedRelief",
  "rasterFunctionArguments" : {
    "Azimuth" : 215.0,
    "Altitude" : 75.0,
    "ZFactor" : 0.3,
    "Colormap" : [
      [0, 1, 2, 3],
      [2, 45, 52, 13]
    ]
  },
  "variableName" : "Raster"
}

"rasterFunction" : "Slope"

The arguments for the Slope function are as shown below:

{
  "rasterFunction" : "Slope",
  "rasterFunctionArguments" : {
    "ZFactor" : <ZFactor> //double (e.g. 0.3)
  },
  "variableName" : "DEM"
}

Example:

{
  "rasterFunction" : "Slope",
  "rasterFunctionArguments" : {
    "ZFactor" : 0.3
  },
  "variableName" : "DEM"
}

"rasterFunction" : "Statistics"

The arguments for the Statistics function are as shown below:

{
  "rasterFunction" : "Statistics",
  "rasterFunctionArguments" : {
    "Type" : "<Min | Max | Mean | StandardDeviation>",
    "KernelColumns" : <KernelColumns>, //int (e.g. 3)
    "KernelRows" : <KernelRows> //int (e.g. 3)
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "Statistics",
  "rasterFunctionArguments" : {
    "Type" : "Mean",
    "KernelColumns" : 3,
    "KernelRows" : 3
  },
  "variableName" : "Raster"
}

"rasterFunction" : "Stretch"

The arguments for the Stretch function are as shown below:

{
  "rasterFunction" : "Stretch",
  "rasterFunctionArguments" : {
    "StretchType" : <StretchType>, //int (0 = None, 3 = StandardDeviation, 4 = Histogram Equalization, 5 = MinMax, 6 = PercentClip)
    "NumberOfStandardDeviations" : <NumberOfStandardDeviations>, //int (e.g. 2)
    "Statistics" : [
      [<min1>, <max1>, <mean1>, <standardDeviation1>], //[double, double, double, double]
      [<min2>, <max2>, <mean2>, <standardDeviation2>]
    ],
    "DRA": <true|false>,//boolean. dervie statistics from current request, Statistics parameter is ignored when DRA is true
    "UseGamma": <true|false>,
    "MinPercent":<minPercent>, //double (e.g. 0.25), applicable to PercentClip
    "MaxPercent":<maxPercent>, //double (e.g. 0.5), applicable to PercentClip
    "UseGamma":<true|false>,
    "Gamma" : [<gamma1>, <gamma2>] //array of doubles
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "Stretch",
  "rasterFunctionArguments" : {
    "StretchType" : 3,
    "NumberOfStandardDeviations" : 2,
    "Statistics" : [
      [0.2, 222.46, 99.35, 1.64],
      [5.56, 100.345, 45.4, 3.96],
      [0, 352.37, 172.284, 2]
    ],
    "UseGamma":true,
    "Gamma" : [1.25, 2, 3.95]
  },
  "variableName" : "Raster"
}

"rasterFunction" : "Convolution"

//Added in 10.1

The arguments for the Convolution function are as shown below:

{
  "rasterFunction" : "Convolution",
  "rasterFunctionArguments" : {
    "Columns" : <Columns>,
    "Rows" : <Rows>,
    "Kernel" : [<k11>, <k12>, ... <k1n>, <k21>, <k22>, <k2n>,... <km1>, <km2>, <kmn>]//an array that has m x n elements
    "Type" : <Type>,//int (-1 = UserDefined, 0 = LineDetectionHorizontal, 1 = LineDetectionVertical, 2 = LineDetectionLeftDiagonal, 
	3 = LineDetectionRightDiagonal, 4 = GradientNorth, 5 = GradientWest, 6 = GradientEast, 7 = GradientSouth, 8 = GradientNorthEast,
	9 = GradientNorthWest, 10 = SmoothArithmeticMean, 11 = Smoothing3x3, 12 = Smoothing5x5, 13 = Sharpening3x3, 14 = Sharpening5x5,
	15 = Laplacian3x3, 16 = Laplacian5x5, 17 = SobelHorizontal, 18 = SobelVertical, 19 = Sharpen, 20 = Sharpen2, 21 = PointSpread)    
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "Convolution",
  "rasterFunctionArguments" : {
    "Type" : 11
  },
  "variableName" : "Raster"
}

"rasterFunction" : "Remap"

//Added in 10.1

The arguments for the Remap function are as shown below:

{
  "rasterFunction" : "Remap",
  "rasterFunctionArguments" : {
    "InputRanges" : [<value1>, <value2>, <value3>],//[double, double, double]
    "OutputValues" : [<value1>, <value2>, <value3>],//[double, double, double]
    "NoDataRanges" : [<value1>, <value2>, <value3>],//[double, double, double]
    "AllowUnmatched" : <true|false>//boolean 
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "Remap",
  "rasterFunctionArguments" : {
    "InputRanges" : [0,100,101,200],
    "OutputValues" : [5,125],
  },
  "variableName" : "Raster"
}

"rasterFunction" : "BandArithmetic"

//Added in 10.1

The arguments for the BandArithmetic function are as shown below:

{
  "rasterFunction" : "BandArithmetic",
  "rasterFunctionArguments" : {
    "Method" : <Method>,//int (0 = UserDefined, 1 = NDVI, 2 = SAVI, 3 = TSAVI, 4 = MSAVI, 5 = GEMI, 6 = PVI, 7 = GVITM, 8 = Sultan)
    "BandIndexes" : "<BandIndexes>"//string e.g. (B3 - B1 / B3 + B1)
  },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "BandArithmetic",
  "rasterFunctionArguments" : {
    "Method" : 0,
    "BandIndexes" : "(B3 - B1 / B3 + B1)"
  },
  "variableName" : "Raster"
}

"rasterFunction" : "Clip"

//Added in 10.1

The arguments for the Clip function are as shown below:

{
  "rasterFunction" : "Clip",
  "rasterFunctionArguments" : {
    "ClippingGeometry" : <geometry>,//a polygon or envelope
    "ClippingType" : <clippingType>//int (1= clippingOutside, 2=clippingInside), use 1 to keep image inside of the geometry
  },
  "variableName" : "Raster"
}

Example:


{
  "rasterFunction" : "Clip",
  "rasterFunctionArguments" : {
    "ClippingGeometry" : {
      "rings" : [[[10,10], [9,11], [10,12], [11,11], [12,10],[10,10]]], "spatialReference" : {"wkid" : 4326} }, 
            "extent" : { "xmin" :10, "ymin" : 10, "xmax" : 12, "ymax" : 12, "spatialReference" : {"wkid" : 4326} },
    "ClippingType": 1
    },
  "variableName" : "Raster"
}

"rasterFunction" : "Geometric"

//Added in 10.1

The arguments for the Geometric function are as shown below:

{
  "rasterFunction" : "Geometric",
  "rasterFunctionArguments" : {
    "GeodataTransforms" : <GeodataTransform>,//Please refer to the Geodata Transformations documentation for more details.
    "AppendGeodataXform" : <true|false>,//boolean
    "ZFactor" : <ZFactor>,//double
    "ZOffset" : <ZOffset>,//double
    "ConstantZ" : <ConstantZ>,//double
    "CorrectGeoid" : <true|false>//boolean
    },
  "variableName" : "Raster"
}

Example:

{
  "rasterFunction" : "Geometric",
  "rasterFunctionArguments" : {
    "GeodataTransforms" : [
        {
          geodataTransform" : "Polynomial",
          "geodataTransformArguments" : {
            "sourcePoints" : [ {"x":0.0, "y":0.0}, {"x":0.0, "y":200.0}, {"x":200.0, "y":0} ],
            "targetPoints" : [ {"x":100.0, "y":100.0}, {"x":100.0, "y":300.0}, {"x":300.0, "y":100.0} ],
            "polynomialOrder" : 1,
            "spatialReference": {"wkid" : 54004}
          }
        }
    ],
    "AppendGeodataXform" : true
  },
  "variableName" : "Raster"
}

Using a raster function template defined by the service

//Added in 10.1

The name of the raster function template is advertised in image service root resource. Function arguments are optional; argument names and default values are created by the author of the raster function template and are not known through REST. Client may simply provide the name of the raster function template only (to "RasterFunction" property), or optionally provide arguments to overwrite default values.

{
  "rasterFunction" : "rasterFunctionTemplateName",
}

{
  "rasterFunction" : "rasterFunctionTemplateName",
  "rasterFunctionArguments" : {
  "ArgumentName1":, //overwrite default value of ArgumentName1, type and default value are defined by the author of the template
  "ArgumentName2":, //overwrite default value of ArgumentName2, type and default value are defined by the author of the template
  ...
  },
  "variableName":"" //variableName can be other than "Raster", as defined by the author of the template
}

Example:

The following service that has raster function templates defined:

http://sampleserver6.arcgisonline.com/arcgis/rest/services/CharlotteLAS/ImageServer?f=pjson

The root resource will advertise supported raster function templates:

 "rasterFunctionInfos": [
  {
   "name": "None",
   "description": "A No-Op Function.",
   "help": ""
  },
  {
   "name": "RFTAspectColor",
   "description": "A raster function template.",
   "help": "This raster function template contains the following processing: aspect, remap, colormap and colormap to RGB functions. The remap fuction remaps divide 0 
      to 90 evenly to 8 directions, (N,NE,E,SE,S,SW,W,NW). The colormap function used the following colormap for the 8 categories:  
     [[0 176 176 176], [1 255 0 0],[2 255 166 0],[3 255 255 0],[4 0 255 0],[5 0 255 255],[6 0 166 255],[7 0 0 255],[8 255 0 255]]. 
     To overwrite the default setting, use InputRanges (double array), NoDataRanges (double array), 
     and OutputValues (int array) for remapping, and use Colormap to change colors."
  },
  {
   "name": "RFTShadedReliefElevationColorRamp",
   "description": "A raster function template.",
   "help": "This raster function template uses a shaded relief function. The default values of ZFactor is 1, Altitude is 45, and Azimuth is 315. An elevation colorramp is used."
  }
 ]

Client can use this function with default function arguments:

{
  "rasterFunction" : "RFTShadedReliefElevationColorRamp"
}

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" : "RFTShadedReliefElevationColorRamp"}&f=image

Client can also provide optional parameter values:

{
"rasterFunction" : "RFTShadedReliefElevationColorRamp",
"rasterFunctionArguments":{"ZFactor":10}},
"variableName" : "Raster"
}

Turn off default raster function template:

The first raster function template in rasterFunctionInfos in image service root resource is applied to exportImage request by default, when renderingRule is not specified in request. To turn it off, specify the following rendering rule.

{
  "rasterFunction" : "None",
}

The following service has a stretch function template applied by default (TorontoStretch):

http://sampleserver6.arcgisonline.com/arcgis/rest/services/Toronto/ImageServer/exportImage?bbox=-8844874.0651,5401062.402699997,-8828990.0651,5420947.402699997&bboxSR=&size=400,400&imageSR=&format=jpgpng&mosaicRule=&f=image

It can be turned off by specifying None as the raster function.

When a single-band image service has raster attribute table and Red,Gree,Blue colors are available in the attribute table, exportImage will automatically use it to render image service by default, for example (NLCDLandCover2001):

http://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover2001/ImageServer/exportImage?bbox=-2364615.0,256035.0,2266845.0,3180435.0&bboxSR=&size=&imageSR=&time=&format=jpgpng&pixelType=UNKNOWN&noData=&interpolation= RSP_BilinearInterpolation&compressionQuality=&bandIds=&mosaicRule=&renderingRule=&f=image

It can be turned off the same way:

If the first raster function template is "None", it means by default no raster function template is used. The image serivce may use a default render if needed (e.g. the above NLCDLandCover2001 example).