【179】IDL 读写 NetCDF 文件

　　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	表示没有数据写入的一个值，该属性的类型必须和变量的类型一致

• NCDF_OPEN：【函数】打开一个 NetCDF 文件，返回值是这个文件的 NetCDF ID 值。
         语法：Result = NCDF_OPEN( Filename [, /NOWRITE | , /WRITE] )
• NCDF_CLOSE：关闭一个 NetCDF 文件。
         语法：NCDF_CLOSE, Cdfid
• NCDF_VARID：【函数】返回一个变量标识符，变量 ID，如果返回值为 -1 说明变量不存在。
         语法：Result = NCDF_VARID(Cdfid, Name)
• NCDF_VARGET：读取一个变量。
         语法：NCDF_VARGET, Cdfid, Varid, Value [, COUNT=vector] [, OFFSET=vector] [, STRIDE=vector]
         说明：Cdfid 是 NCDF_OPEN 函数获取的返回值；
                     Varid 是 NCDF_VARID 函数获取的返回值；
                     Value 是读取变量的结果；
                     COUNT 是每维中读取元素的数目（默认情况是从当前 offset 的位置到每维的最后一个元素）；
                     OFFSET 是每维中读取的第一个元素（从零开始，默认为 [0, 0, ... ,0]；
                     STRIDE 是在每维中提取的间隔（默认为 [1, 1, ... , 1]，意味着每个元素均被选中）。
         注意：如果 offset、count 或 stride 导致变量超出了范围，则 IDL 在读取时将舍去超出的部分，并给出错误信息。
  image.nc 在 HDFView 中显示如下：
  

  IDL> cd, 'F:\IDL\netCDF'
  IDL> cdfid = ncdf_open('image.nc')
  IDL> varid = ncdf_varid(cdfid, 'image')
  IDL> ncdf_varget, cdfid, varid, data
  IDL> help,data
  DATA            BYTE      = Array[, ]
  IDL> tvscl, data

  IDL> cdfid = ncdf_open('image.nc')
  IDL> varid = ncdf_varid(cdfid, 'image')
  IDL> ncdf_varget, cdfid, varid, data, offset=[,], count=[,], stride=[,]
  IDL> help, data
  DATA            BYTE      = Array[, ]
  IDL> tvscl, data

  IDL> ncdf_varget, cdfid, varid, data, offset=[,], count=[,], stride=[,]
  % NCDF_VARGET: Requested read is larger than data in dimension . Reducing COUNT
                  to .

• NCDF_ATTGET：读取一个属性。
         语法：NCDF_ATTGET, Cdfid [, Varid] , Name, Value [, /GLOBAL]
         说明：Name 是包含属性名称的字符串；
                     Value 获取变量结果。

  IDL> cdfid = ncdf_open('sao.nc')
  IDL> varid = ncdf_varid(cdfid, 'PRECIP')
  IDL> ncdf_attget, cdfid, varid, 'long_name', attvalue
  IDL> print, attvalue
  
  IDL> string(attvalue)
  precipitation amount

• NCDF_INQUIRE：返回文件信息
       【函数】返回值是一个结构体，{ NDIMS:0L, NVARS:0L, NGATTS:0L, RECDIM:0L }
         说明：Ndims 这个 NetCDF 文件定义维度的数目；
                     Nvars 这个 NetCDF 文件定义变量的数目；
                     Ngatts 这个 NetCDF 文件定义全局属性的数目；
                     RecDim The ID of the unlimited dimension, if there is one, for this NetCDF file. If there is no unlimited dimension, RecDim is set to -1.
         语法：Result = NCDF_INQUIRE(Cdfid)
• NCDF_VARINQ：返回变量信息
       【函数】返回值是一个结构体，{ NAME:"", DATATYPE:"", NDIMS:0L, NATTS:0L, DIM:LONARR(NDIMS) }
         说明：Name 变量的名称；
                     DataType 变量数据类型，'BYTE', 'CHAR', 'INT', 'LONG', 'FLOAT', or 'DOUBLE'；
                     Ndims 维度的数目；
                     Natts 给这个变量分配属性的数目；
                     Dim A vector of the dimension IDs for the variable dimensions.
         语法：Result = NCDF_VARINQ(Cdfid, Varid)

  Function ncdf_vardir, cdfid
    ;- Check arguments
    if(n_params() ne ) then $
      message, 'Usage: result=ncdf_vardir(cdfid)'
    if(n_elements(cdfid) eq ) then $
      message, 'Argument cdfid is undefined'
  
    ;- Set default return value
    varnames=''
  
    ;- Get file information
    fileinfo = ncdf_inquire(cdfid)
    nvars=fileinfo.nvars
  
    ;- If variables were found, get variable names
    if(nvars gt ) then begin
      varnames = strarr(nvars)
      for index = 0L, nvars - 1L do begin
        varinfo = ncdf_varinq(cdfid, index)
        varnames[index] = varinfo.name
      endfor
    endif
  
    ; -return the result
    return, varnames
  end

  IDL> cdfid = ncdf_open('sao.nc')
  IDL> varnames = ncdf_vardir(cdfid)
  IDL> help, varnames
  VARNAMES        STRING    = Array[]
  IDL> print, varnames
  id region time lat lon elev T TD PSL ALTIM SPD
  DIR GUST WX ZCL CC cloudtype VIS Ptend delP
  PRECIP reftime_PRECIP Tmax Tmin remarks

• NCDF_ATTNAME：返回一个属性名称。
       【函数】返回属性名称，如果没有，就返回空。
         语法：Result = NCDF_ATTNAME( Cdfid [, Varid] , Attnum [, /GLOBAL])
• NCDF_CREATE：创建一个 NetCDF 文件。
       【函数】创建成功的话就会返回 NetCDF ID 值。文件自动转入定义模式（define mode），意味着新的变量、属性和维度可以加入文件中。
         语法：Result = NCDF_CREATE( Filename [, /CLOBBER | /NOCLOBBER] [, /NETCDF3_64BIT] [, /NETCDF4_FORMAT] )
         说明：CLOBBER 设置此关键字，并且文件存在，那么在创建新的版本之前直接擦除文件内容；
                     NOCLOBBER 设置此关键字，只有不存在此文件的情况下才能创建成功，否则报错。
• NCDF_DIMDEF：创建一个维度。
       【函数】如果成功，返回维度的 ID 值。      
         语法：Result = NCDF_DIMDEF( Cdfid, DimName, Size [, /UNLIMITED] )
         说明：DimName 被定义纬度的字符串名称；
                     Size 维度的大小。可以用任何数量的表达式来表达。如果使用了关键字 UNLIMITED，Size 相当于无效；
                     UNLIMITED 设置此关键字可以创建一个无限大小的维度。
• 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])
         说明：如果类型关键字没有数据，默认使用 FLOAT；
                     Dim 包括变量维度的 dimension IDs。如果 ID 是无限大小的，那必须放在数组的最右面。如果没有设置 Dim，变量默认为一个标量。
• NCDF_ATTPUT：写入属性数据。
         语法：NCDF_ATTPUT, Cdfid [, Varid] , Name , Value [, /GLOBAL] [, LENGTH=value] [, /BYTE | , /CHAR | , /DOUBLE | , /FLOAT | , /LONG | , /SHORT] [, /STRING] [, /UBYTE] [, /UINT64] [, /ULONG] [, / USHORT]
         说明：GLOBAL 设置此关键字去创建全局属性。
• NCDF_CONTROL：开始或结束定义模式。
         语法：NCDF_CONTROL, Cdfid [, /ABORT] [, /ENDEF] [, /FILL | , /NOFILL] [, /NOVERBOSE | , /VERBOSE] [, OLDFILL=variable] [, /REDEF] [, /SYNC]
         说明： 设置此关键字可以将一个打开的 NetCDF 文件结束定义模式（define mode），进入数据模式（data mode）文件只有在数据模式下才能写入变量。
• NCDF_VARPUT：写入变量数据。
         语法：NCDF_VARPUT, Cdfid, Varid, Value [, COUNT=vector] [, OFFSET=vector] [, STRIDE=vector]
• ：
• ：
• ：
• ：
• ：
• ：
• ：