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

GDALRasterBand  Class        <gdal_priv.h>

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

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

 

Public Functions

GetLockedBlockRef

GDALRasterBlock *GetLockedBlockRef（int nXBlockOff， int nYBlockOff， int bJustInitialize = FALSE)

获取指向内部缓存栅格块的指针

参数:

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

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

• bJustInitialize -- 如果为 TRUE，则将分配和初始化块，但实际上不会从源读取。当它只是完全设置并写回时，这很有用。

返回:  指向块对象的指针，或失败时为 NULL

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 定义要锁定的数据块的左上角坐标int blockXOff = 0;  // 数据块的起始列int blockYOff = 0;  // 数据块的起始行// 获取锁定的数据块的引用GDALRasterBlock* block = band->GetLockedBlockRef(blockXOff, blockYOff);

TryGetLockedBlockRef

GDALRasterBlock *TryGetLockedBlockRef（int nXBlockOff， int nYBlockYOff)

尝试获取块引用

参数:

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

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

返回:  如果块不可用，则为 NULL，或锁定的块指针

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 定义要锁定的数据块的左上角坐标int blockXOff = 0;  // 数据块的起始列int blockYOff = 0;  // 数据块的起始行// 尝试获取锁定的数据块的引用GDALRasterBlock* block = band->TryGetLockedBlockRef(blockXOff, blockYOff);

1. TryGetLockedBlockRef: 这个函数尝试获取指定位置的锁定数据块的引用，但不会阻塞其他线程或过程对数据块的访问。如果无法立即获取锁定的数据块引用，它将立即返回空指针（nullptr）。这样，其他线程或过程可以继续执行，而不需要等待数据块的可用性。这个函数适用于在多线程环境中使用，以避免等待和竞争条件。

2. GetLockedBlockRef: 这个函数也是用于获取指定位置的锁定数据块的引用，但它是一个阻塞调用。如果无法立即获取锁定的数据块引用，它将等待数据块的可用性，并一直阻塞到数据块可用为止。这意味着其他线程或过程在获取锁定数据块引用之前会被阻塞。因此，这个函数应该在单线程环境或确保不会导致竞争条件的情况下使用。

总结而言，TryGetLockedBlockRef 是一个非阻塞函数，它会立即返回数据块引用（如果可用），而 GetLockedBlockRef 是一个阻塞函数，它会等待数据块的可用性。您应该根据具体的应用场景选择使用哪个函数。在多线程环境下，建议使用 TryGetLockedBlockRef 来避免阻塞其他线程。在单线程环境下，可以使用 GetLockedBlockRef。

FlushBlock

CPLErr FlushBlock（int， int， int bWriteDirtyBlock = TRUE)

从块缓存中清除块

参数:

• nXBlockOff -- 块 x 偏移量

• nYBlockOff -- 块状偏移

• bWriteDirtyBlock -- 如果块脏，是否应该写入磁盘。

返回:   CE_None，如果成功，否则为错误代码

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 定义要写入数据块的左上角坐标int blockXOff = 0;  // 数据块的起始列int blockYOff = 0;  // 数据块的起始行// 获取锁定的数据块的引用GDALRasterBlock* block = band->GetLockedBlockRef(blockXOff, blockYOff);if (block != nullptr){// 在此处处理锁定的数据块// 例如，可以修改数据块的像素值// 将修改后的数据块写入数据集CPLErr err = band->FlushBlock(blockXOff, blockYOff, TRUE);if (err != CE_None){std::cout << "Error writing raster block." << std::endl;}else{std::cout << "Data block written successfully." << std::endl;}// 释放数据块的引用band->DropLock(blockXOff, blockYOff);}

GetIndexColorTranslationTo

unsigned char *GetIndexColorTranslationTo（GDALRasterBand *poReferenceBand， unsigned char *pTranslationTable = nullptr， int *pApproxMatch = nullptr)

计算颜色表的转换表

参数:

• poReferenceBand -- 栅格波段

• pTranslationTable -- 一个已经分配的转换表（至少 256 个字节），或 NULL，让方法分配它

• pApproxMatch -- 指向在匹配是近似时设置的标志的指针。可能为空。

返回:   如果两个波段是调色板索引并且它们不匹配，则为转换表，在其他情况下为 NULL。如果为 pTranslationTable 传递了 NULL，则必须使用 CPLFree 释放该表

    // 获取第一个波段和参考波段（假设参考波段索引为 2）GDALRasterBand* band = dataset->GetRasterBand(1);GDALRasterBand* referenceBand = dataset->GetRasterBand(2);// 获取当前波段的颜色索引到参考波段的颜色索引的转换表int colorTableSize = band->GetColorTable()->GetColorEntryCount(); // 获取颜色表的大小unsigned char* translationTable = new unsigned char[colorTableSize];int approxMatch;band->GetIndexColorTranslationTo(referenceBand, translationTable, &approxMatch);

FlushCache

virtual CPLErr FlushCache（bool bAtClosing = false)

刷新栅格数据缓存        此调用将恢复用于缓存此栅格波段的数据块的内存，并确保将新请求引用到基础驱动程序

参数:

bAtClosing -- 这是否从 GDALDataset 析构函数调用

返回:  CE_None成功

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 读取数据块或执行其他操作，导致波段的缓存被更新// 刷新波段的缓存，将缓存中的数据写入数据集CPLErr err = band->FlushCache();

GetCategoryNames

virtual char **GetCategoryNames()

获取此栅格的类别名称列表

返回:  名称列表，如果没有，则为 NULL

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的分类名称char** categoryNames = band->GetCategoryNames();

GetNoDataValue

virtual double GetNoDataValue（int *pbSuccess = nullptr)

获取此波段的无数据值

参数:

pbSuccess -- 指向布尔值的指针，用于指示值是否实际与此层相关联。可能为 NULL（默认值）。

返回:  此波段的无数据值

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的无数据值int pbSuccess;double noDataValue = band->GetNoDataValue(&pbSuccess);if (pbSuccess){std::cout << "NoData Value: " << noDataValue << std::endl;}else{std::cout << "No NoData Value found for the band." << std::endl;}

GetNoDataValueAsInt64

virtual int64_t GetNoDataValueAsInt64（int *pbSuccess = nullptr)

获取此波段的无数据值        此方法应仅在数据类型为 GDT_Int64 的栅格上调用

参数:

pbSuccess -- 指向布尔值的指针，用于指示值是否实际与此层相关联。可能为 NULL（默认值）。

返回:  此波段的无数据值

GetNoDataValueAsUInt64

virtual uint64_t GetNoDataValueAsUInt64（int *pbSuccess = nullptr)

获取此波段的无数据值。  仅应在数据类型为 GDT_UInt64 的栅格上调用此方法

GetMinimum

virtual double GetMinimum(int *pbSuccess = nullptr)

获取此波段的最小值

参数:

pbSuccess -- 指向布尔值的指针，用于指示返回值是否为紧最小值。可能为 NULL（默认值）。

返回:  最小栅格值（不包括无数据像素）

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的最小值int pbSuccess;double minValue = band->GetMinimum(&pbSuccess);if (pbSuccess){std::cout << "Minimum Value: " << minValue << std::endl;}else{std::cout << "Failed to get the minimum value for the band." << std::endl;}

GetMaximum

virtual double GetMaximum(int *pbSuccess = nullptr)

获取此波段的最大值

参数:

pbSuccess -- 指向布尔值的指针，用于指示返回值是否为紧最小值。可能为 NULL（默认值）。

返回:  最小栅格值（不包括无数据像素）

GetOffset

virtual double GetOffset（int *pbSuccess = nullptr)

获取栅格值偏移       

参数:

pbSuccess -- 指向布尔值的指针，用于指示返回值是否有意义。可能为 NULL（默认值）。

返回:  栅格偏移

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的数据偏移值int pbSuccess;double offset = band->GetOffset(&pbSuccess);if (pbSuccess){std::cout << "Offset Value: " << offset << std::endl;}else{std::cout << "Failed to get the offset value for the band." << std::endl;}

GetScale

virtual double GetScale（int *pbSuccess = nullptr)

获取栅格值比例         单位值 =（原始值 * 比例）+ 偏移量

参数:

pbSuccess -- 指向布尔值的指针，用于指示返回值是否有意义。可能为 NULL（默认值）。

返回:  栅格比例

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的数据比例尺int pbSuccess;double scale = band->GetScale(&pbSuccess);if (pbSuccess){std::cout << "Scale Value: " << scale << std::endl;}else{std::cout << "Failed to get the scale value for the band." << std::endl;}

1. 遥感影像数据：

   • 灰度影像：通常使用一个常数比例尺，例如 0.1 表示每个像素值乘以 0.1 后得到实际测量值。
   • 无单位浮点影像：通常使用一个常数比例尺，例如 0.01 表示每个像素值乘以 0.01 后得到实际物理量值（例如辐射亮度）。
   • 有单位浮点影像：通常使用一个常数比例尺，例如 0.001 表示每个像素值乘以 0.001 后得到实际物理量值（例如温度）。

2. GIS 矢量数据：

   • 点数据：比例尺通常用于将地理坐标（经纬度或投影坐标）转换为实际长度（例如米）。
   • 线数据和多边形数据：比例尺用于将地理坐标转换为实际长度。

GetUnitType

virtual const char *GetUnitType()

返回栅格单位类型

返回: 设备名称字符串

GetUnitType() 是用于获取数据单位类型的函数，

而 GetRasterDataType() 是用于获取像素值的数据类型的函数

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的单位类型const char* unitType = band->GetUnitType();

GetColorInterpretation

virtual GDALColorInterp GetColorInterpretation()

这条带应该如何解释为颜色

当格式对颜色解释一无所知时，将返回GCI_Undefined

返回: 波段的颜色解释值

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的颜色解释方式GDALColorInterp colorInterp = band->GetColorInterpretation();switch (colorInterp){case GCI_Undefined:std::cout << "Color Interpretation: Undefined" << std::endl;break;case GCI_GrayIndex:std::cout << "Color Interpretation: Gray Index" << std::endl;break;case GCI_PaletteIndex:std::cout << "Color Interpretation: Palette Index" << std::endl;break;case GCI_RedBand:std::cout << "Color Interpretation: Red Band" << std::endl;break;case GCI_GreenBand:std::cout << "Color Interpretation: Green Band" << std::endl;break;case GCI_BlueBand:std::cout << "Color Interpretation: Blue Band" << std::endl;break;// 其他颜色解释方式可以继续添加在这里default:std::cout << "Color Interpretation: Unknown" << std::endl;break;}

    GCI_Undefined = 0,      // 未定义颜色解释方式
    GCI_GrayIndex = 1,      // 灰度图像
    GCI_PaletteIndex = 2,   // 调色板索引图像
    GCI_RedBand = 3,        // 红色波段
    GCI_GreenBand = 4,      // 绿色波段
    GCI_BlueBand = 5,       // 蓝色波段
    GCI_AlphaBand = 6,      // 透明度（Alpha）波段
    GCI_HueBand = 7,        // 色调（Hue）波段
    GCI_SaturationBand = 8, // 饱和度（Saturation）波段
    GCI_LightnessBand = 9,  // 亮度（Lightness）波段
    GCI_CyanBand = 10,      // 青色（Cyan）波段
    GCI_MagentaBand = 11,   // 品红色（Magenta）波段
    GCI_YellowBand = 12,    // 黄色（Yellow）波段
    GCI_BlackBand = 13,     // 黑色（Black）波段
    GCI_YCbCr_YBand = 14,   // YCbCr 颜色空间的 Y 波段
    GCI_YCbCr_CbBand = 15,  // YCbCr 颜色空间的 Cb 波段
    GCI_YCbCr_CrBand = 16   // YCbCr 颜色空间的 Cr 波段

GetColorTable

virtual GDALColorTable *GetColorTable()

获取与波段关联的颜色表

如果没有关联的颜色表，则返回结果为 NULL

返回:  内部颜色表，或 NULL

    // 获取第一个波段GDALRasterBand* band = dataset->GetRasterBand(1);// 获取波段的颜色表GDALColorTable* colorTable = band->GetColorTable();if (colorTable != nullptr){int numColors = colorTable->GetColorEntryCount();std::cout << "Number of Colors in Color Table: " << numColors << std::endl;// 输出颜色表中的颜色for (int i = 0; i < numColors; ++i){GDALColorEntry colorEntry;colorTable->GetColorEntryAsRGB(i, &colorEntry);std::cout << "Color " << i << ": R=" << static_cast<int>(colorEntry.c1) << ", "<< "G=" << static_cast<int>(colorEntry.c2) << ", "<< "B=" << static_cast<int>(colorEntry.c3) << std::endl;}}else{std::cout << "No color table found for the band." << std::endl;}