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

GDALRasterBand  Class        <gdal_priv.h>

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

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

Public Functions

Fill

virtual CPLErr Fill（double dfRealValue， double dfImaginaryValue = 0)

用常量值填充此波段

参数:

• dfRealValue -- 填充值的实数分量

• dfImaginaryValue -- 填充值的虚部，默认为零

返回:  CE_Failure如果写入失败，否则CE_None

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

    // 填充波段的像素值为指定的实部和虚部值
    double realValue = 100.0;
    double imaginaryValue = 50.0;
    CPLErr err = band->Fill(realValue, imaginaryValue);

SetNoDataValue

virtual CPLErr SetNoDataValue（double dfNoData)

为此波段设置无数据值

参数:

dfNoData -- 要设置的值。

返回:  CE_None成功，或CE_Failure失败。如果驱动程序不支持，则返回CE_Failure不会发出任何错误消息

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

    // 设置无数据值
    double noDataValue = -9999.0;
    CPLErr err = band->SetNoDataValue(noDataValue);

SetNoDataValueAsInt64

virtual CPLErr SetNoDataValueAsInt64（int64_t nNoData)

为此波段设置无数据值。

此方法应仅在数据类型为 GDT_Int64 的栅格上调用

SetNoDataValueAsUInt64

virtual CPLErr SetNoDataValueAsUInt64（uint64_t nNoData)

为此波段设置无数据值。

仅应在数据类型为 GDT_UInt64 的栅格上调用此方法

DeleteNoDataValue

Virtual CPLErr DeleteNoDataValue()

移除此波段的无数据值

返回:  CE_None成功，或CE_Failure失败。如果驱动程序不支持，则返回CE_Failure不会发出任何错误消息

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

    // 删除无数据值
    CPLErr err = band->DeleteNoDataValue();

SetColorTable

virtual CPLErr SetColorTable（GDALColorTable *poCT)

设置栅格颜色表

参数:

poCT -- 要应用的颜色表。这可能是 NULL 以清除颜色表（如果支持）。

返回:  CE_None成功，或CE_Failure失败。如果驱动程序不支持该操作，则返回值 CE_Failure，但不发出错误

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

    // 创建颜色表并添加颜色项
    GDALColorTable* colorTable = new GDALColorTable(GPI_RGB);
    GDALColorEntry colorEntry;

    colorEntry.c1 = 255; // 红色分量
    colorEntry.c2 = 0;   // 绿色分量
    colorEntry.c3 = 0;   // 蓝色分量
    colorEntry.c4 = 255; // Alpha（透明度）分量
    colorTable->SetColorEntry(0, &colorEntry); // 将像素值为 0 的颜色设置为红色

    colorEntry.c1 = 0;   // 红色分量
    colorEntry.c2 = 255; // 绿色分量
    colorEntry.c3 = 0;   // 蓝色分量
    colorEntry.c4 = 255; // Alpha（透明度）分量
    colorTable->SetColorEntry(1, &colorEntry); // 将像素值为 1 的颜色设置为绿色

    // 设置颜色表
    CPLErr err = band->SetColorTable(colorTable);

SetColorInterpret

virtual CPLErr SetColorInterpret（GDALColorInterp eColorInterp )

设置波段的颜色解释

参数:

eColorInterp -- 适用于此波段的新颜色解释。

返回:CE_None成功或CE_Failure如果格式不支持方法

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

    // 设置颜色解释为红色
    CPLErr err = band->SetColorInterpret(GCI_RedBand);

SetOffset

virtual CPLErr SetOffset（double dfNewOffset)

设置缩放偏移

参数:

dfNewOffset -- 新的偏移量。

返回:CE_None或成功或失败CE_Failure

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

    // 设置偏移值
    double newOffset = 100.0;
    CPLErr err = band->SetOffset(newOffset);

SetScale

virtual CPLErr SetScale（double dfNewScale)

设置缩放比例

参数:

dfNewScale -- 新的规模。

返回:CE_None或成功或失败CE_Failure

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

    // 设置比例尺
    double newScale = 0.01;
    CPLErr err = band->SetScale(newScale);

SetUnitType

virtual CPLErr SetUnitType（const char *pszNewValue)

设置单位类型        设置栅格波段的单位类型。值应为“”（默认值表示未知）、“m”表示米或“ft”表示英尺之一，但允许使用其他非标准值

参数:

pszNewValue -- 新的单位类型值。

返回:CE_None成功或CE_Failure（如果不成功）或不受支持

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

    // 设置单位类型
    const char* unitType = "meters";
    CPLErr err = band->SetUnitType(unitType);

GetStatistics

virtual CPLErr GetStatistics（int bApproxOK， int bForce， double *pdfMin， double *pdfMax， double *pdfMean， double *padfStdDev)

获取图像统计信息

返回此波段中所有像素值的最小、最大值、平均值和标准差。如果近似统计数据足够，则可以将 bApproxOK 标志设置为 true，在这种情况下，可以使用概览或图像磁贴的子集来计算统计数据

参数:

• bApproxOK -- 如果可以根据概览或所有切片的子集计算 TRUE 统计数据。

• bForce -- 如果 FALSE 统计信息仅在无需重新扫描图像的情况下返回。如果为 TRUE，则在预先存在的值无法快速获得时强制进行统计计算。

• pdfMin -- 将图像加载到的最小值位置（可能为 NULL）。

• pdfMax -- 加载图像最大值的位置（可能为 NULL）。

• pdfMean -- 加载图像均值的位置（可能为 NULL）。

• pdfStdDev -- 加载图像标准偏差的位置（可能为 NULL）。

返回: 成功时CE_None，如果未返回任何值，则CE_Warning，CE_Failure发生错误

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

    // 获取波段的统计信息
    int bApproxOK = false; // 是否允许使用近似统计信息
    int bForce = true;     // 是否强制重新计算统计信息
    double pdfMin, pdfMax, pdfMean, padfStdDev;
    CPLErr err = band->GetStatistics(bApproxOK, bForce, &pdfMin, &pdfMax, &pdfMean, &padfStdDev);

    if (err == CE_None)
    {
        std::cout << "Statistics information:" << std::endl;
        std::cout << "Minimum: " << pdfMin << std::endl;
        std::cout << "Maximum: " << pdfMax << std::endl;
        std::cout << "Mean: " << pdfMean << std::endl;
        std::cout << "Standard Deviation: " << padfStdDev << std::endl;
    }
    else
    {
        std::cout << "Failed to get statistics information." << std::endl;
    }

ComputeStatistics

virtual CPLErr ComputeStatistics（int bApproxOK， double *pdfMin， double *pdfMax， double *pdfMean， double *pdfStdDev， GDALProgressFunc， void *pProgressData)

计算图像统计信息

返回此波段中所有像素值的最小、最大值、平均值和标准差。如果近似统计数据足够，则可以将 bApproxOK 标志设置为 true，在这种情况下，可以使用概览或图像磁贴的子集来计算统计数据

参数:

• bApproxOK -- 如果可以根据概览或所有切片的子集计算 TRUE 统计数据。

• pdfMin -- 将图像加载到的最小值位置（可能为 NULL）。

• pdfMax -- 加载图像最大值的位置（可能为 NULL）。

• pdfMean -- 加载图像均值的位置（可能为 NULL）。

• pdfStdDev -- 加载图像标准偏差的位置（可能为 NULL）。

• pfnProgress -- 用于调用以报告进度或 NULL 的函数。

• pProgressData -- 要传递给进度函数的应用程序数据。

返回:  成功时CE_None，如果发生错误或用户终止处理，则CE_Failure

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

    // 计算波段的统计信息
    int bApproxOK = false; // 是否允许使用近似统计信息
    double pdfMin, pdfMax, pdfMean, pdfStdDev;
    CPLErr err = band->ComputeStatistics(bApproxOK, &pdfMin, &pdfMax, &pdfMean, &pdfStdDev, ProgressFunc, nullptr);

    if (err == CE_None)
    {
        std::cout << "Minimum: " << pdfMin << std::endl;
        std::cout << "Maximum: " << pdfMax << std::endl;
        std::cout << "Mean: " << pdfMean << std::endl;
        std::cout << "Standard Deviation: " << pdfStdDev << std::endl;
    }
    else
    {
        std::cout << "Failed to compute statistics." << std::endl;
    }

SetStatistics

virtual CPLErr SetStatistics（double dfMin， double dfMax， double dfMean， double dfStdDev)

设置波段统计信息        此方法可用于在栅格波段上存储最小/最大值/平均值/标准差统计数据

参数:

• dfMin -- 最小像素值。

• dfMax -- 最大像素值。

• dfMean -- 所有像素值的平均值（平均值）。

• dfStdDev -- 所有像素值的标准偏差。

返回: CE_None成功或CE_Failure失败

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

    // 设置波段的统计信息
    double dfMin = 0.0;      // 最小值
    double dfMax = 255.0;    // 最大值
    double dfMean = 127.5;   // 均值
    double dfStdDev = 50.0;  // 标准差

    CPLErr err = band->SetStatistics(dfMin, dfMax, dfMean, dfStdDev);

SetStatistics 函数允许用户手动设置波段的统计信息，包括最小值、最大值、均值和标准差等。虽然通常统计信息是从波段数据计算而来，但有时用户可能希望自行指定统计信息，以便在数据可视化或处理过程中更好地控制数据范围。

用户设置的统计信息可能会导致与从数据计算得到的统计信息不一致的情况。这样做可能会对数据的显示和处理产生影响。因此，在手动设置统计信息时，需要确保所设置的值与实际数据的分布相符合。

为了避免不一致的情况，建议在手动设置统计信息之前先进行数据的预处理和分析，确保设置的值合理且符合实际情况。

需要注意的是，SetStatistics 函数仅用于设置统计信息，不会影响实际数据的值。要修改数据本身，可以使用 RasterIO 函数进行读写操作

ComputeRasterMinMax

Virtual CPLErr ComputeRasterMinMax（int， double*)

计算波段的最小值/最大值

参数:

• bApproxOK -- 如果近似（更快）答案为 OK，则为 TRUE，否则为 FALSE。

• adfMinMax -- 返回最小值 （adfMinMax[0]） 和最大值 （adfMinMax[1]） 的数组。

返回: CE_None成功或CE_Failure失败

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

    // 计算波段的最小值和最大值
    int approxOK = false; // 是否允许使用近似计算
    double minMax[2];
    CPLErr err = band->ComputeRasterMinMax(approxOK, minMax);

    if (err == CE_None)
    {
        std::cout << "Minimum: " << minMax[0] << std::endl;
        std::cout << "Maximum: " << minMax[1] << std::endl;
    }
    else
    {
        std::cout << "Failed to compute raster min/max." << std::endl;
    }

GetMetadataItem

virtual const char *GetMetadataItem(const char *pszName, const char *pszDomain = "") override

提取单个元数据项

参数:

• pszName -- 要获取的元数据项的键。

• pszDomain -- 要获取的域，使用 NULL 作为默认域。

返回:  找不到键时为 NULL，成功时指向值字符串的内部副本的指针

    // 获取数据集或波段的元数据项
    const char* pszName = "METADATANAME"; // 要获取的元数据项名称
    const char* pszDomain = ""; // 元数据项所属的域，可以为空字符串

    const char* pszValue = dataset->GetMetadataItem(pszName, pszDomain);

    if (pszValue != nullptr)
    {
        std::cout << "Metadata item " << pszName << ": " << pszValue << std::endl;
    }
    else
    {
        std::cout << "Metadata item not found." << std::endl;
    }

GetOverviewCount

virtual int GetOverviewCount()

返回可用的概览图层数

返回:  概述计数，如果没有，则为零

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

    // 获取波段的概览数量
    int overviewCount = band->GetOverviewCount();

    std::cout << "Number of overviews: " << overviewCount << std::endl;

GetOverview

virtual GDALRasterBand *GetOverview（int)

获取概览栅格波段对象

参数:

i -- 介于 0 和 GetOverviewCount（）-1 之间的概览索引。

返回:  概述 GDALRasterBand.

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

    // 获取第一个概览波段
    int overviewIndex = 0;
    GDALRasterBand* overviewBand = band->GetOverview(overviewIndex);

    if (overviewBand != nullptr)
    {
        std::cout << "Overview Band Index: " << overviewIndex << std::endl;
        std::cout << "Overview Band XSize: " << overviewBand->GetXSize() << std::endl;
        std::cout << "Overview Band YSize: " << overviewBand->GetYSize() << std::endl;
    }
    else
    {
        std::cout << "Overview Band not found." << std::endl;
    }

GetHistogram

virtual CPLErr GetHistogram（double dfMin， double dfMax， int nBuckets， GUIntBig *panHistogram， int bIncludeOutOfRange， int bApproxOK， GDALProgressFunc， void *pProgressData)

计算栅格直方图

参数:

• dfMin -- 直方图的下限。

• dfMax -- 直方图的上限。

• nBuckets -- panHistogram 中的存储桶数。

• panHistogram -- 放置直方图总数的数组。

• bIncludeOutOfRange -- 如果低于直方图范围的 TRUE 值将映射到 panHistogram[0]，并且上面的值将映射到 panHistogram[nBuckets-1]，否则超出范围的值将被丢弃。

• bApproxOK -- 如果近似或不完整的直方图为 OK，则为 TRUE。

• pfnProgress -- 报告进度完成的函数。

• pProgressData -- 要传递给 pfnProgress 的应用程序数据。

返回:  CE_None成功，或者CE_Failure出了什么问题

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

    // 设置直方图参数
    double dfMin, dfMax;
    int nBuckets = 256;
    GUIntBig* panHistogram = new GUIntBig[nBuckets];
    int bIncludeOutOfRange = FALSE;
    int bApproxOK = FALSE;
    GDALProgressFunc pfnProgress = GDALTermProgress;
    void* pProgressData = nullptr;

    // 获取直方图
    CPLErr err = band->GetHistogram(dfMin, dfMax, nBuckets, panHistogram,
                                    bIncludeOutOfRange, bApproxOK, pfnProgress, pProgressData);

    if (err == CE_None)
    {
        // 输出直方图结果
        std::cout << "Histogram: " << std::endl;
        for (int i = 0; i < nBuckets; ++i)
        {
            std::cout << "Bucket " << i << ": " << panHistogram[i] << std::endl;
        }
    }
    else
    {
        std::cout << "Failed to compute histogram." << std::endl;
    }

    // 释放内存
    delete[] panHistogram;

GetDefaultBeetogram

virtual CPLErr GetDefaultBeetogram（double *pdfMin， double *pdfMax， int *pnBuckets， 吉恩大 **ppanHistogram， int bForce， GDALProgressFunc， void *pProgressData)

获取默认栅格直方图

参数:

• pdfMin -- 指向包含直方图下限的双精度值的指针。

• pdfMax -- 指向包含直方图上限的双精度值的指针。

• pnBuckets -- 指向 int 值的指针，该值将包含 *ppanHistogram 中的存储桶数。

• ppanHistogram -- 指向放置直方图总数的数组的指针。通过 VSIFree 释放

• bForce -- TRUE 表示强制计算。如果 FALSE 且没有可用的默认直方图，则该方法将返回CE_Warning

• pfnProgress -- 报告进度完成的函数。

• pProgressData -- 要传递给 pfnProgress 的应用程序数据。

返回:  CE_None成功时，CE_Failure是否出现问题，如果没有默认直方图可用，则CE_Warning

SetDefaultHistogram

virtual CPLErr SetDefaultHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram)

设置默认直方图

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

    // 设置直方图参数
    double dfMin = 0.0; // 设置最小像素值
    double dfMax = 255.0; // 设置最大像素值
    int nBuckets = 256; // 设置分桶数
    GUIntBig* panHistogram = new GUIntBig[nBuckets]; // 设置直方图数据
    for (int i = 0; i < nBuckets; ++i)
    {
        panHistogram[i] = i * 100; // 设置直方图数据，这里仅为示例数据
    }

    // 设置默认直方图
    CPLErr err = band->SetDefaultHistogram(dfMin, dfMax, nBuckets, panHistogram);

    if (err == CE_None)
    {
        std::cout << "Default histogram set successfully." << std::endl;
    }
    else
    {
        std::cout << "Failed to set default histogram." << std::endl;
    }

    // 释放内存
    delete[] panHistogram;

使用 GetDefaultHistogram 或 GetHistogram 获取直方图数据，再根据需要设置为波段的默认直方图，是一种常见的工作流程。但具体的使用方式还要根据实际需求和数据处理流程来决定

GetDefaultRAT

virtual GDALRasterAttributeTable *GetDefaultRAT()

获取默认栅格属性表

返回:  NULL，或指向乐队拥有的内部 RAT 的指针

栅格属性表是用于存储栅格数据的属性信息的表格结构，它包含了像素值与属性值之间的映射关系。每个像素值都可以对应一个或多个属性值，这些属性值可以是分类标签、类别名称、统计信息等。

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

    // 获取默认栅格属性表
    GDALRasterAttributeTable* rat = band->GetDefaultRAT();

    if (rat != nullptr)
    {
        // 输出栅格属性表信息
        std::cout << "Raster Attribute Table (RAT) Summary:" << std::endl;
        std::cout << "Row count: " << rat->GetRowCount() << std::endl;
        std::cout << "Column count: " << rat->GetColumnCount() << std::endl;

        // 输出每一行的属性信息
        for (int i = 0; i < rat->GetRowCount(); ++i)
        {
            GDALRasterAttributeTableRow* row = rat->GetRow(i);
            std::cout << "Row " << i << ": ";
            for (int j = 0; j < rat->GetColumnCount(); ++j)
            {
                std::cout << row->GetValueAsString(j) << " ";
            }
            std::cout << std::endl;
        }
    }
    else
    {
        std::cout << "No default Raster Attribute Table (RAT) found." << std::endl;
    }

SetDefaultRAT

virtual CPLErr SetDefaultRAT（const GDALRasterAttributeTable *poRAT)

设置默认栅格属性表

参数:

poRAT -- 要分配给频段的 RAT。

返回:  CE_None成功或CE_Failure（如果不受支持或失败）

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

    // 创建一个栅格属性表对象并设置属性
    GDALRasterAttributeTable* rat = new GDALRasterAttributeTable();
    rat->CreateColumn("Category", GFT_Integer, GFU_MinMax);
    rat->CreateColumn("Label", GFT_String, GFU_Name);

    GDALRasterAttributeRow row;
    row.SetField(0, 1);
    row.SetField(1, "Category 1");
    rat->AddRow(&row);

    row.SetField(0, 2);
    row.SetField(1, "Category 2");
    rat->AddRow(&row);

    // 将创建的栅格属性表设置为波段的默认栅格属性表
    CPLErr err = band->SetDefaultRAT(rat);

    if (err == CE_None)
    {
        std::cout << "Default Raster Attribute Table (RAT) set successfully." << std::endl;
    }
    else
    {
        std::cout << "Failed to set default Raster Attribute Table (RAT)." << std::endl;
    }

    // 释放内存
    delete rat;