<<<<<<<<<<<<<<<<<

cdf_reader(visage) VISAGE cdf_reader(visage)

NAME

cdf_reader - VISAGE reader object to read netCDF files

DESCRIPTION

The cdf_reader object reads Network Common Data Format (netCDF) formatted binary files. The purpose of the netCDF interface is to allow the creating, access, and sharing of scientific data in a form that is self- describing and network transparent. The term self- describing indicates that the data file contains information defining the data it contains. The term network transparent means that netCDF data files are independent of binary data representation. That is, any computer can create the binary data file and any computer can read the binary data file. The netCDF software provides many other powerful features such as random access to arbitrary slices of data, common C and FORTRAN application bindings, an ASCII representation that can be easily converted to binary, and automatic code generators for data interface.

The netCDF software is freely available from the Unidata Program Center managed by the University Corporation for Atmospheric Research and sponsored by the National Science Foundation. At GE, the primary contact is Skip Montanaro (518-387-7312) of the Computer Graphics and Systems Program at GE Corporate Research and Development. Will Schroeder (518-387-5106) of the same organization may also be contacted.

The cdf_reader object currently supports the reading of VISAGE data sets and display data. VISAGE data sets consist of geometry, scalar data, and vector data. There are four different types of geometry: structured grids, unstructured grids, structured point sets, and unstructured point sets. In addition, the data can be time varying (i.e., a function of time).

Display data is an object that is used to generally represent visualization data, and is used to build visualization pipelines. It is extremely flexible and can be used to create many sophisticated images. Display data can also be a function of time.

In an netCDF file, VISAGE data sets are represented by creating a dummy variable that contains, as attributes, the name of the geometry, scalar, and vector data. In addition, other information relevant to the geometry are contained as attributes to the dummy variable (e.g., dimensions of structured grid).

Because the netCDF specification is so flexible, it is not possible to provide a rigid format specification. Instead, see the examples at the end of this man page. A general outline of the data follows:

Define dimensions time=unlimited; point_width=3; scalar_width=1; no_nodes=24; element_width=9; no_elements=11;

Define variables float time(time); char mesh_1; float nodes (no_nodes, point_width); int elements (no_elements, element_width); float temperature (time, no_nodes, scalar_width); float pressure (time, no_nodes, point_width);

Define attributes to variables mesh_1: type = "unstructured_grid"; mesh_1: points = "nodes"; mesh_1: elements = "temperature pressure"; mesh_1: data = "velocity pressure";

Define data time = 0.0, nodes = 0.0,0.0,0.0, 1.0,0.0,0.0, ... ; elements = 5,1,2,3,4,5,6,7,8, ... ; temperature = 100,120,122, ... ; temperature = 10,20,22, ... ;

The cdf_object, like other reader objects, is unusual in that it can create instances of other objects. For example, when the cdf_reader object recieves a read! message, (if it can successfully read the file) it will create visage_data_group, visage_data_set, visage_scalar, visage_vector, and structured_grid_set objects.

The naming convention for these objects is based on the data_group instance variable. If data_group is empty, then data_group is set to the filename of the file_prefix or netCDF file, excluding directory path and extension. This results in a the following naming convention:

visage_data_group The name of the visage_data_group instance is visage_data_set(s) The name of the visage_data_set instance(s) is(are) the netCDF variable(s) identified by "type" attribute in netCDF file

visage_scalar(s) The name of the visage_scalar instance(s) is(are) the netCDF variables of width 1 and associated with

a data set through the "data" attribute,

visage_vectors(s) The name of the visage_vector instance(s) is(are) the netCDF variables of width 3 and associated with a data set through the "data" attribute,

SUPERCLASS

visage_reader

INSTANCE VARIABLES

selection a list of data types to extract from the data file. Can be any combination of "structured_grid", "unstructured_grid", "structured_point_set", "unstructured_point_set", or "display_data". By default, all data are extracted from netCDF file.

display_data a list of all display data objects created during the data read.

variable_name the name of a netCDF variable. Used to obtain information about a variable.

dimension_name the name of a netCDF dimension. Used to obtain information about a dimension.

auto_close boolean flag to control whether netCDF files are closed after read operations or are left open. The advantage of leaving them open is that multiple file access is faster. The disadvantage is that if too many files are opened, netCDF reports errors (i.e., netCDF has a open file limit of 64 at the time of this writing).

MESSAGES

selection=+ data_set_type Set/add to the current list of data set types to be extracted.

selection-? data_set_type Remove data_set_type from the current list of data set types to be extracted.

selection?'

display_data? Obtain the list of display data read during the "read!" method.

variable_name= netCDF_variable set the name of the netCDF variable.

variable_name? get the name of the netCDF variable.

dimension_name= netCDF_dimension set the name of the netCDF dimension.

dimension_name? get the name of the netCDF dimension.

auto_close_on!/auto_close_off! turn on/off automatic netCDF file closing.

auto_close? get the name of the auto_close boolean.

auto_close= value set the value of the auto_close boolean. If != 0, auto_close is on.

variable_names? obtain a list of all variables in a netCDF file.

number_dimensions? given a variable (e.g., the variable_name instance value), return the number of dimensions for this variable.

dimension_names? given a variable (e.g., the variable_name instance value), return a list of the names name of the dimensions for this variable.

dimension_sizes? given a variable (e.g., the variable_name instance value), return a list of the sizes of the dimensions for this variable.

number_attributes? given a variable (e.g., the variable_name instance value), return the number of attributes for this variable.

attribute_names? given a variable (e.g., the variable_name instance value), return a list of all the attributes for this variable.

attribute_values? given a variable (e.g., the variable_name instance value), return the values of all the attributes for this variable.

dimension_size? given a dimension (e.g., the dimension_name instance value), return the size of the dimension.

start_time? return the start time (i.e., the first value of the unlimited dimension) for this file.

end_time? return the end time (i.e., the last value of the unlimited dimension) for this file.

time= value set the current time.

time? get the current time.

next_time? given the current time, what is the next time step?

next_time? given the current time, what is the previous time step?

time_steps? return a list of all time steps in the netCDF file.

create_xxx internal method to create a type of data object.

read_xxx internal method to read a type of data object.

EXAMPLE

The first example shows how to use the cdf_reader in a visualization network.

/* * Script to test use of cdf_reader in pipeline */ cdf_reader new: areader file_prefix=test ; /* * Pipeline: outline plus geometry */ display_outline new: outline data_in= areader ; display_lines new: draw_outline data_in=outline ; actor new: outline_actor

modeller=draw_outline ;

data_geometry new: dg data_in= areader extent= (1,1,1,100,1,100) ; display_all new: draw data_in= dg range= [areader range?] ; actor new: data_actor modeller=draw ;

/* * Renderer stuff */ vector new: bbox = ([areader bounds?]); camera new: acamera position=(1,1,1) x_range=([bbox @1 ?],[bbox @2 ?]) y_range=([bbox @3 ?],[bbox @4 ?]) z_range=([bbox @5 ?],[bbox @6 ?]) default! on! ;

renderer new: main_renderer actors=([actor instances?]) cameras=acamera render! ;

The next example is a netCDF file for display data using CDL.

// // Test display data for netCDF reader //

netcdf visualization_data {

dimensions:

time=unlimited; xyz_size=3; points_size=4; lines_size=9; polygons_size=8; strips_size=8;

variables: float time(time);

// // Geometry // char dd_1; float points(time,points_size, xyz_size); int lines(lines_size); int polygons(polygons_size); int strips(strips_size); float scalars(points_size); float vectors(points_size, xyz_size); // // Attributes - these serve to group the data as well as // explain what type of data to expect.

dd_1: type = "display_data"; dd_1: points = "points"; dd_1: lines = "lines"; dd_1: polygons = "polygons"; dd_1: triangle_strips = "strips"; dd_1: scalars = "scalars"; dd_1: vectors = "vectors"; // // Note: the data is a function of time // data: time = 0.0, 1.0, 2.0;

// // Points // points = 0,0,0, 10,0,0, 10,5,0, 10,5,2.5, 0,0,1, 10,0,1, 10,5,1, 10,5,3.5, 0,0,2, 10,0,2, 10,5,2, 10,5,4.5; // // Lines // lines= 2,1,2,2,2,3,2,3,4; // // Polygons // polygons= 3,1,3,2,3,3,2,4; // // Triangle_strips // strips= 3,1,2,3,3,2,3,4; // // Scalars // scalars= 1,2,3,4; // // Vectors // vectors= 1,1,1, 1,1,1, 1,1,1, 1,1,1; }