The NetCDF file

It is useful to look at an example file while considering the NetCDF interface. Fortunately, the NetCDF package provides utilities (ncdump and ncgen) for converting the binary NetCDF files to an ascii format call CDL. A simple NetCDF file, converted to CDL notation by ncdump, is given below:

netcdf test {
dimensions:
	ycoord = 3 ;
	xcoord = 4 ;

variables:
	double image(ycoord, xcoord) ;
		image:long_name = "My favorite tiny image" ;
	double xcoord(xcoord) ;

data:

 image =
  1, 2, 3, 4,
  5, 6, 7, 8,
  9, 10, 11, 12 ;

 xcoord = 100, 200, 300, 400 ;
}

The sample file stores a 3 by 4 image of double precision values. The first thing defined are the dimensions : xcoord and ycoord. Dimensions can represent physical dimensions like x coordinate, y coordinate etc., or they can represent abstract things like lookup-table index. Each dimension has a name and a length and when joined with other dimensions defines the shape of a variable -- the variable image is subscripted by ycoord and xcoord. Dimensions can also be used across variables, relating them to each other. For example, if the file contained another image also subscripted by ycoord and xcoord, we would have the important information that the two variables were sampled on the same grid. Also, coordinate systems can be defined by creating variables by the same name as the dimension, like xcoord in the example above, giving the x coordinate of each point in the image.

Variables are the next thing defined in the cdl file. Each variable has a name, data type and a shape specified by a list of dimensions (up to a maximum of MAX_VAR_DIMS = 32 dimensions per variable). The data types are NC_CHAR, NC_BYTE, NC_SHORT, NC_INT, NC_FLOAT and NC_DOUBLE. Information about each variable is stored in attributes. The attribute ``long_name'' gives a character string describing the variable ``image''. Attributes are either scalars or vectors of one of the six types listed above (a character string is a vector of type NC_CHAR).