Help for RESLOC

Reference:  618-802 Voyager Imaging Science Subsystem Calibration Report,
Milosh Benesh and Paul Jespen.

Resloc is a VICAR program that locates the reseau marks in Voyager images.

When used together, resloc and geoma will remove the camera's geometric
distortions from the image.

	resloc inp=D out=(Res,Geo)
	geoma inp=(D,Geo) out=Dos size=(1,1,1000,1000)

Resloc finds the reseau marks in image D and stores their (line,sample)
coordinates together with their object-space coordinates in tiepoint file Geo.
Geoma creates an object-space version of D by mapping each reseau mark to its
known coordinates in object space and linearly interpolating elsewhere.  In
this procedure, the file Res plays no role.

Alternatively, the geometric correction can be combined with a map projection
by using program map3.

When used together, resloc and ressar77 will remove the reseau marks from the
image:

        resloc inp=D out=Res
        ressar77 inp=(D,Res) out=E

Resloc stores the (line,sample) coordinates of the reseau marks in file Res.
Ressar77 cosmetically removes the marks by interpolating over neighboring
pixels.  

A detailed description of resloc is presented in the following sections:

   1.The Voyager reseau
   2.Image windows
   3.The shape template
   4.Finding the reseau
   5.Correlation coefficient
   6.Darkness measure
   7.Closeness measure
   8.Detrending
   9.Camera noise
  10.Beam bending
  11.Filling the gaps
  12.Geometric calibration
  13.Geoma parameters
  14.Reseau database
  15.Resloc parameters


1.The Voyager reseau 

The Voyager reseau is a network of fiducial marks spatially distributed over
the field of view of the camera.  They are numbered as follows:

   1     2     3     4     5     6     7     8     9    10    11    12
     13    14    15    16    17    18    19    20    21    22    23
  24    25    26    27    28    29    30    31    32    33    34    35
     36    37    38    39    40    41    42    43    44    45    46
  47    48                                       202          49    50
     51    52    53    54    55    56    57    58    59    60    61
  62    63                                                    64    65
     66    67    68    69    70    71    72    73    74    75    76
  77    78                                                    79    80
     81    82    83    84    85    86    87    88    89    90    91
  92    93                                                    94    95
     96    97    98    99   100   101   102   103   104   105   106
 107   108                                                   109   110
    111   112   113   114   115   116   117   118   119   120   121
 122   123                                                   124   125
    126   127   128   129   130   131   132   133   134   135   136
 137   138                                                   139   140
    141   142   143   144   145   146   147   148   149   150   151
 152   153                                                   154   155
    156   157   158   159   160   161   162   163   164   165   166
 167   168   169   170   171   172   173   174   175   176   177   178
    179   180   181    182  183   184   185   186   187   188   189
 190   191   192   193   194   195   196   197   198   199   200   201

The reseau marks are metal squares embedded on the faceplate of the vidicon.
By measuring the positions of these squares on the faceplate, and
the position of their shadows in the image, we obtain a coarse spatial
sampling of the geometric distortion in the image.

The marks are concentrated around the margins where the distortions are
largest.  The reseau is symmetric about its center (mark 101) except for
reseau mark 202, whose uniqueness establishes the orientation of the image.

Note:  The above numbering scheme differs from that in Benesh Fig. 3-39 in 
that the extra reseau mark is number 49 in Benesh, and 202 here.  Also, there
is a right-to-left reversal of the two grid patterens that is analogous to
what happens when a sign in a window is read from the inside and from the
outside.


2.Image_windows

Let D be a Voyager image, where

	    |   d(1,1)   d(1,2) . . . d(1,800) |
	    |   d(2,1)   d(2,2) . . . d(2,800) |
	D = |      .        .  .         .     |
	    |      .        .    .       .     |
	    |      .        .      .     .     |
	    | d(800,1) d(800,2) ... d(800,800) |

and d(l,s) is the DN value at line-sample coordinates (l,s).

An image window is a rectangular area in the image.  Let W be a window in D,
where

	    | w(-m,-n) .  .  . w(0,-n) . . . w(m,-n) | 
	    |     .     .         .       .     .    |
	    |     .       .       .     .       .    |
	    |     .         .     .   .         .    |
	W = | w(-m,0)  .  .  . w(0,0)  . . . w(m,0)  | 
	    |     .        .      .  .         .     |
	    |     .      .        .     .   .  .     |
	    |     .   .           .        .    .    |
	    | w(-m,n)  .  .  . w(0,n)  . . . w(m,n)  | 


The window is centered at pixel (l,s) if w(0,0)=d(l,s).

Example: The window centered at the pixel (1,1) is

            |  0  0     0      0      0   |
            |  0  0     0      0      0   |
        W = |  0  0  d(1,1) d(1,2) d(1,3) |
            |  0  0  d(2,1) d(2,2) d(2,3) |
            |  0  0  d(3,1) d(3,2) d(3,3) |

As this example illustrates, windows along the corners and edges are allowed
provided we keep track of which pixels are real and which are not.

Integers m and n are the half-window dimensions of W.  The height and width
of the window are 2n+1 and 2m+1, which are always odd integers.

The total number of pixels in W is N=(2m+1)(2n+1).

The mean and standard deviations of W are

	         1
	mu(W) = ---sum(sum(w(i,j)))
	         N

	               1
     sigma(W) = sqrt{ ---sum(sum((w(i,j) - mu(W))**2))}
	               N

where i=-m,...,m and j=-n,...,n.


4.The shape template

The shape template is a Gaussian approximation of a reseau mark.  The template
is represented by the window A, where the default A is

                   |250 234 220 234 250|
                   |234 161 100 161 234|
               A = |220 100   0 100 220|
                   |234 161 100 161 234|
                   |250 234 220 234 250|

What follows describes how this A came to be defined.

Each reseau mark is a metal square 0.04 mm on a side, and creates a shadow
in the image that is roughly 3x3 pixels in area.  Here are examples of
these shadows:
 
           3   3   3   3   3		255 255 255 255 255
           5   3   2   3   2		234 144 131 185 239
           3   1   0   0   2		177  51  48 164 241
           4   2   0   2   2		169  34  20 146 236
           5   5   4   3   4		203 147 166 252 252
 
   12  10  10  14  15    103  89  62  48  35    227 205 162 163 192
   11   7   7   9  13     81  33  16  33  48    199 121  43  81 172
   12   8   3   2  13     65  16   3  27  59    180  99   5  54 167
   12  12   7   7  12     79  49  46  79  92    174 116  48 107 206
   12  12  12  12  12    103 110 105 108 108    189 176 164 186 209

As the first example suggests, the shadow is sometimes too faint to locate
with confidence.

The shadows are never shaped like squares, but have a rounded appearance.
We approximate this shape with an inverted Gaussian of the form

			        1
	f(x,y) = 1 - e**{ - ----------*(x**2+y**2)}
                            2*sigma**2
 
f is called the reseau shape function.  f is actually a vast simplification
of John Kresznar’s shape function used in Mariner 9 and Viking Orbiter.  During
those missions, the shape of each reseau mark was individually measured and
modeled by a Gaussian multiplied by a fifth order polynomial.  For Voyager,
a simple Gaussian represents the shape of all 202 reseau marks.

The shape template is a digitized window of f, where

		    | a(-m,-n) .  .  . a(0,-n) .  .  . a(m,-n) |
		    |     .   .           .           .   .    |
		    |     .       .       .       .       .    |
		    |     .           .   .  .            .    |
		A = | a(-m,0)  .  .  . a(0,0)  .  .  . a(m,-0) |
		    |     .               .               .    |
		    |     .       .       .       .       .    |
		    |     .   .           .            .  .    |
		    | a(-m,n)  .  .  . a(0,n)  .  .  . a(m,n)  | 

and
		a(i,j) = 255*f(i,j).

The pixels are scaled by 255 to match the 0 to 255 DN range output by the
Voyager camera.

The default shape template shown at the top is for sigma=1.  A 5x5 template
appears to be the optimum size.  It is large enough to enclose the 3x3 shadow
plus 16 pixels of the surrounding background.


6.Finding the Reseau

Let W be a window centered at line-sample coordinates (l,s) in image D, and
let A be the shape template.  The correlation coefficient rho measures how
closely A and W match:   
         	          cov(A,W)
        	rho = -----------------
               	      sigma(A)*sigma(W)

To find a reseau mark, a search is made in an area surrounding its nominal
coordinates.  Let (l0,s0) be these nominals.  We compute rho at every pixel
in the search area, creating a matrix R, where

	    | r(-m,-n) .  .  . r(0,-n) .  .  . r(m,-n) |
	    |     .    .          .          .    .    |
	    |     .       .       .       .       .    |
	    |     .          .    .    .          .    | 
	R = | r(-m,0)  .  .  . r(0,0)  .  .  . r(m,0)  |
	    |     .          .    .    .          .    | 
	    |     .       .       .       .       .    |
	    |     .    .          .          .    .    |
	    | r(-m,n)  .  .  . r(0,n)  .  .  . r(m,n)  |

and r(0,0) is the value of rho when W is centered at (l0,s0).

The mark is usually at the maximum value of R.  Occasionally, however
resloc will find another object in the search area that resembles A better than
the actual mark.  Also, as many as half of the marks along the margins of the
image fall off the edge.  In other words, we can never be certain
whether we have found the mark or if the mark exists at all.

To reduce this uncertainty, we take the three highest peaks in R and
ask two further questions:

	1) Is the object dark enough to be a reseau mark?
	2) How close is it to where we expected it to be?

Since only stray light shines on the shadow, its center should be the
darkest point in the search area, if it is there at all.

To predict the position of each mark, we allow for a systematic shift of
the entire reseau from the nominals.  We solve for this shift by minimizing
the residual error between the found coordinates and their nominals.

From these two measurements, we compute normalized darkness and closeness
measures g and h that are roughly on the same scale as rho. 

We may then compute a composite match quality measure q, where

		     1
		q = ---(rho+g+h)
		     3
 
In dark-sky regions of the image, where the DN values are near the noise floor, we ignore the darkness measure and set

		     1
		q = ---(rho+h)
		     2
 
The pixel with the highest q is the most likely place for the reseau mark.

To filter out mismatches, we apply thresholds to rho and q, rejecting all
objects where ρ<rthresh or qcognizant programmer: Gary Yagi
revisions:
 16-nov-85 - l.w.kamp - converted i/o to vicar2
 24-jan-86 - l.w.kamp - replaced lock management code with vicar2
                         open status check + call wait.
 26-feb-86 - l.w.kamp - modified subr.maxr to check dn<dnthresh (new parm)
 20-jun-86 - l.w.kamp - revised subr.filloc to fill in all locations
 27-jun-86 - f.f.moss - converted param i/o to vicar2
 10-jul-95 - a.scop   - (cri) made portable for unix
 27-mar-96 - b.a.mcguffie   - modified to accept new ibis reseau location
      3-89  sp  prevent divide by zero.  finish off lwk's fix to filloc where
               min set to 0.
      3-10  lwk replaced testos() with xvhost()
 2013 version:  gmy - added search for margin reseau marks.

The original resloc (the one used throughout the mission) did not
attempt to locate the marks along the margins of the image because of
the difficulty of doing this reliably.  The 2013 resloc version was an
attempt to remedy this.

For purposes of testing, a small sample master reseau location file
named RESFIL.TST is in the current MIPL test directory.  Please check
with Integration and Test to determine where this directory is located.
This file should not be randomly modified: copy it to a scratch directory 
before tampering with it.

PARAMETERS: