com.esri.arcgis.carto
Interface IImageServer

All Superinterfaces:
Serializable
All Known Subinterfaces:
IImageServer2, IImageServer3, IImageServer4
All Known Implementing Classes:
ImageServer, ImageServerIP, ImageServerLP

public interface IImageServer
extends Serializable

Provides access to members that control an image server.

Description

This interface is new at ArcGIS 9.3.

Remarks

You can get information about an image service describing the properties of the service, you can also get the pixel data from the service the way you want it, for instance you can ask the data to be in certain extent, band combination, compression type, etc. To export the data from a service in a well-known raster format (e.g. BMP, PNG) either as MIME data or URL, you can use ExportImage. To get the data from a service as a byte array, you can use GetImage.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.


Method Summary
 IImageResult exportImage(IGeoImageDescription pImageDescription, IImageType pImageType)
          Exports into a well-known image for a given image description.
 byte[] getImage(IGeoImageDescription pImageDescription)
          Gets an image for a given image description.
 IImageServiceInfo getServiceInfo()
          The properties of the image service provided.
 float getVersion()
          The Image Server version number.
 

Method Detail

getVersion

float getVersion()
                 throws IOException,
                        AutomationException
The Image Server version number.

Description

Returns the version number of the Image Server

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
The pVersion
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getServiceInfo

IImageServiceInfo getServiceInfo()
                                 throws IOException,
                                        AutomationException
The properties of the image service provided.

Description

Returns information of the image service. The information includes description, spatial reference, extent, pixel size about the image data.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:
A reference to a com.esri.arcgis.carto.IImageServiceInfo
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getImage

byte[] getImage(IGeoImageDescription pImageDescription)
                throws IOException,
                       AutomationException
Gets an image for a given image description.

Description

Gets the image data in byte array from the image service using the given GeoImageDescription.

Remarks

Gets the image data for a given image description. The returned image data contains first pixel values and then followed by NoData (transparency) bit mask, i.e. <pixels><mask>. The pixel values are organized in a band interleaved by pixel format, as the following:

v[0,0,0], v[1,0,0], v[2,0,0],…, v[nBands-1,0,0],

v[0,0,1], v[1,0,1], v[2,0,1],…, v[nBands-1, 0,1], …,

v[0,nRows-1,nCols-1], …, v[nBands-1,nRows-1,nCols-1]

where nCols, nRows, and nBands are the number of columns, number of rows, and number of bands of the returned image, and v[b,I,j] is a pixel value at band number b, row number I, and column number j. The size in terms of number of bytes of a pixel value depends on pixel type. The following table shows the pixel type to pixel size mapping:

PT_U1 1

PT_U2 1

PT_U4 1

PT_UCHAR 1

PT_CHAR 1

PT_USHORT 2

PT_SHORT 2

PT_ULONG 4

PT_LONG 4

PT_FLOAT 4

PT_DOUBLE 8

The location of the pixel at band b, row I, and column j can be calculated using the following formula:

location = ((i*nCols+j)*nBands+b)*pixelsize (in bytes)

The pixel data are always in Intel (Little Endian) byte order. For pixel types of more than 1 byte, byte swapping may be needed.

The NoData mask is a bit mask, one bit per pixels of all bands, with no padding to the byte boundary for a row. Value 1 indicates the pixel is valid, and 0 indicates NoData. The mask value for a pixel at row I and column j can be calculated as the following:

Bit[] = {0x80, 0x40, 0x20, 0x10, 0x08, 0x04, 0x02, 0x01}

l = i*nCols+j

m[l/8] & Bit[l%8]

The NoData immediately follows pixel data. The size of NoData mask in bytes is (nCols*nRows+7)/8.

The NoData mask is optional. If the total size of the returned image data greater than the pixel data size i.e. nRows*nCols*nBands*pixelsize, then the NoData mask is present.

If LZ77 compressed, the returned image data must be uncompressed (zlib). The uncompressed image data follow the same format as above.

If JPEG compressed, the returned image data are organized as JPEG data stream followed NoData mask, and followed by the size of the JPEG stream, i.e. <JPEG><mask><size>. The NoData mask is the same format as above, but is LZ77 compressed. The JPEG data stream size <size> is a 4-byte integer in Intel byte order.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
pImageDescription - A reference to a com.esri.arcgis.carto.IGeoImageDescription (in)
Returns:
An unsigned byte
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IGeoImageDescription

exportImage

IImageResult exportImage(IGeoImageDescription pImageDescription,
                         IImageType pImageType)
                         throws IOException,
                                AutomationException
Exports into a well-known image for a given image description.

Description

Exports image data from the image server using the GeoImageDescription and ImagType.

Remarks

The supported formats, defined using the ImageType parameter, include JPEG, PNG, BMP, and TIFF. The JPEG format is the same as the JPEG compressed image returned from the GetImage method. Image content can be returned as a URL or as a MIME data stream.

If the size of the image in terms of number of columns and rows exceeds the limit defined in the image service configuration, this method will return an error.

If the pixel type defined in ImageDescription is different from the pixel type of the image service, the pixel values will be converted according to the specified pixel type if possible. Otherwise, an error will be returned at 9.3.

New at 10.0, if the image service pixel type cannot be converted to the requested pixel type, a default raster renderer will be applied. A proper default renderer is created using the same rule as when a raster dataset of the same properties, e.g. number of band, pixel type, and etc is added to map.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
pImageDescription - A reference to a com.esri.arcgis.carto.IGeoImageDescription (in)
pImageType - A reference to a com.esri.arcgis.carto.IImageType (in)
Returns:
A reference to a com.esri.arcgis.carto.IImageResult
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IGeoImageDescription