TUgridInfo TCL UTILITIES USER MANUAL TUgridInfo
SYNOPSIS
Get information about a data grid or its cells
PACKAGE
TCLUTILS
NAME
TUgridInfo
USAGE
set rV  [TUgridInfo  ReT gInfo rInfo {V1} {V2}]
INPUT DEFINITIONS
Query - The information being requested. The input definitions are given under the the procedure description.
gInfo - The grid information array.
rInfo - An array of the returned information. The contents depend on the information requested and are decribed under the procedure description.
V1 - Optional input value. The definition depends on the information requested. These are decribed under the procedure description.
V2 - Optional input value. The definition depends on the information requested. These are decribed under the procedure description.
RETURN DEFINITION
rV - The number of elements returned in the rInfo array.
DESCRIPTION
TUgridInfo returns information about the grid described by the grid information provided in the array gInfo. The information is returned in the array rInfo in response to a Query.
Queries about grid cells often return information based on the cell diagram below.
tr - tc - tl
|       |
cr   c   cl
|       |
br - bc - bl
Each cell in a grid has 9 identifiable postions associated with it, one in the center and 8 along the edge. The nomenclature used in identifying one of the positions is (X,Y)id where id is on of the designators in the figure above.
The table below provides a list of the queries that can be made through the procedure, V1 and V2 inputs if any associated with the query, and the information returned in rInfo. In the table (X,Y) with no subscript represents an arbitrary position in the grid, (C,R) a column and row location, and gL the index of one of the grid cells in the grid array.
Query Description
0 - Locate the grid cell which contains the postion (X,Y). (V1,V2) is set to the (X,Y) position. The values returned in rInfo are:
rInfo(0) - Grid Location (gL)
rInfo(1) - Column Number (C)
rInfo(2) - Row Number (R)
1 - Locate the grid cell for (C,R). V1,V2) is set to the (C,R). The values returned in rInfo are:
rInfo(0) - Grid Location (gL)
20 - Return the cell center and (C,R) of a grid location. V1 is set to the gL. The values in rInfo are:
rInfo(0) - Column Number (C)
rInfo(1) - Row Number (R)
rInfo(2) - Xc
rInfo(3) - Yc
21 - Return a full description of the cell of a grid location. V1 is set to the gL. The values in rInfo are:
rInfo(0) - Column Number (C)
rInfo(1) - Row Number (R)
rInfo(2) - Xc
rInfo(3) - Yc
rInfo(4) - Xcr
rInfo(5) - Ycr
rInfo(6) - Xtr
rInfo(7) - Ytr
rInfo(8) - Xtc
rInfo(9) - Ytc
rInfo(10) - Xtl
rInfo(11) - Ytl
rInfo(12) - Xcl
rInfo(13) - Ycl
rInfo(14) - Xbl
rInfo(15) - Ybl
rInfo(16) - Ybc
rInfo(17) - Xbc
rInfo(18) - Ybr
rInfo(19) - Xbr
30 - Returns in rInfo the sequential X edges of all cells in a grid row. This is the Xcl values for all cells and Xcr for the last cell.
31 - Returns in rInfo the sequential Y edges of all cells in a grid column. This is the Ybc values for all cells and Ytc for the last cell.
32 - Returns in rInfo the sequential set of Xc values of all cells in a grid row.
33 - Returns in rInfo the sequential set of Yc values of all cells in a grid column.
40 - Return the beginning and ending (C,R) values defining a square of grids cells. V1 is the grid location of the center of the square. V2 is a value such that 2*V2 + 1 is the number of cells along the square edge. The values in rInfo are:
rInfo(0) - Beginning Column Number
rInfo(1) - Ending Column Number
rInfo(2) - Beginning Row Number
rInfo(3) - Ending Row Number
41 - Return the gL values of all cells on the perimeter of a square of grid cells. V1 is the grid location of the center of the square. V2 is a value such that 2*V2 + 1 is the number of cells along the squares edge. The gL value of each cell on the perimeter of the defined square is returned in rInfo. If a cell on the parimeter falls outside of the grid it is not included in rInfo.
42 - Return the gL values of all cells defining contained in a square of grid cells. V1 is the grid location of the center of the square. V2 is a value such that 2*V2 + 1 is the number of cells along the squares edge. The gL value of each cell with in the defined square is returned in rInfo. If a cell on the parimeter falls outside of the grid it is not included in rInfo.
If gL comes back -1 in rInfo it signifies that the cell lies outside the grid. Similarly a -1 returned for either C or R indicated that the cell row or column is outside the defined grid.
ERRORS
None Generated
C BACKING
No
EXAMPLE(S) 
# RETRIEVING grid information

# SET up a grid information array

set gInfo(0) -180.0
set gInfo(1)  180.0
set gInfo(2) -90.0
set gInfo(3) 90.0
set gInfo(4) 60
set gInfo(5) 30
set gInfo(6) POINT
set gInfo(7) POINT
set gInfo(8) COLUMN
set gInfo(9) KEEP
set gInfo(10) NEW:ADD:END
set gInfo(11) 0.0
set gInfo(12) -1.0e30
set gInfo(13) -1.0e20
set gInfo(14) 1.0e20
set gInfo(15) YES
set gInfo(16) NO

# FIND which cell in a grid contains X= 33.0, Y = -23.5

set nE [TUgridInfo 0 gInfo rV 33.0 -23.5] 
puts stderr "CELL CONTAINING X= 33.0, Y = -23.5"
puts stderr [format "    gL = %5d; C = %3d; R = %3d" $rV(0) $rV(1) $rV(2)]

# POSITION outside grid X = 200.0, Y = -100.5.  Note that because the grid
#   is cyclic in X, X = 200.0 is inside the grid!

set nE [TUgridInfo 0 gInfo rV 200.0 -100.5] 
puts stderr "CELL CONTAINING X= 200.0, Y = -100.5"
puts stderr [format "     gL = %5d; C = %3d; R = %3d" $rV(0) $rV(1) $rV(2)]

# FIND gL for CELL C = 44, R = 13

set nE [TUgridInfo 1 gInfo rV 44 13] 
puts stderr "CELL LOCATION FOR  C= 44, R = 13"
puts stderr [format "     gL = %5d" $rV(0)]

# CELL information associated with a grid location

set nE [TUgridInfo 20 gInfo rV 525] 
puts stderr "CELL INFO FOR GRID LOCATION 525"
puts stderr [format "     (C,R)   = (%d, %d)" $rV(0) $rV(1)]
puts stderr [format "     (Xc,Yc) = (%.1f, %.1f)" $rV(2) $rV(3)]

# FIND all of the grid locations on the parameter of a square of 5x5
#   CELLs at gL = 0.  Note that since part of the parimeter is off the
#   grid not all of the cells will be included in rV

set nE [TUgridInfo 41 gInfo rV 0 2] 
puts stderr "CELL LOCATIONS OF PERIMETER CELLS"
for { set I 0 } { $I < $nE } { incr I } { 
   puts stderr [format "     rInfo(%d) = %5d" $I $rV($I)]
}

# FIND start and stop column and row number of a cell centerd at gL = 433
#   and with a side 3 cells long.

set nE [TUgridInfo 40 gInfo rV 433 1] 
puts stderr "START AND STOP COLUMN AND ROW NUMBER FOR SQUARE OF CELLS"
puts stderr [format "     C Beg = %3d; C End = %3d" $rV(0) $rV(1)]
puts stderr [format "     R Beg = %3d; R End = %3d" $rV(2) $rV(3)]


> CELL CONTAINING X= 33.0, Y = -23.5
>     gL =  1061; C =  35; R =  11
> CELL CONTAINING X= 200.0, Y = -100.5
>     gL =    -1; C =   3; R =  -1
> CELL LOCATION FOR  C= 44, R = 13
>     gL =  1333
> CELL INFO FOR GRID LOCATION 525
>     (C,R)   = (17, 15)
>     (Xc,Yc) = (-75.0, 3.0)
> CELL LOCATIONS OF PERIMETER CELLS
>     rInfo(0) =  1740
>     rInfo(1) =    60
>     rInfo(2) =  1741
>     rInfo(3) =    61
>     rInfo(4) =  1742
>     rInfo(5) =    62
>     rInfo(6) =  1772
>     rInfo(7) =     2
>     rInfo(8) =    32
> START AND STOP COLUMN AND ROW NUMBER FOR SQUARE OF CELLS
>     C Beg = 403; C End = 463
>     R Beg = 432; R End = 434
June 4, 2003