AVS Modules
Lawrence Berkeley Laboratory

NAME
	read_irregular

SUMMARY
	Name	read_irregular
	Type	data
	Inputs	none
	Output	field
	Parameters	Name		Type
			File Name	Browser

DESCRIPTION
	This module reads data in ascii format into an "irregular
	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:	n
	Number of data dimensions		m
	Dimension 1:				length of dimension 1
	Dimension 2:				length of dimension 2
	   .
	   .
	   .
        Dimension m:				length of dimension m
	Data Vector Length
	coordinates and data

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

	The coordinates and data are organized such that each 
	the coordinate values and data are grouped together, rather
	than seperately.  In other words, one could put the
	coordinate and data information on the same "line"; the
	next "line" would contain the next "logical" coordinate
	and data pair.  The ordering of coordinate/data pairs should
	be with respect to data organization, not coordinate information.
	
	For example, a two dimensional data set could be mapped onto
	a three dimensional sphere.  Imagine a (u,v) coordinate
	system upon which the data is gridded.  The (u,v) coordinate
	system is mapped onto a sphere such that u=v=0 is at one
	pole at, say, longitude -180 while u=v=1 is at the opposite
	pole at longitude 180.

	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", any-dimension, irregular.

EXAMPLE

	1. We have a two-d data field to map onto a sphere.  The
	data consists of a three element vector; temperature, velocity
	and vorticity.  There are, say, 50 samples in each of the 
	(u,v) dimensions of the data.  The ascii file will be 
	organized as follows:  
	(NOTE: do not include the /* comments */ in your ascii file, nor
	include the <end of file> text.)

	3          /* coordinate dimensions */
	2	   /* data dimensions */
	50	   /* length of data dimension */
	50
	3	   /* data vector length */
	x y z temp vel vort
	x y z temp vel vort
	.
	.
	.
	x y z temp vel vort
	<end of file>
	
	x y z are the floating point coordinate values.
	temp vel vort are floating point data values.

	2. An experiments results in a set of x,y,z values (no
	data value).  There are 900 x,y,z points to be input.  The
	ascii file format is:

	3	  /* number of coordinate dimensions */
	1	  /* number of data dimensions */
	900	  /* length of data dimension */
	0	  /* data vector length */
	x y z
	x y z
	.
	.
	.
	x y z
	<end of file>


LIMITATIONS

	Inserting comments into your ascii file will result in errors.

NOTES