TCL UTILITIES

TUdataGrid	TCL UTILITIES USER MANUAL	TUdataGrid

SYNOPSIS

Transfers a set of data to a regular grid

PACKAGE

TCLUTILS

NAME

TUdataGrid

USAGE

TUdataGrid

nP xHold X1 x2 yHold Y1 Y2 V Grid Norm gInfo

INPUT DEFINITIONS

The number of elements in the V input array.

xHold

The number of successive V array values which are assigned one instance of the X coordinate. A 1 indicates a 1-1 correspondence between the input X and V arrays while an input of nP indicates that there is a single X value which is applied to the entire V array.

If the X coordinate data is being input as a range then this is the lower extent of the range otherwise just it just the representative X coordinate associated with the input values.

If the X coordinate data is being input as a range per value then this is the upper extent of the range, otherwise just it should duplicate the X1 entry.

yHold

The number of successive V array values which are assigned one instance of the Y coordinate. A 1 indicates a 1-1 correspondence between the input Y and V arrays while an input of nP indicates that there is a single Y value which is applied to the entire V array.

If the Y coordinate data is being input as a range then this is the lower extent of the range otherwise just it just the representative Y coordinate associated with the input values.

If the Y coordinate data is being input as a range per value then this is the upper extent of the range, otherwise just it should duplicate the Y1 entry.

The array of values associated with (X,Y).

Grid

The data grid output as a 1D array of values. Unless specified through gInfo this is an unnormalized representation of the gridded data.

Norm

The grid normalization factors as a 1D array of values. This holds the number of inputs to each cell in the data grid.

gInfo

The data grid description array. Entries describe how to setup and fill the data grid. The definition of the array elements are:

0	-	The value assigned to the left-hand edge of the grid
1	-	The value assigned to the right-hand edge of the grid
2	-	The value assigned to the bottom edge of the grid.
3	-	The value assigned to the top edge of the grid.
4	-	The number of cells in the grid in the X direction (left to right)
5	-	The number of cells in the grid in the Y direction (bottom to top). This is 1 a 1D grid.
6	-	Storage method associated with the X coordinate of the data. This is either BAND or POINT. POINT storage localizes data within the single grid column containing the average of X1 and X2. BAND spreads the data over all columns between X1 and X2.
7	-	Storage method associated with the Y coordinate of the data. This is either BAND or POINT. POINT storage localizes data within the single grid column containing the average of Y1 and Y2. BAND spreads the data over all columns between Y1 and Y2.
8	-	Grid storage order. This is either ROW or COLUMN. ROW causes the 2D grid to be stored row by row in the 1D Grid array and COLUMN causes the grid matrix to be stored column by column in the 1D Grid array.
9	-	Zero handling. This is either IGNORE or KEEP. IGNORE causes zero data to be excluded from the grid. KEEP causes zero data to be included in the grid.
10	-	The to do flag. This is one or more of the Key Words NEW, ADD, END. When multiple key words are used they must be separated by a :. NEW causes the Grid to be initialized. ADD causes the data passed into the routine to be added to the grid, and END causes the grid to be normalized. The commands can be performed in separate calls to the procedure and when linked together in a single call are performed in the order given. The ADD command may be invoked multiple times between a NEW and END command.
11	-	The value to initialize the grid to.
12	-	The value to set bad grid cells to. These cells are ignored by all procedures which perform grid cell manipulations.
13	-	Data lower limit. Input data below this value is ignored.
14	-	Data upper limit. Input data above this value is ignored.
15	-	X direction cyclic flag. This is YES if the grid is cyclic in X and NO otherwise.
16	-	Y direction cyclic flag. This is YES if the grid is cyclic in Y and NO otherwise.

RETURN DEFINITION

NONE

DESCRIPTION

TUdataGrid stores data in a regular grid (matrix) which can be used as input into any number of procedures which require regularly spaced data. For reference the X direction of the grid is along the matrix rows so that columns represent discrete ranges of X and the Y direction is along the matrix columns so that rows represent discrete ranges of Y. Data is input as (X,Y,V) triads, where both X and Y can be input to have an associated range.
A grid definition array (gInfo) is used to set up all of the options used in building the grid and in storing the data into it. This includes such information as the extent of the grid in the X and Y directions as well as the number of cells in either direction; whether the X and Y coordinates should be stored as point or extended sources; whether points with zero intensity should be included in the grid; and if either of the X or Y grid directions are cyclic. This information is used not only by this routine but by many of the routines which manipulate grid data.

ERRORS

None Generated

C BACKING

Yes

EXAMPLE(S)

EXAMPLE 1: Graphical representation of an underfilled grid.

# SET up a gaussian data set

set nP 0
for { set X -6.0 } { $X <= 6.0 } { set X [expr $X + .5] } {
   for { set Y -6.0 } { $Y <= 6.0 } { set Y [expr $Y + .5] } {
       set Xx($nP) $X
       set Yy($nP) $Y
       set R [expr $Xx($nP) * $Xx($nP) + $Yy($nP) * $Yy($nP)]
       set Vv($nP) [expr exp (-$R / 6.0)]
       incr nP
   }
}

# SET up the grid information array.  There are more cells in the grid than
#   data points

set gInfo(0) -6.0
set gInfo(1) 6.0
set gInfo(2) -6.0
set gInfo(3) 6.0
set gInfo(4) 100
set gInfo(5) 100
set gInfo(6) POINT
set gInfo(7) POINT
set gInfo(8) COLUMN
set gInfo(9) IGNORE
set gInfo(10) NEW:ADD:END
set gInfo(11) -1
set gInfo(12) -5
set gInfo(13) -1.0e30
set gInfo(14)  1.0e30
set gInfo(15)  NO
set gInfo(16)  NO

# GRID the data

TUdataGrid $nP 1 Xx Xx 1 Yy Yy Vv Grid Norm gInfo

# PLOT the Grid

GraphicsOn TK ETones SWAP

GenWindow 1 0.0 0.0 0.0 1.0 1.0 0.0  0. 0. 0. 1. 1. 0.
SqWindow 8 0.15 0.15 0. 0.8 -6. -6. 0. 6. 6. 0.
DefinePlot 8 8 $gInfo(4) $gInfo(5)

PLTcolorMap 0.0 1.0 LINEAR 0 cA

Plot3D 8 Xb Yb Dummy Dummy Grid AUTO Dummy cA
PlotOutlines 8 [list "X" 1.0 "Y" 1.0] [list BOT BOT BOTH BOTH]
update

EXAMPLE 2: Graphical representation of an overfilled grid.

# SET up a gaussian data set

set nP 0
for { set X -6.0 } { $X <= 6.0 } { set X [expr $X + .1] } {
   for { set Y -6.0 } { $Y <= 6.0 } { set Y [expr $Y + .1] } {
       set Xx($nP) $X
       set Yy($nP) $Y
       set R [expr $Xx($nP) * $Xx($nP) + $Yy($nP) * $Yy($nP)]
       set Vv($nP) [expr exp (-$R / 6.0)]
       incr nP
   }
}

# SET up the grid information array.  There are more cells in the grid than
#   data points

set gInfo(0) -6.0
set gInfo(1) 6.0
set gInfo(2) -6.0
set gInfo(3) 6.0
set gInfo(4) 100
set gInfo(5) 100
set gInfo(6) POINT
set gInfo(7) POINT
set gInfo(8) COLUMN
set gInfo(9) IGNORE
set gInfo(10) NEW:ADD:END
set gInfo(11) -1
set gInfo(12) -5
set gInfo(13) -1.0e30
set gInfo(14)  1.0e30
set gInfo(15)  NO
set gInfo(16)  NO

# GRID the data

TUdataGrid $nP 1 Xx Xx 1 Yy Yy Vv Grid Norm gInfo

# PLOT the Grid

GraphicsOn TK ETones SWAP

GenWindow 1 0.0 0.0 0.0 1.0 1.0 0.0  0. 0. 0. 1. 1. 0.
SqWindow 8 0.15 0.15 0. 0.8 -6. -6. 0. 6. 6. 0.
DefinePlot 8 8 $gInfo(4) $gInfo(5)

PLTcolorMap 0.0 1.0 LINEAR 0 cA

Plot3D 8 Xb Yb Dummy Dummy Grid AUTO Dummy cA
PlotOutlines 8 [list "X" 1.0 "Y" 1.0] [list BOT BOT BOTH BOTH]
update

July 27, 2003