【224】◀▶ IDL NetCDF 文件操作說明

參考：I/O - NetCDF Routines —— NetCDF 操作函數

---

01		NCDF_OPEN	打開一個 NetCDF 文件。
02		NCDF_CLOSE	關閉一個 NetCDF 文件。
03		NCDF_VARID	返回一個變量 ID，varid。
04		NCDF_VARGET	讀取一個變量。
05		NCDF_ATTGET	讀取一個屬性。
06		NCDF_ATTINQ	返回一個關於 NetCDF 屬性信息的結構體。
07		NCDF_ATTRENAME	屬性重命名。
08		NCDF_VARINQ	返回變量信息。
09		NCDF_INQUIRE	返回文件信息。
10		NCDF_ATTNAME	返回一個屬性名稱。
11		NCDF_CREATE	創建一個 NetCDF 文件。
12		NCDF_DIMDEF	創建一個維度。
13		NCDF_VARDEF	創建一個變量。
14		NCDF_ATTPUT	寫入屬性數據。
15		NCDF_CONTROL	開始或結束定義模式。
16		NCDF_VARPUT	寫入變量數據。

---

　　NetCDF（network Common Data Form）由位於科羅拉多州波爾市的 Unidata 程序中心開發，主要應用於大氣科學的研究。NetCDF 的數據模式具有簡單性和靈活性的特點。NetCDF 文件的基本組成為變量、屬性和維數：

• 變量為標量或多維數組。NetCDF 所支持的 IDL 數據類型有 string、byte、int、long、float 和 double
• 屬性包含一個變量或這個文件的附加性質。包含變量信息（如單位、有效范圍、尺度因子等）的屬性稱作變量屬性；包含文件信息的屬性稱作全局屬性。屬性可以是標量或一維數組，支持的數據類型為 string、byte、int、long、float 和 double
• 維數為長整形標量，記錄了一個或多個變量的大小

參考：NetCDF 格式文件入門
參考：NetCDF 入門

       從數學上來說，NetCDF 存儲的數據就是一個多自變量的單值函數。 用公式來說就是 f(x,y,z,...) = value，函數的自變量 x,y,z 等在 NetCDF 中叫做維 (dimension) 或坐標軸 (axis)，函數值 value 在 NetCDF 中叫做變量 (Variables)。而自變量和函數值在物理學上的一些性質，比如計量單位 (量綱)、物理學名稱等等在 NetCDF 中就叫屬性 (Attributes)。

       注意：IDL讀取數據與在其他軟件上顯示的數據位置相反，左上對右下！

       注意：NetCDF記錄數據與實際數據是通過一個數量關系獲取的，如下圖所示：

實際結果 = 顯示結果 × scale_factor + add_offset

        

---

數據：可以從 http://www.gumley.com 中下載這些例子的數據文件：

• image.nc
• sao.nc

常用的 NetCDF 程序

名     稱	功     能	名     稱	功     能
NCDF_OPEN()	打開一個 NetCDF 文件	NCDF_ATTNAME()	返回一個屬性名稱
NCDF_CLOSE	關閉一個 NetCDF 文件	NCDF_CREATE()	創建一個 NetCDF 文件
NCDF_VARID()	返回一個變量標識符	NCDF_DIMDEF()	創建一個維度
NCDF_VARGET	讀取一個變量	NCDF_VARDEF()	創建一個變量
NCDF_ATTGET	讀取一個屬性	NCDF_ATTPUT	寫入屬性數據
NCDF_INQUIRE()	返回文件信息	NCDF_CONTROL	開始或結束定義模式
NCDF_VARINQ()	返回變量信息	NCDF_VARPUT	寫入變量數據

常用的標准 NetCDF 文件屬性

屬性名稱	定      義
long_name	詳細描述變量的字符串（如“Northwards velocity component”）
units	描述變量單位的字符串（如“meters/second”）
valid_range	一個兩元素的數組，包含變量有效的最小和最大值（如 [0.0, 5.0]）， 該屬性的類型必須和變量類型一致
scale_factor	變量讀取以后作用於變量的一個乘數（允許 float 值存在 short 或 byte 類型）， 該屬性的類型必須和需要的變量類型一致（如浮點型）
add_offset	變量讀取完畢，並且 scale_factor 使用后，加入到變量的一個偏值， 該屬性的類型必須和需要的變量類型一致（如浮點型）
FillValue	表示沒有數據寫入的一個值，該屬性的類型必須和變量的類型一致

---

序號	名稱		功能說明		語法 & 舉例
01	NCDF_OPEN		打開一個 NetCDF 文件，返回值是這個文件的 NetCDF ID 值。 ---------------------------------------------------------------------------------- Result = NCDF_OPEN( Filename [, /NOWRITE | , /WRITE] ) ---------------------------------------------------------------------------------- ◈ Filename：欲打開或創建的文件路徑 ◈ NOWRITE：只讀模式，默認模式 ◈ WRITE：讀寫模式		offset = [80, 20] count = [70, 70] stride = [2, 3] ;打開 NetCDF 文件 id = NCDF_OPEN('dave.nc') ;獲取 image 的變量 ID image = NCDF_VARID(id, 'image') ;獲取 image 數據內容 NCDF_VARGET, id, image, fullimage ;獲取 image 部分數據內容 NCDF_VARGET, id, image, subimage, COUNT=count, STRIDE=stride, OFFSET=offset ;關閉 NetCDF 文件 NCDF_CLOSE, id
02	NCDF_CLOSE		關閉一個 NetCDF 文件。 ---------------------------------------------------------------------------------- NCDF_CLOSE, Cdfid ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值
03	NCDF_VARID		返回一個變量 ID，varid。 如果返回值為 -1 說明變量不存在。 ---------------------------------------------------------------------------------- Result = NCDF_VARID(Cdfid, Name) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Name：變量名稱
04	NCDF_VARGET		讀取一個變量。 ---------------------------------------------------------------------------------- NCDF_VARGET, Cdfid, Varid, Value [, COUNT=vector] [, OFFSET=vector] [, STRIDE=vector] ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid ◈ Value：是讀取變量的結果 ◈ COUNT=vector：是每維中讀取元素的數目，默認情況是從當前 offset 的位置到每維的最后一個元素 ◈ OFFSET=vector：是每維中讀取的第一個元素，從零開始，默認為 [0, 0, ... ,0] ◈ STRIDE=vector：是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中 ---------------------------------------------------------------------------------- 注意：如果 offset、count 或 stride 導致變量超出了范圍，則 IDL 在讀取時將舍去超出的部分，並給出錯誤信息。
05	NCDF_ATTGET		讀取一個屬性。 ---------------------------------------------------------------------------------- NCDF_ATTGET, Cdfid [, Varid] , Name, Value [, /GLOBAL] ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid ◈ Name：是包含屬性名稱的字符串 ◈ Value：獲取變量結果 ◈ GLOBAL：返回全局變量結果		;打開一個新的 NetCDF 文件 id = NCDF_CREATE('test.nc', /CLOBBER) ;創建兩個全局屬性 TITLE 和 DATE NCDF_ATTPUT, id, /GLOBAL, 'TITLE', 'MY TITLE' NCDF_ATTPUT, id, /GLOBAL, 'DAY', 'July 1,1996' ; ATTRENAME 可以用來給屬性重命名 NCDF_ATTRENAME, id, 'DAY', 'DATE', /GLOBAL ;獲取第二個屬性的名稱 name = NCDF_ATTNAME(id, /GLOBAL, 1) ;獲取屬性值 NCDF_ATTGET, id, /GLOBAL, name, date ;獲取這個屬性的信息 result = NCDF_ATTINQ(id, /GLOBAL, name) HELP, name, date, result, /STRUCTURE PRINT, date PRINT, STRING(date) NCDF_CLOSE, id
06	NCDF_ATTINQ		返回一個關於 NetCDF 屬性信息的結構體。 ---------------------------------------------------------------------------------- Result = NCDF_ATTINQ( Cdfid [, Varid] , Name [, /GLOBAL]) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid ◈ Name：是包含屬性名稱的字符串 ◈ GLOBAL：返回全局變量結果
07	NCDF_ATTRENAME		屬性重命名。 ---------------------------------------------------------------------------------- NCDF_ATTRENAME, Cdfid [, Varid] Oldname, Newname [, /GLOBAL] ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid ◈ Oldname：屬性的當前名稱 ◈ Newname：屬性的新名稱 ◈ GLOBAL：返回全局變量結果
08	NCDF_VARINQ		返回變量信息。 返回值是一個結構體，{ NAME:"", DATATYPE:"", NDIMS:0L, NATTS:0L, DIM:LONARR(NDIMS) } ◈ Name：變量的名稱 ◈ DataType：變量數據類型，'BYTE', 'CHAR', 'INT', 'LONG', 'FLOAT', or 'DOUBLE' ◈ Ndims：維度的數目 ◈ Natts：給這個變量分配屬性的數目 ◈ Dim：變量維度 ID 的數組 ---------------------------------------------------------------------------------- Result = NCDF_VARINQ(Cdfid, Varid) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid		id = NCDF_OPEN('test.nc') INQ_VID = NCDF_VARINQ(id, 'dist_image') HELP, INQ_VID, /STRUCTURE file_inq = NCDF_INQUIRE(id) HELP, file_inq, /STRUCTURE NCDF_CLOSE, id
09	NCDF_INQUIRE		返回文件信息。 返回值是一個結構體，{ NDIMS:0L, NVARS:0L, NGATTS:0L, RECDIM:0L } ◈ Ndims：這個 NetCDF 文件定義維度的數目 ◈ Nvars：這個 NetCDF 文件定義變量的數目 ◈ Ngatts：這個 NetCDF 文件定義全局屬性的數目 ---------------------------------------------------------------------------------- Result = NCDF_INQUIRE(Cdfid) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值
10	NCDF_ATTNAME		返回一個屬性名稱。 返回屬性名稱，如果沒有，就返回空。 ---------------------------------------------------------------------------------- Result = NCDF_ATTNAME( Cdfid [, Varid] , Attnum [, /GLOBAL]) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid ◈ Attnum：屬性的索引值，通過 NCDF_VARINQ（從0~屬性總數-1） 或 NCDF_INQUIRE （全局屬性，從0~屬性總數-1）獲取 ◈ GLOBAL：返回全局變量結果
11	NCDF_CREATE		創建一個 NetCDF 文件。 創建成功的話就會返回 NetCDF ID 值。文件自動轉入定義模式（define mode），意味着新的變量、屬性和維度可以加入文件中。 ---------------------------------------------------------------------------------- Result = NCDF_CREATE( Filename [, /CLOBBER | /NOCLOBBER] [, /NETCDF3_64BIT] [, /NETCDF4_FORMAT] ) ---------------------------------------------------------------------------------- ◈ Filename：欲創建的文件名稱 ◈ CLOBBER：設置此關鍵字，並且文件存在，那么在創建新的版本之前直接擦除文件內容 ◈ NOCLOBBER：設置此關鍵字，只有不存在此文件的情況下才能創建成功，否則報錯		;打開一個新的 NetCDF 文件，如果文件存在，直接將其毀掉 id = NCDF_CREATE('test.nc', /CLOBBER) ;寫入屬性數據 NCDF_ATTPUT, id, 'TITLE', 'Incredibly Important Data', /GLOBAL NCDF_ATTPUT, id, 'GALAXY', 'Milky Way', /GLOBAL NCDF_ATTPUT, id, 'PLANET', 'Earth', /GLOBAL ; Define the X dimension. xid = NCDF_DIMDEF(id, 'x', 100) ; Define the Y dimension. yid = NCDF_DIMDEF(id, 'y', 200) ; Define the Z dimension. zid = NCDF_DIMDEF(id, 'z', /UNLIMITED) ;創建變量 vid0 = NCDF_VARDEF(id, 'image0', [yid, xid], /FLOAT) vid1 = NCDF_VARDEF(id, 'image1', [yid, xid], /FLOAT) NCDF_CLOSE, id
12	NCDF_DIMDEF		創建一個維度。 如果成功，返回維度的 ID 值。 ---------------------------------------------------------------------------------- Result = NCDF_DIMDEF( Cdfid, DimName, Size [, /UNLIMITED] ) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ DimName：被定義維度的字符串名稱 ◈ Size：維度的大小。可以用任何數量的表達式來表達。如果使用了關鍵字 UNLIMITED，Size 相當於無效 ◈ UNLIMITED：設置此關鍵字可以創建一個無限大小的維度
13	NCDF_VARDEF		創建一個變量。 如果成功，返回變量的 ID 值，如果不能創建這個新的變量，就會返回-1。 ---------------------------------------------------------------------------------- Result = NCDF_VARDEF( Cdfid, Name [, Dim] [, /BYTE | , /CHAR | , /DOUBLE | , /FLOAT | , /LONG | , /SHORT] [, CHUNK_DIMENSIONS] [, /CONTIGUOUS] [, GZIP=value] [, /SHUFFLE] [, /STRING] [, /UBYTE] [, /UINT64] [, /ULONG] [, /USHORT]) ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Name：變量名稱 ◈ Dim：包括變量維度的 dimension IDs。如果 ID 是無限大小的，那必須放在數組的最右面。如果沒有設置 Dim，變量默認為一個標量。 ◈ INT：數據為整型 ◈ FLOAT：數據為浮點型 ---------------------------------------------------------------------------------- 注意：如果類型關鍵字沒有數據，默認使用 FLOAT
14	NCDF_ATTPUT		寫入屬性數據。 ---------------------------------------------------------------------------------- NCDF_ATTPUT, Cdfid [, Varid] , Name , Value [, /GLOBAL] [, LENGTH=value] [, /BYTE | , /CHAR | , /DOUBLE | , /FLOAT | , /LONG | , /SHORT] [, /STRING] [, /UBYTE] [, /UINT64] [, /ULONG] [, / USHORT] ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARID 函數獲取的返回值 varid ◈ Name：屬性的名稱 ◈ Value：屬性的值 ◈ GLOBAL：設置此關鍵字去創建全局屬性 ◈ LENGTH=value：值的長度 ◈ FLOAT：數據為浮點型
15	NCDF_CONTROL		開始或結束定義模式。 ---------------------------------------------------------------------------------- NCDF_CONTROL, Cdfid [, /ABORT] [, /ENDEF] [, /FILL | , /NOFILL] [, /NOVERBOSE | , /VERBOSE] [, OLDFILL=variable] [, /REDEF] [, /SYNC] ---------------------------------------------------------------------------------- ◈ 設置此關鍵字可以將一個打開的 NetCDF 文件結束定義模式（define mode），進入數據模式（data mode）文件只有在數據模式下才能寫入變量 ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ ENDEF：將一個打開的文件結束 define mode，進入 data mode ◈ REDEF：將一個打開的文件進入 define mode
16	NCDF_VARPUT		寫入變量數據。 ---------------------------------------------------------------------------------- NCDF_VARPUT, Cdfid, Varid, Value [, COUNT=vector] [, OFFSET=vector] [, STRIDE=vector] ---------------------------------------------------------------------------------- ◈ Cdfid：由 NCDF_OPEN 或 NCDF_CREATE 返回的 NCDF ID 值 ◈ Varid：是 NCDF_VARDEF 或 NCDF_VARID 函數獲取的返回值 varid ◈ Value：是寫入變量的值 ◈ COUNT=vector：是每維中寫入元素的數目，默認情況是從當前 offset 的位置到每維的最后一個元素 ◈ OFFSET=vector：是每維中寫入的第一個元素，從零開始，默認為 [0, 0, ... ,0] ◈ STRIDE=vector：是在每維中寫入的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中 ：是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中 ：是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中：是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中：是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中：是在每維中提取的間隔，默認為 [0, 0, ... , 0]，意味着每個元素均被選中