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
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.