How to use variables in raster process definition files

When a raster is added to an image service definition, a new raster process definition (RPDef) is created for each raster. The RPDef defines all the properties of the raster and these properties can be edited for either/or:

•	A single raster using the Raster Properties dialog box (available when you click the Raster Properties button on the Image Service Definition toolbar).

Variables provide a number of benefits because they can be used to make parameters controllable using values in the service table. Variables can be used to:

•

Manage process parameters using values in service tables: Typically parameters to be used in processes may be already known and available in a tabular form and it is required to control the processes based on these values. Alternatively, a parameter may need to be different for different rasters and a method is required to set these using selection sets within the GIS.

•	Create template based raster process definitions: This enables multiple rasters to be defined by a single Raster Process Definition. This is especially useful for creating services based on properties of images that are already in a tabular form.

Each Raster in the image service definition has a RasterSource field that points to a Raster Process Definition (RPDef). The RPDef defines all properties, processing, and metadata for a raster. The only properties about a raster that are not defined in the RPDef are the actual pixels (defined by a specific format), the MinPS and MaxPS that are used to define scale based visibility of the raster and the footprint and seamline that define how the raster is clipped. RPDefs are XML files and can either be edited one at a time using the Raster Properties dialog box or multiple ones using the Edit Raster Properties wizard. Alternatively they can also be edited using an XML editor or text editor as long as they remain valid RPDefs.

A fixed value in a RPDef can be replaced by a variable using the notation ${FieldName}$, were FieldName is the name of field that must exist within the footprint table. Prior to an RPDef is being used (in preview) or being compiled, variables are replaced by the associated values defined in the footprints table. Any value in a RPDef can be fully or partially replaced by a field name. For example, the Source value in a RPDef that defines the location of the raster file could be replaced with ${FullName}$, as long as the field FullName exists and contains the required path and name of the file. Alternatively ${FullName}$ could be replaced with ${Path}$\MyData\${RasterName}$.TIF

A typical example of when a parameter may be required to be controlled in a table is in the enhancement of imagery. For example a stretch process is applied to images and the Gamma needs to be adjusted from image to image. This could be done by setting the gamma value in each individual raster, alternatively the Gamma value in the stretch process can be defined as ${Gamma}$ and a field called Gamma added to the footprint table. Thereafter the gamma for a set of images can be set by selecting the fields and using the Calculate tool to set the required Gamma. The value ${Gamma}$ can be set in all or a set of rasters by using the Edit Raster Properties wizard.

2.	Create an image service definition using the Image Service Definition Editor toolbar using either the wizard or the Advanced menu.

4.	The values in this field for each record can be added manually or by joining to create a table or by extracting it from the metadata.

5.	After the values are set in the footprint attribute table, use the Edit Raster Properties wizard to add the Stretching process at the raster group level (to change values in multiple rasters simultaneously). In the Stretching Process dialog box, define ${GammaR}$ for gamma value.

By defining the variable for this process, you will use the values for GammaR from the footprint attribute table.

When you add a raster using the ArcGIS Image Service Definition Editor toolbar, a new RPDef is created for the corresponding raster. In some cases large number of rasters are added to image service definitions and only a few parameters are different from raster to raster. In this case the RPDef for each of the rasters is nearly the same, with only a few parameters being different. Typical examples are rasters being added from digital aerial photography missions where there may be a large number of rasters but only the orientation data varies from one raster to the other. Another example is the case where you already have catalogs or tables of images and the fields contain a definition of all the values that are different from one image to the next. In such cases it may be advantageous to use a template RPDef.

The RPDef for a raster is defined by the RasterSource field in the footprint table and a set of rasters can point to a single RPDef. The parameters that change from raster to raster are then defined as variables. The process to create rasters involves creating a template RPDef by using an existing RPDef that defines all the fixed values and replacing the values define in the table with variables. The table with variable values is merged into the service footprint table using any available footprint geometry and the source field set to point to the template. The footprint can generally be updated using the recompute footprint by geometry feature. The process to create such template based services is defined as part of the ArcGIS Image Server Developers Kit.

There are cases when it is required to extract metadata from the RPDef such that the values are fields in the database. Being fields in the database enables them to be used as attributes, for example to order the images when using the mosaic method. Attributes are also displayed in a tabular form as part of the raster information to users. Attributes can also be used as variables. To extract values from the metadata as attributes, the Xpath of the node in the RPDef needs to be set in the Field Properties and then the Extract Metadata option in Build used which will result in the values being extracted.

Note: XPaths can be used to set the path to get the field values from an XML file. By setting the Xpath in service fields, you can extract information from RPDefs to the table. An alternative to using the Edit Raster Properties wizard is to use a search and replace utility available with some text editors.

•	If a variable is used to modify the geometry of the raster, for example by changing the affine transform then it is also necessary to modify the footprint. For most rasters the recompute footprint feature may be used.

•	The RPDef also contains a footprint and optionally a Seamline geometry defined using a GML node. These nodes are only used when a raster is added, so there is no need to define variables for them.

•	A RPDef that contains variables cannot be added using the Add Raster wizard if the following are defined as variables: Name, SRS, HiPixelSize, LoPixelSize, Footprint, Seamline.