Help for INTERLOC

PURPOSE:

Program "interloc" is a special purpose VICAR applications program used in the
camera calibration process.  "interloc" operates on an input image containing
horizontal and vertical grid lines.  "interloc" roughly locates the grid line
intersections in the input image.  This is similar to what program "gridloca"
does.  ("gridloca" is not currently implemented on the VAX.) "interloc" is
faster than "gridloca", though, and "interloc" also has an interactive
capability which makes it more convenient to use.  It is presently capable of
operating on byte data only. 
EXECUTION:

"interloc" has two modes of operation, interactive and batch.
 
   1. Interactive Mode - Interactive mode is used if the INT parameter is 
         entered on the TAE command line.  For interactive mode, a display 
         device with a trackball needs to be allocated before "interloc" is
         run.  Once interactive mode is selected, parameters can be entered 
         interactively when the parameter prompt (from subroutine IPARAM) is 
         present.  

         Program "interloc" has several interactive parameters.  Most of the 
         parameters can be entered interactively when the parameter prompt (from
         subroutine IPARAM) is present.  Some of the parameters can also be 
         entered initially as part of the TAE command line.  The parameters 
         that can be entered on the TAE command line are INT, NH, NV, HORI, and 
         VERT.  As many commands may be entered on one line as will fit, and a 
         command specification may be continued on more than one input line 
         using TAE line continuation.  When all processing of the entered 
         commands is complete, the message 'interloc READY' will be displayed 
         on the user's terminal.  Further processing of any command line is 
         cancelled if an error is found, and a new command line is requested 
         from the user.  If cursor locations are to be specified (as for 
         HTRACK, VTRACK, HSEARCH, VSEARCH, and FIX), the message 'Position 
         cursor and press <RETURN>' will appear on the user's terminal.  The 
         user then presses the RETURN key on the terminal when the cursor is 
         positioned correctly.

	Note: To position the cursor click on the arrow icon in the lower
	right hand corner of the display window.  This will cause the cursor
	to be displayed in the upper left corner.  Clicking on an area in
	the display window will position the cursor there.

   2. Batch Mode - Batch mode is used if the INT parameter is not entered.  
         Batch mode can be used in a batch job or in an interactive session.  
         In batch mode the NH, NV, HORI, and VERT parameters are required.  The 
         interactive parameters are not used. In batch mode the GO parameter is 
         not used since in batch mode "interloc" is set up to perform the 
         routines for the GO, PRINT, and EXIT parameters when it comes to the 
         end of the parameter list. 
INPUT:

In "interloc" the input image contains horizontal and vertical grid rulings.
The rulings are distinguished by having a lower DN than the background of the
image.  (See also the documentation from the IBM for program "gridloca".)  

When operating in interactive mode, it is important for the user to keep in 
mind that "interloc" implicitly numbers horizontal grid rulings from top (1) to 
bottom (n) and vertical grid rulings from left (1) to right (m).  The user must 
follow this convention when using the HTRACK, VTRACK, HSEARCH, VSEARCH, and 
FIX parameters. 

OUTPUT:

"interloc" has three output files.  The first output file is the diagnostic 
output file.  This file is the same as the input image except that the 
successive pixels encountered as "interloc" follows along the grid rulings are
given a DN of 255.  This file is not generated in interactive mode until 
(unless) the GO command is executed.

The second output file is the mark data set containing the coordinates of the
grid intersections.  This file is in VICAR format and has one line containing
2*NH*NV REAL*4 words (see NH and NV parameters).  The coordinates are 
line-sample pairs.

The third output file is an intermediate (work) file with size NH lines by
NSI halfword samples.
SIZE:

In "interloc" the SIZE parameter is ignored in both modes.

PARAMETERS:

  INP - Input image file name

  OUT - Output diagnostic image file, MARK data set file, and work file names.

  SIZE - (Not used.)

  NL - (Not used.)

  NS - (Not used.)

  INT - Selects interactive mode. (keyword)

  NH - Number of horizontal grid rulings.  NH is a required parameter.  NH must 
       be a positive integer.

  NV - Number of vertical grid rulings.  NV is a required parameter.  NV must 
       be a positive integer.

  HORI - Starting line and sample coordinates of horizontal grid rulings.  The 
         coordinates are entered as (line,sample) pairs, one after another.  
         The coordinates should be entered in increasing line coordinate value.
         In batch mode the coordinates must be specified this way.  In 
         interactive mode, coordinates can be specified this way or by 
         positioning the cursor for the HTRACK, HSEARCH, or TRACK parameters.

  VERT - Starting line and sample coordinates of vertical grid rulings.  The 
         coordinates are entered as (line,sample) pairs, one after another.  
         The coordinates should be entered in increasing sample coordinate 
         value.  In batch mode the coordinates must be specified this way.  In 
         interactive mode, coordinates can be specified this way or by 
         positioning the cursor for the VTRACK, VSEARCH, or TRACK parameters.

  TRACK - Specifies that coordinates of all horizontal or all vertical grid 
          rulings will be input by positioning cursor with a trackball.  Valid 
          values for TRACK are HTRACK, VTRACK, HSEARCH, and VSEARCH.  The 
          starting coordinates of horizontal grid rulings can be entered using
          HTRACK or HSEARCH.  The starting coordinates of vertical grid rulings 
          can be entered using VTRACK or VSEARCH.  If HTRACK, VTRACK, HSEARCH, 
          or VSEARCH is specified as keyword values, "interloc" will prompt the 
          user NH times in succession for horizontal grid rulings or NV times 
          for vertical grid rulings.  If HTRACK, VTRACK, HSEARCH, or VSEARCH is 
          followed by a single numeric value, then "interloc" will ask the
          cursor to be positioned  for a single grid ruling, (the grid ruling 
          corresponding to the number entered).  If HTRACK, VTRACK, HSEARCH, or 
          VSEARCH is followed by two numeric values, say n1 and n2, then 
          "interloc" will ask the cursor to be positioned in succession for
          grid rulings n1 through n2.  (This is useful if the entire grid image 
          cannot be displayed at one time.)   When a cursor position has been 
          accepted by "interloc", a small box marking the position will appear
          on the display. (keyword)

          The syntax for the case of HTRACK would be:

          'HTRACK              to specify all NH horizontal grid rulings.
           HTRACK = n1         to specify horizontal grid ruling n1.
           HTRACK = (n1,n2)    to specify NH horizontal grid rulings n1 
                               through n2.

  HTRACK - Specifies that coordinates of select horizontal grid rulings will be 
           input by positioning cursor with a trackball.  Enter a single number
           for one grid ruling or two numbers for a range of grid rulings.

  VTRACK - Specifies that coordinates of select vertical grid rulings will be 
           input by positioning cursor with a trackball.  Enter a single number 
           for one grid ruling or two numbers for a range of grid rulings. 

  HSEARCH - Same as HTRACK except cursor will be initially positioned by 
            program.

  VSEARCH - Same as VTRACK except cursor will be initially positioned by 
            program.

  DISP - Displays input image or diagnostic output image (see GO parameter) on 
         display device. If the image is too large to display in its entirety, 
         a portion within the 'display window' is displayed. (See HOME, UP, 
         DOWN, RIGHT, LEFT.)  (keyword)

  HOME - Moves display window to the upper left corner of image. (keyword)

  UP - Moves display window up by one screen length (512 lines). (keyword)

  DOWN - Moves display window down by one screen length (512 lines). (keyword)

  LEFT - Moves display window to the left by one screen width (512 samples).
         (keyword)

  RIGHT - Moves display window to the right by one screen width (512 samples).
          (keyword)

  PRINT - Prints the grid intersection coordinates on the user's terminal. 
          (keyword)

  GO - Causes program to find grid intersections.  GO sets up for the DISP 
       command to display the diagnostic output image so the user can make 
       corrections if necessary.  (See the FIX command.)  (keyword)

  FIX - Specifies that select grid intersections will be determined by 
        positioning the cursor with trackball.  The user specifies the 
        horizontal and vertical grid ruling numbers whose intersection(s) is to 
        be FIXed as values for the FIX parameter.  The user may enter the 
        number of the horizontal grid ruling followed by the number of the 
        vertical grid ruling (two values for one intersection) or a range of 
        the horizontal grid rulings followed by a range of vertical grid rulings
        (four values for a range of intersections).   When a range of 
        intersections is specified, the program accepts coordinates for each 
        intersection on a specified horizontal grid ruling before moving on to 
        the next horizontal ruling.  This command can be used to correct 
        intersections not properly found by the GO command, or may be used to 
        manually specify the intersections without using the intersection 
        finding algorithm at all.

  RETRY - Resets "interloc" to allow grid ruling coordinates to be changed
          and GO command to be respecified. (keyword)

  EXIT - Used to end a run of "interloc". (keyword)

  TEST - TEST=(l,s) Parameter for testing. Causes "interloc" to use (l,s) as
         the line and sample image coordinates instead of the current cursor 
         position.  TEST values are in terms of image coordinates.
TAE COMMAND LINE FORMAT:

The following command line formats show the major allowable forms:

   interloc INP=a OUT=(d,m,w) parameters
   interloc a (d,m,w) parameters

     where a = input image file name
           d = diagnostic output image file name
           m = mark data set file name
           w = work file name
EXAMPLES:

1. interloc INP=a OUT=(d,mark,work) NH=2 NV=3 HORI=(100,10, 200,10)        VERT=(10,150, 10,250, 10,350)

   In this example "interloc" operates in batch mode to find the intersections
   of two horizontal grid rulings and three vertical grid rulings.  The 
   starting points of the rulings are identified by the HORI and VERT values.
2. interloc INP=a OUT=(d,mark,work) NH=2 NV=3 'INT
          
      'HSEARCH
            

      'VSEARCH
         


      'GO
          
      'PRINT
          
      'EXIT
          
   In this example "interloc" operates in interactive mode to find the 
   intersections of two horizontal grid rulings and three vertical grid 
   rulings.  The starting points of the rulings are specified by cursor
   positions.  For the HSEARCH and VSEARCH parameters, "interloc" searches
   for the next grid ruling and provides an initial positioning of the cursor 
   to the next ruling.  Note that since no value is specified with HSEARCH
   and VSEARCH, "interloc" prompts NH times for vertical rulings and NV times
   for vertical rulings.  (See Help for TRACK.)   The user can adjust 
   the cursor position if desired before pressing the RETURN key.  
   "interloc" then records the cursor position    and advances the cursor
   for the next grid ruling.  The GO command causes the    intersections
   to be located.  The PRINT command displays the intersection   
   locations.  The EXIT command causes the mark data set to be written and
   completes the execution. 
OPERATION:

The job of "interloc" is to produce a set of rough grid intersection locations
in a "mark" format data set.  The user specifies the starting coordinates for
each horizontal and vertical grid ruling at the left or top of the ruling.
Then "interloc" "follows" the course of the grid lines across and down the
image using the following algorithm:

   For each horizontal ruling all pixels to the left of the starting point
   on the same line are considered to be part of the grid ruling.  Then
   "interloc" moves across the image one pixel at a time, and at each
   successive sample coordinate decides which of the three pixels is the
   darkest (has the lowest DN):   P(L-1,S), P(L,S), P(L+1,S).
   This darkest pixel becomes the next pixel in the grid ruling, and the 
   algorithm continues from there.

   When all horizontal rulings have been "followed", the very same thing is
   done for each vertical ruling, moving from top to bottom instead of left to
   right.  When a vertical ruling crosses a horizontal ruling, the 
   coordinates of the intersection are recorded for printing and for output
   to the MARK data set.

Program "interloc" uses dynamic memory allocation (using subroutine "stacka")
to avoid imposing restrictions on the image size.  
RESTRICTIONS:

1. The input image must be byte data.
2. The maximum number of horizontal grid rulings is 600.
   If the HORI parameter is used, the maximum is 300 rulings due to the
   maximum count for HORI.
3. The maximum number of vertical grid rulings is 600.
   If the VERT parameter is used, the maximum is 300 rulings due to the
   maximum count for VERT.
WRITTEN BY:             Steve Pohorsky              30 Jan 1985

COGNIZANT PROGRAMMER:   Steve Pohorsky              30 Jan 1985

REVISION:               3                            4 Aug 1987
Made portable for UNIX ... V. Unruh ... (CRI) (May  8, 1995)
Put grid size into output label ...RRD... 7-97 

PARAMETERS: