Creating a custom raster type

How Image Service Editor uses a raster type

This section explains how ArcGIS Image Server components interact with a raster type. It is important for you to understand because it will provide you with a deeper understanding of the dynamics at work. All custom raster types that implement an RPDef generator are .NET DLLs. You may use Visual Basic .NET, C#, or C++ .NET to create a library that contains your code.

Below is a brief look at the interaction between the objects.

Object relationships involved while creating a raster type

 

image008

How Image Service Editor uses an RPDef generator

Image Service Editor first obtains a list of all *.RPDefGen files in <ImageServerHome>/XADefs/RPDef Generators folder and uses the information contained in them to populate Service Editor’s Add Rasters dialog.
When the user picks the raster type from the Add Rasters dialog in the Image Service Editor toolbar:
The application uses the RPDef Generator Factory to create an RPDef generator.
The factory ensures that the object returned to the application is initialized by the Init function with a valid ISDef file-path, the name of the Raster Type which the user picked, and the RPDefGen file-path.
The RPDef generator object is free to initialize itself however it deems fit.
Image Service Editor then invokes the ShowAddDataDialog function on the RPDef generator object. Details of what the dialog shows or does is left to the object.
Service Editor then invokes the ShowProcessParametersDialog function.
-This optional dialog is provided to allow you to input additional parameters that can further affect how the RPDefs are created.
-For instance, when you select the Georeferenced Imagery/TIFF raster type, the Add Data dialog allows you to pick files or folders from where to obtain data, where as the Process Parameters dialog allows you to input parameters like the default spatial reference, whether to use the world file, and how to enhance the raster datasets.
Every RPDef Generator object must allow applications to set and get AddDataParameters and ProcessParameters (strings) without having to show the respective dialogs.
-This is useful when RPDef generators are used programmatically by other application or perhaps by another RPDef generator.
-RPDef generators must save user specified information from the show functions into the corresponding parameter strings. The show functions must not have any side-effects that are exploited by the object later.
-This ensures that the RPDef generator object can be safely used by Image Service Editor, by other Raster Types that might link to your custom RPDef generator, or by another application designed to utilize the algorithms contained within your RPDef generator object.
Image Service Editor then invokes the FindItemsToAdd function.
-This indicates to the RPDef generator that it can now proceed with the task of finding items that match the criteria specified in the AddDataParameters and ProcessParameters.
-The application is returned an array of RPDef Entry structures containing only the source names of possible items for which RPDefs may be generated via the GetItemsToAdd function call.
-The RPDef Entry structure corresponds to an item generated by the Raster Type. It’s designed for storing the source name, the generated RPDef XML, whether the item is Enabled, and (for an item that gets disabled) it also contains the Status XML string explaining the reasons.
The array returned to Image Service Editor is then split into more manageable chunks of 100 items each. The GenerateRPDefs function is repeatedly called with the partial array.
-Here, the generator object processes all the input parameters to create the RPDef for each item.
-The generator object typically fills up another array of RPDef Entry structures with: valid RPDef XML string (if the creation was successful); or valid Status XML string (if the object was unable to create an RPDef for the particular entry). In case the generation is a failure for any entry, the Enabled property should be set to False.
-Image Service Editor obtains this final array of RPDef Entry structures by using the GeneratedRPDefs property.
As a general behavior, whenever a function call on the RPDef generator object fails, the calling application invokes the GetStatus function expecting a valid Status XML.
Once Image Service Editor obtains the RPDef XMLs, the RPDef Validator is used to ensure the integrity of the RPDefs before being imported into the image service definition.

The RPDefGenerator Interface

The following table briefly defines the interface that every custom raster type must implement.

Properties

Name

Description

Name

[Read-only, String] Name of the raster type. Typically, it’s the same name as passed by the RPDef Generator Factory to the RPDef Generator object after reading the value from the RPDefGen file.

AddDataParameters

[String] The add data parameters which the RPDef Generator uses while finding matching items or generating RPDefs. This property should also be internally set by the ShowAddDataDialog Method.

ProcessParameters

[String] The process parameters which the RPDef Generator uses while finding matching items or generating RPDefs. This property should also be internally set by the ShowProcessParametersDialog Method.

GeneratedRPDefs

[Read-only, Array of RPDefEntry] Array of entries for which generation of RPDefs was attempted.

Status

[Read-only, String] An XML string that informs the application about the status of the last operation performed by the object.

Methods

Name

Description

Init

Initializes the RPDef Generator object. Invoked by the RPDef Generator Factory prior to returning the object to the application.

ShowAddDataDialog

Image Service Editor uses this function to shows the first UI form after a user double-clicks on the Raster Type entry. Here, you are typically presented with a form allowing them to select files, folder, or any criteria that helps in find matching source items for which RPDef generation may be attempted.

ShowProcessParametersDialog

Image Service Editor uses this function to shows an optional second UI form after a user double-clicks on the Raster Type entry. Here, you are typically presented with a form allowing them to specify additional parameters that might help in RPDef generation.

FindItemsToAdd

This function is invoked by Image Service Editor after the user has successfully dismissed the two forms. The RPDef Generator object is expected to proceed with identifying and listing the source items for which RPDef generation should be attempted.

GetItemsToAdd

The application calls this method after a successful call to the FindItemsToAdd function. This function is expected to return an Array of RPDefEntry structure containing names of source items for which RPDef Generation will soon be attempted.

GenerateRPDefs

This is the call to the object indicating that it begin RPDef Generation for each of the RPDefEntry in the Array that’s provided as an argument to this function.

GetProperty

Generic function that allows access to a recognized property.

SetProperty

Generic function that allows updates to a recognized property.

The RPDefGen file

The first point of interaction between Image Service Editor and a Raster Type is the RPDefGen file. This XML file contains information that the application uses to fill the Add Rasters Dialog with a valid entry for the Raster Type and to create the RPDef Generator object once the user double-clicks on the Raster Type. Here’s a brief introduction to each node in the RPDefGen XML:

 

Name

Type

Required

Description

Information

Name

String

Yes

Name of the RPDef Generator that uniquely identifies the Raster Type and the underlying object. This property is shown to you only in error messages in Image Service Editor.

Version

String

Yes

Version of this RPDefGen file. Currently not used by Image Service Editor.

Author

String

No

Defines the author of this RPDef Generator. This property is shown by Image Service Editor in the "Add Rasters" dialog.

Description

String

Yes

This is the publicly visible name of the Raster Type. Forward slashes in the name is translated to a folder structure in Image Service Editor's Add Rasters Dialog.

LongDescription

String

Yes

Image Service Editor displays this text for each Raster Type in the Add Rasters dialog.

Visible

Boolean

Yes

If Visible is set to "False", Image Service Editor will not show this Raster Type in the Add Rasters dialog. The Raster Type is, however, accessible to other application or modules which load it using methods shown in the SDK.

GeoreferencingDetails

String

No

Details of georeferencing performed by the Raster Type.

SrsDetails

String

No

Details of how Spatial referencing information is specified in the Raster Type.

RadiometryDetails

String

No

Details of what radiometric processing is performed in the Raster Type.

EnhancementDetails

String

No

Details of what enhancement of the imagery is performed in the Raster Type.

MetadataDetails

String

No

Details of how metadata is extracted by the Raster Type.

FootprintDetails

String

No

Details of how the footprint shape is defined in the Raster Type.

SeamlineDetails

String

No

Details of how the seamline shape is defined in the Raster Type.

RPDef Generator

AssemblyName

String

Yes

The full assembly name that contains the object implementing the raster type. An example would be: "ESRI.ImageServer.RPDefGenerator.Georeferenced, Version=1.0.0.1, Culture=neutral, PublicKeyToken=1fe19dd100662792".

ObjectName

String

Yes

The full object name that implements the underlying RPDef Generator. An example would be: "ESRI.ImageServer.RPDefGenerator.Landsat1GRPDefGen"

The schema for an RPDefGen file is installed with the SDK; it’s available in the “<ImageServerHome>/Developer Kit/Raster Types/Schemas” sub-folder.

The Sample Raster Type

Our simple RPDef Generator generates RPDefs for raw (BIP, BIL, or BSQ) image files. The image files are accompanied by header files (in HDR format) which contain raster and georeferencing information. The Add data dialog allows the user to pick one ore more BIL, BIP or BSQ files. The Process parameter dialog allows the user to specify a PRJ file from which the spatial reference information is read.

A typical HDR file looks like this:

BYTEORDER M

LAYOUT BIL

NROWS 1201

NCOLS 1201

NBANDS 1

NBITS 16

BANDROWBYTES 2402

TOTALROWBYTES 2402

BANDGAPBYTES 0

NODATA -32768

ULXMAP -73

ULYMAP -15

XDIM 0.000833333333333

YDIM 0.000833333333333

The sample demonstrates how we add a Process chain to one of the rasters, how we compute the footprint for the dataset, how we fire events to notify Image Service Editor of the progress. Please note that the complete, buildable, source code for this sample is available with the Developer Kit at “<ImageServerHome>/Developer Kit/Raster Types/Sample/RPDefGenHDR”. The sample raster type is installed under “Georeferenced Imagery/Raw with HDR (Sample SDK)” in Image Service Editor.