GDAL綜合整理–6：GDAL部分類說明

在網上看到這篇文章寫得非常全面，而且是中文的，就轉過來了，學習一下
其中有部分內容是重複的，不過不影響，非常好的資料

主要轉自http://blog.csdn.net/liminlu0314?viewmode=contents

GDALMajorObject

所有核心類的父類是GDALMajorObject，它定義了一些操作中繼資料的屬性和方法供子類繼承。

中繼資料：data about date 描述資料的資料，majorobject使用GDALMultiDomainMetadataObject Storage Service中繼資料。該對象存在一個網域名稱列表和一個中繼資料內容列表。使用者傳入網域名稱以及中繼資料內容已進行資料設定。可序列化為xml。

GDALDriverManager

管理GDALDriver的類，儲存了GDALDriver的數目以及列表。

可以通過序號以及名稱來擷取處理對象資料對應的driver。

使用一個全域變數static volatileGDALDrvierManager poDM管理，在register資料驅動時，通過GetGDALDriverManage這個全域函數，建立或擷取，然後通過RegisterDriver添加對應驅動。

GDALDriver

資料驅動類，只定義了成員方法，沒有成員變數，通過函數指標來實現對於不同的驅動類型採用不同的方式。

有Create方法建立資料集，Delete刪除資料集，Rename重新命名資料集，CopyFile，CreateCopy

另外定義了其他函數指標，算是介面了。

在註冊的時候，根據物件類型建立driver，並設定driver的描述，中繼資料等，並設定函數指標為對應資料集的靜態函數。如poDriver->pfnOpen = JDEMDataset::Open。其中Open方法為JDEMDataset中的靜態函數。

GDALDataSet

一套關聯柵格波段，通常來自一個檔案。

資料成員包括GDALDriver指標，波段的數目大小，波段列表，引用計數，是否被共用。等資訊。以及一個GDALDefaultOverViews對象。提供一個IRasterIO介面給衍生類別使用，作為讀取資料的介面。其他方法以及介面介紹如下：

 

 

#include <gdal_priv.h>

GDALDataset的繼承圖表：

GDALMajorObject 《 GDALDataset  《 GDALPamDataset

 

所有成員列表：

 

公有成員函數

Virtual ~GDALDataset（）

     銷毀一個開啟的GDALDataset

Int GetRasterXSize（void）

         取出柵格寬度，單位像素

Int GetRasterYSize()

         取得柵格高度，單位像素

Int GetRasterCount（）

         取得該dataset中柵格波段數目

GDAlRasterBand * GetRasterBand（int）

         為一個dataset取得波段對象

Virtual void FlushCache（void）

         重新整理所有寫入的快取資料到磁碟

Virtual const char * GetProjectionRef（void）

         取得該dataset的投影定義字元

Virtual CPLErr SetProjection (const char *)

         為該dataset 設定投影參考字元

Virtual CPLErr GetGeoTransform (double *)

         取得仿射投影變換係數

Virtual CPLErr SetGeoTransform（double *）

         設定仿射投影變換係數

Virtual CPLErr AddBand （GDALDataType eType， char **papszOptions=NULL）

         為dataset增加波段

Virtual void * GetInternalHandle（const char *）

         取得格式細節的內部有意義的控制代碼

Virtual GDALDriver * GetDriver（void）

         取得dataset有關係的驅動

Virtual char ** GetFileList（void）

         取得檔案構成資料集

Virtual int GetGCPCount（）

         取得GCPs的數目

Virtual const char * GetGCPProjection（）

         得到GCP的輸出投影

Virtual const GDAL_GCP * GetGCPs（）

         取得GCPs

Virtual CPLErr SetGCPs（int nGCPCount, const GDAL_GCP * pasGCPList,const char * pszGCPProjection）

         制定GCPs

Virtual CPLErr AdviseRead（int nXOff, int nYOff, int nXSize, int nYSize,int nBufXSize, int nBuffYSize, GDALDataTyoe eDT, int nBandCount, int *panBandList, char ** papszOptions）

         向驅動告知即將進行的讀請求

Virtual CPLErr CreateMaskBand (int nFlags)

         為dataset增加一個掩膜

Virtual GDALAsyncReader * BeginAsyncReader（int nXOff, int nYOff, int nXSize, int nYsize,void *pBuf, int nBufXSize, int nBufYSize, GDALDataType eBufType, intnBandCount, int *panBandMap, int PixelSpace, int nLineSpace, int nBandSpace,char **papszOptions）

         設定非同步資料請求

Virtual void EndAsyncReader(GDALAsyncReader *)

         結束一個非同步請求

CPLerr RasterIO（GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, int, int*,int,int,int）

         從多個波段中讀寫一定地區的映像

Int Reference()

          Dataset引用總數加一

Int Dereference ()

         Dataset引用總數減一

GDALAccess GetAcess()

 

Int GetShared()

         返回共用標誌

Void MarkAsShared（）

         把dataset標記為共用可用

CPLErr BuildOverviews (const char *, in,int*, int, int*,GDALProgressFunc, void *)

         構建柵格預覽視圖

 

靜態公有成員函數

 

Static GDALDataset** GetOpenDatasets（int * pnDatasetCount）

         取得所有開啟的GDAL dataset 的控制代碼

 

 

保護成員列表

void RasterInitialize (int, int)

void SetBand (int, GDALRasterBand *)virtualCPLErr IBuildOverviews (const char *, int, int *, int, int *, GDALProgressFunc,void *)virtual CPLErr IRasterIO (GDALRWFlag, int, int, int, int, void *, int,int, GDALDataType, int, int *, int, int, int)CPLErr         
BlockBasedRasterIO (GDALRWFlag, int, int, int, int, void *,int, int, GDALDataType, int, int *, int, int, int)void BlockBasedFlushCache ()

 

保護屬性

GDALDriver *  poDriver

GDALAccess eAccess

int nRasterXSize

int nRasterYSize

int nBands

GDALRasterBand **  papoBands

int bForceCachedIO

int nRefCount

int bShared

GDALDefaultOverviews  oOvManager

 

友元

class GDALDriver

class GDALDefaultOverviews

class GDALProxyDataset

class GDALRasterBand

GDALDatasetH GDALOpen（const char *, GDALAccess）

        以GDALDataset的格式開啟柵格檔案

GDALDatasetH GDALOpenShared（const char *, GDALAccess）

         以GDALDataset的格式開啟柵格檔案

 

 

詳細說明

一套關聯柵格波段，通常來自一個檔案。

一個dataset包封了一個或多個柵格波段

更多詳細討在GDAL Data Model

 

用GDALOpen（）或GDALOpenShared（）來建立GDALDataset 通過開啟一個有名字的的檔案

或者用GDALDriver::Create 或 GDALDriver::CreateCopy()來建立一個新的dataset

 

 

建構函式和解構函式文檔

GDALDataset::~GDALDataset  (  )  [virtual]

析構一個開啟的GDALDataset。

這是一個可接受的方法來關閉一個GDALDataset 並且重新分配所有關聯的資源。

 

錯誤的單詞？Equivelent（Equivalent）

與之等價的是c 中的GDALClose（）。除了GDALClose（）首先先減少Reference總數，然後當總數變為0時再關閉。

對於windows使用者，使用在Dataset對象上刪除操作是不可被使用的，因為分配和釋放空間跨越了模組的界限這個已知的issue. 調用 GDALClose（）是一個更好的選擇.

參考GDALMajorObject::GetDescription（）

 

成員函數文檔

 

CPLErr GDALDataset::AddBand  ( GDALDataType  eType, char **  papszOptions = NULL    )  [virtual]

增加一個波段到dataset中.

如果基本格式支援這種操作的話，這個方法將會在dataset中增加一個新的波段。大部分的格式不支援這種操作。

注意新的GDALRasterBand（）不會被返回。 但是在這個操作成功之後可以通過調用函數GDALDataset::GetRasterBand（GDALDataset::GetRasterCount（）-1）來取得，因為最新的波段總是在最後一個波段中。

參數：

         eType新波段中像素的資料類型

         papszOptionsName=value選項字串的列表。 被支援的選項是格式細節。NULL作為預設值也可通過。

傳回值：

         CE_None成功

         CE_Failure失敗

 

 

CPLErr GDALDataset::AdviseRead  ( int nXOff, 

 int  nYOff, 

 int  nXSize, 

 int  nYSize, 

 int  nBufXSize, 

 int  nBufYSize, 

 GDALDataType  eDT, 

 int  nBandCount, 

  int*  panBandMap, 

 char **  papszOptions  

)  [virtual]

告知磁碟機即將進行的讀請求。

一些GDAL 驅動會更有效率的工作，如果它們事Crowdsourced Security Testing道即將進行的讀請求的設定。AdviseRead（）方法允許程式通知驅動哪個範圍和波段會被讀取。

一些驅動會忽略調adviseRead（）的調用，但是它會明顯的增加讀取熟讀在另外一些驅動上。

 

參數：

nXOff 被讀取的波段地區距離左上方的偏離值（單位：像素）。從左邊以0開始

nYOff 被讀取的波段地區距離左上方的偏離值（單位：行）。從頂部以0開始。

nXSize 被讀取的波段地區寬度（單位：像素）

nYSize 被讀取的波段地區高度（單位：行）

nBufXSize 緩衝區映像的寬度

nBufYSize 緩衝區映像的高度

eBufType

nBandCount 將要被讀寫的波段數目

panBandMap nBandCount個將被讀寫的波段的列表。注意波段數目至少為1。將會是NULL來選擇第一個nBandCount波段

papszOptions 一個name=value的關於特殊控制選項的列表，正常來說為NULL

 

傳回值：

 CE_Failure 如果請求無效

 CE_None 如果見效了或被忽略了

參考GDALRasterBand::AdviseRead(),和GetRasterBand().

 

GDALAsyncReader *GDALDataset::BeginAsyncReader  ( int  nXOff, 

 int  nYOff, 

 int  nXSize, 

 int  nYSize, 

 void *  pBuf, 

 int  nBufXSize, 

 int  nBufYSize, 

  GDALDataType  eBufType, 

 int  nBandCount, 

  int*  panBandMap, 

 int  nPixelSpace, 

  int nLineSpace, 

  int nBandSpace, 

  char ** papszOptions  

 )   [virtual]

 

建立非同步資料請求。

這個方法在dataset中指定的視窗建立了一個非同步柵格讀取請求到指定的緩衝區。參數為了windowing，緩衝區大小，緩衝類型和緩衝組織和GDALDataset::RasterIO（）的這些類似；

這個調用只會開啟請求，填入緩衝區被完成通過調用GetNextUpdateRegion（）在返回GDALAsyncReader會話對象

一旦建立對話的所有進程完成時，或者沒有進一步動作的需求時，GDALAsyncReader 對象將會通過GDALDataset::EndAsyncReader（）方法自動被銷毀

注意資料緩衝區（pData）在會話的生命週期中可能會潛在的持續更新，但是當對話（GDALAsyncReader）被EndAsyncReader結束時，它不會被重新分配。它會被那個點的程式重新分配。

有關GDAL中非同步IO的補充資訊可在http://trac.osgeo.org/gdal/wiki/rfc24_progressive_data_support上找到。

這個方法和C的GDALBeginAsyncReader（）一樣。

 

CPLErr GDALDataset::BuildOverviews  ( const char *  pszResampling, 

 int  nOverviews, 

  int*  panOverviewList, 

 int  nListBands, 

  int*  panBandList, 

 GDALProgressFunc pfnProgress, 

 void *  pProgressData  

 )

 

建立柵格預覽圖。

如果指定的dataset不支援這個操作，傳回值將是CE_Failure, CPLGtLastErrorNo() 將會返回CPLE_NotSupported.

這個方法和C的函數GDALBuildOverviews（）相同

 

 

CPLErr GDALDataset::CreateMaskBand  ( int nFlags   )  [virtual]

對dataset增加一個掩膜。

CreateMaskBand（）方法的預設執行是在與.ovr操作工具類似的規則的基礎上使用GDALDefualtOverviews對象執行。 一個帶有.msk擴充的TIFF檔案會被建立成與原始檔案相同的基本名稱，並且會有一個波段。如果可能的話掩膜映像會是與原始映像有著相同的block size的壓縮映像

 

int GDALDataset::Dereference  (  ) 

從dataset引用計數中減一

執行個體化之後引用計數為一。一般來說引用計數減到零時這個dataset已經被安全的刪除（關閉）了。

這個方法和C的GDALDereferenceDataset（）函數相同。

 

 

void GDALDataset::EndAsyncReader  ( GDALAsyncReader *  poARIO  )  [virtual]

結束非同步請求。

這個方法將銷毀一個非同步IO請求，並恢複與之相關聯的資源。

這個方法和C的GDALEndAsyncReader（）相同。

 

 

void GDALDataset::FlushCache  ( void   )  [virtual]

重新整理所有寫入的緩衝到磁碟。

任何柵格（或其他GDAL）資料通過GDAL的調用被寫入，但是緩衝區會被內部機制寫入到磁碟。

使用這個方法不會阻止調用GDALClose（）來正常關閉一個dataset，並且確保重要的資料不會被FlushCache分配地址寫入發哦檔案中。

這個方法和C下面的函數GDALFlushCache（）相同。

在GDALPamDataset中執行。

GDALDriver * GDALDataset::GetDriver  ( void   )  [virtual]

取得dataset相關聯的驅動。

這個方法和C的GDALGetDatasetDriver（）函數相同。

 

char ** GDALDataset::GetFileList  ( void   )  [virtual]

取得構成dataset的檔案。

返回被認為是構成dataset的檔案清單。如果返回一個空的檔案清單，意味著認為沒有本地檔案系統的檔案和該dataset相關聯（例如一個虛擬dataset）。這個返回的檔案清單是歸調用者擁有的，並可以被CSLDestory（）所銷毀。

返回的檔案名稱通常是相對路徑或絕對路徑，這取決於開啟dataset時使用的路徑。

這個方法和C的GDALGetFileList（）函數相同。

 

int GDALDataset::GetGCPCount  (  )  [virtual]

取得GCP的數目。

這個方法和C的GDALGetGCPCount（）相同。

 

 

const char *GDALDataset::GetGCPProjection  (   ) [virtual]

取得GCP輸出投影。

這個方法和C的 GDALGetGCPProjection（）相同。

投影字串遵循GetProjectionRef（）的標準規則。

 

 

const GDAL_GCP * GDALDataset::GetGCPs  (  )  [virtual]

取得GCPs。

這個方法和C的GDALDataset::GetGCPs（）相同。

 

 

CPLErr GDALDataset::GetGeoTransform  ( double * padfTransform   )  [virtual]

取得仿射變換係數。

取得在pixel/line(P, L)柵格空間和投影座標空間之間變換的係數。

Xp = padfTransform[0] + P*padfTransform[1]+ L*padfTransform[2];

   Yp= padfTransform[3] + P*padfTransform[4] + L*padfTransform[5];

在北朝上的映像裡，padfTransform[1]是像素寬，padfTransform[5]是像素高。左上像素的左上方就是這個座標（padfTransform[0]，padfTransform[3]）。

預設的轉換是（0,1,0,0,0,1）即使當返回CE_Failure 錯誤也會被返回，，例如格式上不支援轉換到投影座標系。

注意：GetGeoTransfrom （）不能夠表達處理多種從OGC Grid Coverage pixel/line 到投影變換的方案。最後這個方法將會被讓位於更普遍的scheme。

這個方法和C的GDALGetGeoTransfrom（）相同。

 

 

 

 

void * GDALDataset::GetInternalHandle  ( const char *    ) [virtual]

取得一個格式詳盡的內部有意義的控制代碼。

這個方法和C的GDALGetGeoInternalHandle（）相同。

 

 

GDALDataset **GDALDataset::GetOpenDatasets  ( int*  pnCount   ) [static]

取得所有開啟的GDAL dataset 的控制代碼。

這個方法和C的GDAL GetOpenDatasets（）相同。

 

 

const char *GDALDataset::GetProjectionRef  (void    ) [virtual]

取得這個dataset的投影定義字串。

這個方法和C的GDAL GetProjectionRef（）相同。

這個返回的字串使用Open GIS WKTformat定義了該映像的投影座標系。它也適合於和OGRSpatialReference類使用。

當投影定義不可用時，將返回一個空的字串（但不是NULL）。

 

 

GDALRasterBand *GDALDataset::GetRasterBand  ( int  nBandId  )  

取得dataset的一個波段對象。

相當於C的GDALGetRasterBand()

 

 

int GDALDataset::GetRasterCount  ( void   ) 

取得dataset的柵格波段數量。

和C的函數GDALGetRasterCount()相同

 

 

int GDALDataset::GetRasterXSize  ( void   )  

取得柵格寬度（單位像素）

等同於C的GDAL GetRasterXSize（）

 

 

int GDALDataset::GetRasterYSize  ( void   )  

取得柵格高度（單位像素）

等同於C的GDAL GetRasterYSize（）

 

 

int GDALDataset::GetShared  (  )  

返回共用標誌

 

CPLErr GDALDataset::RasterIO  ( GDALRWFlag eRWFlag, 

 int  nXOff, 

 int  nYOff, 

 int  nXSize, 

 int  nYSize, 

 void *  pData, 

 int  nBufXSize, 

 int  nBufYSize, 

 GDALDataType  eBufType, 

 int  nBandCount, 

  int*  panBandMap, 

 int  nPixelSpace, 

 int  nLineSpace, 

 int  nBandSpace  

 )

從多個波段中讀寫一個地區的映像資料。

這個方法允許從dataset中把一個或多個GDAL柵格波段的地區資料讀取到緩衝區，或者把緩衝區資料寫入到GDAL柵格波段的一個地區中。如果緩衝區的資料類型（eBufType）和GDAL柵格波段的資料類型不同的話，它會自動處理資料類型轉換。如果緩衝區大小（nBufXSize x nBufYSize）和被存取的地區大小（nXSize x nYSize）不同的話，這個方法同樣也會處理映像的抽取和複製。

nPixelSpace, nLineSpace 和 nBandSpace 參數允許從多種緩衝區組織圖中讀和寫。

為了最高精確性的全解析度資料存取，在“區塊分界線”（block boundaries）的讀寫被GetBlockSize（）的傳回值，也可以使用ReadBlock（）和WriteBlock（）方法。

這個方法和CGDALDatasetRasterIO（）相同

 

 

int GDALDataset::Reference  (  )  

dataset資源計數加一。

執行個體化之後資源數量為一。

這個方法和CGDALReferenceDataset（）相同。

 

 

CPLErr GDALDataset::SetGCPs  ( int nGCPCount, 

 const GDAL_GCP *  pasGCPList, 

 const char * pszGCPProjection  

 )  [virtual]

分配GCPs。

這個方法和C的GDALSetGCPs（）相同。

這個方法給該Dataset和它們的座標系統分配已經通過的設定。內部拷貝是有座標系統和一個點的列表構成，如果適當調用者將會遺留下重新分配這些參數的責任。

大部分的格式不支援GCPs的設定，即使格式能處理GCPs。這些格式將會返回CE_Failure。

 

 

LErr GDALDataset::SetGeoTransform  ( double *   )  [virtual]

設定仿射變換參數。

參考GetGeoTransform()獲得更多細節有關padfTransform係數。

這個方法和CGDALSetGeoTransform（）一樣。

 

 

CPLErr GDALDataset::SetProjection  ( const char *    ) [virtual]

為dataset設定投影參考字串

這個在OGC WKT或PROJ.4 格式。因為錯誤的投影字串，dataset不可寫或者dataset不支援標出投影，會導致一個錯誤出現。許多格式不支援寫入投影。

這個方法和C的GDALSetProjection（）相同。

 

 

 

友類和相關函數文檔

 

GDALDatasetH GDALOpen  ( const char *  pszFilename, 

 GDALAccess  eAccess  

 )  [friend]

用GDALDataset方式開啟柵格檔案。

這個函數將嘗試著開啟通過的檔案或者輪流通過援引每個登入的GDALDriver的開啟方法來開啟虛擬dataset名字。第一次成功的開啟將會返回一個dataset。如果所有的驅動都失敗了，將會返回一個NULL。

一些建議：

如果你用GA_Update 存取方式開啟一個dataset對象，不建議在同一個基礎的檔案上開啟一個新的dataset。

返回的dataset每次僅僅被單線程存取。如果你想通過不同線程開啟dataset，你必須增加必要的代碼（mutexes等等）來避免同時使用這個對象。（一些驅動像GeoTIFF支援內態變數，每次更新時一個新的地區被讀取，這樣防止同時使用。）

 

 

GDALDatasetH GDALOpenShared  ( const char *  pszFilename, 

 GDALAccess  eAccess  

 )  [friend]

用GDALDataset方式開啟柵格檔案。

這個函數工作時和GDALOpen（）一樣，但是允許為其他的調用者dataset分享GDALDataset控制代碼。

尤其，GDALOpenShared（）將首先考慮當前開啟和共用的GDALDataset的列表，並且如果GetDescription（）名稱和pszFilename精確的匹配的話，將會被引用和返回。

開始於GDAL1.6.0, 如果GDALOpenShared（）被兩個不同的線程在一樣的pszFilename上調用，一個不同的differentGDALDataset對象將被返回，通過不同的線程使用同一個dataset是不安全的，除非使用者在代碼中明確使用了互斥。

 

GDALRasterBand

一個單一的柵格資料波段

存在一個GDALRasterBlock友元

存在一個GDALDataset對象（GDAL貌似很喜歡把外層對象的指標存在分類的對象裡面。如在學生的資訊裡面儲存班級的資訊，班級的資訊裡面要有一個年級的指標，當然，班級類是學生類的友元，年級類是班級類的友元。難道是學生犯錯了，然後由班級處置的意思？）

Rasterband中定義了比rasterdataset更細緻的資料類型