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 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, for exampled during startup or installation.

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

A typical version number is divided into 3 parts: major.minor.build (10.0.2414).

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\ArcGIS\ImageServer10.0\XADefs\MyApp.Config"

If pISClient.Init(configFilepath) = False Then

MsgBox pISClient.Status

End If

Selecting an image service using the Add Image Service 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(“”)

The first method of selecting an image service involves selecting a server and then selecting an image service published by that server. In this case, the dialog box returns the selected service names as XML string. Below is an example of an XML string with 3 services selected.

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

The second method of selecting an image service involves selecting an image service reference (.ISRef) file. This file can be passed directly to the ISClient object. In this case, the XML string returned looks like this:

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

Displaying all the property pages in a modal dialog box

pISService.GetServicePropertiesDialog.ShowPropertiesModalDialog()

Displaying individual pages

pISService.GetServicePropertiesDialog.ShowPropertyPage(Page, hWnd)

Where:

       Page—is a 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 that 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 file path).

Dim saveDone As Boolean

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

Client Application Samples:

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