AVS Modules read HDF SDS National Center for Supercomputing Applications University of Illinois NAME read HDF SDS - data reader for NCSA HDF files containing SDSes VERSION 1.0 AUTHOR Bill Sherman (NCSA) wsherman@ncsa.uiuc.edu COPYRIGHT Copyright 1992 the Board of Trustees of the University of Illinois All Rights Reserved. SUMMARY Name read HDF SDS Type Data Input Inputs None Outputs field float -- up to four scalar, or one vector Params Name Type Description HDF Filename char * Name of file containing data Scalar/Vector int (toggle) Choose type of output Port Choice int (choice) Select SDSes to send Next int (oneshot) Increment the SDSes selected Prev int (oneshot) Decrement the SDSes selected Transpose Data? int (toggle) Some HDF files are transposed Transpose Dims? int (toggle) Transpose dimensions of data Auto Send int (toggle) Do a send when file is chosen Display Info? int (toggle) Show some basic info on hdf file Send Data int (oneshot) Send the data down the pipe SDS Information void Widget that shows hdf file info DESCRIPTION The "read HDF SDS" module reads Scientific Data Sets (SDS) from a HDF files, outputting up to four AVS field data sets. HDF is the Hierarchical Data Format developed at the National Center for Supercomputing Applications (NCSA). The SDS is only one of several types of data that may be contained in an HDF file, but it is the only type recognized by this module. "HDF Filename" widget: When the module begins, only the file browser widget will appear. The file browser widget shows all directories in red, and all files that end in ".hdf" in black. (Soft-links to other directories do not show up in the browser in all versions of AVS; this is an AVS bug - at least one version.) Once a file is selected, the rest of the widgets will appear, well, all but one. There are several options that affect how the data will be sent, but the only required selection(s) that have to be made are the mapping of SDS numbers to ports using the array of buttons that list the ports at the top, and the SDS labels down the right side. "Send Data" widget: Not all ports need to be used. Data will be sent from each port with an SDS assigned to it - vector data is combined, and sent out the rightmost port. No data is sent however, until the "Send Data" widget at the top of the widget area is pressed. Alternately, if the "Auto Send" toggle is on, data will be send each time a new file is selected, or when the "Next" or "Prev" buttons are pressed. "Scalar/Vector" widget: "Transpose Data?" widget: "Transpose Dims?" widget: The optional widgets include choosing between sending multiple scalar fields, or one vector field. The data and/or the dimensions of the data can be transposed before being put on the pipe. These two options are sometimes necessary when data was written to the HDF file in column-major order. "Display Info?" widget: The last widget (actually two), is used simply to examine some information that may have been stored with the data. This data includes the label, unit, format (FORTRAN or C), coordinate system, grid information, and minimum and maximum values or extent. When the "Display Info?" toggle is turned on, a large string browser widget will appear in a separate X window. The columns are not yet properly labeled, due to an AVS bug, but the order is as listed above. "Auto Send" widget: As previously mentioned, when the "Auto Send" widget is on, new file selections, and "Next" and "Prev" activations cause data to automatically be sent down the pipe. Typically, when a saved network is reloaded, data will not be sent until the "Send Data" button is pushed. However, with "Auto Send" on when the network is saved, data will be sent when the network is reloaded. "Next" widget: "Prev" widget: The "Next" and "Prev" buttons can be used to step forward or backward through the data sets stored in one file. When scalar data is being sent, SDSes are incremented or decremented by one. When a port goes past an edge (beginning or end), it is set to no SDS, and is no longer effected by subsequent presses of "Next" or "Prev". The same is true for ports initially assigned to no SDS. OUTPUTS Field Output 1 (field float n-tuple) Field Output 2 (field float scalar) only if Output 1 is scalar Field Output 3 (field float scalar) only if Output 1 is scalar Field Output 4 (field float scalar) only if Output 1 is scalar All outputs are optional, though at least one is usually used. When a vector is being output on port 1, the remaining ports are unavailable. For scalars, any port can output any SDS in the chosen file, or it can output nothing. EXAMPLES This example simply sends the data to the "print field" module: "read HDF SDS" | | "print field" RELATED MODULES The "print field" module of the supported AVS module library can be used to display the contents of field data that is sent. This provides a simple means of checking that the data is being properly read and processed. (See EXAMPLES section). The convex supported module library contains a "read hdf field" module, that has the same basic functionality, but has several limitations this module hopefully overcomes. These include the ability to combine data sets into a vector (up to a 4-tuple) from scalar data sets in an hdf file -- this is usually how vectors are stored in hdf files. Another benefit is the ability to see the labels of the hdf data sets; in fact several descriptive bits of information can be displayed in a separate widget. Label and unit information is placed into the field structure and passed along with the data. And finally, sometimes HDF data sets are written in different orderings, such as row-major versus column-major. To overcome the problems this can cause, the toggles "Transpose Data?" and "Transpose Dims?" are provided. LIMITATIONS (i.e. bugs?) There are several types of data that can be contained in an HDF file. This program only reads Scientific Data Sets (SDS). Other types include 8/24 bit raster images, color palettes, and V-sets (poligonal geometries). Future versions may read these as well, or more likely, there will be future separate modules to read these data types. HDF filenames must end in ".hdf" to be seen by the browser. This is done by design, but I may change this depending on feedback. When several data sets are being read from a single HDF file, it is convenient to have a single modules control parameters such as the filename, and when to send the data. To facilitate this, a possible new feature would be to allow parameters to be duplicated as output ports, that could then be connected to input port parameters. (SGI's explorer allows parameters to be both input and output ports on request, whereas AVS only allows this for input.) AVS bugs and short comings have also placed some constraints on this module. Most have been overcome, but some minor problems remain. The problems that remain can be found in the source code by searching for the string "AVS_BUG", which is used to prevent code calling suspect AVS routines from being compiled. The rest of the section deals with situations created by some AVS bugs and short comings. Problems encountered include: an undocumented limitation on widget title length. Title longer than about 63 characters cause AVS to dump core. The information display widget requires a lengthly title to label the columns of data. When vector data is being output, three output ports go unused, and should probably not be shown on the module icon. However, the call to "AVSset_output_flags()" causes the module to die. HDF files allow minimum and maximum data values to be stored with a data set. Optimally, if provided, this data should be passed unaltered to the AVS field. However, "AVSfield_set_minmax()" sets all values for all dimensions to the values of the first dimension. To work around this bug, minimum and maximum values are set though with a call to "AVSfield_reset_minmax()". To allow the full range of ascii characters to be used as data set labels, a C '\n' should be used as the separator character for choice widgets. Unfortunately, when networks with these choice widgets are stored to a file, and later reloaded, AVS cannot handle it, and produces several error messages. This is overcome by converting '|' charaters to ':' characters in labels, and using '|' as the choice separator.