Help for LOCUS2


LOCUS2 is a VICAR applications program which transforms one set of 
MARK-format coordinates to match another.  Six fits are calculated with
the quality reported.  Two of the fits are used to produce output
text files for illustrating the spatial variation of the fit.

INPUT FORMAT
The one or two input files contain sets of coordinates:  the first is 
the set to be transformed and fit to the optional second (or reference) set; 
Each input file is assumed to contain one set of coordinates.  Each 
input file should be in VICAR REAL format, one line (record) of length 
2*n words, where n is the number of points in each set of coordinates.  
The standard VICAR SIZE parameter is not used in LOCUS2 because the input
files are not image files.

The second input is optional.  If it is not supplied, LOCUS2 will 
constuct a perfect grid to use as the reference grid (based upon the NROW and 
NCOL parameters).  

If the second input is supplied, LOCUS2 will look for
the grid size among the keywords in its label (GRID_NROW and GRID_NCOL).

The first input will normally have been generated by INTERLOC, GRIDLOCB or
FIXLOC.

EXECUTION

	locus2 (raw,ref) parms

OPERATION
LOCUS2 first check that the number of points in each file are identical.
It also checks that the grid size specified in the second input label 
(or by parameters) implies the number of samples in the input file records.

The program then does a best fit transformtion of the Raw data (first input)
to the Reference data (a perfect grid or the second input).  Six fits are 
performed with the transformed coordinates stored in the array for later use.
The six fits are:
	1. No change
	2. Offset
	3. Rotation and offset
	4. Scale and offset
	5. Scale, rotation and offset
	6. Unconstrained

Quality information is printed for all fits.

OUTPUT FILE FORMAT
Fits 5 and 6 produce output files which contain the residuals after the
fits to the reference. Three files are needed for each fit.  One file 
contains the residuals in Line, one the residuals in Samp and one the 
Magnitude of the residuals (sqrt(dl*dl+ds*ds)).

The output files are ASCII text files and therefore are not VICAR files.
The filenames are entered via the SROFILES (fit 5) and UNCFILES (fit 6).
The files are written as TAB-delimitted values (F8.4) with the number 
values per record being the number of grid columns and the number of 
records being the number of grid rows.

Format of output files: 
where residual value is denoted by res(i,j) (with i=row num., j=col num.)

	res(1,1)	res(1,2)	res(1,3)  ...   res(1,ncol)
	res(2,1)	res(2,2)	res(2,3)  ...   res(2,ncol)
            .
            .
            .
	res(nrow,1)	res(nrow,2)	res(nrow,3) ... res(nrow,ncol)

Example ASCII output:

	  6.2145	  5.5742	  5.0520  ...     6.6877	  
	  5.5688	  4.8335	  4.2088  ...     5.7503	  
            .
            .
            .
	  6.6733	  6.7403	  5.8532  ...     6.0715	  

In addition, the RADIAL parameter allows the generation of an output file
containing the magnitude and components of the residuals for fits 5 and 6 
sorted by distance from the center of the image.  The CENTER parameter 
is required if the RADIAL parameter is used.  The file is written as 
TAB-delimitted ASCII values, one record per point: 
                 fit 5 : SRO                     fit 6: UNC
radial_distance, mag., radial comp., azm. comp., mag., radial comp., azm. comp.

Example RADIAL table output:

  16.97	  0.4324  -0.2657   0.3412  0.4325  -0.2657   0.3413
  39.85	  0.2732  -0.2732   0.0015  0.2683  -0.2682  -0.0064
  39.85	  0.3513   0.0035  -0.3513  0.3419   0.0038  -0.3419
  53.74	  0.4494   0.4403  -0.0899  0.4375   0.4274  -0.0934
  63.15	  0.3666  -0.2700   0.2480  0.3599  -0.2694   0.2387
  63.15	  0.2719   0.2437  -0.1207  0.2646   0.2396  -0.1123
  72.72	  0.1763  -0.1643  -0.0640  0.1640  -0.1511  -0.0636
  72.72	  0.2237  -0.0442  -0.2193  0.2155  -0.0326  -0.2130
  87.69	  0.5201  -0.1314   0.5032  0.5203  -0.1442   0.4999

Also, the residual value for the Unconstrained fit may be optionally
output to a TCL variable in the calling procedure or session.  The 
user must specify the name of the declared (real) variable as the 
value of the UNCRES parameter.

RESTRICTIONS

1.  No more than 900 coordinates.

2.  MARK-format input files.  Real*4 (line,samp) pairs on one record.

3.  Both inputs must have the same number of coordinates and that must
    agree with the parameters or label values.

4.  No more than 100 columns of coordinates in grid.

EXAMPLES

1. Comparison with perfect input grid.
	gridlocb IN RAW
	gridgen REF NCOL=20 NROW=20
	locus2 (RAW,REF) NCOL=20 NROW=20 SROFILES=(A,B,C) UNCFILES=(D,E,F)

2. Comparison of two imaged grids.
	gridlocb IN  RAW
	gridlocb IN2 REF
	locus2 (RAW,REF) NCOL=20 NROW=20 UNCFILES=(A,B,C)

3. Comparison with internally-generated perfect grid.
	gridlocb IN RAW
        local U42 REAL
	locus2 RAW NROW=20 NCOL=20 UNCFILES=(A,B,C)  		RADIAL=RAD.TBL CENTER=(512,512) UNCRES=U42
        disp U42

WRITTEN BY:             Charlie Avis

COGNIZANT PROGRAMMER:   Charlie Avis

REVISIONS:
   02-73  ...kreznar...  wrote LOCUS
   12-93  ...CCA...      inital simplification into LOCUS2
    1-96  ...CCA...      MADE GENGRID INC REAL, ADDED OUTPUT OF RADIAL
                         COMPONENT OF VECTORS IN RADIAL TABLE
    1-97  ...cca...      updated Help and added output of unc. res. to TCL
    6-97  ...rrd...      Made portable for UNIX.