Function raster datasets and raster functions (ArcObjects .NET 10.5 SDK)

Summary

Raster functions and function raster datasets are new at ArcGIS 10. This topic introduces raster functions and function raster datasets, describes the raster functions that are available, and provides guidelines for writing a custom raster function.

In this topic

About raster functions and function raster datasets
Raster function template
Custom raster functions

About raster functions and function raster datasets

A raster function is an operation (function) to be performed on one or more rasters. In most cases, a raster function requires a raster as an input.

In addition to an input raster, a raster function can take in parameters that control the operation to be performed on the raster (for example, the stretch method to use when applying the Stretch function). These parameters are encapsulated in an arguments object, which is a representation of the parameters of a raster function.

A raster function and its arguments are stored as a function raster dataset. The function raster dataset is a raster dataset that represents the result of applying the raster function to its arguments. It is stored on disk as a binary file with a .afr extension. It can be used in the same manner as a raster dataset, which means it can be used as an input to another raster function.

ArcGIS 10.2 includes built-in raster functions. The following table lists the raster functions and their corresponding arguments objects that are part of ArcGIS 10.2:

Raster function	Raster function argument
ArithmeticFunction	ArithmeticFunctionArguments
AspectFunction
BandArithmetricFunction	BandArithmetricFunctionArguments
CachedRasterFunction	CachedRasterFunctionArguments
ClipFunction	ClipFunctionArguments
ColormapFunction	ColormapFunctionArguments
ColormapToRGB
ColorspaceCoversionFunction	ColorspaceConversionFunctionArguments
ComplexFunction
CompositeBandFunction
ConstantFunction	ConstantFunctionArguments
ContrastBrightnessFunction	ContrastBrightnessFunctionArguments
ConvolutionFUnction	ConvolutionFUnctionArguments
ExcludedAreaFunction	ExcludedAreaFunctionArguments
ExtractBandFunction	ExtractBandFunctionArguments
FootprintFunction	FootprintFunctionArguments
GeometricFunction	GeometricFunctionArguments
GrayscaleFunction	GrayscaleFunctionArguments
HillshadeFunction	HillshadeFunctionArguments
IdentityFunction
KauthThomasFunction
LocalFunction (ESRI.ArcGIS.SpatialAnalyst)	LocalFunctionArguments (ESRI.ArcGIS.SpatialAnalyst)
MaskFunction	MaskFunctionArguments
MergeRasterFunction	MergeRasterFunctionArguments
MLClassifyFunction(ESRI.ArcGIS.GeoAnalyst)	MLClassifyFunctionArguments(ESRI.ArcGIS.GeoAnalyst)
MosaicFunction	MosaicFunctionArguments
MosaicRasterFunction	MosaicRasterFunctionArguments
NDVIFunction
PansharpeningFunction	PansharpeningFunctionArguments
PanSharpenGramSchmidtFunction
RadarCalibrationFunction	RadarCalibrationFunctionArguments
RasterInfoFunction	RasterInfoFunctionArguments
RasterItemFunction	RasterItemFunctionArguments
ReflectanceFunction	ReflectanceFunctionArguments
RemapFunction	RemapFunctionArguments
RenderedRasterFunction	RenderedRasterFunctionArguments
ReprojectedFunction	ReprojectedFunctionArguments
RGB32Function
RGB32ToRGBFunction
SAIFunction	SAIFunctionArguments
ShadedReliefFunction	ShadedReliefFunctionArguments
SpectralConversionFunction	SpectralConversionFunctionArguments
SlopeFunction	SlopeFunctionArguments
SpeckleFuncton	SpeckleFunctonArguments
StatisticsFunction	StatisticsFunctionArguments
StretchFunction	StretchFunctionArguments
TableFunction	TableFunctionArguments
TrendFunction	TrendFunctionArguments

Some of the raster functions listed do not have corresponding arguments objects. This is because these functions do not have parameters other than the input raster.

ArcGIS 10 also provides the ability to view, add, remove, and edit the raster functions in a function raster dataset or a mosaic dataset. You can edit the functions associated with a function raster dataset using the Functions tab in the raster dataset properties dialog box. Similarly, the mosaic dataset properties dialog box has a Functions tab that allows you to view and edit the functions applied on a mosaic dataset.

Function raster datasets can be created using the ArcObjects application programming interface (API) to apply one or more raster functions to a raster dataset or a mosaic dataset. For more information, see Create a Function Raster dataset.

Raster functions can be chained together to apply a series of operations to a raster. This can be done in the following ways:

Using a function raster dataset as an input to a raster function, thereby chaining two functions together.
Defining a chain of functions that can be applied to a set of rasters.

The second option is achieved by using raster function templates and raster function variables.

Raster function template

A raster function template is a raster function or a chain of raster functions in the form of a template (that is, the input raster and some of the parameters for the function have not been set). This is done by using raster function variables. The variables can be resolved at a later date thereby converting the raster function template to a function raster dataset. The advantage of the template is that the same chain of functions can be applied to more than one raster without the whole chain being recreated.

Raster function templates are the basis for adding data to a mosaic dataset. They are used extensively by raster types to add different kinds of data with different function chains to a mosaic dataset.

Custom raster functions

Custom raster functions can be implemented using the ArcObjects API. To implement a custom raster function, you must implement the following:

The custom raster function by implementing the IRasterFunction interface
The raster function arguments by implementing the IRasterFunctionArguments interface

Every custom raster function and its arguments object must have the capability to be serialized in binary and Extensible Markup Language (XML) formats. They must also be able to support different versions. For this reason, both the custom raster function and its corresponding arguments object must implement the following interfaces:

IPersistVariant
IDocumentVersionSupportGEN
IXMLSerialize
IXMLVersionSupport

To access the custom raster function in the raster function user interface (UI) in ArcGIS, an optional custom UI page for the custom raster function can be created by implementing the IComPropertyPage interface. For the UI framework to recognize the custom raster function, both the UI property page and the custom function need to register themselves with the respective component categories.

Implementing the custom raster function

Every custom raster function is responsible for providing the following basic functionality:

Changing pixel type for the pixels processed by it
Resampling the pixels processed by it

You do not need to implement this functionality. The IRasterFunctionHelper interface provides a helper object that performs this functionality. This allows you to focus on the processing to be implemented.

A custom raster function has the following two main methods:

Bind—This method takes an arguments object as input for a function that has multiple parameters or an input image for functions that do not have other parameters. It initializes the function using the arguments object and prepares to process pixels.
Read—This method performs the actual processing of pixels, which are provided in the form of a pixel block. The other arguments are a point that defines where in the output the pixel block starts and a reference raster that specifies what properties the pixel block expects.

Implementing the custom raster function argument

The custom raster function arguments object is basically a list of the parameters of the function, including the input raster. A raster function that does not have parameters, other than the input raster, does not need an arguments object. The raster function arguments object provides two methods to set parameters: as properties on the object (get and set) or as key value pairs in a property set maintained by the arguments object. The first method is preferred because it performs validation. However, the second method is necessary to enable raster function variables to be set as the value of the parameter.

Implementing the custom raster function UI

The custom raster function UI page is responsible for creating or editing a raster function arguments object through the UI in ArcGIS. The UI is also responsible for determining the raster function to which it applies (that is, one UI page can potentially support multiple raster functions). This validation occurs in the IComPropertyPage.Applies function. This UI page is only needed if you want to manipulate the function using the ArcGIS raster function editor. It is not essential to the performance of the function.

The UI supports the creation and editing of a raster function arguments object in the following two modes:

Normal—This mode is used for creating and editing function raster datasets. It is a straightforward assignment of values from the UI page to the corresponding properties in the arguments object.
Template mode—This mode is used to create and edit the arguments object for a raster function template. This means that every parameter of the arguments object is converted to a raster function variable. This adds an additional layer of abstraction between values from the form (which are set as default values for the raster function variable corresponding to the specific property) and the corresponding properties in the arguments object.

Development licensing	Deployment licensing
ArcGIS Desktop Basic	ArcGIS Desktop Basic
ArcGIS Desktop Standard	ArcGIS Desktop Standard
ArcGIS Desktop Advanced	ArcGIS Desktop Advanced
Engine Developer Kit	Engine

Function raster datasets and raster functions