Creating an ArcGIS Image Server client application

ArcGIS Image Server Developer Kit provides the capability of creating your own custom client applications with minimum amount of coding. Client applications can be written in .NET environment, COM, ANSI C, or C++. The following sections will help a developer in creating a client application.

Client DLL references

When writing a client application we need to add references to the client library. Depending on the development environment, the libraries to include in your code are as follows:

ESRI.ImageServer.ISClient.dll

ISClient.Dll

ISClient.Dll

isclientc.h

Configuring and initializing the client DLL

There are different methods to access the imagery and different features that should or should not be available to an application depending on its capabilities. The functionality of the client is controlled primarily by a client configuration file. This client configuration file is to be distributed with the program and should be installed in a location accessible by the program using any login. The configuration file will vary for each client application and shall contain parameters optimized for the application. The configuration file should be loaded on startup of the client application and will enable or disable functionality of the ArcGIS Image Server Client. This configuration file is not exposed to the normal user. It is up to the developer to expose or hide functionality of the ArcGIS Image Server interface.

The ArcGIS Image Server client configuration files are generally given the same names as the application with the extension .ISCConfig. Alternatively, the configuration file can be stored within the application and passed as a string during initialization.

The schema of the ISCConfig file can be viewed at <ArcGIS Image Server installation folder>\Developer Kit\XML\ISClient.ISCConfig.XSD. Use this schema to create an XML file and enter in the default values for your application.

The table below outlines the different nodes and default values that can be used within the .ISConfig file. It can be used as a guide to set the default values for an application.

Version control

The version of the client application needs to be checked. The core client installation will enter the ArcGIS Image Server Client DLL version number in the registry. The client application should check the version of the client DLL from the registry and flag a warning if the major or minor version number is more recent than the version number it was compiled with. This warning can be show at the discretion of the developer, such as at startup or installation.

The registry entry to be checked by the client application is HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Image Server\ClientVersion.

A typical version number is divided into 4 parts: major.minor.revision.build (9.2.0.1).

The warning messages in client applications are added at the developer’s discretion.

Using the client DLL

There is one generic ArcGIS Image Server client interface used for all standard ArcGIS Image Server client applications. This consists of a DLL and GUI component. The DLL exposes the necessary functions and properties to acquire an image from the ArcGIS Image Server and set different properties for the acquired image. The DLL utilizes the GUI component to display the various interface dialog boxes needed for user interaction.

The DLL is designed to be relatively light and easy to program with built-in GUI components. The function calls to the client DLL are designed to take the input and output as XML strings so that the interface is open to modification and expansion.

The following are the functions that can be used to build a client application:

Initialize the ISClient object

The client application needs to be initialized at startup. Create a global object on startup and use this object to open the necessary image services.

Public pISClient As New CClientObject

Dim configFilepath As String

configFilepath = "c:\Program Files\Common Files\ESRI\Image Server\XADefs\MyApp.Config"

If pISClient.Init(configFilepath) = False Then

MsgBox pISClient.Status

End If

Selecting an image service using the Add Image Services dialog box

An image service can be selected using two methods:

Both these methods can be carried out by displaying the Add Image Service dialog box. The ShowImageServicesDialog function displays a dialog box that allows the user to select a server and image services from that server. It also allows the user to pick an .ISRef file.

ShowImageServicesDialog request is made using the ISClient Object.

Dim selectedImageServicesXml as String

selectedImageServicesXml=pISClient.ShowImageServicesDialog(“”)

<SelectedImageServices> 

<Name>ImageService://hawkings:10000/30_nov_s357_uln</Name>

<Name>ImageService://hawkings:10000/Amberg_GeoTiffs</Name>

<Name>ImageService://hawkings:10000/Amberg_TFW_10Dec</Name>

</SelectedImageServices>

<SelectedImageServices>

   <Name>C:\Temp\TestImageService.ISRef</Name>

</SelectedImageServices>

Opening an Image Service

As described above an image service or multiple image services can be selected using the ShowImageServicesDialog. However, to actually connect the image service you must use the open image service request. This request opens one service at a time. To get access to the list of service names it must be parsed using an XML parser.

Dim pISService As CImageService

Set pISService = pISClient.OpenImageService(serviceName, "")

Here serviceName can be a Service Name or a .IsRef filename as returned in the SelectedImageServices XML string. E.g

serviceName = “ImageService://hawkings:10000/30_nov_s357_uln”

OR

serviceName = “C:\Temp\TestImageService.ISRef”

The opened service has to be maintained as global object and part of an array to access. Some form of a collection would be ideal.

Displaying Service Properties

The Properties page provides the user the option of viewing or setting additional properties for the image service. This Properties dialog box contains two pages that can be displayed simultaneously in a modal dialog box or each page can be displayed separately depending on the user’s requirement.

pISService.GetServicePropertiesDialog.ShowPropertiesModalDialog()

pISService.GetServicePropertiesDialog.ShowPropertyPage(Page, hWnd)

Where:

       Page is an property page to display.

       hWnd is the handle to the source window.

To get the updated service properties, use the ‘GetUpdatedProperties’ method:

pISService.GetServicePropertiesDialog.GetUpdatedProperties

To see the affect of the newly set properties, use the ‘ApplyServiceProperties’ method:

pISService.ApplyServiceProperties

Displaying an image

Client applications will need to display the image it gets back from the service provider. Currently, there are two methods of displaying this image. The first is to draw it directly onto the display of the host application. The second is to create a georeferenced file and load that onto the display.

Creating a virtual image

In the image service client, the image information has to be set based on the current extent of the display. To do this, the SetimageInfo request has to be used on the open Image Service.

isSetInfoDone = pISService.SetImageInfo(pXMin, pYMin, pXMax, pYMax, pNCols, pNRows)

If isSetInfoDone = False Exit Function

To write the virtual image a buffer of bytes needs to be created and maintained. 

Dim pBuffer() As Byte

pBufferSize = pISService.GetRecommendedBufferSize

The buffer needs to be initialized to the recommended buffer size.

ReDim pBuffer(pBufferSize)

A pointer to the buffer needs to be passed to the Image Service.

Dim pBufferAddress As Long

pBufferAddress = VarPtr(pBuffer(0))

pISService.ImageBuffer = pBufferAddress   

Create the image and save it in the buffer.

Dim isImageCreated As Boolean

isImageCreated = pISService.GetImageByExtent

This buffer then needs to be drawn directly onto the display using the tools provided by the host application.

Creating a file based image

To create a file based image all the below mentioned steps have to be followed:

The image info has to be set based on the current extent of the display.

Dim isSetInfoDone as Boolean 

isSetInfoDone =  = pISService.SetImageInfo(pXMin, pYMin, pXMax, pYMax, pNCols, pNRows)

Create the Image file by calling the ‘GetImage’ method. This method requires an XML string which sets the output properties of the image file.

Set the default XML string

Dim imageInfoXml as String

imageInfoXml = "<ImageServer><Client><GetImage><OutputType></OutputType><FileName></FileName><Format></Format></GetImage></Client></ImageServer>"

Load the XML string in COM document object and modify the values of each node.

Dim imageInfoDoc As New DOMDocument  

imageInfoDoc.loadXML (imageInfoXml)

imageInfoDoc.selectSingleNode("//ImageServer/Client/GetImage/OutputType").Text = "File"

imageInfoDoc.selectSingleNode("//ImageServer/Client/GetImage/FileName").Text = "C:\Temp\MyImage.tif"

imageInfoDoc.selectSingleNode("//ImageServer/Client/GetImage/Format").Text = "TIFF"

imageInfoXml = imageInfoDoc.Text

Create the image file to the output location

Dim isGetImageDone as String 

isGetImageDone = pISService.GetImage(imageInfoXml)

It is recommended that this entire procedure be created as a separate function that will accept the required parameters and write out a file.

For more information, see IImageService.GetImage method.

Exporting an image using Export dialog

This option is available as part of an image service object. To display the export image dialog box you have to use the following command:

pISService.GetExportImageDialog.ShowModalDialog

When the user clicks OK the dialog will write out the image.

To avoid using this interface one has to follow the procedure mentioned in Creating a file based image.

Displaying the Viewpoint dialog

The Viewpoint dialog box is used for setting the viewpoint for the service that supports this method. Depending on the user’s requirement, this dialog box can be displayed separately as a modal dialog box or by clicking on the Viewpoint button that appears on the service properties dialog box.

Displaying Viewpoint as a modal dialog box

pISService.GetServicePropertiesDialog.ShowViewPointModalDialog()

For Viewpoint to work, get the updated service properties and apply them.                                    

pISService.GetServicePropertiesDialog.GetUpdatedProperties

       pISService.ApplyServiceProperties

Saving an Image Service Reference (.ISRef) file

An image service reference (.ISRef) file stores the reference to an image service with its current state. It defines the service connection and the properties of the image service. Using the Image Service Client interface, we can save an .ISRef file which can then be loaded later by any ArcGIS Image Server client application. This is optionally available as part of service properties.

In order to save an .ISRef file, the SaveProperties method should be used. The input to this method is the path of the output file. The GUI should be provided by the client application (Add a button to invoke this function and display a file save dialog box for the user to specify the output filepath).

Dim saveDone As Boolean

saveDone = pISService.SaveProperties("c:\temp\test.isref")

Defining Projections

ArcGIS Image Server allows clients to retrieve data from published image service sources in any desired coordinate system (if the required transformation from source spatial reference system to the client requested spatial reference system is valid). This can be done using the Service Properties dialog box available in the client DLL.

Additionally, users can create custom rotated coordinates system definitions and request the service for rotated data based on these definitions. These newly created rotated coordinate systems are known as Adjusted Horizontal Coordinate Systems (ADJHCS) within ArcGIS Image Server framework.

Below is a sample explaining how to define such custom rotated coordinate system projection strings. Once a definition string is created, to access published data in this newly created coordinate system, set the client spatial reference system to the newly created spatial reference system definition on the image service being accessed by the client and place a request for data covering the desired area of interest.

Where,

A = Scaling of x axis * cos(Rotation angle)

B = Scaling of y axis * sin(Skew angle - Rotation angle)/cos(Skew angle)

C = Translation in X

D = Scaling of x axis * sin(Rotation angle)

E = Scaling of y axis * cos(Skew angle - Rotation angle)/cos(Skew angle)

F = Translation in Y

Client Application Samples:

Sample code of two client applications have been provided with the Developer Kit install. These are as follows:

ISViewer sample in VB 6.0

This is a sample written in VB 6.0 development environment. It has the following functionalities implemented:

The source code is available at <ArcGIS Image Server installation folder>\Developer Kit\Client Applications\Samples\ISViewer.

Client Application in ANSI C

This is a sample written in the ANSI C development environment. It has the following functionalities implemented:

The source code is available at <ArcGIS Image Server installation folder>\Developer Kit\Client Applications\Samples\C_ClientTest_Sample

Sample Code