Function raster datasets and raster functions

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.

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 includes built-in raster functions. The following table lists the raster functions and their corresponding arguments objects that are a part of ArcGIS 10:
Raster function
Raster function argument
ArithmeticFunction
ArithmeticFunctionArguments
AspectFunction
 
ClipFunction
ClipFunctionArguments
ColormapFunction
ColormapFunctionArguments
ColorspaceCoversionFunction
ColorspaceConversionFunctionArguments
ComplexFunction
 
CompositeBandFunction
 
ConstantFunction
ConstantFunctionArguments
ExtractBandFunction
ExtractBandFunctionArguments
GeometricFunction
GeometricFunctionArguments
GrayscaleFunction
GrayscaleFunctionArguments
HillshadeFunction
HillshadeFunctionArguments
IdentityFunction
 
MaskFunction
MaskFunctionArguments
MosaicFunction
MosaicFunctionArguments
NDVIFunction
 
PansharpeningFunction
PansharpeningFunctionArguments
RasterInfoFunction
RasterInfoFunctionArguments
RGB32Function
 
SAIFunction
SAIFunctionArguments
ShadedReliefFunction
ShadedReliefFunctionArguments
SpectralConversionFunction
SpectralConversionFunctionArguments
SlopeFunction
SlopeFunctionArguments
StatisticsFunction
StatisticsFunctionArguments
StretchFunction
StretchFunctionArguments
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 you 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 argument 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.


See Also:

Create a custom raster function



To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced
Engine Developer Kit Engine