NAME

rgenx -- Create a new reseau file.

USAGE

rgenx output template entry coordfile nrows ncols gridtype

DESCRIPTION

This program generates a reseau file from data supplied either in an abbreviated format that provides only a few parameters needed to generate the grid, or alternatively, as a list of coordinates for all the reseau positions. The latter may be supplied as a text file, or as a cursor file, which is produced by the stsdas.vdisplay.tvcursor task.

Note that the order of the reseau marks is most useful as complete rows of marks along the direction most closely parallel to the scan direction (AXIS1 direction). A column of marks refers to the direction most closely parallel to AXIS2. All rows should start on the same column. On the image display the order is as follows:

12

11

10

9

8

7

6

5

4

3

2

1

^

|

|

NAXIS2 inc

NAXIS1 increasing ----->

in a typical case. This order is used because the positions are usually used to perform a geometric correction and the geomcorrx task assumes this order.

PARAMETERS

output [file name]

File name for the reseau table created by this task. The operation may be done in-place in the template table, i.e., the output and template names may be the same.

template [file name]

Optional input reseau file. If this parameter is used, the contents of the file indicated by template will be copied to the output file and the new grid will be inserted.

entry = "Reference" [string]

Entry name to be used for the reseau entry created by this task.

coordfile [file name]

The name of the file containing numerical parameters needed to generate the grid. If gridtype = grid, then coordfile can be either a table or a text file. For all other values of gridtype the coordinate file is a free-format text file, and the number of entries and their interpretation depend on gridtype (see below).

This task first tries to open coordfile as a table; if that fails, it is opened as a text file. A fatal error occurs if the file contains too few numbers; if there are too many numbers, the task may accept them and give you an unexpected grid.

The following chart explains what values are expected in the coordinate file for different types of grids. X and Y are pixel coordinates of a point in the grid, and altogether there are (ncols*'nrows') points in the grid.

Grid Type		Coordinate File Contents
=========		========================
square			Four numbers: the X values of the first and
			last grid points, and the Y values of the
			first and last grid points.

rectangle		'nrows' + 'ncols' numbers: all X values 
			followed by all Y values.

grid			2 * 'nrows' * 'ncols' numbers: X and Y 
			values for each point in the grid.  This 
			may be either a table or a text file.

skew			Six numbers (e.g., 'a1' to 'a6') giving a
			linear transformation from column number i
			and row number j to X and Y:
			  X = a1 + a2 * (i - 1) + a3 * (j - 1)
			  Y = a4 + a5 * (i - 1) + a6 * (j - 1)

If the coordinate file is a table, e.g., a file written by the tvcursor task, then names of columns containing X and Y values are obtained from the xcol and ycol parameters.

nrows [integer, min=1]

The number of rows in the reseau grid. If a template is specified, nrows and ncols are taken from the template and these parameters are ignored.

ncols [integer, min=1]

The number of columns in the reseau grid. (Not needed if a template is used.)

gridtype [string, allowed values: squa | rect | grid | skew]

Type of grid to be generated. (See the description of the coordfile parameter). The distinction between a square grid and a rectangular grid may be obscure. Both are generated by intersections between vertical and horizontal lines. In a square grid, the spacing of the lines is uniform, but the horizontal spacing may differ from the vertical spacing. Boxes are therefore congruent, but may not necessarily be square.

If gridtype = squa, the grid is generated by four numbers (e.g., a1 to a4) that are read in from coordfile. The grid will have ncols X coordinates ranging from a1 to a2, so the interval is (a2 - a1) / ncols. There will be nrows Y coordinates ranging from a3 to a4 in intervals of (a4 - a3) / nrows.

If gridtype = rect, the grid is generated by the intersections of ncols vertical lines and nrows horizontal lines, the coordinates of which are read in from coordfile. The first ncols values are the coordiantes of the vertical lines, and the next nrows values are the coordinates of the horizontal lines.

If gridtype = grid, the coordfile may be either a table or a text file containing X and Y coordinates of each point in the grid. If it is a table, there must be one row for each grid point, and you must give the names of the columns of X and Y coordinates using the paramters xcols and ycol, respectively. If coordfile is a text file, it should contain X,Y coordinate pairs--a total of 2 * nrows * ncols values.

If gridtype = skew, then coordfile should contain six values (e.g., a1 to a6) that describe a linear transformation from column and row numbers to X and Y coordinates. For column i, row j:

	X = 'a1' + 'a2' * (i - 1) + 'a3' * (j - 1)
	Y = 'a4' + 'a5' * (i - 1) + 'a6' * (j - 1)

(xcol = PIX1) [string]

The name of the column containing X coordinates. This parameter is used only if coordfile is a table.

(ycol = PIX2) [string]

The name of the column containing Y coordinates. This parameter is used only if coordfile is a table.

(sfieldthrough sfield4 = 1.,1.,1024.,1024.) [real]

The parameters sfield1 through sfield4 take real values and are used to label the new reseau grid. The parameter sfield1 is the starting line number, sfield2 is the starting pixel number, sfield3 is the number of lines, and sfield4 is the number of pixels on a line. Absolute coordinates are assumed, so that 1,1,10,10 refers to a 10 by 10 area starting at the beginning of the entire 1024 x 1024 image area. The default is (1., 1., 1024., 1024.). These values may be used by other tasks, for example, rfitx might use them to define the area over which a surface fit may be made.

EXAMPLES

1. Generate a new reseau file called "res" with one entry named "tester". The grid will be 8 rows by 7 columns. The coordinate file is called "squa.dat" and contains the values 200.0, 900.0, 100.0, 1000.0 (the grid will start at line=200.0, pixel = 100.0 and intervals 100.0 in the line direction (AXIS2), 150.0 in the sample direction (AXIS1)).

 fo> rgenx res "" tester squa.dat 8 7 squa

BUGS

REFERENCES

This task was written by David Giaretta.

SEE ALSO

rprintx

Type "help focgeom opt=sys" for a higher-level description of the focgeom package.

Type "help reseau" for a description of reseau files.