AVS Modules						    read rectilinear
Lawrence Berkeley Laboratory					   July 1992

NAME
	read rectilinear

SUMMARY
	Name	read rectilinear
	Type	data
	Inputs	none
	Output	field rectlinear
	Parameters	Name		Type
			File Name	Browser

DESCRIPTION
	This module reads data in ascii format into an "rectilinear
	field" data structure.

	The disk file is structured to contain information about
	the field at the beginning of the file, followed by the
	data.

	Specifically, the file format this module expects is:
	
	Number of coordinate dimensions:	m
	Dimension 1:				length of dimension 1
	Dimension 2:				length of dimension 2
	   .
	   .
	   .
        Dimension m:				length of dimension m
	Data Vector Length
	Coordinates for dimension 1
	Coordinates for dimension 2
	   .
	   .
	   .
	Coordinates for dimension m
	data

	Or, more broadly, the input file is divided into three broad
	subsections:

		1.	header information
		2.	coordinate information
		3.	data information

	Each of the specification values, number of data dimensions,
	length of dimension, and data vector length,
	are integers separated by whitespace.  

	Immediately following the header information is the coordinate
	information for the field.  The coordinates are logically
	organized so that all the X-coordinates are listed first (the number
	of X-coordinates is specified by the length of "dimension 1"),
	then all the Y-coordinates (length of dimension 2), etc.

	After the coordinate information is the data.  The data is 
	organized such that if the data vector length is N, the first
	N data items are interpreted as being the data vector at the
	first grid location X[0],Y[0]...W[0]; the next N items are
	the data vector at the next grid location X[1],Y[0]...W[0].
	(The use of X,Y,..W labels for coordinates is for illustration
	only.)

	See the EXAMPLE section below for more info.

INPUTS	

PARAMETERS

	This module accepts as a parameter a file name.  The user
	is provided a file browser.

OUTPUTS
	"Field float", any-vector, rectilinear.

EXAMPLE
	In this example, we have a 2 by 3 grid of 2 vector values.
	This two-dimensional dataset represents height and temperature
	at each location of a small grid.  The comments in the
	example below are delimited with double slashes "//".  These
	should NOT be included in any of your data files.

	2   	// two data and spatial dimensions
	2	// length of first dimension
	3	// length of second dimension
	2	// data vector length is 2
	0.1 15.2	// the two x coordinates
	0.3 .2 .6e-3   // the three y coordinates
	10 3.1e-2	// data at x[0],y[0]
	11 2.9e-2	// data at x[1],y[0]
	9  .02		// data at x[0],y[1]
	9.5 1.9e-2	// data at x[1],y[1]
	8.33 1.99e-2	// data at x[0],y[2]
	8.0 .5e-2	// data at x[1],y[2]

LIMITATIONS

	Inserting comments into your ascii file will result in errors.

RELATED MODULES
	write rectilinear

NOTES

AVS Modules						    read rectilinear
Lawrence Berkeley Laboratory					   July 1992