【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]，意味着每个元素均被选中