Supported with:
Additional library information: Contents, Object Model Diagram
To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
See the following sections for more information about this namespace:
[C#]
[C#]
[C#]
[C#]
- Engine
- ArcGIS for Desktop Basic
- ArcGIS for Desktop Standard
- ArcGIS for Desktop Advanced
- Server
Additional library information: Contents, Object Model Diagram
To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
The DataSourcesRaster library contains raster-related classes in the following categories:
- Classes that access the three raster data models—raster datasets, raster catalogs, and mosaic datasets—from various data sources including file systems, personal geodatabases, file geodatabases, and ArcSDE geodatabases
- Classes that perform geometric transformations such as polynomial transformation, Rational Polynomial coefficient (RPC) camera model, and frame camera model
- Classes used for on-the-fly raster processing, such as creating shaded relief, pan-sharpening, and arithmetic operations
- Classes used for creating mosaics from data of various raster formats and multiple satellite sensors
- Classes used for loading raster datasets and raster catalogs in geodatabases, and other miscellaneous classes
The following abstract classes can be instantiated:
- GeodataXform
- RasterFunction
- RasterFunctionArguments
- RasterBuilder
- Crawler
- PixelResampler
- PixelReader
- MosaicOperato
Classes used for rendering raster data, accessing and rendering image services, as well as accessing and rendering Web Coverage Service (WCS) services are located in the Carto library.
See the following sections for more information about this namespace:
- Raster data access classes
- Function raster datasets and raster functions
- Mosaic datasets and raster types
- Geodata transformation and pixel filtering
- Raster data loading and other miscellaneous objects
Raster data access classes
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 global resource information database (GRID), tagged image file format (TIFF), ERDAS IMAGINE, and Joint Photographic Experts Group (JPEG). It also supports raster data in geodatabases, such as file geodatabases, personal geodatabases, and ArcSDE geodatabases. Regardless of the data sources, the following three information models are used to model raster data:
- Raster dataset
- Raster catalog
- Mosaic dataset
A raster dataset represents one or multiple arrays of pixels, as well as associated information that is stored as a particular raster format in a storage media, such as a file system or a geodatabase. A raster catalog is a special type of feature class that can store both the footprints of raster datasets and the raster datasets in geodatabases. The raster catalog data model is used to manage a collection of raster datasets. A mosaic dataset, new at ArcGIS 10, is used to manage rasters from various raster formats and multiple sensors, and to provide a mosaic view of the data.
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 also contain pyramids, a stack of down resample pixels stored in the dataset and used for fast display of large raster datasets, statistics of the pixels, and many other properties.
A single band raster dataset can contain a color map consisting of a set of colors (red, green, blue [RGB]) used in displaying the pixels, and a raster attribute table that stores additional information about the pixels, such as land use or soil type.
As a type of geodataset, a raster dataset can contain a geodata transformation and a spatial reference. The geodata transformation defines how the pixels are transformed during access, and a spatial reference defines the coordinate system of the pixels to which they are mapped.
If the pixels or cells of a raster dataset have missing information, those cells are called NoData cells. A file-based raster dataset uses a NoData value to represent NoData, while a geodatabase raster dataset uses a bit mask to represent NoData.
The raster data access objects are shown in the following diagram:
Workspace
A Workspace object 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, then use the IRasterWorkspace2 or IRasterWorkspaceEx interface. The following functions create workspaces from difference sources. These functions are referenced throughout this topic.
- The OpenRasterWorkspace function opens a raster workspace from a given directory as shown in the following code:
IRasterWorkspace OpenRasterWorkspace(string filePath)
{
Type factoryType = Type.GetTypeFromProgID(
"esriDataSourcesRaster.RasterWorkspaceFactory");
IWorkspaceFactory wsFactory = (IWorkspaceFactory)Activator.CreateInstance
(factoryType);
IRasterWorkspace rasterWS = (IRasterWorkspace)wsFactory.OpenFromFile(filePath, 0)
;
return rasterWS;
}
[VB.NET]
Private Function OpenRasterWorkspace(ByVal filePath As String) As IRasterWorkspace
Dim factoryType As Type = Type.GetTypeFromProgID("esriDataSourcesRaster.RasterWorkspaceFactory")
Dim wsFactory As IWorkspaceFactory = (IWorkspaceFactory)Activator.CreateInstance(factoryType)
Dim rasterWS As IRasterWorkspace = CType(wsFactory.OpenFromFile(filePath, 0), IRasterWorkspace)
Return rasterWS
End Function
- The OpenFileGDBWorkspace function opens a file geodatabase workspace as shown in the following code:
IRasterWorkspaceEx OpenFileGDBWorkspace(string filePath)
{
Type factoryType = Type.GetTypeFromProgID(
"esriDataSourcesGDB.FileGDBWorkspaceFactory");
IWorkspaceFactory wsFactory = (IWorkspaceFactory)Activator.CreateInstance
(factoryType);
IRasterWorkspaceEx rasterWS = (IRasterWorkspaceEx)wsFactory.OpenFromFile
(filePath, 0);
return rasterWS;
}
[VB.NET]
Private Function OpenFileGDBWorkspace(ByVal filePath As String) As IRasterWorkspaceEx
Dim factoryType As Type = Type.GetTypeFromProgID("esriDataSourcesGDB.FileGDBWorkspaceFactory")
Dim wsFactory As IWorkspaceFactory = CType(Activator.CreateInstance(factoryType), IWorkspaceFactory)
Dim rasterWS As IRasterWorkspaceEx = CType(wsFactory.OpenFromFile(filePath, 0), IRasterWorkspaceEx)
Return rasterWS
End Function
- The OpenSDEWorkspace function opens an ArcSDE workspace by passing the connection information as shown in the following code:
IRasterWorkspaceEx OpenSDEWorkspace(string sServer, string sInstance, string sDB,
string sUser, string sPasswd, string sVersion)
{
Type factoryType = Type.GetTypeFromProgID(
"esriDataSourcesGDB.SdeWorkspaceFactory");
IWorkspaceFactory wsFactory = (IWorkspaceFactory)Activator.CreateInstance
(factoryType);
Dim sdeConnection As IPropertySet = New PropertySetClass();
sdeConnection.SetProperty("Server", sServer);
sdeConnection.SetProperty("Instance", sInstance);
sdeConnection.SetProperty("Database", sDB);
sdeConnection.SetProperty("User", sUser);
sdeConnection.SetProperty("Password", sPasswd);
sdeConnection.SetProperty("Version", sVersion);
IRasterWorkspaceEx ws = CType(wsFactory.Open(sdeConnection, 0),
IRasterWorkspaceEx);
Return ws;
}
[VB.NET]
Private Function OpenSDEWorkspace(ByVal sServer As String, ByVal sInstance As String, ByVal sDB As String, ByVal sUser As String, ByVal sPasswd As String, ByVal sVersion As String) As IRasterWorkspaceEx
Dim factoryType As Type = Type.GetTypeFromProgID("esriDataSourcesGDB.SdeWorkspaceFactory")
Dim wsFactory As IWorkspaceFactory = (IWorkspaceFactory)Activator.CreateInstance(factoryType)
Dim sdeConnection As IPropertySet = New PropertySetClass()
sdeConnection.SetProperty ("Server", sServer)
sdeConnection.SetProperty ("Instance", sInstance)
sdeConnection.SetProperty("Database", sDB)
sdeConnection.SetProperty ("User", sUser)
sdeConnection.SetProperty ("Password", sPasswd)
sdeConnection.SetProperty ("Version", sVersion)
Dim ws As IRasterWorkspaceEx = CType(wsFactory.Open(sdeConnection, 0), IRasterWorkspaceEx)
Return ws
End Function
To access a RasterDataset from a file raster format, use IRasterWorkspace2. The following code opens a raster dataset from an IMAGINE file in a given directory:
//Open a raster dataset from a file system.
IRasterWorkspace ws = OpenRasterWorkspace(@"d:\data");
IRasterDataset rasterDataset = ws.OpenRasterDataset("airphoto.img");
[VB.NET]
'Open a raster dataset from a file system.
Dim ws As IRasterWorkspace = OpenRasterWorkspace ("d:\data")
Dim rasterDataset As IRasterDataset = ws.OpenRasterDataset("airphoto.img")
IRasterWorkspaceEx is used to open and create a RasterDataset and a RasterCatalog in a geodatabase. The following code opens a raster dataset and a raster catalog from a file geodatabase:
[C#]
//Open a raster catalog from a file geodatabase workspace.
IRasterWorkspaceEx wsFGDB = OpenFileGDBWorkspace(@"d:\data\fgdb_images.gdb");
IRasterCatalog rasterCatalog = wsFGDB.OpenRasterCatalog("RedlandImages");
//Open a raster dataset from an SDE workspace.
IRasterWorkspaceEx wsSDE = OpenSDEWorkspace("myserver", "5151", "myuser",
"mydatabase", "mypassws", "SDE.DEFAULT");
IRasterDataset rasterdataset1 = wsSDE.OpenRasterDataset("airphoto");
[VB.NET]
'Open a raster catalog from a file geodatabase workspace.
Dim wsFGDB As IRasterWorkspaceEx = OpenFileGDBWorkspace("d:\data\fgdb_images.gdb")
Dim rasterCatalog As IRasterCatalog = wsFGDB.OpenRasterCatalog("RedlandImages")
'Open a raster dataset from an SDE workspace.
Dim wsSDE As IRasterWorkspaceEx = OpenSDEWorkspace("myserver", "5151", "myuser", "mydatabase", "mypassws", "SDE.DEFAULT")
Dim rasterdataset1 As IRasterDataset = wsSDE.OpenRasterDataset("airphoto")
To access a mosaic dataset in a geodatabase, create a MosaicWorkspaceExtension using the MosaicWorkspaceExtensionHelper class, then use the IMosaicWorkspaceExtension interface to open or create a mosaic dataset. The following code opens a mosaic dataset:
[C#]
public static IMosaicDataset OpenMosaicDataset(IWorkspace ws, String mdName)
{
IMosaicWorkspaceExtensionHelper MosaicWsHelper = new
MosaicWorkspaceExtensionHelperClass();
IMosaicWorkspaceExtension mosaicWsExtension = MosaicWsHelper.FindExtension(ws);
IMosaicDataset mosaicDataset = mosaicWsExtension.MosaicDataset(mdName);
return mosaicDataset;
}
[VB.NET]
Private Function OpenMosaicDataset(ws As IWorkspace, mdName As String)
Dim MosaicWsHelper As IMosaicWorkspaceExtensionHelper = New MosaicWorkspaceExtensionHelperClass()
Dim mosaicWsExtension As IMosaicWorkspaceExtension = MosaicWsHelper.FindExtension(ws)
Dim mosaicDataset = mosaicWsExtension.OpenMosaicDataset(mdName)
End Function
Raster datasets
The RasterDataset class represents a raster dataset stored in a storage media, file system, geodatabase, or in memory. RasterDataset is a file raster dataset if it is opened from a file system or a personal geodatabase, and it 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 a file system, is also a file raster dataset. ArcGIS allows you to create an in-memory RasterDataset where the pixels are stored in memory. This type of raster dataset has the characteristics of a file raster dataset. A file raster dataset and a geodatabase raster dataset behave the same except for some minor differences.
The RasterDataset, RasterBand, and Raster objects are shown in the following diagram:
Creating raster datasets in various workspaces requires specifying the properties of the raster data to be created, as well as the properties of the storage container. In an ArcSDE geodatabase, raster data is stored as a set of database management system (DBMS) tables that are used to manage the pixel values, pyramids, and other auxiliary information. The pixels of raster data are divided into small tiles and each tile is stored as a binary large object (BLOB) in a row of the block table. The raster column in the business table defines the properties of the raster dataset and the geometry column defines properties of the footprint of the raster dataset. A file geodatabase raster has a similar implementation as an ArcSDE geodatabase. The only difference is that raster data is stored as a set of file geodatabase tables in the file system instead of in a relational geodatabase.
IRasterWorkspaceEx is used to create a raster dataset and a raster catalog in a geodatabase. When creating data in a geodatabase, RasterDef can be used to set the properties of the raster field, and RasterStorageDef can be used to specify the storage properties such as tile size, cell size, pyramid origin, and compression. Because raster data in a personal geodatabase is implemented by converting it to an IMAGINE file format and managing it in the personal geodatabase, only some of the raster storage properties apply to a personal geodatabase (such as cell size and compression).
Creating a geodatabase raster dataset using IRasterWorkspaceEx initially creates an empty raster dataset, which servers as a placeholder for the specified properties of the raster dataset. The extent and pixel values of the dataset can be populated by mosaicking from other raster datasets or, alternatively, writing using PixelBlock.
To create a raster dataset in any supported file raster format using IRasterWorkspace2, 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. If IRasterWorkspace2 is used to create a geodatabase raster dataset, the default storage parameters are used. The following code creates a TIFF file with a dimension of 1024 by 1024 and a cell size of 30 meters:
[C#]
IRasterWorkspace2 ws = (IRasterWorkspace2)OpenRasterWorkspace(@"d:\data");
IPoint origin = new PointClass();
origin.PutCoords(100, 100);
ISpatialReference sr = new UnknownCoordinateSystemClass();
IRasterDataset newRaster = ws.CreateRasterDataset("myimage.tif", "TIFF", origin,
1024, 1024, 30, 30, 1, rstPixelType.PT_UCHAR, sr, true);
[VB.NET]
Dim ws As IRasterWorkspace2 = CType(OpenRasterWorkspace("d:\data"), IRasterWorkspace2)
Dim origin As IPoint = New PointClass()
origin.PutCoords(100, 100)
Dim sr As ISpatialReference = New UnknownCoordinateSystemClass()
Dim newRaster As IRasterDataset = ws.CreateRasterDataset("myimage.img", "IMAGINE Image", origin, 1024, 1024, 30, 30, 1, rstPixelType.PT_UCHAR, sr, True)
As a type of dataset, RasterDataset 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 RasterDataset is a type of geodataset and supports the IGeoDataset and IGeoDataset2 interfaces. A RasterDataset has an extent, a spatial reference, and a geodata transformation (GeodataXform). The geodata transformation is used to transform the pixels geometrically. Normally, a raster dataset has an IdentityXform, which does not change the extent and spatial reference of the data. In some cases, a raster dataset can contain a non-IdentityXform, for example a raster dataset created from the IRasterGeometryProc.Register method (using the Georeferencing tool's Update in ArcMap) contains a PolynomialXform, which stores the transformation added to the raster dataset.
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 they can be retrieved using the IGeoDataset interface. Before a transformation is applied, the extent and spatial reference are called native extent and native spatial reference. The native extent and native spatial reference can be retrieved from the IGeoDataset2 interface. The following code shows the use of this interface:
[C#]
void GetDatasetXform(IRasterDataset rasterDataset)
{
//Get the Xform.
IGeoDataset2 geoDataset = (IGeoDataset2)rasterDataset;
IGeodataXform xform = geoDataset.GeodataXform;
//Get the native extent.
IEnvelope nativeExtent = geoDataset.NativeExtent;
//Get the native spatial reference.
ISpatialReference nativeSR = geoDataset.NativeSpatialReference;
}
[VB.NET]
Private Sub GetDatasetXform(ByVal rasterDataset As IRasterDataset)
'Get the Xform.
Dim geoDataset As IGeoDataset2 = CType(rasterDataset, IGeoDataset2)
Dim xform As IGeodataXform = geoDataset.GeodataXform
'Get the native extent.
Dim nativeExtent As IEnvelope = geoDataset.NativeExtent
'Get the native spatial reference.
Dim nativeSR As ISpatialReference = geoDataset.NativeSpatialReference
End Sub
The spatial reference and the geodata transformation of a raster dataset can be altered using the IGeoDatasetSchemaEdit2 interface.
The IRasterDatasetEdit3 interface is used to work with the raster attribute table, color maps, statistics, and histograms. You can build, add, and delete the properties of a RasterDataset. You can also merge pixels from another raster dataset to the current raster dataset through the IRasterDatasetEdit3.Mosaic method.
The IRasterPyramid3 interface is used for creating raster pyramids. You can build pyramids for a specified pyramid level and a specified resampling method.
ISaveAs is used to perform format conversion. ArcGIS supports writing to many raster formats such as GRID, TIFF, IMAGINE, JEPG2000, JPEG, PNG, BMP, GIF, MEM (in memory raster), and geodatabases. The following code saves a raster dataset to the IMAGINE format:
[C#]
void SaveAs(IRasterDataset rasterDataset)
{
ISaveAs saveAs = (ISaveAs)rasterDataset;
IWorkspace ws = (IWorkspace)OpenRasterWorkspace(@"d:\data");
saveAs.SaveAs("mygrid", ws, "GRID");
}
[VB.NET]
Private Sub SaveAs(ByVal rasterDataset As IRasterDataset)
Dim saveAs As ISaveAs = CType(rasterDataset, ISaveAs)
Dim ws As IWorkspace = CType(OpenRasterWorkspace("d:\data"), IWorkspace)
saveAs.SaveAs("mygrid", ws, "GRID")
End Sub
To specify storage properties (such as tile size, compression type, and handling pyramids) during the save as operation, use the ISaveAs2 interface and RasterStorageDef class. The following code saves to a raster dataset in a file geodatabase with 64 by 64 tile size and JPEG2000 compression:
[C#]
void SaveAsWithCompression(IRasterDataset rasterDataset)
{
ISaveAs2 saveAs = (ISaveAs2)rasterDataset;
//Set the storage properties.
IRasterStorageDef2 storageDef = (IRasterStorageDef2)new RasterStorageDefClass();
storageDef.CompressionType =
esriRasterCompressionType.esriRasterCompressionJPEG2000;
storageDef.CompressionQuality = 30;
storageDef.Tiled = true;
storageDef.TileHeight = 64;
storageDef.TileWidth = 64;
//Set the output workspace.
IWorkspace ws = (IWorkspace)OpenFileGDBWorkspace(@"d:\data\fgdb.gdb");
saveAs.SaveAsRasterDataset("compressedRaster", ws, "GDB", storageDef);
}
[VB.NET]
Private Sub SaveAsWithCompression(ByVal rasterDataset As IRasterDataset)
Dim saveAs As ISaveAs2 = CType(rasterDataset, ISaveAs2)
'Set the storage properties.
Dim storageDef As IRasterStorageDef2 = CType(New RasterStorageDefClass(), IRasterStorageDef2)
storageDef.CompressionType = esriRasterCompressionType.esriRasterCompressionJPEG2000
storageDef.CompressionQuality = 30
storageDef.Tiled = True
storageDef.TileHeight = 64
storageDef.TileWidth = 64
'Set the output workspace.
Dim ws As IWorkspace = CType(OpenFileGDBWorkspace("d:\data\fgdb.gdb"), IWorkspace)
saveAs.SaveAsRasterDataset("compressedRaster", ws, "GDB", storageDef)
End Sub
A RasterDataset is composed of one or more persistent raster bands. You can get a RasterBand through the IRasterBandCollection.Item method. Other methods of the IRasterBandCollection interface, such as Add or Remove, have no effect on the RasterDataset. IRasterBandCollection.SaveAs produces the same result as ISaveAs.SaveAs.
The RasterDataset class can be used to initiate a Raster. In addition to being accessed through a workspace, the RasterDataset can also be retrieved from a RasterBand using the RasterDataset property. To access the RasterDataset from a Raster, first access a band from the Raster, then obtain a reference to the dataset from the band. This technique is shown in the following code:
[C#]
void GetRasterDataset(IRaster raster)
{
IRasterBandCollection bandCol = (IRasterBandCollection)raster;
IRasterBand rasterBand = bandCol.Item(0);
IRasterDataset rasterDataset = rasterBand.RasterDataset;
}
[VB.NET]
Private Sub GetRasterDataset(ByVal raster As IRaster)
Dim bandCol As IRasterBandCollection = CType(raster, IRasterBandCollection)
Dim rasterBand As IRasterBand = bandCol.Item(0)
Dim rasterDataset As IRasterDataset = rasterBand.RasterDataset
End Sub
Raster bands
The RasterBand class represents an existing band of a raster dataset. You can access a RasterBand of a Raster or a RasterDataset. Regardless of whether it is derived from the static RasterDataset or the transient Raster, the RasterBand always represents a static band of raster data.
The IRasterBand interface provides access to the raster color map, histogram, statistics, and attribute table if they exist. The following code accesses a raster color map:
[C#]
void GetColormap(IRasterDataset rasterDataset)
{
IRasterBandCollection bandCol = (IRasterBandCollection)rasterDataset;
IRasterBand rasterBand = bandCol.Item(0);
IRasterColormap rasterColormap = rasterBand.Colormap;
IRaster2 raster = (IRaster2)rasterDataset.CreateDefaultRaster();
rasterColormap = raster.Colormap;
}
[VB.NET]
Private Sub GetColormap(ByVal rasterDataset As IRasterDataset)
Dim bandCol As IRasterBandCollection = CType(rasterDataset, IRasterBandCollection)
Dim rasterBand As IRasterBand = bandCol.Item(0)
Dim rasterColormap As IRasterColormap = rasterBand.Colormap
Dim raster As IRaster2 = CType(rasterDataset.CreateDefaultRaster(), IRaster2)
rasterColormap = raster.Colormap
End Sub
A raster band contains pixel values, which can be accessed through the IRawPixels interface or through the Raster class using the IRasterEdit interface. The properties of the IRasterProps interface on RasterBand supports read-only with the exception of NoDataValue, which is used in writing pixel blocks.
A file-based RasterBand also supports the IRasterTransaction interface, which is used to manage the pixel editing transaction.
Raster attribute table, raster color map, and raster statistics
A raster attribute table is a generic table that stores pixel information, such as soil type and land use type. A raster attribute table is stored as a .dbf file (with the same name as the dataset) for file-based raster data, 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 (except a grid VAT). You can build a raster table for a single band raster dataset using IRasterDataset2, open a raster attribute table from a RasterBand using IRasterBand.AttributeTable or from a Raster using IRaster2.AttributeTable, edit the table the same way you would edit a generic table, and set the table to the raster dataset. Assuming that RasterDataset is known, the following code opens a raster attribute table from a Raster:
[C#]
void RasterAttributeTable(IRaster raster)
{
IRaster2 raster = (IRaster2)raster;
ITable rasterTable = raster.AttributeTable;
}
[VB.NET]
Private Sub RasterAttributeTable(ByVal raster As IRaster)
Dim raster As IRaster2 = CType(raster, IRaster2)
Dim rasterTable As ITable = raster.AttributeTable
End Sub
The following code opens a raster attribute table from a raster band:
[C#]
void RasterAttributeTable(IRasterDataset rasterDataset)
{
IRasterBandCollection bandCol = (IRasterBandCollection)rasterDataset;
IRasterBand rasterBand = bandCol.Item(0);
ITable rasterTable = rasterBand.AttributeTable;
}
[VB.NET]
Dim bandCol As IRasterBandCollection = CType(rasterDataset, IRasterBandCollection)
Dim rasterBand As IRasterBand = bandCol.Item(0)
Dim rasterTable As ITable = rasterBand.AttributeTable
The RasterStatistics class represents the statistical information of the pixel values of a raster band. It is not creatable and can be retrieved from a RasterBand. The IRasterStatistics interface can be used to calculate the statistics of a raster band with some special settings, for example, it allows you to ignore certain pixels by setting the pixel values using the IgnoredValues property, or to skip some rows and columns by setting the skip factors in the calculation. The following code gets a RasterStatistics from a RasterBand and retrieves statistical information:
[C#]
void CalculateStats(IRasterDataset rasterDataset)
{
IRasterBandCollection bandCollection = (IRasterBandCollection)rasterDataset;
IRasterBand rasterBand = bandCollection.Item(0);
IRasterStatistics rasterStats = rasterBand.Statistics;
rasterStats.SkipFactorX = 100;
rasterStats.SkipFactorY = 100;
rasterStats.Recalculate();
}
[VB.NET]
Private Sub CalculateStats(ByVal rasterDataset As IRasterDataset)
Dim bandCollection As IRasterBandCollection = CType(rasterDataset, IRasterBandCollection)
Dim rasterBand As IRasterBand = bandCollection.Item(0)
Dim rasterStats As IRasterStatistics = rasterBand.Statistics
rasterStats.SkipFactorX = 100
rasterStats.SkipFactorY = 100
rasterStats.Recalculate()
End Sub
The RasterHistogram class represents the histogram information of the pixel values of a raster band. It is not creatable and can be retrieved from a RasterBand using the IRasterBand.Histogram property.
The RasterColormap class contains a collection of colors that are represented in an RGB form. It can be created by loading from a .clr file or defining the RGB colors using the IRasterColormap3 interface. A RasterColormap can be retrieved from a RasterBand using IRasterBand.Colormap, or retrieved from a Raster using IRaster2.Colormap. You can also set the color map of a dataset through the IRasterDatasetEdit interface.
Raster
The Raster class, in contrast to the static RasterDataset and RasterBand classes, is transient in nature and can be modified without affecting the source data. This allows the raster to represent what you want, for example, you can set a transformation or a pixel filter on a raster, specify a projection or extent, and set 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 Raster is always transient in nature, it must be associated with one or more raster bands, which provides a source for the data to be read through the raster. As such, the Raster is most easily understood as a vehicle to provide resampling, transformation, and data type conversion from one or more raster bands to a desired output coordinate system.
Creating a raster
A raster can be created from a RasterDataset using the following methods:
- The IRasterDataset2.CreateFullRaster method creates a raster with all the properties from the raster dataset, such as the number of bands and width and height of the raster dataset.
- The IRasterDataset.CreateDefaultRaster method creates a raster that has a square cell size and contains only three raster bands even if the dataset has more than three bands. The three bands are the default bands used in the raster RGB renderer and are determined by the settings for default raster behavior made on the RasterDefaultsEnv class in the Carto library.
See the following code example:
[C#]
void CreateRaster(IRasterDataset rasterDataset)
{
//Create a default raster.
IRaster raster = rasterDataset.CreateDefaultRaster();
//Create a raster with all bands.
IRasterDataset2 rasterDataset2 = (IRasterDataset2)rasterDataset;
IRaster raster2 = rasterDataset2.CreateFullRaster();
}
[VB.NET]
Private Sub CreateRaster(ByVal rasterDataset As IRasterDataset)
'Create a default raster.
Dim raster As IRaster = rasterDataset.CreateDefaultRaster()
'Create a raster with all bands.
Dim rasterDataset2 As IRasterDataset2 = CType(rasterDataset, IRasterDataset2)
Dim raster2 As IRaster = rasterDataset2.CreateFullRaster()
End Sub
A raster can be obtained from the RasterLayer class in the Carto library.
A raster is also creatable. Creating a raster 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 raster and populating it with the desired bands provides flexibility. When a band is added or removed from a raster, its default settings for spatial reference, extent, and cell size can change, and these default settings are applied to the raster if they have not been previously set. See the following code example:
void CreateRaster(IRasterDataset rasterDataset)
{
//Create an empty raster and append bands.
IRasterBandCollection newRaster = new RasterClass();
newRaster.AppendBands((IRasterBandCollection)rasterDataset);
}
[VB.NET]
Private Sub CreateRaster(ByVal rasterDataset As IRasterDataset)
'Create an empty raster and append bands.
Dim newRaster As IRasterBandCollection = New RasterClass()
newRaster.AppendBands(CType(rasterDataset, IRasterBandCollection))
End Sub
Setting raster properties
IRasterProps is used to get and set the properties of the raster, such as extent, width, height, spatial reference, pixel type, and NoData value. Resampling occurs when the raster is changed geometrically, such as setting an extent, a spatial reference, or a geodata transformation. In this case, the IRaster.ResampleMethod property can be used to specify the resampling method, and it will be applied during SaveAs or during raster display. The following code projects the raster by setting a new spatial reference and calling SaveAs. To project a raster with a specified datum transformation, use IRaster2.GeoTransformations.
[C#]
void SetRasterProperties(IRaster raster, ISpatialReference sr, IWorkspace ws)
{
IRasterProps rasterProps = (IRasterProps)raster;
rasterProps.SpatialReference = sr;
raster.ResampleMethod = rstResamplingTypes.RSP_BilinearInterpolation;
ISaveAs saveAs = (ISaveAs)raster;
saveAs.SaveAs("projectedimage.tif", ws, "TIFF");
}
[VB.NET]
Private Sub SetRasterProperties(ByVal raster As IRaster, ByVal sr As ISpatialReference, ByVal ws As IWorkspace)
Dim rasterProps As IRasterProps = CType(raster, IRasterProps)
rasterProps.SpatialReference = sr
raster.ResampleMethod = rstResamplingTypes.RSP_BilinearInterpolation
Dim saveAs As ISaveAs = CType(raster, ISaveAs)
saveAs.SaveAs("projectedimage.tif", ws, "TIFF")
End Sub
You can get the cell size of a raster. However, setting a cell size for a raster should be done by adjusting the width, height, and extent of the raster. If the height and/or width are changed, the cell size of the raster will be recalculated using the new height and width to divide the current raster extent. In this case, it will most likely result in a raster with non-square cell size. To use SaveAs on a raster with a square cell size, specify a precalculated height and width.
Setting transformations on a raster
A raster can be transformed geometrically by setting a GeodataXform using IRaster2. To save a transformed raster, you must transform the extent and cell size using the GeodataXform of the raster, and set the transformed extent and cell size on the raster as shown in the following code:
[C#]
void SetAndSaveAsXform(IRaster2 raster, IGeodataXform xform, IWorkspace ws)
{
//Get the extent and cell size of the raster.
IRasterProps rasterProps = (IRasterProps)raster;
IEnvelope extent = rasterProps.Extent;
IPnt cellSize = rasterProps.MeanCellSize();
double xCell = cellSize.X;
double yCell = cellSize.Y;
//Set the geodataXform.
raster.GeodataXform = xform;
//Transform the cell size first, then the extent. The sequence matters.
xform.TransformCellsize(esriTransformDirection.esriTransformForward, ref xCell,
ref yCell, extent);
xform.TransformExtent(esriTransformDirection.esriTransformForward, extent);
//Put the transformed extent and cell size on the raster.
rasterProps.Extent = extent;
rasterProps.Width = (int)(extent.Width / xCell);
rasterProps.Height = (int)(extent.Width / yCell);
//Save the transformed image.
ISaveAs saveAs = (ISaveAs)raster;
saveAs.SaveAs(@"c:\temp\result.img", null, "IMAGINE Image");
}
[VB.NET]
Private Sub SetAndSaveAsXform(ByVal raster As IRaster2, ByVal xform As IGeodataXform, ByVal ws As IWorkspace)
'Get the extent and cell size of the raster.
Dim rasterProps As IRasterProps = CType(raster, IRasterProps)
Dim extent As IEnvelope = rasterProps.Extent
Dim cellSize As IPnt = rasterProps.MeanCellSize()
Dim xCell As Double = cellSize.X
Dim yCell As Double = cellSize.Y
'Set the geodataXform.
raster.GeodataXform = xform
'Transform the cell size first, then the extent. The sequence matters.
xform.TransformCellsize(esriTransformDirection.esriTransformForward, xCell, yCell, extent)
xform.TransformExtent(esriTransformDirection.esriTransformForward, extent)
'Put the transformed extent and cell size on the raster.
rasterProps.Extent = extent
rasterProps.Width = CInt(Fix(extent.Width / xCell))
rasterProps.Height = CInt(Fix(extent.Width / yCell))
'Save the transformed image.
Dim saveAs As ISaveAs = CType(raster, ISaveAs)
saveAs.SaveAs("c:\temp\result.img", Nothing, "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 and y coordinates in map space and vice versa. GetPixelValue can be used to identify a pixel value on a raster by specifying the column and row of the pixel. The following code identifies a pixel value of the first band by passing in the x,y coordinates in map space:
[C#]
void IdentifyOnRaster(IRaster raster, double xmap, double ymap)
{
IRaster2 raster2 = (IRaster2)raster;
int col = raster2.ToPixelColumn(xmap);
int row = raster2.ToPixelRow(ymap);
double idValue = (double)raster2.GetPixelValue(0, col, row);
}
[VB.NET]
Private Sub IdentifyOnRaster(ByVal raster As IRaster, ByVal xmap As Double, ByVal ymap As Double)
Dim raster2 As IRaster2 = CType(raster, IRaster2)
Dim col As Integer = raster2.ToPixelColumn(xmap)
Dim row As Integer = raster2.ToPixelRow(ymap)
Dim idValue As Double = CDbl(raster2.GetPixelValue(0, col, row))
End Sub
The raster can be transformed radiometrically by setting PixelFilter using the IPixelOperation interface. The following code sets a low pass filter on a raster:
[C#]
void SetFilter(IRaster raster)
{
//Create the filter.
IStockConvolutionFilter pixelFilter = new RasterConvolutionFilterClass();
pixelFilter.Type = esriRasterFilterTypeEnum.esriRasterFilterSmoothing3x3;
//Set the filter to the raster.
IPixelOperation pixelOperation = (IPixelOperation)raster;
pixelOperation.PixelFilter = (IPixelFilter)pixelFilter;
}
[VB.NET]
Private Sub SetFilter(ByVal raster As IRaster)
'Create the filter.
Dim pixelFilter As IStockConvolutionFilter = New RasterConvolutionFilterClass()
pixelFilter.Type = esriRasterFilterTypeEnum.esriRasterFilterSmoothing3x3
'Set the filter to the raster.
Dim pixelOperation As IPixelOperation = CType(raster, IPixelOperation)
pixelOperation.PixelFilter = CType(pixelFilter, IPixelFilter)
End Sub
Editing and displaying a raster
The pixel values of the raster can be modified and written directly to the raster bands of the raster dataset using the IRasterEdit interface. A raster can be displayed using the RasterLayer class and various raster renderer objects in the Carto library.
Pixel blocks
The PixelBlock class 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 class can handle generic pixel arrays from any raster data source. To support different pixel types, PixelBlock transports pixels in a SafeArray, which can contain many different data types.
The PixelBlock class is used to read, modify, and write pixel values or a portion of pixel values of the raster data. Create a pixel block from a raster using the IRaster.CreatePixelBlock method. This initializes the size and other properties of the pixel block. Use the IRaster.Read method to read the pixel values into the pixel block, then use IPixelBlock3.PixelData or PixelDataByRef to get or modify the 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:
[C#]
void UsingPixelBlock(IRaster raster)
{
//Create a pixel block using the size provided by the system.
IRaster2 raster2 = (IRaster2)raster;
IPixelBlock pixelBlock = raster2.CreateCursorEx(null).PixelBlock;
int w = pixelBlock.Width;
int h = pixelBlock.Height;
//Read the first pixel block.
IPnt topleftCorner = new PntClass();
topleftCorner.SetCoords(0, 0);
raster.Read(topleftCorner, pixelBlock);
//Modify one pixel value at locations w-1 and h-1
//(assume the raster has a pixel type of uchar).
IPixelBlock3 pixelBlock3 = (IPixelBlock3)pixelBlock;
System.Array pixels = (System.Array)pixelBlock3.get_PixelData(0);
pixels.SetValue(Convert.ToByte(10), w - 1, h - 1);
pixelBlock3.set_PixelData(0, pixels);
//Write the modified pixel block to the raster dataset.
IRasterEdit rasterEdit = (IRasterEdit)raster;
rasterEdit.Write(topleftCorner, pixelBlock);
}
[VB.NET]
Private Sub UsingPixelBlock(ByVal raster As IRaster)
'Create a pixel block using the size provided by the system.
Dim raster2 As IRaster2 = CType(raster, IRaster2)
Dim pixelBlock As IPixelBlock = raster2.CreateCursorEx(Nothing).PixelBlock
Dim w As Integer = pixelBlock.Width
Dim h As Integer = pixelBlock.Height
'Read the first pixel block.
Dim topleftCorner As IPnt = New PntClass()
topleftCorner.SetCoords(0, 0)
raster.Read(topleftCorner, pixelBlock)
'Modify one pixel value at locations w-1 and h-1
'(assume the raster has a pixel type of uchar).
Dim pixelBlock3 As IPixelBlock3 = CType(pixelBlock, IPixelBlock3)
Dim pixels As System.Array = CType(pixelBlock3.get_PixelData(0), System.Array)
pixels.SetValue(Convert.ToByte (10), w - 1, h - 1)
pixelBlock3.set_PixelData(0, pixels)
'Write the modified pixel block to the raster dataset.
Dim rasterEdit As IRasterEdit = CType(raster, IRasterEdit)
rasterEdit.Write(topleftCorner, pixelBlock)
End Sub
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 a large amount of raster data, the best practice is to divide the raster into small pixel blocks, and perform reading and writing pixels block by block using the RasterCursor class.
The IRaster.CreateCursor method provides a simple 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 system-provided pixel block size (pass nothing to the pixel block size).
NoData
Pixels, or cells, in a raster dataset that are missing information are called NoData. For a file-based raster dataset, NoData is stored as a value, called 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 that the corresponding pixel is a NoData pixel.
IRasterProps.NoDataValue can be used to get and set the NoData value on a raster. The NoData value is used in saving (SaveAs) to a new dataset.
IRasterProps.NoDataValue can also be used to get and set the NoData value on a RasterBand. The NoData value is used in writing pixel blocks to the raster dataset with the IRasterEdit or IRawPixels interface. For mask-based NoData, the IPixelBlock3.Mask method can be used to set NoData when writing pixel blocks. The following code sets the NoData value on a raster and saves it to a new raster dataset:
[C#]
void SaveAsRasterWithNoData(IRaster raster)
{
//Set NoData.
IRasterProps rasterProps = (IRasterProps)raster;
rasterProps.NoDataValue = 255;
//Or set a different NoData value for each band.
int[] nodata =
{
255, 255, 236
};
rasterProps.NoDataValue = nodata;
//Save.
ISaveAs saveAs = (ISaveAs)raster;
saveAs.SaveAs(@"c:\temp\nodata.img", null, "IMAGINE Image");
}
[VB.NET]
Private Sub SaveAsRasterWithNoData(ByVal raster As IRaster)
'Set NoData.
Dim rasterProps As IRasterProps = CType(raster, IRasterProps)
rasterProps.NoDataValue = 255
'Or set a different NoData value for each band.
Dim nodata As Integer() = { 255, 255, 236 }
rasterProps.NoDataValue = nodata
'Save.
Dim saveAs As ISaveAs = CType(raster, ISaveAs)
saveAs.SaveAs("c:\temp\nodata.img", Nothing, "IMAGINE Image")
End Sub
Raster catalogs
RasterCatalog, a special type of FeatureClass 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 the pixel values of the raster dataset. It can also contain other fields, such as metadata, text, and so on. Only one Raster field is allowed in a raster catalog.
The geodatabase raster catalog objects are shown in the following diagram:
The Raster field of a raster catalog has a spatial reference, defined by RasterDef, which serves as a default for loading raster datasets that have unknown spatial reference. In ArcGIS, the raster datasets in a raster catalog are allowed to store their 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 values in the raster catalog. An unmanaged raster catalog stores only the paths to the raster datasets, and those raster datasets may 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 [PCS] or geographic coordinate system [GCS], the coordinate domain, and the coordinate precision) and the spatial index of the geometry field can be set using the GeometryDef class.
The value stored in the Raster field is called a RasterValue. A RasterValue contains a RasterDataset and a RasterStorageDef that describes how the RasterDataset 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, as well as the resampling method for pyramid building.
As a subclass of FeatureClass, RasterCatalog consists of rows. Each row is a RasterCatalogItem, which is a type of Feature. A RasterCatalog operates the same way as a FeatureClass when accessing or updating the raster datasets in the RasterCatalog (for example, enumeration of the raster datasets in a RasterCatalog is accomplished by acquiring a standard FeatureCursor on the RasterCatalog). 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, then add rows that contain raster values to the raster catalog. The following code shows how to load a raster dataset to a raster catalog and retrieve a raster dataset inside a raster catalog:
[C#]
void AddRasterToRasterCatalog(IRasterDataset rasterDataset, IRasterCatalog
rasterCatalog)
{
IFeatureClass fClass = (IFeatureClass)rasterCatalog;
IFeature feature = fClass.CreateFeature();
//Create a raster value.
IRasterValue rasterValue = new RasterValueClass();
rasterValue.RasterDataset = rasterDataset;
feature.set_Value(rasterCatalog.NameFieldIndex, rasterValue);
feature.Store();
}
[VB.NET]
Private Sub AddRasterToRasterCatalog(ByVal rasterDataset As IRasterDataset, ByVal rasterCatalog As IRasterCatalog)
Dim fClass As IFeatureClass = CType(rasterCatalog, IFeatureClass)
Dim feature As IFeature = fClass.CreateFeature()
'Create a raster value.
Dim rasterValue As IRasterValue = New RasterValueClass()
rasterValue.RasterDataset = rasterDataset
feature.set_Value(rasterCatalog.NameFieldIndex, rasterValue)
feature.Store()
End Sub
The following code shows how to store the raster dataset in the first row of a raster catalog:
[C#]
void GetRasterDataset(IRasterCatalog rasterCatalog, int index)
{
IFeatureClass fClass = (IFeatureClass)rasterCatalog;
IRasterCatalogItem catalogItem = (IRasterCatalogItem)fClass.GetFeature(index);
IRasterDataset rasterDataset = catalogItem.RasterDataset;
}
[VB.NET]
Private Sub GetRasterDataset(ByVal rasterCatalog As IRasterCatalog, ByVal index As Integer)
Dim fClass As IFeatureClass = CType(rasterCatalog, IFeatureClass)
Dim catalogItem As IRasterCatalogItem = CType(fClass.GetFeature(index), IRasterCatalogItem)
Dim rasterDataset As IRasterDataset = catalogItem.RasterDataset
End Sub
A RasterCatalog can be displayed using the GdbRasterCatalogLayer class in the Carto library.
Function raster datasets and raster functions
A function raster dataset encapsulates a raster function, which defines a raster operation, and the data on which it operates. As a special type of raster dataset, a function raster dataset provides a mechanism for on-the-fly raster processing by binding a raster function and its arguments together. For example, a function raster dataset may contain a hillshade function with its corresponding arguments, which include an input digital elevation model (DEM), altitude, azimuth, and z factor. When accessed, the raster function in the function raster dataset is evaluated, providing a virtual hillshade of the DEM.
Function raster datasets on disk are stored in a file format with an extension of .afr and in geodatabases as binary data. The FunctionRasterDataset and RasterFunction objects are shown in the following diagram:
Raster function
A raster function defines an operation that operates on raster data. The RasterFunction class is an abstract class (from which many concrete classes—including PansharpeningFunction, ArithmeticFunction, and HillshadeFunction—are derived), which define various raster operations.
The RasterFunctionArguments class is an abstract class used to define the parameters of its corresponding raster function and has many concrete raster function arguments classes derived from it. Some raster functions can be used directly. However, most raster functions have a corresponding RasterFunctionArguments class for defining their arguments. For example, the arguments of the PansharpeningFunction are defined by PansharpeningFunctionArguments, the arguments of ArithmeticFunction are defined by ArithmeticFunctionArguments, and the arguments of HillshadeFunction are defined by HillshadeFunctionArguments. The following table lists the raster functions and corresponding function arguments currently supported in ArcGIS:
Raster function
|
Raster function argument
|
ArithmeticFunction
|
ArithmeticFunctionArguments
|
AspectFunction
|
|
ATCORFunction
|
|
BandArithmeticFunction
|
BandArithmeticFunctionArguments
|
CachedRasterFunction
|
CachedRasterFunctionArguments
|
ClipFunction
|
ClipFunctionArguments
|
ColormapFunction
|
ColormapFunctionArguments
|
ColorspaceCoversionFunction
|
ColorspaceConversionFunctionArguments
|
ComplexFunction
|
|
CompositeBandFunction
|
|
ConstantFunction
|
ConstantFunctionArguments
|
ConvolusionFunction
|
ConvolusionFunctionArguments
|
ExcludedAreaFunction
|
ExcludedAreaFunctionArguments
|
ExtractBandFunction
|
ExtractBandFunctionArguments
|
FootprintFunction
|
FootprintFunctionArguments
|
GeometricFunction
|
GeometricFunctionArguments
|
GrayscaleFunction
|
GrayscaleFunctionArguments
|
HillshadeFunction
|
HillshadeFunctionArguments
|
IdentityFunction
|
|
MaskFunction
|
MaskFunctionArguments
|
MosaicFunction
|
MosaicFunctionArguments
|
MosaicRastersFunction
|
MosaicRasterFunctionsArguments
|
NDVIFunction
|
NDVIFunctionArguments
|
RadarCalibrationFunction
|
RadarCalibrationFunctionArguments
|
PansharpeningFunction
|
PansharpeningFunctionArguments
|
RasterItemFunction
|
RasterItemFunctionArguments
|
RasterFunctionCollection
|
|
RasterInfoFunction
|
RasterInfoFunctionArguments
|
RemapFunction
|
RemapFunctionArguments
|
RGB32Function
|
|
RGB32ToRGBFunction
|
|
RGBToColormapFunction
|
|
ColormapToRGBFunction
|
|
SAIFunction
|
SAIFunctionArguments
|
ShadedReliefFunction
|
ShadedReliefFunctionArguments
|
SpeckleFunction
|
SpeckleFunctionArguments
|
SpectialConversionFunction
|
SpectialConversionFunctionArguments
|
SlopeFunction
|
SlopeFunctionArguments
|
StatisticsFunction
|
StatisticsFunctionArguments
|
StretchFunction
|
StretchFunctionArguments
|
TrendFunction
|
TrendFunctionArguments
|
TableFunction
|
TableFunctionArguments
|
RasterFunctionTemplate
|
|
The LasToRaster, LasDatasetToRaster, and TerrainToRaster functions are part of the data sources library but require the 3D Analyst extension to be stable to use them.
The IRasterFunction interface provides access to the RasterInfo object. RasterInfo contains raster information, such as the extent, spatial reference, width, and height. The following code shows how to creates a hillshade function:
[C#]
public static IRasterFunction CreateHillshadeFunction(IRasterDataset demDS, Double
altitude, Double azimuth, Double zFactor)
{
IRasterFunction hillshadeFunction = new HillshadeFunctionClass();
IHillshadeFunctionArguments arguments = new HillshadeFunctionArgumentsClass();
arguments.Altitude = altitude;
arguments.Azimuth = azimuth;
arguments.ZFactor = zFactor;
arguments.DEM = demDS;
hillshadeFunction.Bind(arguments);
return hillshadeFunction;
}
[VB.NET]
Public Function CreateHillshadeFunction(ByVal demDS As IRasterDataset, ByVal altitude As Double, ByVal azimuth As Double, ByVal zFactor As Double) As IRasterFunction
Dim hillshadeFunction As IRasterFunction = New HillshadeFunctionClass()
Dim arguments As HillshadeFunctionArguments = New HillshadeFunctionArgumentsClass()
arguments.Altitude = altitude
arguments.Azimuth = azimuth
arguments.ZFactor = zFactor
arguments.DEM = demDS
hillshadeFunction.Bind(arguments)
Return hillshadeFunction
End Function
The RasterFunctionTemplate class is used to define a raster function for which the parameters are variables. For example, a CompositeBandFunction can have any number of bands as input. The RasterFunctionTemplate can be used to define a CompositeBandFunction from a given number of bands using RasterFunctionVariable objects.
Raster functions can also be customized. The RasterFunction abstract class can be extended by implementing a new concrete class to perform processing that is not included with the software. For information on how to create a custom raster function, see Function raster datasets and raster functions.
Function raster dataset
A function raster dataset is a virtual raster that represents the application of a raster function on raster data. The FunctionRasterDataset class contains a RasterFunction and its associated RasterFunctionArguments. The IFunctionRasterDataset interface provides a way to instantiate a function raster dataset and obtain the RasterFunction, RasterFunctionArguments, and RasterInfo from the function raster dataset.
A function raster dataset can be instantiated through a FunctionRasterDatasetName, a type of DatasetName. The following code shows how to open a function raster dataset:
[C#]
//Create a function raster dataset name.
IFunctionRasterDatasetName functionDSName = new FunctionRasterDatasetNameClass();
//Set the name string and open the function raster dataset.
functionDSName.FullName = "c:\data\image.afr";
IName name = (IName)functionDSName;
IFunctionRasterDataset ds = (IFunctionRasterDataset)name.Open();
[VB.NET]
'Create a function raster dataset name.
Dim functionDSName As IFunctionRasterDatasetName = New FunctionRasterDatasetNameClass()
'Set the name string and open the function raster dataset.
functionDSName.FullName = "c:\data\image.afr"
Dim Name As IName = CType(functionDSName, IName)
Dim ds As IFunctionRasterDataset = CType(Name.Open(), IFunctionRasterDataset)
As a special type of raster dataset, the FunctionRasterDataset class inherits interfaces from RasterDataset, such as IRasterDataset, IRasterbandCollection, and ITemporaryDataset.
The function raster dataset is temporary when initially created using the Init method. It is removed automatically if the application goes out of scope. To persist it, the ITemporaryDataset interface can be used. In addition, to save the function raster dataset as a raster dataset, use the IRasterDataset interface to obtain a RasterDataset, then use ISaveAs.SaveAs.
The following code creates a function raster dataset with a given raster function:
[C#]
public static Void CreateFunctionRasterDataset(String fullName, IRasterFunction
rasterFunction, IRasterFunctionArguments functionArguments)
{
//Create a function raster dataset.
IFunctionRasterDataset functionDS = new FunctionRasterDatasetClass();
//Define a name for the function raster dataset.
IFunctionRasterDatasetName functionDsName = new FunctionRasterDatasetNameClass();
functionDsName.FullName = fullName;
functionDS.FullName = functionDsName;
//Initialize the function raster dataset using a given raster function and its
//corresponding function arguments.
functionDS.Init(rasterFunction, functionArguments);
//Make permanent.
ITemporaryDataset tempDS = (ITemporaryDataset)functionDS;
tempDS.MakePermanent();
}
[VB.NET]
Public Sub CreateFunctionRasterDataset(ByVal fullName As String , ByVal rasterFunction As IRasterFunction, ByVal functionArguments As IRasterFunctionArguments)
' Create a function raster dataset.
Dim functionDS As IFunctionRasterDataset = New FunctionRasterDatasetClass()
' Define a name for the function raster dataset.
Dim functionDsName As IFunctionRasterDatasetName = New FunctionRasterDatasetNameClass()
functionDsName.FullName = fullName
functionDS.FullName = functionDsName
' Initialize the function raster dataset using a given raster function and its
' corresponding function arguments.
functionDS.Init(rasterFunction, functionArguments)
' Make permanent.
Dim tempDS As ITemporaryDataset = CType(functionDS, ITemporaryDataset)
tempDS.MakePermanent()
End Sub
Mosaic datasets and raster types
At ArcGIS 10, a mosaic dataset is a geodatabase raster data model for managing and serving large amounts of raster data of various raster formats and multiple sensor platforms. A mosaic dataset has the characteristics of both a raster dataset and a raster catalog. It manages all the information associated with the raster data except the pixels, using an improved internal raster catalog. It provides features such as on-the-fly processing and the ability to create a virtual mosaic of the raster data by dynamically applying the defined mosaic rules. The mosaic dataset and mosaic function objects are shown in the following diagram:
Mosaic dataset
A mosaic dataset contains the following:
- A mosaic catalog, which is an internal raster catalog for managing rasters, raster functions, and footprints
- A polygon feature class defining the boundary of the mosaic
- A raster type table that stores the raster types used in the mosaic
- A log table containing the operations performed on the mosaic dataset
- A stereo table providing stereo pair information (optional)
- A color correction table storing the derived local mean and local standard deviation images (optional)
- A seamline table that defines seamlines for mosaicking (optional)
The mosaic catalog has a list of predefined fields—such as MinPS, MaxPS, LowPS, and MaxPS—and a raster field of type Function. This special type of raster field allows the storage of function raster datasets, which are the foundation of on-the-fly processing. The rows in the mosaic catalog are populated with information obtained from these function raster datasets, which are created from the source data based on the raster type that was specified when the dated was added.
The MinPS and MaxPS fields store pixel sizes that define display ranges for the rasters stored in the mosaic catalog. When a request is made at a certain pixel resolution, only rasters with pixel ranges matching the requested pixel resolution are selected and mosaicked on-the-fly. Overviews are raster tiles generated at user-defined resolutions to make the display faster.
The MosaicDataset object is a special type of FunctionRasterDataset. It contains a mosaic function. MosaicDataset can be accessed through the IMosaicWorkspaceExtension interface. The IMosaicDataset interface provides access to the MosaicDataset, arguments, and the various components of the mosaic dataset including the boundary, catalog, and seamline table.
The following code creates a mosaic dataset:
[C#]
public static IMosaicDataset CreateMosaicDataset(IWorkspace fgdbWorkspace, string
mdName, ISpatialReference mosaicSrs)
{
// Create the mosaic dataset creation parameters object.
ICreateMosaicDatasetParameters creationPars = new
CreateMosaicDatasetParametersClass();
// Set the number of bands for the mosaic dataset.
creationPars.BandCount = 3;
// Set the pixel type of the mosaic dataset.
creationPars.PixelType = rstPixelType.PT_UCHAR;
// Create the mosaic workspace extension helper class.
IMosaicWorkspaceExtensionHelper mosaicExtHelper = new
MosaicWorkspaceExtensionHelperClass();
// Find the right extension from the workspace.
IMosaicWorkspaceExtension mosaicExt = mosaicExtHelper.FindExtension
(fgdbWorkspace);
// Use the extension to create a new mosaic dataset, supplying the
// spatial reference and the creation parameters object previously created.
IMosaicDataset theMosaicDataset = mosaicExt.CreateMosaicDataset(mdName,
mosaicSrs, creationPars);
return theMosaicDataset;
}
[VB.NET]
Public Function CreateMosaicDataset(ByVal fgdbWorkspace As IWorkspace , ByVal mdName As String, ByVal mosaicSrs As ISpatialReference ) As IMosaicDataset
' Create the mosaic dataset creation parameters object.
Dim creationPars As ICreateMosaicDatasetParameters = New CreateMosaicDatasetParametersClass()
' Set the number of bands for the mosaic dataset.
creationPars.BandCount = 3
' Set the pixel type of the mosaic dataset.
creationPars.PixelType = rstPixelType.PT_UCHAR
' Create the mosaic workspace extension helper class.
Dim mosaicExtHelper As IMosaicWorkspaceExtensionHelper = New MosaicWorkspaceExtensionHelperClass()
' Find the right extension from the workspace.
Dim mosaicExt As IMosaicWorkspaceExtension = mosaicExtHelper.FindExtension(fgdbWorkspace)
' Use the extension to create a new mosaic dataset, supplying the
' spatial reference and the creation parameters object previously created.
Dim theMosaicDataset As IMosaicDataset = mosaicExt.CreateMosaicDataset(mdName, mosaicSrs, creationPars)
'
Return theMosaicDataset
End Function
A mosaic dataset can reference an external raster catalog or another mosaic dataset. This type of mosaic dataset is called a referenced mosaic dataset. For example, a raster catalog cannot be published by ArcGIS Server directly; however, a referenced mosaic dataset can be created from the raster catalog and published. A mosaic dataset that references another mosaic dataset can be created. This allows mosaic datasets to be a data management solution, with referenced mosaic datasets created to provide multiple views of the same data. For example, you can put your data—such as a Landsat of the world—in one mosaic dataset, then use referenced mosaic datasets to view and distribute portions of the data or different band combinations.
When creating a referenced mosaic dataset from a raster catalog, a predefined maximum visible size is used as a threshold to determine what displays, that is, a rasterized wireframe or a dynamically mosaicked image. A referenced mosaic dataset can also be created from an ArcGIS Military Analyst raster catalog, where the display ranges of the rasters in the mosaic dataset are determined by the scales defined in one of the fields in the raster catalog. To create a referenced mosaic dataset from an existing mosaic dataset, the MinPS and MaxPS fields can be used to define display behavior. For information on how to create a referenced mosaic dataset from different sources, see How to create a referenced mosaic dataset.
Mosaic function
The MosaicFunction object defines the mosaic rules for mosaicking rasters in the mosaic dataset. A mosaic rule is used to define the following:
- The selection of rasters that participates in the mosaic
- The mosaic method (for example, how the selected rasters are ordered)
- The mosaic operation (for example, how overlapping pixels at the same location are resolved)
The IMosaicFunction interface provides access to properties and methods that define the mosaic process. The WhereClause and Search properties are used to select rasters that participate in the mosaic. The MosaicMethod property specifies the order in which the rasters are mosaicked. MosaicOperator is used to resolve the overlapping pixels.
The following table lists the supported mosaic methods and operations. Not all mosaic operations apply to all mosaic methods.
Mosaic method
|
Description
|
Mosaic operations
|
esriMosaicLockRaster
|
Selects only the rasters in a given list of raster IDs to participate in the mosaic. This method takes LockRasterIDs as a parameter, which defines the list. The rasters are in random order. The rasters are visible at all pixel sizes regardless of the minimum and maximum pixel size range of the locked rasters.
|
First (default), Last, Min, Max, Mean, Blend
|
esriMosaicCenter
|
Sorts rasters based on their proximity to the view center or the center of view extent. The rasters that have their center closest to the view center are placed on top.
|
First (default), Last, Min, Max, Mean, Blend
|
esriMosaicNadir
|
Sorts rasters based on the distance between the nadir position and view center. This is similar to the esriMosaicCenter method but uses the nadir point to a raster, which can be different than the center, especially for oblique imagery.
|
First (default), Last, Min, Max, Mean, Blend
|
esriMosaicViewpoint
|
Sorts rasters based on a user-defined view point location and nadir location for the rasters.
|
First (default), Last, Min, Max, Mean, Blend
|
esriMosaicNorthwest
|
Sorts rasters in a view-independent way, where rasters with their centers most northwest are displayed on top.
|
First (default), Last, Min, Max, Mean, Blend
|
esriMosaicAttribute
|
Sorts rasters based on an attribute field and its difference from a base value.
|
First (default), Last, Min, Max, Mean, Blend
|
esriMosaicSeamline
|
Cuts the raster using a predefined seamline shape for each raster using optional feathering along the seams. Ordering is defined in the SOrder field in the footprint table during seamline generation.
|
First (default), Blend, Min, Max, Mean
|
esriMosaicNone
|
No sorting occurs.
|
First (default), Blend, Min, Max, Mean
|
There are also many properties that are used to define pixel visibility. For example, use MaximumVisibleCellsize if the mosaic dataset is referenced and created from a regular raster catalog; use LODInfos if the mosaic dataset is created from an ArcGIS Military Analyst raster catalog; and use MinCellSizeName and MaxCellSizeName if a referenced mosaic dataset is created from another mosaic dataset.
The IMosaicDatasetOperation interface is used to perform operations on the mosaic dataset, for example, adding rasters to a mosaic dataset, building boundaries, calculating cell size ranges, and building overviews. The parameters for each operation are defined using a corresponding operation parameters class. For example, the AddRastersParameters class defines parameters required for adding rasters including crawler and raster type.
Raster type
The RasterType object is used to add rasters to a mosaic dataset. The RasterType object specifies the following:
- The raster data type to be added (for example, regular raster datasets or data from sensors with special metadata information, so that the crawler understands what files to search for)
- The processes to be used in creating the rasters (for example, multiband rasters, single band rasters, or pan-sharpened rasters)
The raster type and raster builder objects are shown in the following diagram:
ArcGIS currently supports many raster types including, Raster dataset, Landsat, QuickBird, SPOT5, IKONOS, WorldView-1, WorldView-2, GeoEye-1, LAS, Radarsat2, and so on.
Any ArcGIS-supported raster format can be added to a mosaic dataset using the Raster Dataset raster type. To add Landsat MS data to a mosaic dataset, use a Landsat raster type.
A RasterType class contains a RasterBuilder and an ItemTemplateArray. RasterBuilder uses the output from the crawler and builds items that are then converted to function rasters using the templates defined in the ItemTemplateArray. RasterBuilder is an abstract class that has many concrete builder classes derived from it, such as LandsatBuilder, SpotBuilder, and IkonosBuilder. RasterBuilder constructs one or more BuilderItem objects from the crawled data. Each builder item corresponds to a FunctionRasterDataset that has an Item Uniform Resource Identifier (ItemURI). For example, LandsatBuilder constructs an item of a panchromatic function raster dataset and an item of a multiband function raster dataset from one Landsat scene, then RasterType creates a multiband raster and a pan-sharpening raster from these items using ItemTemplateArray and adds them as rows in the mosaic raster catalog.
RasterType can be instantiated though the RasterTypeEnvrionment class. To load rasters to a mosaic dataset, a raster type must be used in the AddRastersParameters object. For information on adding rasters to a mosaic dataset, see How to add rasters to a Mosaic dataset.
The raster type class can be customized. You can add a custom raster type by creating a custom raster builder and saving it as a raster type file (.art). For information on adding a custom raster type, see Create a custom raster type.
Geodata transformation and pixel filtering
A geodata transformation is a mathematical operation that is used to perform geometric transformations for geodatasets such as raster datasets. ArcGIS supports many geodata transformations, such as coordinate transformation (reprojection), polynomial transformation, rubber sheeting (Adjust) transformation, Spline transformation, and Rational Polynomial Coefficient (RPC) transformation.
Geodata transformations are represented as an abstract class, GeodataXform, and as many concrete geodata transformation classes (Xform) as follows:
- AdjustXform
- SplineXform
- RPCXform
- PolynomialXform
- CoordinateXform
- ApproximationXform
- GCSShiftXform
- GeometricXform
- CompositeXform
- FrameXform
- SPOT5XForm
- LSRXform
- ProjectiveXform
- CSMXForm
- Formosat2Xform
- IdentityXform
You can also create a custom Xform by implementing interfaces of the GeodataXform abstract class. The geodata transformation objects are shown in the following diagram:
All GeodataXform objects can have an output spatial reference that defines the spatial reference of the data after transformation (for example, in output space). The domains of GeodataXform objects, if they exist, are also defined in the output space. All GeodataXform objects perform point (IPointCollection or WKSPoint) transformation, extent (IEnvelope) transformation, and cell size transformation in forward and backward directions. To transform raster data, the RasterXformer object (discussed at the end of this section) provides the behind-the-scenes mechanism by calling PixelReader, PixelResampler, and IRasterXform. The IRasterXform interface is used for geodata transformations that need raster-specific information to optimize operations. Therefore, when creating a custom geodata transformation to work with raster data, implement 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 xform, IPointCollection points, IEnvelope extent,
ref double xcell, ref double ycell)
{
xform.TransformPoints(esriTransformDirection.esriTransformForward, points);
xform.TransformExtent(esriTransformDirection.esriTransformForward, extent);
xform.TransformCellsize(esriTransformDirection.esriTransformForward, ref xcell,
ref ycell, extent);
}
[VB.NET]
Private Sub TransformPoints(ByVal xform As IGeodataXform, ByVal points As IPointCollection, ByVal extent As IEnvelope, ByRef xcell As Double, ByRef ycell As Double)
xform.TransformPoints(esriTransformDirection.esriTransformForward, points)
xform.TransformExtent(esriTransformDirection.esriTransformForward, extent)
xform.TransformCellsize(esriTransformDirection.esriTransformForward, xcell, ycell, extent)
End Sub
A GeodataXform object is stored as 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 GeodataXform on a raster and persist the transformed raster using ISaveAs. Saving as a RasterDataset will not apply the GeodataXform to the pixels but will persist the GeodataXform with the output raster dataset.
PolynomialXform
The PolynomialXform object performs transformation using a polynomial, which is built based on a least squares fitting (LSF) algorithm. A PolynomialXform can be defined in the following two ways:
- Use two sets of control points—source and target—to construct the polynomial of an order of 1, 2, or 3. The minimum number of non-correlated control points required for this method must be 3, 6, and 10, respectively.
- Set the polynomial coefficients directly using the IPolynomialXform.DefineFromCoefficients method if the polynomial coefficients are known.
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; the other is based on a set of checkpoints using the CheckResidualRMS method. Assuming sourcePoints and targetPoints are known source and target control point collections, the following code example creates a PolynomialXform:
[C#]
IPolynomialXform Polynomial(IPointCollection fromPoints, IPointCollection toPoints)
{
IPolynomialXform polyXform = new PolynomialXformClass();
polyXform.DefineFromControlPoints(fromPoints, toPoints, 2);
return polyXform;
}
[VB.NET]
Private Function Polynomial(ByVal fromPoints As IPointCollection, ByVal toPoints As IPointCollection) As IPolynomialXform
Dim polyXform As IPolynomialXform = New PolynomialXformClass()
polyXform.DefineFromControlPoints(fromPoints, toPoints, 2)
Return polyXform
End Function
SplineXform
The SplineXform class 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 exactly 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 the overall accuracy of the Spline transformation. A SplineXform can be created from two sets of control points using the DefineFromControlPoints method of the ISplineXform interface.
AdjustXform
The AdjustXform class, also called a rubber sheeting transformation, is built on an algorithm that combines a polynomial transformation and a triangulated irregular network (TIN) interpolation technique. Adjust transformation first 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. When compared to the PolynomialXform and SplineXform, AdjustXform has both the characteristics of global optimization (because of the use of the LSF algorithm) and local accurate approximation of the control points. Assuming sourcePoints and targetPoints are known source and target control point collections, the following code example creates an AdjustXform using the IAdjustXform interface:
[C#]
void AdjustXform(IPointCollection fromPoints, IPointCollection toPoints)
{
//Create AdjustXform using control points.
IAdjustXform xform = new AdjustXformClass();
xform.DefineFromControlPoints(fromPoints, toPoints);
xform.PolynomialApproximation = 2;
//Use interpolation to perform the adjustment.
xform.NaturalNeighbor = true;
}
[VB.NET]
Private Sub AdjustXform(ByVal fromPoints As IPointCollection, ByVal toPoints As IPointCollection)
'Create AdjustXform using control points.
Dim xform As IAdjustXform = New AdjustXformClass()
xform.DefineFromControlPoints(fromPoints, toPoints)
xform.PolynomialApproximation = 2
'Use interpolation to perform the adjustment.
xform.NaturalNeighbor = True
End Sub
ApproximateXform
The ApproximateXform class is used to perform an approximate transformation of a GeodataXform to achieve improved performance. It is mainly for 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 between points. It guarantees the approximation error does not exceed the specified tolerance. The following code creates an ApproximateXform using IApproximateXform and IGeodataXformApproximation:
[C#]
void CreateApproximationXform(IGeodataXform xform)
{
IApproximationXform appXform = new ApproximationXformClass();
appXform.GeodataXform = xform;
IGeodataXformApproximation gdApproximation = (IGeodataXformApproximation)
appXform;
gdApproximation.Tolerance = 0.5;
gdApproximation.GridSize = 32;
}
[VB.NET]
Private Sub CreateApproximationXform(ByVal xform As IGeodataXform)
Dim appXform As IApproximationXform = New ApproximationXformClass()
appXform.GeodataXform = xform
Dim gdApproximation As IGeodataXformApproximation = CType(appXform, IGeodataXformApproximation)
gdApproximation.Tolerance = 0.5
gdApproximation.GridSize = 32
End Sub
CoordinateXform
The CoordinateXform class is a coordinate transformation that transforms data from one projection system to another. To create a CoordinateXform, you need to specify the input and output spatial references. If the IGeodataXformApproximation interface is used, the CoordinateXform 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 is implemented using this approximation technique, which projects raster data based on a 16 by 16 mesh. The following code transforms a collection of points from one spatial reference to another using the ICoordinateXform2 interface:
[C#]
void CoordinateXform(ISpatialReference sourceSR, ISpatialReference targetSR,
IPointCollection points)
{
//Create CoordinateXform and set the spatial reference.
ICoordinateXform2 coorXform = (ICoordinateXform2)new CoordinateXform();
coorXform.InputSpatialReference = sourceSR;
coorXform.SpatialReference = targetSR;
//Define the approximation parameters.
IGeodataXformApproximation gdApproximation = (IGeodataXformApproximation)
coorXform;
gdApproximation.Approximation = true;
gdApproximation.GridSize = 16;
//Ensure unit is in the input space.
gdApproximation.Tolerance = 15;
//Transform.
coorXform.TransformPoints(esriTransformDirection.esriTransformForward, points);
}
[VB.NET]
Private Sub CoordinateXform(ByVal sourceSR As ISpatialReference, ByVal targetSR As ISpatialReference, ByVal points As IPointCollection)
'Create CoordinateXform and set the spatial reference.
Dim coorXform As ICoordinateXform2 = CType(New CoordinateXform(), ICoordinateXform2)
coorXform.InputSpatialReference = sourceSR
coorXform.SpatialReference = targetSR
'Define the approximation parameters.
Dim gdApproximation As IGeodataXformApproximation = CType(coorXform, IGeodataXformApproximation)
gdApproximation.Approximation = True
gdApproximation.GridSize = 16
'Ensure unit is in the input space.
gdApproximation.Tolerance = 15
'Transform.
coorXform.TransformPoints(esriTransformDirection.esriTransformForward, points)
End Sub
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 class is used to support RPC transformation and image orthorectification.
When creating an RPCXform, in addition to setting the 92 coefficients using IRPCXform, you must also 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 GeodataXform classes
GCSShiftXform is used to perform transformation from a non-standard GCS coordinate (0 to 360) to a standard GCS (–180 to 180). For example, if your world image is in a coordinate system of (0, 360, -90 , 90), GCSShiftXform can be used to transform the image to (-180, 180, -90, 90).
FrameXform is used to support standard frame camera model transformation.
GeometricXform is a geodata transformation based on the transformation classes defined in the Geometry library (for example, AffineTransformation2D and ProjectiveTransformation2D). It is a wrapper of these classes and allows these classes to be incorporated in the geodata transformation pipeline.
IdentityXform is an identity coordinate transformation that has no effect on coordinates and is used solely to associate or change the spatial reference of the data. A raster dataset created from IRasterGeometryProc.Rectify has an identity transformation, while a raster dataset created from IRasterGeometryProc.Register has a polynomial transformation.
CompositeXform consists of a set of ordered Xforms and is used to manage the Xform list, for example, to add or remove a GeodataXform. The sequence of the applied transformation is from bottom to top for forward transformation, and top to bottom for reverse transformation.
Raster transformation
To transform raster data with geodata Xforms, the RasterXformer class plays a behind-the-scenes role. RasterXformer contains a GeodataXform, a PixelResampler, and a PixelReader, as well as the logic to drive these three components to perform raster transformations. Raster transformation is a reverse transformation. For a given extent (Envelope for example) in the output space, RasterXformer first rasterizes it into pixels, then reverse transforms the pixels into the input space using GeodataXform. Finally, it resamples the pixels provided by PixelReader in the input space using PixelResampler. If an approximation is used in the transformation, only pixels on a predefined mesh are reversely transformed to the input space, and the values of the pixels inside the mesh are interpolated.
The raster transformation objects are shown in the following diagram:
The default pixel reader used by RasterXformer is SimplePixelReader, and it provides input pixels, either from a raster or from raw pixels read by implementing a call back function using the IRawPixelReader interface. If the input pixels are not from a raster, IRasterXformer2 can be used to dynamically transform pixels, such as on-the-fly projected pixels from an ArcIMS layer. In this case, you are responsible for setting up a custom PixelReader.
The default pixel resampler used by RasterXformer is SimplePixelResampler, which supports the following types of resampling methods:
- Nearest neighbor
- Bilinear
- Cubic convolution
- Majority
You can modify the properties of SimplePixelResampler. The following code sets the cubic convolution parameter to –0.5:
[C#]
void SetCubicResamplingFactor(IRaster raster)
{
//Get the xformer.
IRaster2 raster2 = (IRaster2)raster;
IRasterXformer xformer = raster2.RasterXformer;
//Set the resampling method and factor (-3, 0).
raster.ResampleMethod = rstResamplingTypes.RSP_CubicConvolution;
ISimplePixelResampler resampler = (ISimplePixelResampler)xformer.PixelResampler;
resampler.CubicConvolutionParameter = - 0.5;
}
[VB.NET]
Private Sub SetCubicResamplingFactor(ByVal raster As IRaster)
'Get the xformer.
Dim raster2 As IRaster2 = CType(raster, IRaster2)
Dim xformer As IRasterXformer = raster2.RasterXformer
'Set the resampling method and factor (-3, 0).
raster.ResampleMethod = rstResamplingTypes.RSP_CubicConvolution
Dim resampler As ISimplePixelResampler = CType(xformer.PixelResampler, ISimplePixelResampler)
resampler.CubicConvolutionParameter = -0.5
End Sub
Pixel filters
The pixel filter classes perform radiometric transformation, which transforms pixel values. PixelFilter, an abstract class, supports the IPixelFilter and IPixelFilter2 interfaces and is implemented by the following pixel filter classes:
- RasterConvolutionFilter
- PansharpeningFilter
- BackgroundFilter
- ColormapFilter
- LutFilter
- MultibandFilter
- RemapFilter
The PixelFilterCollection class 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.
The pixel filter objects are shown in the following diagram:
The PansharpeningFilter class is used to perform 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 class, setting a panchromatic raster and specifying a pan-sharpening type.
The following pan-sharpening methods are provided in ArcGIS:
- Brovey
- IHS (intensity, hue, saturation)
- ESRI
- Mean
Each of these methods is based on the following general model:
A pixel value of a pan image is considered a weighted average of RGB and (optional) infrared components:
P = R*RW + G*GW + B*BW + I*IW
1 = RW + GW + BW + IW
In this model, RW, GW, BW, and IW (>0) are weights for RGB, and infrared components. P, R, G, B, and I (as well as P', R', G', I') represent the input and output pixel values of the panchromatic, RGB, and infrared bands respectively.
Brovey method
DNF = (P-IW*I)/(RW*R+GW*G+BW*B)
R' = R*DNF
G' = G*DNF
B' = B*DNF
I' = I*DNF
IHS method
RGBToHSI(R, G, B, H, S, INTENSITY)
INTENSITY = P-I*IW
HSIToRGB(H, S, INTENSITY, R', G', B')
ESRI method
WA (Weighted average) = R*RW + G*GW + B* BW + + I*IW /(RW+GW+BW+IW)
ADJ (Adjusted value) = P- WA
R' = R+ADJ
G' = G+ADJ
B' = B+ADJ
I' = I+ADJ
Mean method
R' = 0.5 * (R + P)
G' = 0.5 * (G + P)
B' = 0.5 * (B + P)
The RasterConvolutionFilter class is used to perform various pixel filtering techniques to enhance 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:
[C#]
IPixelFilter FilterKernel()
{
IRasterConvolutionFilter filter = new RasterConvolutionFilterClass();
double[] kernel =
{
- 1, - 1, - 1, 2, 2, 2, - 1, - 1, - 1
};
filter.PutCoefficients(ref kernel);
return (IPixelFilter)filter;
}
[VB.NET]
Private Function FilterKernel() As IPixelFilter
Dim Filter As IRasterConvolutionFilter = New RasterConvolutionFilterClass()
Dim kernel As Double() = { -1, -1, -1, 2, 2, 2, -1, -1, -1 }
Filter.PutCoefficients(kernel)
Return CType(Filter, IPixelFilter)
End Function
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 creates a 3 by 3 filter and applies it to a raster:
[C#]
void SetPixelFilterOnRaster(IRaster raster)
{
IStockConvolutionFilter filter = (IStockConvolutionFilter)new
RasterConvolutionFilterClass();
filter.Type = esriRasterFilterTypeEnum.esriRasterFilterSmoothing3x3;
IPixelOperation pixelOp = (IPixelOperation)raster;
pixelOp.PixelFilter = (IPixelFilter)filter;
}
[VB.NET]
Private Sub SetPixelFilterOnRaster(ByVal raster As IRaster)
Dim Filter As IStockConvolutionFilter = CType(New RasterConvolutionFilterClass(), IStockConvolutionFilter)
Filter.Type = esriRasterFilterTypeEnum.esriRasterFilterSmoothing3x3
Dim pixelOp As IPixelOperation = CType(raster, IPixelOperation)
pixelOp.PixelFilter = CType(Filter, IPixelFilter)
End Sub
Raster data loading and other miscellaneous objects
This section includes classes used for mosaicking raster datasets, loading raster datasets and raster catalogs, as well as conversion. It also contains other miscellaneous objects.
Raster mosaicking
The MosaicRaster and RasterLoader classes 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 an input and mosaics all raster datasets, or a portion of the raster datasets in a raster catalog defined by a Where clause, 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 MosaicOperator class. You can also control the output color map for mosaicking color mapped raster datasets.
The MosaicRaster class supports the IRasterProps interface, which allows you to control the properties of the output raster dataset such as pixel type and cell size. By default, the output raster takes the properties from the first raster to be mosaicked (the exception is the output raster takes the union of extents of all rasters). The MosaicRaster class supports the ISaveAs interface, allowing you to create a mosaic output to a file-based raster or to a raster dataset in a geodatabase. The following code creates one seamless raster dataset from a subset of raster datasets in a raster catalog:
[C#]
void MosaicRasterCatalog(IRasterWorkspaceEx ws)
{
//Open a raster catalog.
IRasterCatalog rasterCatalog = ws.OpenRasterCatalog("images");
//Mosaic a raster catalog with a Where clause.
IMosaicRaster mosaicRaster = new MosaicRasterClass();
mosaicRaster.RasterCatalog = rasterCatalog;
mosaicRaster.WhereClause = "state = 'CA'";
//Save the result.
ISaveAs saveAs = (ISaveAs)mosaicRaster;
saveAs.SaveAs("mosaicresult", (IWorkspace)ws, "GDB");
}
[VB.NET]
Private Sub MosaicRasterCatalog(ByVal ws As IRasterWorkspaceEx)
'Open a raster catalog.
Dim rasterCatalog As IRasterCatalog = ws.OpenRasterCatalog("images")
'Mosaic a raster catalog with a Where clause.
Dim mosaicRaster As IMosaicRaster = New MosaicRasterClass()
mosaicRaster.RasterCatalog = rasterCatalog
mosaicRaster.WhereClause = "state = 'CA'"
'Save the result.
Dim saveAs As ISaveAs = CType(mosaicRaster, ISaveAs)
saveAs.SaveAs("mosaicresult", CType(ws, IWorkspace), "GDB")
End Sub
The following code mosaics two rasters to a geodatabase:
[C#]
void Mosaic2(IRasterWorkspaceEx ws, IRaster raster1, IRaster raster2)
{
IRasterCollection rasterCollection = (IRasterCollection)new MosaicRasterClass();
rasterCollection.Append(raster1);
rasterCollection.Append(raster2);
//Save the result.
ISaveAs saveAs = (ISaveAs)rasterCollection;
saveAs.SaveAs("mosaicresult", (IWorkspace)ws, "GDB");
}
[VB.NET]
Private Sub Mosaic2(ByVal ws As IRasterWorkspaceEx, ByVal raster1 As IRaster, ByVal raster2 As IRaster)
Dim rasterCollection As IRasterCollection = CType(New MosaicRasterClass (), IRasterCollection)
rasterCollection.Append (raster1)
rasterCollection.Append (raster2)
'Save the result.
Dim saveAs As ISaveAs = CType(rasterCollection, ISaveAs)
saveAs.SaveAs("mosaicresult", CType(ws, IWorkspace), "GDB")
End Sub
The RasterLoader class is used to mosaic raster data, in any format, to an existing raster dataset. This method works if the existing raster datasets are in a supported writable format, but it works best for ArcSDE or file geodatabase raster datasets. RasterLoader allows you to specify certain properties during data loading such as background value to be ignored or the output color map. This class extends the functionality of IRasterDatasetEdit.Mosaic by allowing you to specify additional properties for the mosaicking operation.
The IRasterLoader interface allows you to specify certain ways to load raster data into an existing raster dataset. MosaicColormapMode sets the operation mode for color map manipulation. Background sets the background value of the input raster to be ignored when loading. Foreground, when set to 255, instructs the loader to load a 1 bit raster into an 8 bit raster dataset for better display effect. PixelAlignmentTolerance sets the tolerance for resampling.
Raster catalog loader
Two loader classes are available in ArcGIS to facilitate raster catalog loading—RasterCatalogLoader and DrLoader (distributed raster catalog loader). RasterCatalogLoader is a class for loading a set of raster datasets or a directory of raster datasets to a geodatabase raster catalog. Since ArcGIS 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 these raster datasets into a geodatabase raster catalog and apply the transformation, re-project to the output dataset during the loading or persisting of the transformation, spatially reference the properties of the raster dataset, or any combination of these options.
Assuming a directory contains images of universal transverse Mercator (UTM) Zone 16 and UTM Zone 17, the following code loads those images to a raster catalog by preserving their original spatial reference. Setting projected to true projects the images to the spatial reference defined in the raster field.
[C#]
void RasterCatalogLoader(IPropertySet propertySet)
{
//Set the storage.
IRasterStorageDef storage = new RasterStorageDefClass();
storage.CompressionType = esriRasterCompressionType.esriRasterCompressionLZ77;
//Set the loader.
IRasterCatalogLoader loader = new RasterCatalogLoaderClass();
loader.ConnectionProperties = propertySet;
loader.StorageDef = storage;
loader.Projected = false;
loader.Load("state_catalog", @"\c:\data", null);
}
[VB.NET]
Private Sub RasterCatalogLoader(ByVal propertySet As IPropertySet)
'Set the storage.
Dim storage As IRasterStorageDef = New RasterStorageDefClass()
storage.CompressionType = esriRasterCompressionType.esriRasterCompressionLZ77
'Set the loader.
Dim loader As IRasterCatalogLoader = New RasterCatalogLoaderClass()
loader.ConnectionProperties = propertySet
loader.StorageDef = storage
loader.Projected = False
loader.Load("state_catalog", "\c:\data", Nothing)
End Sub
When creating a raster catalog of RPC images, you can set IRasterCatalogLoader.Transformed to false to persist 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.
Mensuration
The Mensuration class is used to measure building height, length, area, and location from a single image. The Mensuration class takes a Raster and outputs a measurement result class such as HeightResult, PerimeterResult, or AreaResult, and so on, depending on the type of measurement requested. These classes contain both values of the measurement and the corresponding uncertainty. The minimum requirement of using the Mensuration class is that the input raster must have a spatial reference. Additionally, for measuring building height, the input raster must contain a camera model (RPCXform, FrameXform, and so on) and Sun information (angle and azimuth) if measured with shadow is needed. See the following code:
[C#]
static void MeasureBuildHeight(IRaster inputRaster, IPoint firstPoint, IPoint
secondPoint)
{
//Define the Mensuration class and set the input.
IMensuration measure = new MensurationClass();
measure.Raster = inputRaster;
//Define the mensurement result.
IHeightMeasurement heightResult = new HeightMeasurementClass();
//Measure.
if (measure.CanMeasureHeight == true)
{
measure.GetHeightFromBaseAndTop(firstPoint, secondPoint, out heightResult);
double height = heightResult.HeightMeasurement;
double uncertainty = heightResult.HeightUncertainty;
}
}
[VB.NET]
Private Shared Sub MeasureBuildHeight(inputRaster As IRaster, firstPoint As IPoint, secondPoint As IPoint)
'Define the Mensuration class and set the input.
Dim measure As IMensuration = New MensurationClass()
measure.Raster = inputRaster
'Define the mensurement result.
Dim heightResult As IHeightMeasurement = New HeightMeasurementClass()
'Measure.
If measure.CanMeasureHeight = True Then
measure.GetHeightFromBaseAndTop(firstPoint, secondPoint, heightResult)
Dim height As Double = heightResult.HeightMeasurement
Dim uncertainty As Double = heightResult.HeightUncertainty
End If
End Sub
RasterGeometryProc
The RasterGeometryProc class is used to perform polynomial transformations such as flip, rotate, and warp. It can also project rasters from one spatial reference to another. RasterGeometryProc is built based on the PolynomialXform class but provides easy to use methods for end users.
RasterGeometryProc manipulates only the Raster class, not RasterBand nor RasterDataset. This is because the Raster is transient, as are the effects of the RasterGeometryProc. This means that any transformation disappears when the raster goes out of scope.
To keep the transformed data for later use, you must 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. Alternatively, you can use ISaveAs to save to a new raster dataset. If used on a raster contained in a RasterLayer, processing performed by this class is visible when the display is refreshed. The following code uses the IRasterGeometryProc interface to rotate a raster based on the center of the raster and persist the transformation to the same dataset:
[C#]
void Rotate(IRaster raster)
{
IRasterGeometryProc rasterGP = new RasterGeometryProcClass();
rasterGP.Rotate(null, 45, raster);
rasterGP.Register(raster);
}
[VB.NET]
Private Sub Rotate(ByVal raster As IRaster)
Dim rasterGP As IRasterGeometryProc = New RasterGeometryProcClass()
rasterGP.Rotate(Nothing, 45, raster)
rasterGP.Register(raster)
End Sub
The ProjectFast method projects a raster to a new projection with a specified cell size. In ArcGIS, raster projection is built on a point-to-point approximation algorithm that performs fast and accurate re-projection 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 within a tolerance of a half pixel; otherwise, it projects the remaining pixels using a point-to-point projection. Since pixels on a sub-mesh are 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 higher accuracy than the default half-pixel tolerance.
When more than one domain is involved in a raster dataset, such as a raster dataset with Cube projection, Fuller projection, or projection with non-zero central meridian, the algorithm divides 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 no discontinuity in the output raster dataset.
Color map to RGB conversion
The RasterColormapToRGBConverter class is used to convert between a raster dataset that contains a color map and a three-band raster dataset.
The following code converts a color mapped raster dataset (rasterDataset) to an RGB raster dataset:
[C#]
void ColormapToRGB(IRasterDataset rasterDataset)
{
IRasterColormapToRGBConversion converter = new RasterColormapToRGBConverterClass
();
IRaster raster = converter.CreateRGBRaster(rasterDataset);
ISaveAs saveAs = (ISaveAs)raster;
IWorkspace = (IWorkspace)OpenRasterWorkspace(@"c:\temp");
saveAs.SaveAs("rgbraster.img", ws, "IMAGINE Image");
}
[VB.NET]
Private Sub ColormapToRGB(ByVal rasterDataset As IRasterDataset)
Dim converter As IRasterColormapToRGBConversion = New RasterColormapToRGBConverterClass()
Dim raster As IRaster = converter.CreateRGBRaster(rasterDataset)
Dim saveAs As ISaveAs = CType(raster, ISaveAs)
IWorkspace = CType(OpenRasterWorkspace("c:\temp"), IWorkspace)
saveAs.SaveAs("rgbraster.img", ws, "IMAGINE Image")
End Sub
Other miscellaneous classes
RasterCatalogTable is a legacy class used to represent a table-based raster catalog, and SdeRasterCatalogTable is used for ArcGIS 8.x style raster catalogs.
The RasterDomainExtractor class 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 control.
UniqueValues, StatsHistogram, RasterCalcStatsHistogram, and RasterCalcUniqueValues are helper classes for raster renderers, which are in the Carto library.
DERasterDataset, DERasterBand, and other data element classes are used in geoprocessing scripting language.