The CAPS User Interface

HDF I/O

HDF is the primary file output format for CAPS. An HDF file can be created using a caps command or a NAP command. The form of the caps command is:

set HDF_fileName hdftest.hdf caps put_hdf { <parameter name> <parameter name> ..... }

The HDF_filename parameter must be set to define the name of the HDF output file.The parameter name is used to create an HDF SDS of the same name and with the attributes of the NAO associated with the parameter name. Coordinate variables associated with the NAO are also set up in the HDF file. Attributes can be defined using the form:

caps put_hdf { out_<parameter name>:<attribute name> }

In this example there must be a corresponding input parameter name pointing to the value of the attribute. The attribute is associated with an SDS. Global attributes can also be written by omitting the <parameter name>. For example:

caps put_hdf { in_orbit = 'n14_12345' out_orbit = ":identifier" avhrr_3 in_avhrr_3:range='0 to 200' out_avhrr_3:range="range" ..... }

will create a global attribute called ":identifier" with a value of "n14_12345". The explicit "parameter = value" overrides the normal naming substitution conventions. Also created will be an SDS called ${_caps_valuePrefix}_avhrr_3 and an attribute associated with avhrr_3 called range with value "0 to 200".

Using NAP to write HDF files

NAP provides a simple interface to write HDF files. The HDF write command under NAP is object oriented. The general form is:

<nao identity> hdf <hdf filename> <name>

where <name> can either be an SDS name, or a global attribute name (:<attribute name>) or an attribute name associated with an SDS (<SDS name>:<attribute name>), for example:

[nap "a = {-1 8}"] hdf test.hdf small_vector

creates a numeric array object with two elements that is then used with the "hdf" method to create an HDF file called "test.hdf". The contents of the nao (a) will be written into the file as an SDS called "small_vector". HDF attributes can be written and read with CAPS version 2.1 and beyond.

nap text = 'hello universe - this will create a text nao' $text hdf test.hdf :text_message

here the text is written as a global attribute in the HDF file. Alternatively the attribute could be attached to the SDS thus:

nap "text = 'text over two lines the second line of text'" $text hdf test.hdf small_vector:text_two

Using NAP to read HDF files

A special command called nap_get is used to read data from an HDF file: The command syntax is:

nap_get hdf <file name> <name> "<subscripts>"

The command creates a nao as the result. The <name> can be an SDS name, a global attribute name or the name of an attribute attached to an SDS. The nao will also have attached coordinate variables if the variables were attached to the nao generating the original SDS. The subscripts are optional and can either be a direct index into the HDF SDS or they can index indirectly through the SDS coordinate variables (HDF uses the notation scale factor). For example:

nap a = [nap_get hdf test.hdf small_vector "{0}"]

would return a nao with a value of -1 in "a". If the SDS contains multiple dimensions then the command becomes:

nap a = [nap_get hdf test.hdf big_matrix "{0 4 9},{1 3 7},...."]

big_matrix is intended to represent some multi-dimensional SDS. Double quotes are used to group the vector constants. The double quotes have been omitted from the NAP expression to avoid confusion with the quoting of the subscript vectors. The quotes are only needed on nap expressions when there are " {" constructs (explicitly <space>{ ) in the NAP expression. The problem with " {" is that the Tcl parser will remove the first layer of " {}" before the NAP parser is called. The index vectors can also be called indirectly using the SDS coordinate variables:

nap a = [nap_get hdf test.hdf big_matrix "@@{22.0 37.0 90.0},@@{11 13 17},...."]

The "@@" usage is described in the section on NAP.

Information about the contents of an HDF file can be found by using the command:

set sds [nap_get hdf list test.hdf]

The Tcl variable sds would contain a list of SDSs in the file test.hdf. SDSs with attributes appear as <sds>:<attribute name>. Each attribute associated with an SDS will be listed separately. There is no direct way of getting the shape or type of an SDS using nap commands without reading the SDS. For very large SDSs in HDF files reading the SDS may cause a memory overflow. If the SDS has associated coordinate variables (also stored as an SDS) the CVs can be read to determine the size of the main data SDS. The only other alternative is to use the hdp utility provided with HDF to return the required information.

In CAPS versions before 2.1 the nap_hdf command performed the functions now implemented by the nap_get command. The syntax for the old nap_hdf command is:

nap_hdf <file name> <name> "<subscripts>"

The nap_hdf command has been retained in version 2.1 and beyond for compatibility purposes. New scripts should use the nap_get form.

Binary I/O (Version 2.1+)

Binary files can be created using the nap object oriented command. A small binary file can be created:

set tclChan [open test.file w+] nap "array = reshape({1 2 3 4 5 6 7 8},{2 4})" $array write $tclChan close $tclChan

Note that the open and close are standard Tcl commands. Binary files can be read with the nap_get command, the syntax is:

nap_get binary <tcl channel number> [<data type>] [<shape>]

The Tcl channel number is returned from the standard Tcl open command. The Tcl channel should be closed after using the nap_get command. The data type refers to the standard NAP data types: c8 u8 u16 u32 i8 i16 i32 f32 f64. The <shape> is any nap expression, however, as with any nap expression, be careful to include quotation marks to prevent Tcl removing outer braces etc. For example:

set tclChan [open test.file r] [nap_get binary $tclChan i32"{2 4}"] 1 2 3 4 5 6 7 8 close $tclChan

or to read the binary data and write to an HDF file:

set tclChan [open test.file r] nap bdata = [nap_get binary $tclChan i32 "{2 4}"] $bdata hdf science.dat new_data close $tclChan

It is important to specify the data type. The input data type defaults to byte if not specified. It is necessary to use the tcl seek command to rewind to the start if the data needs to be read again (seek $c 0 start). There is also a tcl library called bin_io.tcl that provides scripts for reading certain standard Fortran file types.

Last Updated 29 May 2002