Implementing a custom Geotransformer

The purpose of writing your own GeoTransformers is to extend the capability of ArcGIS Image Server in georeferencing custom Raster Types. This topic describes how to create a Dynamic Link Library (DLL) that implements custom GeoTransformers. It will also explain the available resources that can help you in creating such custom GeoTransformer module.

First step in writing a custom GeoTransformer is to define the parameters used by the transformation as an XML having the following structure:

The root node of the XML structure must be named GeoTransDef and contain two attributes: class and version. The rest of the XML document’s content is your choice to define and use as it fits your needs in describing all the parameters that construct your objects.

The class attribute is made of two parts separated by a dot: idModule and idType. The idModule is the filename of your custom module (without the “.dll” file extension), and it tells to GeoTransCore component to load and call your custom module, in order to create your custom GeoTransformerobjects. The idType is any identifier string naming a GeoTransformer type supported by your implementation.

The version attribute is used entirely by your implementation in order to support versioning control. We encourage versioning control support for GeoTransformers, since their implementation changes may be completely silent and the use of incompatible version of the input could have catastrophic impact on the results. We recommend using the 4-number versioning system (1.0.0.0), in which first two numbers (major and minor) are considered critical changes to the content, thus your implementation should refuse to use it. Please upgrade the value of the version attribute within the GeoTransformer definition on every change of its content or its interpretation.

Any number of custom GeoTransformers can be implemented in your module, but its interface must represent a facade that wraps the internal implementation. The required Application Programming Interface (API) is defined as functions using __stdcall calling convention, exported by name. When using a C++ compiler, these functions must be specifically exported with an undecorated name, by using extern "C" and a *.def file. The name of the DLL must be as defined in the class attribute of the GeoTransformer Definition (explained in above section) and must be located in a folder specified in the PATH environment variable (GeoTransCore calls LoadLibrary only with the filename).

A custom GeoTransformer module will be refused by GeoTransCore component when does not export the following functionalities, grouped by category:

Constructor/Destructor	Create initialized custom GeoTransformer instances and later discard them.
Instance_Create	Creates an instance of a custom GeoTransformer, initialized upon given arguments. When your custom module implements multiple GeoTransformers, it acts as a factory method and decides which one should be initiated.
Instance_Discard	Discards an instance of a custom GeoTransformer. It should free any resources used by specified GeoTransformer instance. On return, given handle will be considered invalid.
Processing	Bidirectional coordinates transformations called FromGlobal and ToGlobal.
GeoTrans_FromGlobalDirection	Performs coordinates transformation used in the process chain starting from global ground (real world) coordinates, converting them into a virtual object's coordinate system. In this document, we will refer to the direction of this transformation as FromGlobal (also know as "ground to image"). Our convention on defining, for example, a correction is that we correct towards global ground coordinates, which means this function will 'uncorrect'.
GeoTrans_ToGlobalDirection	Performs coordinates transformation used in the process chain that computes global ground (real world) coordinates, in reference to a chosen coordinate system. In this document, we will refer to the direction of this transformation as ToGlobal (also know as "image to ground"). Our convention on defining, for example, a correction is that we correct towards global ground coordinates, which means this function will 'correct'.
GeoTrans_FromGlobalEnvelope	Transforms the envelope of a sensor definition, in the process chain starting from global ground (real world) coordinates, converting them into a virtual object’s coordinate system.
GeoTrans_ToGlobalEnvelope	Transforms the envelope of a sensor definition, in the process chain that computes global ground (real world) coordinates, in reference to a chosen coordinate system.
Reporting	Provide error / warning descriptions.
Error_FormatMessage	Translates custom error / warning codes that were set by your implementation.
Caching	Reinitialize existing GeoTransformer instances.
Instance_TryReuseCached	Tries to reinitialize an existing GeoTransformer instance for caching purposes. Provides an optimized alternative to calling Instance_Discard and Instance_Create when an existing GeoTransformer needs to be initialized with different data.
Serialization	Restore discarded GeoTransformer instances.
Instance_Serialize	Given a handle to an instance of custom GeoTransformer, it generates a serialization buffer. The serialization consists in saving transformation parameters (including possible precomputed variables) in binary format, enabling faster reconstruction.
Instance_UnSerialize	Creates a custom GeoTransformer instance, initialized with identical content of a discarded instance. It reconstructs the state of the previously serialized object, including possible precomputed variables.

In order to implement these functions, following namespaces and data structures may be required (for C++ developers, have been already declared in GeoTransformers.h located at "[ArcGIS Image Server installation folder]\Developer Kit\GeoTransformers\Include"):

GeoTransData	Self descriptive I/O package holding data interpreted by a GeoTransformer.
GeoTransData::GTD	Union of data structures encapsulated within GeoTransData I/O packages. GeoTransformers are interpreting the given address as to which of these structures it points to.
VERTEX2D	Single 2D point. Could be referring to an image, film, camera, ground-plane coordinate or any other 2D space (usually cartesian).
VERTEX3D	Single 3D point. Could be referring to a ground coordinate or any other 3D space (usually cartesian).
ARRAY2D	Multiple 2D points that share the same Z value. Could be referring to image, film, camera, ground-plane coordinates or any other 2D space (usually cartesian).
ARRAY3D	Multiple 3D points. Could be referring to ground coordinates or any other 3D space (usually cartesian).
TABLE	Grid of float Z values. Usually represents a digital elevation model (DEM).
SIZE2D	Size of a two dimensional array (grid, image, etc.), expressed as columns and rows.

If Microsoft Visual Studio 6.0 was installed previous to ArcGIS Image Server SDK installation, an application wizard was added to its New project dialog to help you start a C++ project that creates a Win32 DLL implementing a custom GeoTransformer sample class. If you wish to install Microsoft Visual Studio 6.0 after, please copy CustomGeoTransModule.awx from "[ArcGIS Image Server installation folder]\Developer Kit\GeoTransformers\AppWizard" to "Microsoft Visual Studio\Common\msdev98\Template" directory. When the "Custom GeoTransformer AppWizard" is available, you should be able to select it from the New project dialog, as seen the graphic Custom GeoTransformer AppWizard in VS 6.0.

GeoTransCreation	Describes the creational flags specifying how a GeoTransformer instance will be used.
GTM_Errors_Warnings	Recommended list of errors and warnings to be generated by a custom GeoTransformer module.
GeoTransDataTypes	Enumerates types of I/O packages interpreted by a GeoTransformer.