This document is archived and information here might be outdated.  Recommended version.


How to access pixel data using a raster cursor (ArcObjects .NET 10.6 SDK)
ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Managing data > Working with image and raster data > Accessing raster datasets > How to access pixel data using a raster cursor (ArcObjects .NET 10.6 SDK)

How to access pixel data using a raster cursor


Summary
When you're working with pixel blocks on a large raster dataset, you need to work with a raster cursor to read data block-by-block to avoid reading all the pixels at one time. This topic shows how to work with a pixel block and raster cursor to read and write pixel values.

Accessing pixel blocks using a raster cursor

Raster pixel access is normally handled block-by-block, and the RasterCursor class is used to loop through the pixel blocks of a whole raster. You can define the size of a pixel block or use a system-optimized pixel block size.
To access pixel blocks using a raster cursor, see the following code example:
[C#]
public static void UsingRasterCursorWithPixelBlock(IRasterDataset2 rasterDs)
{
    try
    {
        //Create a raster. 
        IRaster2 raster2=rasterDs.CreateFullRaster()as IRaster2;
        //Create a raster cursor with a system-optimized pixel block size by passing a null.
        IRasterCursor rasterCursor=raster2.CreateCursorEx(null);
        //Use the IRasterEdit interface.
        IRasterEdit rasterEdit=raster2 as IRasterEdit;
        //Loop through each band and pixel block.
        IRasterBandCollection bands=rasterDs as IRasterBandCollection;
        IPixelBlock3 pixelblock3=null;
        long blockwidth=0;
        long blockheight=0;
        System.Array pixels;
        IPnt tlc=null;
        object v;
        long bandCount=bands.Count;
        do
        {
            pixelblock3=rasterCursor.PixelBlock as IPixelBlock3;
            blockwidth=pixelblock3.Width;
            blockheight=pixelblock3.Height;
            pixelblock3.Mask(255);
            for (int k=0; k < bandCount; k++)
            {
                //Get the pixel array.
                pixels=(System.Array)pixelblock3.get_PixelData(k);
                for (long i=0; i < blockwidth; i++)
                {
                    for (long j=0; j < blockheight; j++)
                    {
                        //Get the pixel value.
                        v=pixels.GetValue(i, j);
                        //Do something with the value.
                    }
                }
                //Set the pixel array to the pixel block.
                pixelblock3.set_PixelData(k, pixels);
            }
            //Write back to the raster.
            tlc=rasterCursor.TopLeft;
            rasterEdit.Write(tlc, (IPixelBlock)pixelblock3);
        }
        while (rasterCursor.Next() == true);
        System.Runtime.InteropServices.Marshal.ReleaseComObject(rasterEdit);
    }
    catch (Exception ex)
    {
        System.Diagnostics.Debug.WriteLine(ex.Message);
    }
}
[VB.NET]
Public Sub UsingRasterCursorWithPixelBlock(ByVal rasterDS As IRasterDataset2)
    
    Try
    'Create a raster from the raster dataset.
    Dim raster2 As IRaster2
    Dim rasterCursor As IRasterCursor
    raster2=rasterDS.CreateFullRaster
    'Create a raster cursor using a default pixel block size.
    rasterCursor=raster2.CreateCursorEx(Nothing)
    'Use the IRasterEdit interface to edit the pixel values.
    Dim rasterEdit As IRasterEdit
    rasterEdit=raster2
    'Loop through each pixel block in the raster, modify some pixels, and write back.
    Dim rasterBands As IRasterBandCollection
    Dim pixelBlock As IPixelBlock3
    Dim tlc As IPnt
    Dim k As Long, i As Long, j As Long
    Dim pixels As System.Array
    Dim Value As UInt16 ' Assume the input raster has a 16-bit unsigned type.
    Dim PixelBlockWidth As Long, PixelBlockHeight As Long
    rasterBands=rasterDS
    Do
        'Get the pixel block and size.
        pixelBlock=rasterCursor.PixelBlock
        PixelBlockWidth=pixelBlock.Width
        PixelBlockHeight=pixelBlock.Height
        pixelBlock.Mask(255) 'Set NoData mask.
        For k=0 To rasterBands.Count - 1
            'Get the pixel array.
            pixels=CType(pixelBlock.PixelData(k), System.Array)
            'Loop through each pixel.
            For i=0 To PixelBlockWidth - 1
                For j=0 To PixelBlockHeight - 1
                    'Get the pixel value.
                    Value=pixels.GetValue(i, j)
                    'Do something with the value.
                Next
            Next
            'Set the pixel array to the pixel block.
            pixelBlock.PixelData(k)=pixels
        Next
        'Get the top left corner of the pixel block and write back.
        tlc=rasterCursor.TopLeft
        rasterEdit.Write(tlc, pixelBlock)
    Loop While rasterCursor.Next
    Catch ex As Exception
    System.Diagnostics.Trace.WriteLine(ex.Message)
    End Try
End Sub


See Also:

How to access pixel data using the RawBlocks object




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):
Development licensing Deployment licensing
ArcGIS Desktop Basic ArcGIS Desktop Basic
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Advanced ArcGIS Desktop Advanced
Engine Developer Kit Engine