Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB

Additional library information: Contents, Object Model Diagram

The DataSourcesRaster library contains raster related objects in the following categories:
The PixelFilter, GeodataXform,PixelResampler, PixelReader, and MosaicOperator classes can be instantiated. Adding a new raster format support in ArcGIS does not extent this library, but is handled by creating a format driver (format .dll). Objects used for renderering raster data are located in esriCarto.lib.

See the following sections for more information about this namespace:

Raster data access objects

Raster data consists of a rectangular array of equally spaced cells, which taken as a whole, represent thematic, spectral, or picture data. Raster data can represent everything from qualities of a land surface, such as elevation or vegetation, to satellite images, scanned maps, and photographs.
ArcGIS supports file based raster data such as grid, Tagged Image File Format (TIFF), ERDAS IMAGINE, Joint Photographic Experts Group (JPEG), and so on. It also supports raster data in geodatabases including file geodatabase, personal geodatabase, and an ArcSDE geodatabase. Regardless of the various data sources, raster datasets and raster catalogs data types are used to represent raster data.

A raster dataset represents one or multiple arrays of pixels and associated information that is stored as a raster format in a storage media, such as file systems or geodatabases. A raster catalog, a collection of raster datasets, is stored as a special type of feature class in geodatabases and is used to manage the raster datasets and associated footprints as a single entity.
A raster dataset consists of one or more raster bands. Each band in a dataset can contain the statistics and histogram of the pixel values. A raster dataset can contain pyramids and a stack of down resampled pixels stored in the dataset used for fast display of large raster datasets.

A single band raster dataset can contain a colormap consisting of a set of red, green, and blue (RGB) colors used to display pixels and a raster attribute table that stores extra information about the pixels, such as landuse type, soil type, and so on.
As a type of geodataset, a raster dataset can contain a geodata transformation and a spatial reference. The geodata transformation defines how pixels are transformed during access and a spatial reference defines the coordinate system of the pixels that are mapped to.
If pixels or cells of a raster dataset have missing information, those cells are referred to as NoData cells. NoData is stored as a NoData value or a bit mask in a raster dataset.


A workspace is a repository that stores geodatasets. For raster data, a workspace can be a raster workspace (or a directory) for file based raster data, an Access workspace for raster data in a personal geodatabase, a file geodatabase workspace, or an ArcSDE workspace.
To access raster data, create a workspace, use IRasterWorkspace2 or IRasterWorkspaceEx interface, depending on the data souces, to access raster data. Initiate a workspace from a workspace factory.
See the following illustration of Workspace objects:
The following code example creates workspaces from different sources (these methods will be used throughout this topic) and opens a raster workspace from a directory:
IWorkspace openRasterWorkspace(String path)throws IOException{
    RasterWorkspaceFactory rasterWorkspaceFactory = new RasterWorkspaceFactory();
    return rasterWorkspaceFactory.openFromFile(path, 0);
The following code example opens a file geodatabase workspace:
IWorkspace openFileGDBWorkspace(String gdbFileName)throws IOException{
    FileGDBWorkspaceFactory fileGDBWorkspaceFactory = new FileGDBWorkspaceFactory();
    return fileGDBWorkspaceFactory.openFromFile(gdbFileName, 0);
The following code example opens an ArcSDE workspace by passing connection information:
IRasterWorkspaceEx openSDERasterWorkspace(String server, String instance, String db,
    String user, String passwd, String version)throws IOException{
    SdeWorkspaceFactory sdeWorkspaceFactory = new SdeWorkspaceFactory();

    PropertySet connectionProperties = new PropertySet();
    connectionProperties.setProperty("Server", server);
    connectionProperties.setProperty("Instance", instance);
    connectionProperties.setProperty("Database", db);
    connectionProperties.setProperty("User", user);
    connectionProperties.setProperty("Password", passwd);
    connectionProperties.setProperty("Version", version);

    IWorkspace workspace =, 0);
    if (workspace instanceof IRasterWorkspaceEx){
        return (IRasterWorkspaceEx)workspace;
    return null;

The following interfaces on the Workspace object provide access to RasterDataset and RasterCatalog objects:
Because of different storage media, the method to create a RasterDataset in different workspaces vary; however, once created, a RasterDataset behaves the same except for minor differences.
The following code example opens an Imagine file in a given directory:
IRasterWorkspace rasterWorkspace = (IRasterWorkspace)openRasterWorkspace("d:/data");
IRasterDataset rasterDataset = rasterWorkspace.openRasterDataset("airphoto.img");
The following code example opens a raster dataset and a raster catalog from a geodatabase:
// From a file geodatabase.
IRasterWorkspaceEx fileGDBWorkspace = (IRasterWorkspaceEx)openFileGDBWorkspace(
// From an enterprise geodatabase.
fileGDBWorkspace = openSDERasterWorkspace("myserver", "5151", "myuser", "mydatabase",
    "mypasswd", "SDE.DEFAULT");

IRasterDataset rasterDataset = fileGDBWorkspace.openRasterDataset("airphoto");
IRasterCatalog rasterCatalog = fileGDBWorkspace.openRasterCatalog("RedlandImages");
Creating raster datasets in various workspaces require specifying the properties of the raster data and the properties of the storage. To create a file based raster dataset, the origin, number of bands, pixel type, width, and height of the raster dataset must be specified along with other required parameters. The created raster dataset has a specified dimension and a default pixel value. The default pixel value is normally the maximum value of the specified pixel type and can be populated by writing pixel blocks.
The following code example creates an Imagine file with a dimension of 1024 by 1024 and a cell size of 30 meters:
IRasterWorkspace2 rasterWorkspace2 = (IRasterWorkspace2)openRasterWorkspace(

// The origin is the lower left corner of the dataset in map space.
Point point = new Point();
point.putCoords(100, 100);
IRasterDataset rasterDataset = rasterWorkspace2.createRasterDataset("MyImage.img", 
    "IMAGINE Image", point, 1024, 1024, 30, 30, 1,
    com.esri.arcgis.geodatabase.rstPixelType.PT_UCHAR, new UnknownCoordinateSystem(),
A geodatabase raster dataset (ArcSDE and file geodatabases) is stored in a set of tables consisting of a raster dataset schema and is represented as a raster value in the raster field of the business table. Internally, the raster data is divided into small tiles with a typical size of 128 by 128. The tiles are stored as binary large objects (BLOBs) in the block table; one of the tables of raster dataset schema.
To create a raster dataset in a geodatabase, use RasterDef to set the properties of the raster field and use RasterStorageDef to specify the storage properties, such as tile size, cell size, pyramid origin, compression, and so on (only cell size and compression are applied to creating a raster in a personal geodatabase).
A raster dataset in a personal geodatabase is implemented by converting it to an Imagine file format and managed internally in the personal geodatabase; therefore, some of the raster storage properties, such as tile size will not apply to a personal geodatabase raster dataset and will be ignored.

Creating a raster dataset in a geodatabase initially creates an empty raster dataset. This empty raster dataset, with no dimension, is basically a placeholder for the specified properties of the raster dataset and can be populated by mosaicking from other raster data or alternatively, writing using PixelBlock.

Raster datasets

The RasterDataset object represents a raster dataset stored in a storage media, a file system, a geodatabase or in memory. A raster dataset is a file raster dataset if it is opened from a file system or a personal geodatabase, or is a database raster dataset if it is opened from a file geodatabase or an ArcSDE geodatabase. A raster dataset in an unmanaged raster catalog, where raster datasets are stored in file system, is also a file raster dataset. ArcGIS 9.2 allows the creation of an in-memory raster dataset where the pixels are stored in memory. This type of raster dataset has the characteristics of a file raster dataset. Regardless of the data source it is coming from, a raster dataset behaves the same except for some minor differences. See the following illustration:
As a type of dataset, the RasterDataset object performs basic dataset management functions, such as copy, rename, and delete. It can also be used to examine dataset properties, such as raster format and compression type by using the IRasterDataset interface.
A raster dataset is a type of geodataset and supports IGeoDataset and IGeoDataset2 interfaces. A raster dataset has an extent, a spatial reference, and a geodata transformation (GeodataXform). The geodata transformation is stored as special metadata of the raster dataset and is used to transform pixels to the current extent and spatial reference. Normally, the geodata transformation is an IdentityXform, which does not transform pixels.
In some cases, such as raw images with Rational Polynomial Coefficients (RPC) information or a raster dataset created using IRasterGeometryProc.Register method (for example, using the Georeferencing tool in ArcMap), those raster datasets contain a GeodataXform, an RPCXform, and and a PolynomialXform, respectively.
The extent and spatial reference of a raster dataset are the extent and spatial reference after the geodata transformation is applied to the dataset and can be retrieved using the IGeoDataset interface. The extent and spatial reference before a transformation is applied are called native extent and native spatial reference. The native extent and native spatial reference can be retrieved from IGeoDataset2 interface. The following code example shows the use of this interface:
void getDatasetXform(IRasterDataset rasterDataset)throws IOException{
    IGeoDataset2 geoDataset2 = (IGeoDataset2)rasterDataset;

    // Get the native extent, native spatial reference, and xform.
    IEnvelope nativeExtent = geoDataset2.getNativeExtent();
    ISpatialReference nativeSpatialReference = geoDataset2.getNativeSpatialReference
    IGeodataXform geodataXForm = geoDataset2.getGeodataXform();
    // ...
The spatial reference and the geodata transformation of a raster dataset can be altered using the IGeoDatasetSchemaEdit2 interface.
The IRasterDataset2 interface is used to build, add, and delete a raster table on a raster dataset. The IRasterDatasetEdit interface is used to add and remove a colormap of a raster dataset. You can also merge pixels from another raster dataset to the current raster dataset through the IRasterDatasetEdit.Mosaic method.
Assuming that a raster (IRaster) and raster colormap (IRasterColormap) have been created, the following code example adds a color map to the dataset and also mosaics from the raster:
// Alter colormap.
// Mosaic pixels from IRaster to the dataset.
rasterDataset.mosaic(raster, 0.5);
IRasterDataset.PrecalculateStats is used to calculate the statistics of a raster dataset at full resolution. IRasterDatasetEdit.ComputeStats, which applies to a database raster dataset only, is used to calculate raster statistics on a pyramid layer, for example, skipping some pixels in the calculation. Calculating statistics on a pyramid layer reduces the computation time at the expense of providing less accurate statistics.
You can build pyramids for a raster dataset. When the IRasterPyramid interface is used to build pyramids for a file raster dataset, the resampling method used is determined by the system automatically based on the data representation type. If the data type is thematic, nearest neighbor resampling will be used; otherwise, bilinear resampling will be used. The IRasterPyramid2 interface is used for creating raster pyramids by specifying a resampling method. This interface is useful for a database raster dataset. The following are the supported writable formats (for ISaveAs) in ArcGIS 9.2:
It can also be written to an in-memory raster dataset. The following code example saves a raster dataset to an Imagine format:
void saveAs(RasterDataset rasterDataset)throws IOException{
    rasterDataset.saveAs("MyImage.img", openRasterWorkspace("c:/data"), 
        "IMAGINE Image");
To save a raster with a specified compression type and a specific tile size, use ISaveAs2. The following code example saves to a raster dataset in a file geodatabase with 64 by 64 tile size and a JPEG2000 compression:
void saveAsWithCompression(IRasterDataset rasterDataset)throws IOException{
    ISaveAs2 saRasterDataset = (ISaveAs2)rasterDataset;
    // Set storage.
    IRasterStorageDef2 rasterStorageDef = (IRasterStorageDef2)new RasterStorageDef();
    // Save it.
    IWorkspace workspace = openFileGDBWorkspace("c:/data/fgdb.gdb");
    saRasterDataset.saveAsRasterDataset("filegdbRaster", workspace, "gdb",
A raster dataset is composed of one or more persistent raster bands. You can get a raster band through an IRasterBandCollection.Item method. Other methods of the IRasterBandCollection interface, such as adding or removing bands, have no effect on the raster dataset. The IRasterBandCollection.SaveAs plays the same role as ISaveAs.SaveAs.
The RasterDataset object can be used to initiate a Raster object. Besides being accessed through a workspace, a raster dataset can also be retrieved from a raster band using the RasterDataset property. To access the raster dataset from a Raster object, access a band from the raster and obtain a reference to the dataset from the band. See the following code example:
// Query interface (QI) IRasterBandCollection from the Raster object.
IRasterBandCollection rasterBandCollection = raster;
// Get the first band from the raster.
IRasterBand rasterBand = rasterBandCollection.item(0);
// Get the raster's dataset from the band.
IRasterDataset rasterDataset = rasterBand.getRasterDataset();

Raster bands

The RasterBand object represents an existing band of a raster dataset. You can access a raster's raster band or raster dataset. Regardless of whether it is derived from the static raster dataset or the transient raster, the raster band always represents a static band of raster data. The following code example shows how to access a raster band from a Raster or a RasterDataset object:
// Can be a raster or a raster dataset.
IRasterBandCollection rasterBandCollection = rasterOrRasterDataset;
// Get the first band of the raster.
IRasterBand rasterBand = rasterBandCollection.item(0);
The IRasterBand interface provides access to the raster colormap, raster histogram, statistics, and the raster attribute table, if they exist. The following code example accesses a raster colormap:
RasterColormap getRasterColormap(IRasterBand rasterBand)throws IOException{
    RasterColormap rasterColormap = null;
    boolean hasColormap[] = new boolean[1];
    if (hasColormap[0]){
        rasterColormap = (RasterColormap)rasterBand.getColormap();
    return rasterColormap;
A raster band contains pixel values, which can be accessed through the IRawPixels interface or through a Raster object using the IRasterEdit interface. The properties of the IRasterProps interface on the RasterBand object supports read-only format with an exception of NoDataValue, which is used in writing pixel blocks.
A file based raster band also supports the IRasterTransaction interface, which is used to manage the transaction of pixel editing.

Raster attribute table, raster colormap, and raster statistics

A raster attribute table is a generic table that stores additional information about pixels, such as, soil type, land use type, and so on. A raster attribute table is stored as a .dbf file with the same name of the dataset for file based raster data, except for storing as a value attribute table (VAT) for a grid, and as an internal table for raster data in geodatabases.
A raster attribute table is loosely coupled with the raster dataset. You can build a raster table for a single band raster dataset using IRasterDataset2, open a raster attribute table from a RasterBand using IRasterband.GetAttributeTable, or a raster using IRaster2.GetAttributeTable, edit the table the same way you edit any generic table, and set the table to the raster dataset. Assuming that the raster dataset is known, the following code example opens a raster attribute table from a raster:
IRaster2 raster2 = (IRaster2)rasterDataset.createDefaultRaster();
ITable table = raster2.getAttributeTable();
The following code example opens a raster attribute table from a raster band:
IRasterBandCollection rasterBandCollection = rasterDataset;
IRasterBand rasterBand = rasterBandCollection.item(0);
ITable table = rasterBand.getAttributeTable();
The RasterStatistics object represents the statistical information of the pixel values of a raster band. It can be retrieved from a raster band. The IRasterStatistics interface can be used to calculate the statistics of a raster band with special settings; for example, it allows you to ignore certain pixels by setting the pixel values using the IgnoreValue property or skip rows and columns by setting the skip factors in the calculation. The following code example gets a raster statistics from a raster band and retrieves statistical information:
IRasterStatistics getRasterStats(IRasterDataset rasterDataset)throws IOException{
    IRasterBandCollection rasterBandCollection = (IRasterBandCollection)
    IRasterBand rasterBand = rasterBandCollection.item(0);
    IRasterStatistics rasterStatistics = rasterBand.getStatistics();
    return rasterStatistics;
A RasterHistograms object represents the histogram information of the pixel values of a raster band. It is not cocreatable and can be retrieved from a raster band using the IRasterBand.GetHistogram method.
The RasterColormap object contains a collection of colors that are represented in a RGB form. It can be created, retrieved from a raster band using IRasterBand.GetColormap, or retrieved from a raster using IRaster2.GetColormap. You can also set the colormap of a dataset through the IRasterDatasetEdit interface.


The Raster object, in contrast to the static RasterDataset and RasterBand objects, is transient and can be modified without affecting the source data. This allows the raster to represent your requirements, as you can set a transformation, a pixel filter on a raster, specify a projection, extent, and other properties without changing the raster dataset. If you want to persist change, the modified raster can be saved to another raster dataset using the ISaveAs interface.
Although the Raster object is always transient, associate it with one or more raster bands, which provide a source for data to be read through the raster. As such, the raster is understood as a vehicle to provide resampling, transformation, and data type conversion from one or more raster bands to a desired output coordinate system.
// Create a raster with square cell size and three raster bands. 
IRaster defaultRaster = rasterDataset.createDefaultRaster();

// Create a raster with all the properties from the raster dataset.
IRasterDataset2 rasterDataset2 = rasterDataset;
IRaster fullRaster = rasterDataset2.createFullRaster();
A raster can be obtained from the RasterLayer object, which is located in the esriCarto library. See the following code example:
IRaster raster = rasterLayer.getRaster();
A raster can also be created and results in an empty raster that is not useful until one or more bands are placed into the raster, providing data for the raster to read. Creating a new raster and populating it with the desired bands provides flexibility. Any time a band is added or removed from a raster, its default settings for spatial reference, extent, and cell size can be changed, and these default settings will be applied to the raster if they have not been previously set by the user. See the following code example:
Raster raster = new Raster();
  • Setting raster properties—IRasterProps is an important interface that is used to get and set the properties of the raster, such as extent, width, height, spatial reference, pixel type, NoData value, and so on. Resampling occurs when the raster is changed geometrically, such as setting an extent, a spatial reference, or a geodata transformation. In this case, IRaster.ResampleMethod can be used to specify the resampling method and it will be applied during SaveAs or raster display.

    The following code example projects the raster by setting a new spatial reference and calling SaveAs. To project a raster with a specified datum transformation, use IRaster2.SetGeoTransformationsByRef.
void setRasterProperties(Raster raster, ISpatialReference spatialReference,
    IRasterWorkspace rasterWorkspace)throws IOException{
    raster.saveAs("MyRaster", (IWorkspace)rasterWorkspace, "GRID");
You can get the cell size of a raster; however, setting a raster's cell size should be done by adjusting the width, height, and extent of the raster. If the height or width are changed, the cell size of the raster will be recalculated by using the new height and width to divide the current raster extent. In this case, it can result in a raster with a non-square cell size. You can SaveAs a raster with a square cell size by specifying a precalculated height and width.
  • Setting transformations on raster—A raster can be transformed geometrically by setting a GeodataX from using IRaster2. To save a transformed raster, transform the extent and cell size using the GeodataXform of the raster, then set the transformed extent and cell size on the raster. See the following code example:
void setAndSaveAsXform(IRaster2 raster2, IGeodataXform geodataXform)throws
    // Get the raster's extent and cell size.
    IRasterProps rasterProps = (IRasterProps)raster2;
    IEnvelope rasterExtent = rasterProps.getExtent();
    IPnt meanCellSize = rasterProps.meanCellSize();
    double[] xCell = new double[1];
    double[] yCell = new double[1];
    xCell[0] = meanCellSize.getX();
    yCell[0] = meanCellSize.getY();
    // Set the Xform.
    // Transform the cell size, then the extent; the sequence matters.
        xCell, yCell, rasterExtent);
    // Put the transformed extent and cell size on the raster and SaveAs.
    rasterProps.setWidth((int)(rasterExtent.getWidth() / xCell[0]));
    rasterProps.setHeight((int)(rasterExtent.getHeight() / yCell[0]));
    ISaveAs pSaveAs = null;
    pSaveAs = (ISaveAs)raster2;
    pSaveAs.saveAs("c:/temp/image1.img", null, "IMAGINE Image");
The MapToPixel and PixelToMap methods are used to perform a transformation between pixel and map space. You can get the column and row in pixel space by passing x,y coordinates in map space, and vice versa. The GetPixelValue method can be used to identify a pixel value on a raster by specifying the column and row of the pixel. The following code example identifies a pixel value of the first band by passing in the x,y coordinates in map space:
Object identifyOnRaster(IRaster raster, double mapX, double mapY)throws IOException{
    IRaster2 raster2 = (IRaster2)raster;
    int col = raster2.toPixelColumn(mapX);
    int row = raster2.toPixelRow(mapY);
    return raster2.getPixelValue(0, col, row);
The raster can be transformed radiometrically by setting a PixelFilter using the IPixelOperation interface. The following code example sets a low pass filter on a raster:
void setFilter(Raster raster)throws UnknownHostException, IOException{
    // Create a pixel filter.
    RasterConvolutionFilter convolutionFilter = new RasterConvolutionFilter();
    // Set the pixel filter to the raster.
  • Editing and displaying a raster—The pixel values of the raster can be modified and written to the raster bands of the raster dataset using the IRasterEdit interface. A raster can be displayed using a RasterLayer object and various raster renderer objects in the esriCarto library.

Pixel blocks

A PixelBlock is a container for pixel arrays. It has the properties of width, height, pixel type, and number of planes. Each plane is a pixel array corresponding to one raster band. The PixelBlock object is designed to handle generic pixel arrays from any raster data source. To support different pixel types, PixelBlock transports pixels of different data types.
The PixelBlock object is used to read, modify, and write pixel values or a portion of pixel values of the raster data. To work with a pixel block, create a pixel block from a raster using the IRaster.CreatePixelBlock method to initialize the size and other properties of the pixel block. Use the IRaster.Read method to read pixel values into the pixel block, then use IPixelBlock3.GetPixelData or GetPixelDataByRef to get or modify pixel values of the pixel block. The IRasterEdit interface can be used to write the pixel block to the raster dataset. See the following code example:
void usingPixelBlock(Raster raster)throws UnknownHostException, IOException{
    // Define the size of the pixel block.
    Pnt pixelBlockSize = new Pnt();
    pixelBlockSize.setCoords(256, 256);
    // Create the pixel block.
    PixelBlock pixelBlock = (PixelBlock)raster.createPixelBlock(pixelBlockSize);
    // Read pixels from a starting pixel (10,10).
    Pnt topLeftPnt = new Pnt();
    topLeftPnt.setCoords(10, 10);, pixelBlock);
    // Modify the pixel values of the pixel block.
    pixelBlock.setPixelData(0, new Integer(10)); // not sure
    // Write the modified pixel block to the raster dataset through the Raster object.
    raster.write(topLeftPnt, pixelBlock);
For a small raster dataset, the size of the pixel block can be the size of the entire dataset, which can usually be held in memory at one time. When working with large raster data, divide the raster into small pixel blocks and read-write the pixels block by block using the RasterCursor object.
The IRaster.CreateCursor method provides a way to create a RasterCursor based on a pixel block that has the width of the whole raster and a height of 128. The IRaster2.CreateCursorEx method allows you to create a raster cursor with a user specified pixel block size or a system defined pixel block size (pass null to the pixel block size).


Some pixels in a raster dataset can have missing information; these pixels or cells are referred to as NoData. For a file based raster dataset, NoData is stored as a value, (NoData value) in the raster dataset. The pixels that have the same value as the NoData value are NoData pixels. For a database raster dataset, NoData pixels are stored as a bit mask, a two-dimensional array of 0s and 1s, where 0 represents the corresponding pixel is a NoData pixel.
The IRasterProps.(get/set)NoDataValue methods can be used to get and set the NoData value on a Raster. The NoData value will be utilized in saving (saveAs) to a new dataset.
The IRasterProps.(get/set)NoDataValue methods can also be used to get and set the NoData value on a raster band. The NoData value is utilized in writing pixel blocks to the raster dataset with the IRasterEdit or IRawPixels interefaces. For mask based NoData, use the IPixelBlock3.Mask method to set NoData when writing pixel blocks. The following code example sets the NoData value on a raster and saves it to a new raster dataset:
void saveAsRasterWithNoData(Raster raster)throws AutomationException, IOException{
    // Set NoData value.
    raster.setNoDataValue(new Integer(255));
    // Or define different NoData values for each band.
    Integer value[] = new Integer[3];
    value[0] = new Integer(1);
    value[1] = new Integer(1);
    value[2] = new Integer(32);
    // SaveAs.
    raster.saveAs("c:/temp/nodata.img", null, "IMAGINE Image");

Raster catalogs

The RasterCatalog object, a special type of feature class in geodatabases, manages a collection of raster datasets as one entity. It has a Name field that stores the name of the raster dataset, a Geometry field that stores the footprint (bounding box) of the raster dataset, and a Raster field that stores pixel values of the raster dataset. It can also contain other fields, such as Metadata, Test, and so on. Only one Raster field is allowed in a raster catalog. See the following illustration:
The Raster field of a raster catalog has a spatial reference, defined by RasterDef, which serves as the default for loading raster datasets that have unknown spatial reference. In ArcGIS 9.2, the raster datasets inside a raster catalog are allowed to store their own spatial references and geodata transformations.
In addition to defining the spatial reference for the Raster field, RasterDef also defines how raster values are managed in the raster catalog. A managed raster catalog stores raster value internally inside the raster catalog. An unmanaged raster catalog stores the paths to the raster datasets, and those raster datasets can reside in a file system. A raster catalog in an enterprise geodatabase is always managed.
The footprints of the raster datasets stored in the Geometry field are automatically managed, populated, and spatially indexed by the geodatabase. The spatial reference (the projected or geographic coordinate system, the coordinate domain and the coordinate precision) and the spatial index of the Geometry field can be set using a GeometryDef object.
The value stored in the Raster field is a RasterValue object. A raster value contains the RasterDataset and RasterStorageDef objects that describe how the raster dataset is stored in the geodatabase. You can specify the tile size, cell size, and origin of the raster dataset. You can also define the compression type and the resampling method for pyramid building.
Related to the FeatureClass object, a RasterCatalog object consists of rows. Each row is a RasterCatalogItem, which is a type of feature. A raster catalog operates the same way as a feature class when accessing or updating raster datasets in the raster catalog (for example, enumeration of the raster datasets in a raster catalog is accomplished by acquiring a standard feature cursor on the raster catalog). Insert and update can be achieved by an insert cursor or an update cursor.
To create a raster catalog, create an empty raster catalog with defined fields and add rows that contain raster values to the raster catalog.
The following code example shows how to load a raster dataset to a raster catalog and retrieve the raster dataset inside a raster catalog:
// Create a raster value from a raster dataset.
RasterValue rasterValue = new RasterValue();
// Raster catalog is a type of feature class.
IFeatureClass featureClass = rasterCatalog;
// Insert a row and set the raster value.
IFeatureCursor featureCursor = featureClass.IFeatureClass_insert(false);
IFeatureBuffer featureBuffer = featureClass.createFeatureBuffer();
featureBuffer.setValue(rasterCatalog.getRasterFieldIndex(), rasterValue);
The following code example shows how to get a raster dataset stored in the first row in a raster catalog:
IFeatureClass featureClass = rasterCatalog;
RasterCatalogItem rasterCatalogItem = (RasterCatalogItem)featureClass.getFeature(1);
rasterDataset = rasterCatalogItem.getRasterDataset();
A RasterCatalog can be displayed using the GdbRasterCatalogLayer, which is an object in the esriCarto library.

Geodata transformation and pixel filtering

A geodata transformation is a mathematical operation used to perform geometric transformations for geodatasets, such as raster datasets, feature classes, or triangulated irregular network (TIN) datasets, and so on.
ArcGIS 9.2 supports many geodata transformations including coordinate transformation (re-projection), polynomial transformation, rubber sheeting (adjust) transformation, Spline transformation, RPC transformation, and so on. The geodata transformations are represented as a Component Object Model (COM) abstract class, GeodataXform, and 10 concrete geodata transformation (Java) classes (Xform), which include AdjustXform, SplineXform, RPCXform, PolynomialXform, CoordinateXform, ApproximationXform, GCSShiftXform, GeometricXform, CompositeXform, and IdentityXform. You can also create a custom Xform by implementing interfaces of the GeodataXform abstract class. See the following illustration:
GeodataXforms can have an output spatial reference that defines the spatial reference of the data after being transformed (for example, in output space). The domains of GeodataXforms, if they exist, are also defined in the output space. All GeodataXforms perform point (IPointCollection or WKSPoint) transformation, extent (IEnvelope) transformation, and cell size transformation in forward and backward directions. To transform raster data, the RasterXformer provides the mechanism behind the scenes by calling PixelReader, PixelResampler and IRasterXform. The IRasterXform interface is used for those geodata transformations that need raster specific information to optimize the operations. Therefore, creating a custom geodata transformation to work with raster data implements the IRasterXform interface.
The following code example transforms a collection of points. The point collection, extent, and cell size are transformed by reference, for example, the input and output use the same variable.
void transformPoints(IGeodataXform geodataXform, IPointCollection pointCollection,
    IEnvelope extent, double[] cellX, double[] cellY)throws AutomationException,
        cellX, cellY, extent);
    geodataXform.transformExtent(esriTransformDirection.esriTransformForward, extent)
A GeodataXform is stored as a metadata of the raster dataset and can be modified using IGeodataSchemaEdit2.AlterGeodataTransformation. The GeodataXform of a raster dataset will be applied to transform the pixels on-the-fly during raster layer display. You can also set a GeodataXform on a raster and persist the transformed raster using ISaveAs. SaveAs a RasterDataset will not apply the GeodataXform to the pixels, but will persist the GeodataXform with the output raster dataset.
A polynomial transformation is an approximate transformation and the IPolynomialXform interface provides two ways to calculate the system residuals and root mean square (RMS). One is based on the control points using the GetSystemResidual and GetSystemRMS methods and the other is based on a set of check points using the CheckResidualRMS method.
Assuming the SourcePointCollection and TargetPointCollection are known source and target control point collections, the following code example creates a polynomial Xform:
PolynomialXform polynomialXform = new PolynomialXform();
// Assuming the input point collections contain at least six points each.
polynomialXform.defineFromControlPoints(sourcePointCollection, targetPointCollection,
  • SplineXform—The SplineXform object performs a geodata transformation using a Spline function, a piecewise polynomial that maintains continuity and smoothness between adjacent polynomials. It transforms the source control points to the target control points, while the points or pixels that are away from the control points are not always guaranteed to have higher accuracy. Spline transformation is useful when the control points are important and required to be registered precisely. Adding more control points can increase an overall accuracy of the Spline transformation. A SplineXform object can be created from two sets of control points using the DefineFromControlPoint method of the ISplineXform interface.
  • AdjustXform—The AdjustXform class, also called a rubber sheeting transformation, is built upon an algorithm that combines a polynomial transformation and a TIN interpolation technique. Adjust transformation performs a polynomial transformation using two sets of control points, then adjusts the control points locally to better match the target control points using a TIN interpolation technique. Compared to the PolynomialXform and SplineXform, AdjustXform has the characteristics of global optimization (because of the use of LSF algorithms) and local accurate approximation of the control points.

    Assuming SourcePointCollection and TargetPointCollection are known source and target control point collections, the following code example creates an AdjustXform object using the IAdjustXform interface:
AdjustXform adjustXform = new AdjustXform();
// Set control points and the polynomial order.
adjustXform.defineFromControlPoints(sourcePointCollection, targetPointCollection);
// Use interpolation to do the adjustment.
  • ApproximateXform—The ApproximateXform is used to perform an approximate transformation of a GeodataXform to achieve a better performance and is mainly for those GeodataXforms that are computationally expensive, such as CoordinateXform, AdjustXform, and so on. An ApproximateXform has an associated GeodataXform, a user defined point grid (or mesh), and a tolerance. ApproximateXform approximates its base GeodataXform by applying the true transformation only on the coarse mesh, and performing bilinear interpolation for between points. It guarantees the approximation error does not exceed the specified tolerance.

    The following code example creates an ApproximateXform object using IApproximateXform and IGeodataXformApproximation interfaces:
ApproximationXform createApproximationXform(IGeodataXform geodataXform)throws
    UnknownHostException, IOException{
    ApproximationXform approximationXform = new ApproximationXform();
    return approximationXform;
  • CoordinateXform—The CoordinateXform object is a coordinate transformation that transforms data from one projection system to another. To create a CoordinateXform, specify the output spatial reference and the input spatial reference. If the IGeodataXformApproximation interface is used, the CoordinateXform object performs an approximation of the coordinate transformation using a bilinear approximation mesh algorithm; otherwise, it transforms points using a point-to-point projection. Raster projection in ArcGIS 9.2 is implemented using this approximation technique, which projects raster data based on a 16 by 16 mesh.

    The following code example transforms a collection of points from one spatial reference to another using the ICoordinateXform2 interface:
void transformPointsWithCoordinateXForm(ISpatialReference sourceSpatialReference,
    ISpatialReference targetSpatialReference, IPointCollection pointCollection)
    throws UnknownHostException, IOException{
    // Create the CoordinateXform.
    CoordinateXform coordinateXform = new CoordinateXform();
    // Set source and target spatial reference.
    // Define approximation parameters.
    coordinateXform.setTolerance(15); // Unit in the input space.
    // The points will be transformed to a target spatial reference after this call.
  • RPCXform—Some image products delivered from satellite image companies, such as Digital Globe or Space Imaging contain RPC information in the image data. The RPC, represented as 92 parameters, defines the transformation to be used for image registration. The RPCXform object is used to support RPC transformation and image orthorectification.

    To create an RPCXform, besides setting the 92 coefficients using IRPCXform, set the forward transformation since RPC only defines the reverse transformation (ground to image). The ISensorXform interface is used to set the elevation information to perform image orthorectification.
  • Other GeodataXforms—GCSShiftXform is used to perform transformation from a nonstandard geographic coordinate system (GCS) (0 to 360) to a standard GCS (–180 to 180). For example, if your world image comes in a coordinate system of (0,360, -90 , 90), the GCSShiftXform can be used to transform your image to (-180, 180, -90,90).

    The GeometricXform is a geodata transformation based on the transformation objects defined in the Geometry library (AffineTransformation2D, ProjectiveTransformation2D, and so on). It is a wrapper of these classes and allows these classes to be incorporated in the geodata transformation pipeline.

    The IdentityXform object is an identity coordinate transformation that has no effect on coordinates and is used to associate or change the spatial reference of the data. A raster dataset created from RasterGeometryProc.Rectify has an identity transformation, while a raster dataset created from RasterGeometryProc.Register has a polynomial transformation.

    The CompositeXform consists of a set of ordered xforms and is used to manage the Xform list, for example, to add, remove, or get a geodata Xform. The sequence of the transformation being applied is from bottom to top for forward transformation and top to bottom for reverse transformation.

    To transform raster data with these geodata Xforms, the RasterXformer object plays a critical role behind the scenes. A RasterXformer contains a GeodataXform, a PixelResampler, and a PixelReader. It also contains the logic to drive these three components to perform raster transformations. Raster transformation is a reverse transformation. For a given extent (envelope) in the output space, the RasterXformer rasterizes it into pixels, then reverse transforms the pixels into the input space using the GeodataXform. Finally, it resamples the pixels, provided by the PixelReader, in the input space using the PixelResampler. If an approximation is used in the transformation, only pixels on a predefined mesh will be reversely transformed to the input space, and the values of the pixels inside the mesh will be interpolated.

    The default pixel reader used by the RasterXformer is a SimplePixelReader, and it provides input pixels, either from a Raster object or from a raw pixel read by implementing a call back method using the IRawPixelReader interface. If the input pixels are not coming from a raster, IRasterXformer2 can be used to dynamically transform pixels, such as on-fly-projected pixels from an ArcIMS layer. In this case, the developer is responsible for setting up a custom PixelReader.

    The default pixel resampler used by the RasterXformer is a SimplePixelResampler, which supports four types of resampling methods (nearest neighbor, bilinear resampling, cubic convolution, and majority). You can modify the properties of the SimplePixelResampler. The following code example sets the cubic convolution parameter to be –0.5:
void setCubicResamplingFactor(Raster raster)throws AutomationException, IOException{
    // Set raster resampling method.
    // Get the transformer and resampler.
    IRaster2 raster2 = (IRaster2)raster;
    IRasterXformer rasterXformer = raster2.getRasterXformer();
    ISimplePixelResampler simplePixelResampler = (ISimplePixelResampler)
    // Set the factor.
    simplePixelResampler.setCubicConvolutionParameter( - 0.5);

Pixel filters

Pixel filter objects perform radiometric transformation, which transforms pixel values. The PixelFilter object, an abstract class, supports the IPixelFilter and IPixelFilter2 interfaces and is implemented by seven pixel filter objects: RasterConvolutionFilter, PanSharpeningFilter, BackgroundFilter, ColormapFilter, LutFilter, MultibandFilter, RemapFilter, and a PixelFilterCollection object that allows you to define more than one pixel filter operation on a pixel block. You can also create a custom filter by implementing the IPixelFilter interface. See the following illustration:
The PanSharpeningFilter object, new at ArcGIS 9.2, performs image enhancement using various panchromatic sharpening techniques. Panchromatic sharpening uses a higher-resolution panchromatic image (or raster band) to fuse with a coregistered lower resolution multiband raster dataset. The result of this produces a multiband raster dataset with the resolution of the panchromatic raster where the two rasters fully overlap. IPansharpeningFilter is used to create a PansharpeningFilter object, set a panchromatic raster, and specify a pan-sharpening type.
ArcGIS 9.2 provides the following pan-sharpening methods: Mean, Brovey, Intensity, Hue, and Saturation (IHS), and ERSI pansharpening. These methods are based on the following general model:
The RasterConvolutionFilter object performs various pixel filtering techniques to enhance an image. The IStockConvolutionFilter interface provides access to many existing convolution filters, such as low pass filter, high pass filter, and so on. The IRasterConvolutionFilter interface allows you to create your convolution filter by defining a kernel. The following code example creates a convolution filter with a 3 by 3 kernel:
RasterConvolutionFilter rasterConvolutionFilter = new RasterConvolutionFilter();
double[][] kernel = {
         - 1,  - 1,  - 1
    , {
        2, 2, 2
    , {
         - 1,  - 1,  - 1
The pixel filter can be set on a raster and the pixel values of the raster will be transformed by the pixel filter when saving to a raster dataset or sending to the display. The following code example creates a 3 by 3 filter and applies it to a raster:
void setFilterOnRaster(Raster raster)throws UnknownHostException, IOException{
    RasterConvolutionFilter rasterConvolutionFilter = new RasterConvolutionFilter();

Raster data loading and other miscellaneous objects

This section includes objects used for mosaicing raster datasets, loading raster datasets and raster catalogs, conversion, and other miscellaneous objects.

Raster mosaicing

MosaicRaster and RasterLoader objects are used to mosaic raster data. MosaicRaster mosaics a collection of raster datasets and saves the result to a new seamless raster dataset. MosaicRaster also takes a raster catalog as input and mosaics all raster datasets or a portion of raster datasets in a raster catalog, defined by a WhereClause, into a single raster dataset. You can control how the overlapped pixels are resolved by specifying MosaicOperatorType or by creating a custom operator by implementing the IMosaicRaster class. You can also control the output colormap for mosacing colormapped raster datasets.
The MosaicRaster object supports the IRasterProps interface, which allows you to control the properties of the output raster dataset, such as pixel type, cell size, NoData, and so on. By default, the output raster takes the properties from the first raster to be mosaiced except taking the union of extents of all rasters. The MosaicRaster object also supports the ISaveAs interface, allowing you to create a mosaic output to a file based raster or to a raster dataset in geodatabase. The following code example creates one seamless raster dataset from a subset of raster datasets in a raster catalog:
// Open raster catalog.
RasterWorkspaceFactory factory = new RasterWorkspaceFactory();
workspace = (Workspace)factory.openFromFile("d:/data/pgdb.mdb", 0);
IRasterCatalog rasterCatalog = workspace.openRasterCatalog("mycatalog");
// Initialize MosaicRaster.
MosaicRaster mosaicRaster = new MosaicRaster();
// Assign RasterCatalog to MosaicRaster and define a WhereClause.
mosaicRaster.setWhereClause("state = 'CA'");
IRasterDataset rasterDataset = (IRasterDataset)mosaicRaster.saveAs("MosaicOutput",
    workspace, "SDR");
The following code example mosaics two rasters, assuming raster1 and raster2 have been created to an Imagine file:
MosaicRaster mosaicRaster = new MosaicRaster();
mosaicRaster.saveAs("output.img", openRasterWorkspace("D:/data"), "IMAGINE Image");
The RasterLoader object is used to mosaic raster data, in any format, to an existing raster dataset. Thie method works if the existing raster datasets are in any of the supported writable formats, but it works better for ArcSDE or file geodatabase raster datasets. This RasterLoader allows you to specify certain properties during data loading, such as background value to be ignored, the output colormap, and so on. This object extends the functionality of IRasterDatasetEdit.Mosaic by allowing to specify more properties for mosacing operation.
The following code example mosaics a raster to a raster dataset and uses the colormap on the raster:
RasterLoader rasterLoader = new RasterLoader();
rasterLoader.load(rasterDataset, raster);

Raster catalog loader

In ArcGIS 9.2, two loader objects are available to facilitate raster catalog loading (RasterCatalogLoader and Distributed Raster Loader (DrLoader). The RasterCatalogLoader is an object for loading a set of raster datasets or a directory of raster datasets to a geodatabase raster catalog.
Since ArcGIS 9.2 supports persisting transformation with raster datasets in a raster catalog and allows the spatial references of the raster datasets to be different from the spatial reference of the raster column, the IRasterCatalogLoader interface can be used to load raster datasets to a geodatabase raster catalog with options of applying the transformation or reprojection to the output dataset during the loading, or persisting the transformation and spatial reference as the properties of the raster dataset.
Assuming a directory contains images of universal transverse Mercator (UTM) Zone 16 and UTM Zone 17, the following code example loads those images to a raster catalog by preserving their original spatial reference. Passing true to SetProjected projects the images to the spatial reference defined in the raster field.
void rasterCatalogLoader(IPropertySet propertySet)throws UnknownHostException,
    // Define the storage property.
    RasterStorageDef rasterStorageDef = new RasterStorageDef();
    // Set the loader.
    RasterCatalogLoader rasterCatalogLoader = new RasterCatalogLoader();
    // Set to not project the raster dataset.
    // Load.
    rasterCatalogLoader.load("State_catalog", "C:/data", null);
When creating a raster catalog of RPC images, set IRasterStorageDef.setTransformed to be false to persist the RPCXform with the raster datasets during the loading.
DrLoader is used to load raster datasets or a directory of raster datasets to a raster catalog. It is designed for the ArcGIS Server environment where there are multiple containers. DrLoader distributes the loading tasks to all the worker machines to reduce loading time through parallel loading.


The RasterGeometryProc object performs polynomial transformations, such as flip, rotate, warp, and so on. It can also project rasters from one spatial reference to another. The RasterGeometryProc is built based on the PolynormialXform object, but provides easy to use methods for end users.
The RasterGeometryProc only manipulates the Raster object—not RasterBand or RasterDataset. This is because the raster is transient, as are the effects of the RasterGeometryProc. This means that any transformation will also go away when the Raster object goes out of scope.
To keep the transformed data for later use, persist the transformation using the Register or Rectify method. Register persists the transformation into the auxiliary file associated with the input dataset, which prevents the need for resampling. Rectify persists the transformed raster into a new file. Aternatively, you can use ISaveAs to save to a new raster dataset. If used on a raster contained in a RasterLayer, processing performed by this object will be visible when the display is refreshed. Utilizing the IRasterGeometryProc interface, the following code example rotates a raster based on the center of the raster and persists the transformation to the same dataset.
void registerRaster(Raster raster)throws UnknownHostException, IOException{
    RasterGeometryProc rasterGeometryProc = new RasterGeometryProc();
    rasterGeometryProc.rotate(null, 45, raster);
The ProjectFast method projects a raster to a new projection with a specified cell size. In ArcGIS 9.2, raster projection is built upon a point-to-point approximation algorithm that performs fast and accurate reprojection of raster data. The algorithm projects pixels on a predefined 16 by 16 mesh using a point-to-point projection. It then transforms the pixels inside the mesh using a bilinear interpolation technique if the error on a sub mesh is in a tolerance of a half pixel; otherwise, it projects the remaining pixels using a point-to-point projection.
Since pixels on a sub mesh will also be projected using point-to-point projection during the estimation of the interpolation accuracy, the algorithm performs point-to-point projection on a finer grid mesh and results in a much higher accuracy than the default half-pixel tolerance.
When more than one domain is involved in the raster datasets, such as raster datasets with a Cube projection, Fuller projection, or projection with a non-zero central meridian, the algorithm dividea the output space into contiguous domains by overlaying input and output domains and project pixels in each domain. This algorithm maintains the integrity of the raster dataset and guarantees that there is not discontinuity in the output raster dataset.

Colormap to RGB conversion

The RasterColormapToRGB object is used to convert between a raster dataset that contains a colormap and a three-band raster dataset.
The following code example converts a colormapped raster dataset (RasterDataset) into a RGB raster dataset:
RasterColormapToRGBConverter rasterColormapToRGBConverter = new
Raster raster = (Raster)rasterColormapToRGBConverter.createRGBRaster(rasterDataset);
raster.saveAs("RGBImage.img", openRasterWorkspace("d:/data"), "IMAGINE Image");

Other miscellanous objects

  • RasterCatalogTable is a legacy object used to represent a table based raster catalog, and SdeRasterCatalogTable is used for the 8.x style raster catalogs.
  • The RasterDomainExtractor object extracts a polygon boundary from a raster along the borders of pixels that are not NoData (value pixels).
  • RasterPicture can load a raster into a Picture object.
  • UniqueValues, StatsHistogram, RasterCalcStatsHistogram, and RasterCalcUniqueValues are helper objects for raster renderers, which are in the esriCarto library.
  • DERasterDataset, DERasterBand, and other data element objects are used in scripting language in geoprocessing.