GDAL C++ API 学习之路 （1） GDALRasterBand篇 代码示例 翻译 自学

GDALRasterBand  Class        <gdal_priv.h>

GDALRasterBand是GDAL中用于表示栅格数据集中一个波段的类。栅格数据集通常由多个波段组成，每个波段包含了特定的数据信息，例如高程、红、绿、蓝色等，

用于表示影像的不同特征。提供了许多功能来访问和操作波段的像素数据以及相关信息。它是GDAL C++ API中处理栅格数据的核心类之一，为栅格数据处理和分析提供了强大的功能和灵活性。

Public Functions​​​​​​​

GetXSize

int GetXSize()                

获取栅格的 XSize                

返回:此波段的宽度（以像素为单位）

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 获取 X 方向大小
    int xSize = band->GetXSize();

    // 输出 X 方向大小
    std::cout << "X Size: " << xSize << std::endl;

GetYSize

int GetYSize()

获取栅格的 YSize

返回:  此波段的高度（以像素为单位）

与上面同理

GetBand

int GetBand()

获取频段编号

返回:  波段编号 （1+） 或 0（如果波段编号未知）

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 获取当前波段的频段编号
    int bandNumber = band->GetBand();

    // 输出频段编号
    std::cout << "Band Number: " << bandNumber << std::endl;

GetRasterDataType

GDALDataType GetRasterDataType（void)

获取此波段的像素数据类型

返回:  此波段的像素数据类型

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 获取当前波段的像素数据类型
    GDALDataType dataType = band->GetRasterDataType();

    // 输出像素数据类型的字符串表示
    const char* dataTypeStr = GDALGetDataTypeName(dataType);
    std::cout << "Raster Data Type: " << dataTypeStr << std::endl

有可能一个数据集（GDALDataset）中的不同波段（GDALRasterBand）具有不同的像素数据类型。在实际应用中，一个多波段数据集中的不同波段可能表示不同的信息，因此它们的像素数据类型可以不同。

例如，对于一张彩色影像，通常有三个波段：红、绿和蓝。红、绿和蓝波段可能具有不同的像素数据类型，例如红波段可能是8位无符号整数（GDT_Byte），绿波段可能是16位无符号整数（GDT_UInt16），蓝波段可能是32位浮点数（GDT_Float32）。

因此，在处理多波段数据集时，您需要注意每个波段的像素数据类型，以确保正确解释和处理像素值。您可以通过GDALRasterBand类的GetRasterDataType()函数来获取每个波段的像素数据类型，进而处理不同类型的像素值。

GetBlockSize

void GetBlockSize（int*， int*)

获取此波段的“自然”块大小

参数:

• pnXSize -- 整数，用于将 X 块大小放入或 NULL。

• pnYSize -- 整数，用于将 Y 块大小放入或 NULL 

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 获取当前波段的数据块大小
    int blockWidth, blockHeight;
    band->GetBlockSize(&blockWidth, &blockHeight);

    // 输出数据块大小
    std::cout << "Block Width: " << blockWidth << std::endl;
    std::cout << "Block Height: " << blockHeight << std::endl;

GetActualBlockSize

CPLErr GetActualBlockSize（int， int， int*， int*)

获取给定块偏移的实际块大小        处理栅格边缘的部分块并返回真实的像素数

参数:

• nXBlockOff -- 用于计算有效像素数的水平块偏移量，零表示最左边的块，1 表示下一个块，依此类推。

• nYBlockOff -- 垂直块偏移量，零表示最左边的块，1 表示下一个块，依此类推。

• pnXValid -- 指向一个整数的指针，其中将存储 x 方向上有效像素的数量

• pnYValid -- 指向一个整数的指针，其中将存储 y 方向上有效像素的数量

返回:  CE_None输入参数是否有效，否则CE_Failure

GDALSuggestedBlockAccessPattern

virtual GDALSuggestedBlockAccessPattern GetSuggestedBlockAccessPattern（） const

将建议/最有效的访问模式返回到块（用于读取操作）

1. GF_READ：仅读取模式。此模式下，数据块可以被读取，但不能进行写入操作。

2. GF_WRITE：仅写入模式。此模式下，数据块可以被写入，但不能进行读取操作。

3. GF_READWRITE：读写模式。此模式下，数据块既可以被读取，也可以进行写入操作。

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 获取数据块的访问模式
    GDALSuggestedBlockAccessPattern accessPattern = band->GetSuggestedBlockAccessPattern();

    // 根据获取的访问模式进行操作
    switch (accessPattern)
    {
    case GF_READ: // 仅读取模式
        std::cout << "Block Access Pattern: Read Only" << std::endl;
        break;
    case GF_READWRITE: // 读写模式
        std::cout << "Block Access Pattern: Read and Write" << std::endl;
        break;
    case GF_WRITE: // 仅写入模式
        std::cout << "Block Access Pattern: Write Only" << std::endl;
        break;
    default:
        std::cout << "Block Access Pattern: Unknown" << std::endl;
        break;
    }

GetAccess

GDALAccess GetAccess()

了解我们是否具有此频段的更新权限

返回: 要么GA_Update，要么GA_ReadOnly

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 获取数据块的访问模式
    GDALAccess access = band->GetAccess();

    // 根据获取的访问模式进行操作
    switch (access)
    {
    case GA_ReadOnly:
        std::cout << "Band Access Mode: Read Only" << std::endl;
        break;
    case GA_Update:
        std::cout << "Band Access Mode: Read and Write" << std::endl;
        break;
    default:
        std::cout << "Band Access Mode: Unknown" << std::endl;
        break;
    }

RasterIO

CPLErr RasterIO（GDALRWFlag， int， int， int， void*， int， int， GDALDataType， GSpacing ， GSpacing， GDALRasterIOExtraArg *psExtraArg )

读取/写入此波段的图像数据区域

参数:

• eRWFlag -- GF_Read读取数据区域，或GF_Write写入数据区域。

• nXOff -- 要访问的波段区域左上角的像素偏移。从左侧开始将为零。

• nYOff -- 要访问的波段区域左上角的线偏移量。从顶部开始，这将是零。

• nXSize -- 要访问的波段区域的宽度（以像素为单位）。

• nYSize -- 要以行为单位访问的波段区域的高度。

• pData -- [inout] 应将数据读取或写入的缓冲区。此缓冲区必须至少包含 nBufXSize * nBufYSize 类型为 eBufType 的单词。它按从左到右，从上到下的像素顺序进行组织。间距由 nPixelSpace 和 nLineSpace 参数控制。

• nBufXSize -- 要读取所需区域或从中写入所需区域的缓冲区图像的宽度。

• nBufYSize -- 要读取所需区域或从中写入所需区域的缓冲区图像的高度。

• eBufType -- pData 数据缓冲区中像素值的类型。像素值将根据需要自动转换为 GDALRasterBand 数据类型。

• nPixelSpace -- 从 pData 中一个像素值的开始到扫描线内下一个像素值的开始的字节偏移量。如果默认值 （0），则使用数据类型 eBufType 的大小。

• nLineSpace -- 从 pData 中一条扫描线的开头到下一条扫描线开头的字节偏移量。如果默认值 （0），则使用数据类型 eBufType * nBufXSize 的大小。

• psExtraArg -- [in]（GDAL 2.0 中的新功能）指向 GDALRasterIOExtraArg 结构的指针，带有用于指定重采样和进度回调的附加参数，或默认行为的 NULL。还可以定义GDAL_RASTERIO_RESAMPLING配置选项，以覆盖默认重采样为双线性、立方、立方样、兰佐斯、平均或模式之一。

返回:  如果访问失败，则CE_Failure，否则CE_None

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 定义读取的数据范围和数据类型
    int xOff = 0;            // 读取数据的起始列
    int yOff = 0;            // 读取数据的起始行
    int xSize = 100;         // 读取数据的列数
    int ySize = 100;         // 读取数据的行数
    int nbufXSize = xSize;    // 输出缓冲区的列数（设置与 xSize 相同）
    int nbufYSize = ySize;    // 输出缓冲区的行数（设置与 ySize 相同）
    GDALDataType dataType = GDT_Float32;  // 读取的数据类型

    // 分配输出缓冲区
    float* buffer = new float[xSize * ySize];

    // 定义读取选项
    GDALRasterIOExtraArg options;
    options.eResampleAlg = GRIORA_NearestNeighbour; // 设置重采样算法

    // 执行数据读取
    CPLErr err = band->RasterIO(GF_Read, xOff, yOff, xSize, ySize, buffer, nbufXSize, nbufYSize, dataType, 0, 0, &options);

    // 检查读取是否成功
    if (err != CE_None)
    {
        std::cout << "Error reading raster data." << std::endl;
    }
    else
    {
        // 在此处处理读取的数据
        // 例如，可以输出前 10 个像素的值
        for (int i = 0; i < 10; i++)
        {
            std::cout << "Pixel " << i << ": " << buffer[i] << std::endl;
        }
    }

    // 释放资源并关闭数据集
    delete[] buffer;

ReadBlock

CPLErr ReadBlock（int， int， void *)

高效读取图像数据块

参数:

• nXBlockOff -- 水平块偏移量，零表示最左边的块，1 表示下一个块，依此类推。

• nYBlockOff -- 垂直块偏移量，零表示最上面的块，1 表示下一个块，依此类推。

• pImage -- 数据将被读取到的缓冲区。缓冲区必须足够大，以容纳 GetRasterDataType（） 类型的 GetBlockXSize（）*GetBlockYSize（） 字。

返回:  CE_None成功或CE_Failure错误

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 定义数据块的左上角坐标
    int blockXOff = 0;  // 数据块的起始列
    int blockYOff = 0;  // 数据块的起始行

    // 获取数据块的大小
    int blockXSize = band->GetBlockXSize();  // 数据块的列数
    int blockYSize = band->GetBlockYSize();  // 数据块的行数

    // 分配输出缓冲区
    float* buffer = new float[blockXSize * blockYSize];

    // 执行数据读取
    CPLErr err = band->ReadBlock(blockXOff, blockYOff, buffer);
    
    //执行某些操作

    // 释放资源并关闭数据集
    delete[] buffer;

WriteBlock

CPLErr WriteBlock（int， int， void *)

高效写入图像数据块

参数:

• nXBlockOff -- 水平块偏移量，零表示最左边的块，1 表示下一个块，依此类推。

• nYBlockOff -- 垂直块偏移量，零表示最左边的块，1 表示下一个块，依此类推。

• pImage -- 将从中写入数据的缓冲区。缓冲区必须足够大，以容纳 GetRasterDataType（） 类型的 GetBlockXSize（）*GetBlockYSize（） 字。

返回:  CE_None成功或CE_Failure错误

    // 获取第一个波段
    GDALRasterBand* band = dataset->GetRasterBand(1);

    // 定义数据块的左上角坐标
    int blockXOff = 0;  // 数据块的起始列
    int blockYOff = 0;  // 数据块的起始行

    // 获取数据块的大小
    int blockXSize = band->GetBlockXSize();  // 数据块的列数
    int blockYSize = band->GetBlockYSize();  // 数据块的行数

    // 分配输入缓冲区，用于存储要写入数据块的栅格数据
    float* buffer = new float[blockXSize * blockYSize];

    // 在此处填充输入缓冲区，例如，将缓冲区中的数据设置为一定值

    // 执行数据写入
    CPLErr err = band->WriteBlock(blockXOff, blockYOff, buffer);

    //执行某些操作

    // 释放资源并关闭数据集
    delete[] buffer;

​​​​​​​