Help for NAV2

PURPOSE

NAV2 is an interactive program which improves the camera pointing of an image
by registering it to a reference image whose camera pointing is accurately
known.  NAV2 is currently specific to Voyager, Galileo, and Cassini flight
images.  

The image to be navigated (primary image) and the reference image must have
overlapping areas in which common features (tiepoints) can be identified.
These tiepoints are used in combination with image projection data retrieved
from the MIPS SPICE server to correct the camera pointing angles (C-matrix) of
the primary image.

In cases where the uncertainties in camera pointing for the primary and
reference frames are equivalent, both images may be navigated simultaneously.
The C-matrices of both frames are modified, with the geometric errors being
split evenly between the two frames.

The algorithms implemented in NAV2 are based on notes provided by
Andy Ingersoll, 3-19-85.  See also VICAR programs NAV, FARENC and MANMATCH.

EXECUTION:

NAV2 is an interactive program and requires the allocation of a display device
with an image plane, graphics plane, and cursor (e.g. trackball, mouse):

      USE  EPA2		!allocate a display device
      NAV2  INP=(PIC,REF)  TARGET=targetname
   or NAV2  INP=(PIC,REF)  OUT=NEWPTS  TARGET=targetname
   or NAV2  INP=(PIC,REF,OLDPTS)  OUT=NEWPTS  TARGET=targetname
where
    PIC is the image to be navigated (primary frame),
    REF is a reference image whose camera pointing is accurately known.
    OLDPTS and NEWPTS are optional input and output tiepoint files.
    TARGET is a required parameter for Voyager.

PIC and REF must be Galileo, Voyager, or Cassini images in byte format.
The input images may be raw images containing geometric camera distortions
or images which have been geometrically corrected.

If NEWPTS is included, NAV2 will output all tiepoints to this file.
Tiepoints saved from a previous session can be input as an optional
third input file (0LDPTS).  OLDPTS and NEWPTS are in IBIS graphics file format.

OPERATION:

NAV2 uses an east-longitude system.  For Voyager, latitudes are input
and output to the user as planetographic.  Planetocentric latitudes are
used for all other missions.  An oblate spheroid target-body model is used.

Initially, the input frames are displayed on a split screen, with the primary
frame on the left and the reference frame on the right (this is the same
convention used by the program PICREG).  The images are displayed at reduced
resolution to display the complete field of view.  If tiepoints are input from
a previous session, these are displayed in graphics (see OLDPTS and NEWPTS in
program execution statement above).

The MIPS SPICE server is accessed to retrieve the image projection geometry
for both the left and right images.  If the input image(s) contain geometric
distortions, the program will attempt to account for this.  Special provisions
must be made for dealing with vidicon camera distortions (e.g. Voyager).  See
the following sections below for details:

	GEOMETRIC CAMERA DISTORTIONS
	ACCESSING SPICE DATA

The primary frame is navigated via the following steps:

   1) Using the cursor and split-screen display, the user identifies one or
      more common features (tiepoints) in both images.

   2) The FIT command is used to recompute the C-matrix so as to minimize
      displacement errors (in pixels) between the left and right images.
      The displacement error for a tiepoint is zero if both left and right
      pixel locations project to the same latitude-longitude coordinates.
      The RMS error, the tiepoint generating the maximum error, and the number
      of points used in the fit are reported.

   3) The user may iteratively delete bad points and redo the fit,
      or go back to acquire more tiepoints.

   4) When the user exits from the program, a final fit is performed.
      The (line,sample) position of the planet center and the north
      angle (ANGLN) are computed and reported.  Finally, the corrected
      camera pointing can be optionally stored in a C-kernel.

All tiepoint selection is peformed interactively, with the user responding to
prompts from the program.  See NAV2 COMMAND PROCESSOR below.

ADJUSTING FOR ATMOSPHERIC FEATURE MOTION:

If the target-body is a planet with an atmosphere, NAV2 will automatically
prompt the user for intructions for dealing with zonal and meridional wind
currents:

	Do you wish to adjust for wind speed?
	Enter Y or N >

If the user responds with 'N', then all tiepoints are assumed to be stationary.
If the user responds with 'Y', the next prompt is issued:

	Do you wish to split the pointing error between the two frames?
	Enter Y or N >

Entering 'Y' will cause both primary and reference frames to be navigated
simultaneously.  The camera pointing angles of both frames are adjusted by
moving each optic axis an equal distance (i.e. it is assumed that the
uncertainties in camera pointing are equivalent for the two frames).

If the target-body is Jupiter, the following prompt is issued:

	Do you wish to use the zonal velocity profile?
	Enter Y or N >

Entering 'Y' will cause the zonal velocity of each tiepoint to be computed
as a function of its latitude using a zonal velocity profile.  The profile is
based on Voyager data.  The meridional velocities are assumed to be zero.

The profile is a table consisting of (latitude, zonal-velocity) pairs, where
the latitudes are stored in monotonically increasing order but at variable
angular spacing.  For latitudes between table values, linear interpolation is
used to compute the zonal velocity.  The table contains data between latitudes
-55.26 and +55.26.  For latitudes outside the range of the table, the zonal
velocities are assumed to be zero.

The SCET is used to determine the time separation between frames. This is used
to convert zonal velocities into pixel displacements (see SCET parameter).

At this point, control is passed to the NAV2 command processor.

NAV2 COMMAND PROCESSOR:

Upon entry, the user will be prompted to input commands.

The user-prompts in NAV2 are nested, so that certain commands will
invoke program modules which issue lower level prompts, and so forth.
All prompts (ideally) will accept the 'EXIT command, which causes
an exit to the next higher level prompt.  In many cases, entering

The controlling program is identified by the prompt:

		NAV2>

Entering 'HELP will result in:

	ENTER EXIT, CZOOM, H, HIST, SPIKES, STRETCH, STR1, STR2,
        GERASE, SPTS, GET, DELETE, FIT, NAVPTS, NAVVEL, EDIT, PARAMS,
        SL, SL1, SL2, SS, SS1, SS2, ZOOM, U, U1, U2, D, D1, D2, L, L1,
        L2, R, R1, R2, HELP>

If the user responds by typing carriage return (without entering any
characters at all) the program will acquire a tiepoint.  See Tiepoint
Acquisition Cycle below.

The CZOOM command is used to center the display about a feature and
change the image resolution of the display.  Entering CZOOM=1 will
cause the split screen to be re-displayed at normal resolution.  The
user will be prompted to center the left and right screens via the
trackball.  If previously acquired features are visible, they are
re-displayed in graphics.

Entering 'H (for Home) will cause the original full-field-of-view
display to appear.

Entering STRETCH=(5,220) will cause a hardware stretch (linear) of
the displayed images.

The STR1 and STR2 commands may be used to stretch the left and right
image areas independently.  Entering STR1=(10,128) will cause the left
image area to be stretched as it is being written to the image-display memory
plane.  Note that these commands are independent of the hardware stretch,
so that following these commands with STRETCH=(5,220) will result in further
stretching of the stretched images.

The 'HIST command displays the histograms of the image areas for both left and
right pictures.  The histograms are displayed in graphics, using a logarithmic
scale in the frequency axis.  The histogram display may be modified by entering
SPIKES=5, which will cause the five highest frequencies to be scaled to the
maximum height of the frequency axis.

Entering 'GERASE will erase the graphics plane.

Entering 'SPTS will re-display the acquired tiepoints.

Entering GET=15 will move the cursor to feature 15 on the left
screen.  If the feature is not visible, the display window will be
moved so that it is.  The (line,sample) and (lat,lon) coordinates
of the feature are reported.

Entering DELETE=15 will delete feature 15.  If you later change
your mind, entering RESTORE=15 will restore the feature.

Entering FIT=2 will cause the camera angular components ANGLA and
ANGLB of the left image to be recomputed, resulting in an updated
transformation from (line,sample) to (lat,lon).  The angles are
recomputed by performing a least squares fit so that points in the
left image occur at the same (lat,lon) coordinates as corresponding
points in the right image.

Entering FIT=3 will cause the camera angular components ANGLA, ANGLB,
and ANGLN (north angle) of the left image to be recomputed.

Entering NAVVEL will cause NAV2 to adjust for wind speed when fitting
the tiepoints.  The user is prompted to specify processing modes for wind
adjustment as before.  This command is valid for atmospheric planets only.

Entering NAVPTS cancels any adjustments made for wind speed.

Entering 'EDIT will enable the user to edit the navigation data.
See EDIT COMMAND below.

Entering 'PARAMS will enable the user to edit the area correlation
parameters.  See PARAMS COMMAND below.

Entering SL=250 SS=80 will move the display windows of both left and
right image so that (line,samp)=(250,80) appears in the upper left
corner.

Entering ZOOM=2 will magnify the displayed area to twice normal resolution
(via pixel replication).

The commands U, D, L, R are for moving the displayed areas up, down,
left, or right.  Entering U=10 will move the displayed areas up 10 pixels.

The left image may be moved independently using SL1, SS1, U1, D1, etc.
Similarly, the right image may be moved using SL2, SS2, U2, D2, etc.

EDIT COMMAND

Typing 'EDIT will permit the user to edit the navigation data.

	Enter LEFT or RIGHT>

Typing 'RIGHT will permit the navigation data for the right image to be
edited.  The EDIT command processor is identified by the prompt:

	EDIT>

The EDIT command processor enables the user to modify values which
effect camera pointing.  These include planet constants, camera
constants, and SEDR data.  Under normal circumstances, the user
will never have to edit the camera pointing data since these are
automatically retrieved from the SEDR file and frame label.

Typing HELP will cause of all the available commands to be listed:

	Enter EXIT,HELP,GEODET,GEOCEN,PR,ER,CAMERA,FL,OAXIS,
	SC,SSP,PC,ANGLN,RANGE,TARGET,WAPC,STATUS,
        SAVE,RESTORE,GETSEDR,CKNAME>

Typing 'EXIT will return control back to the NAV2 command processor.

Typing 'GEODET will cause all latitudes input by the user to be treated as
planetographic, and to report all latitudes to the user as planetographic.
Typing 'GEOCEN will cause all input and output latitudes to be treated as
planetocentric.  Note that the default is GEODET for Voyager and GEOCEN for
all other projects.


Typing PR=54450 ER=60330 will change the values of the planet's
polar and equatorial radii to 54450 and 60330 km respectively.

Typing CAMERA=7 will change the camera-ID to VGR-1 NA (provided the image is
from Voyager).  The focal length, picture scale, and optic axis intercept for
this camera will be automatically set for this camera.

Typing  FL=1200.175 will change the camera focal length to
1200.175 mm.

Typing OAXIS=(400,300) will place the optical axis intercept
at (line,sample)=(400,300).

Typing SC=80 will change the picture scale to 80 pixels
per mm on the focal plane.

Typing SSP=(60,240.3) will change the spacecraft position
to (SCLAT,SCLON)=(60,240.3).

Typing PC=(445.3,558.4) will move the planet center to
(SCLINE,SCSAMP)=(445.3,558.4).  This will cause the camera pointing
to be updated.

Typing ANGLN=190.9 will cause the orientation of the projected
spin axis to be changed to 190.9 degrees, measured clockwise
from right (the positive sample direction).

Typing RANGE=4794909 will cause the distance from spacecraft to
planet center to be changed to 4794909 km.

Typing TARGET=SATURN will change the target-ID to Saturn and
automatically changes the polar and equatorial radii to Saturn's
nominal values.

Typing WAPC=(455.1,376.2) changes the (line,sample) coordinates
of the planet center in the wide-angle frame.  The (line,sample)
coordinates are converted to the narrow-angle field of view and
the result used as the (line,sample) coordinates for the NA planet
center.  The camera pointing is then updated.  Here it is assumed
that the frame being processed is the NA from a WA-NA simultaneous
exposure.

Typing 'STATUS will cause a summary of the navigation data to be
printed.

Typing 'SAVE will store the current navigation data in the array
SNAV.  Typing 'RESTORE will replace the navigation data by
whatever is in SNAV.  Typing 'GETSEDR will replace the navigation
data with the nominal pointing.

Typing CKNAME=FARE specifies that the desired source of C-matrix is FARENC.
Valid source names are:

	DAVI	--Data determined by Mert Davies
	NAV     --Data determined by program NAV
	FARE    --Data determined by program FARENC
	NAV2    --Data determined by program NAV2
	NEAR    --Data determined by program MANMATCH
        NAIF    --Data determined by NAIF

The default is to select the C-matrix in the above order of priority.

PARAMS COMMAND

Typing 'PARAMS will enable the user to modify the area correlation
parameters:

	Enter EXIT, CORR, PROJECT, HPF, PHASE, INTERP, NLW, NSW,
        ZWIND, NOCORR, NOPROJEC, NOHPF, NOPHASE, NOINTERP, STATUS

Typing 'EXIT will return control to the NAV2 command processor.

Entering 'CORR will enable the area correlation algorithm.  The algorithm
consists of multiplying the Fourier transform of the right area by the
complex conjugate of the transform of the left area, computing the inverse
transform and locating the maximum.

Entering 'PROJECT will cause the left area to be projected to the same
perspective as the right area, prior to correlation.  This feature
corrects for large perspective differences between frames.

Entering 'HPF will cause the axes of the transforms to be set to zero.
This is equivalent to applying a high-pass filter to the areas prior
to correlation.

Entering 'PHASE will cause the correlation to be performed using phase
information only.

Entering 'INTERP will cause the correlation maxima to be located to
sub-pixel accuracy by locating the centroid of the correlation peak.

Entering NLW=64 NSW=80 specifies the dimensions of the correlation
areas to be 64x80 pixels.  NLW and NSW must be even integers.

Entering ZWIND=10 will cause a 10x10 window to be used for computing the
average DN value centered on each tiepoint.  This value is stored in the
output tiepoint file (see below).

The commands 'NOCORR, 'NOPROJEC, 'NHPF, 'NOPHASE, and 'NOINTERP disable
the corresponding functions.

Entering 'STATUS displays the current parameter settings.

The default values are 'CORR, 'NOPROJEC, 'HPF, 'NOPHASE, 'INTERP,
NLW=64 and NSW=64.

TIEPOINT ACQUISITION CYCLE

Tiepoints are selected by means of the split screen display.  When a new
tiepoint is to be acquired, its initial location is determined by positioning
the cursor over the feature in the left image.  The user enters a carriage
return (CR), thus sending a blank string to the command processor.  This
signals the command processor to begin a tiepoint acquisition cycle.

The coordinates of the cursor position on the left image are read and
converted into (line,sample) image coordinates.  The (lat,lon) coordinates
of the selected feature are computed, based upon current camera pointing
information, and the results reported:

	FN= 25  (L1,S1)=( 345.23, 673.31)  (LAT1,LON1)=( 22.32,245.32)

If the user has elected to compensate for atmospheric motion, the following
prompt is issued:

	Enter velocity components (U,V) >

The zonal and meridional velocities should be entered in meters/sec.  If
the Jupiter zonal velocity profile has been selected, U is automatically
computed and the prompt is not issued.

A rough estimate of the feature's location in the right image is obtained by
computing the location of the corresponding (lat,lon) coordinates in the
right image, compensating for any feature motion.  The cursor is automatically
moved to this location in the right screen and the following prompt is issued:

	Position RIGHT cursor>

The user may then position the right cursor to center it over the feature.
When the user is satisfied that the cursor has been properly centered,
he responds by entering (CR).  The program then performs an area correlation
to refine the position of the right feature (See PARAMS COMMAND to modify
the correlation parameters).  The resulting position is then reported:

	        (L2,S2)=( 673.34, 124.32)  (LAT2,LON2)=( 25.23,247.31)

The tiepoint is then stored and the program returns with the NAV> prompt.

The tiepoint acquisition cycle may be aborted at any time by entering
'EXIT.  If, for example, the selected feature is not visible in the right
screen, the user should exit the cycle to re-position the right window.
If a tiepoint is accidentally acquired, it may be deleted via the
DELETE command.

Initially, the program may fail badly in predicting the position of the
feature in the right image.  This is because the nominal pointing may
be very inaccurate.  The program periodically updates the camera pointing
of the left image, based upon the tiepoints acquired up to that point.

GENERAL COMMENTS

The general rules regarding TAE parameters apply:

Commands may be abbreviated, as long as enough letters are typed
to insure uniqueness.

When a command is not followed by a value, it must be preceded
by an apostrophe, e.g. 'EDIT.  The exception is that if the first
keyword in a list is entered, the apostrophe may be ommitted,
e.g:
	Enter LEFT or RIGHT> L

If you need help or want to get out of a routine, try typing
HELP or EXIT.  Sometimes it works, sometimes it doesn't....

GEOMETRIC CAMERA DISTORTIONS:

NAV2 assumes that the input images (primary and reference) have been acquired
via a camera system with a shutter and focal plane (e.g. vidicon/CCD sensor),
so that the images are perspective projections of the target body.  The input
images may be raw images containing geometric camera distortions (image-space
frames), or images which have been geometrically corrected (object-space
frames).

NAV2 corrects for Galileo or Cassini camera distortions using a built-in radial
distortion model.

If a Voyager image-space frame is used, then the reseau locations must first
be located and stored into a reseau location file (see RES parameter):

  	RESLOC  (PIC,RFILE)
	RESLOC  (REF,RFILE)
	NAV2  (PIC,REF)  OUT=TPT  RES=RFILE

In this case, both PIC and REF are image-space frames (It is possible for one
or both images to be object-space).  The reseaux are located using RESLOC
and stored in the Reseau Location File.   NAV2 then retrieves the reseau
locations from the file (see RES parameter).

If the RES parameter is not specified, the program automatically accesses the
file for the planet-of-encounter as follows:

		VGR:[CCA314.VGR]RESJ.FIL	(Jupiter)
		VGR:[CCA314.VGR]RESS.FIL	(Saturn)
		VGR:[CCA314.VGR]RESU.FIL	(Uranus)
		VGR:[CCA314.VGR]RESN.FIL	(Neptune)

Note that the RES parameter is not required for object-space frames.

ACCESSING SPICE DATA

NAV2 will retrieve the projection geometry for both images by accessing the
MIPS SPICE server.  Data is retrieved from the server by target name,
spacecraft ID, camera ID, and Spacecraft-Event-Time.  These image identifiers
are usually determined by scanning the image label.  Note, however, that the
Voyager flight label does not include the target name.  Therefore, the target
parameter must be included when running NAV2 on Voyager images.

The following parameters may also be used to control the access of SPICE data:

  SPICEMODE specifies whether SPICE data is retrieved from LOCAL kernels or
  or via the REMOTE SPICE server.  If defaulted, SPICEMODE is set to the value
  of the environmental variable DEFAULTSPICE.

  CKNAME and CKID are alternative ways to specify the C kernel to be used.  For
  example, CKNAME=FARE or CKID=M904 specifies that MIPS_FARENC.CK is to be used.
  When specified, the CKID parameter overrides the CKNAME parameter.  If the
  camera pointing data is not found in the requested C kernel, the other C 
  kernels are searched.

Within a given C kernel, there may be a number of different versions of camera
pointing for a given image.  The segment identifier for each version contains
provenance information identifying the creator of the pointing data.  One or
more of the following parameters may be used to retrieve a specific 
instance of camera pointing based upon this provenance information:

  CDATE specifies the date and time the camera pointing was created.
  REQNUM identifies the request number associated with the camera pointing.
  PURPOSE identifies the purpose for creating the camera pointing.
  PROGRAM identifies the program which created the camera pointing.
  SPKID identifies the SP-kernel used to create the camera pointing.
  USERID identifies the user who created the camera pointing.
  GROUPID identifies the group which created the camera pointing.
  INSTITUTE identifies the facility which created the camera pointing.

  A complete list of CK and SPK IDs are located in the ASCII file assigned the
  logical name (or environmental variable) KERNELDB.

TIEPOINT FILE FORMAT

The tiepoints are written to an IBIS interface (tabular) file with one
row for each tiepoint.  The following column format is used:

     Column       Description			   Format

        1     First input matching line            real*4
        2     First input matching sample          real*4
        3     Second input line                    real*4
        4     Second input sample                  real*4
	5     First input estimated line           real*4
	6     First input estimated sample         real*4
        7     First input Z value                  real*4
        8     Second input Z value                 real*4
        9     Correlation value                    real*4
       10     Sequence number                      real*4

The estimated (line,sample) coordinates of the left image are computed
using the camera pointing information retrieved from the SEDR (prior to
any updates by the program).  The Z values are obtained by averaging
the DN values over an area centered on the tiepoint (see ZWIND and
ZREJECT parameters).  The correlation value is a number between -1 and
+1, where +1 represents perfect positive correlation and -1 represents
perfect negative correlation.  The sequence number is 1 for the first
tiepoint, 2 for the second, etc.

HISTORY

Original Programmer: Gary Yagi, 1 November, 1986
Current Cognizant Programmer: Gary Yagi
Revisions:
 1988-09-23 GMY * Modify for new VRDI interface, multiple versions of camera
		  pointing in SEDR.
		* Implement 1024x1024 display capability.
		* Add code to support systems with only one video plane.
		* Implement capability to process image-space frames.
		* Change tiepoint file format to IBIS interface file.
		* Add independent stretches for left and right images.
		* Implement compensation for atmospheric feature motion.
		* Add Jupiter zonal-velocity profile.
		* Fix FRs 35652 and 37254.
		* Numerous other modifications and minor bug fixes.
 1990-07-28 GMY * Galileo conversion
 1991-08-21 GMY * Fix FRs 66566, 61146.
 1997-05-07 SMC Port to Unix and Alpha
                 * Switch the image memory plane (IMP) of image and tiepoint,
                   so the image can be properly displayed on 8-bit device.
                 * Upgrade all CONVISOS calls to take camera_id parameter.
                 * Replace all implicit declaration with explicit ones.
                 * distinguish between REAL*8 and REAL*4, the old VMS was able
                   to operate between the two types interchangablly, but the
                   new OS has problems with it.
                 * Upgraded to GETSPICE2 and PUTSPICE2
                 * Convert the S/C ID and Planet ID of the VGR SPICE/SEDR
                   buffer to that of the GLL's so that PBNAME and PUTSPICE2
                   can operate and terminate correctly
                 * Replaced the xdglconstant call with xdglinit so that the
                   graphic plane can be displayed accross all kinds of devices
                   and that colors can be used.
                 * Modified maplabel.f/zonal routine to use Binary Searching
                   algorithm to find the proper record.  The previous routine
                   had a problem of going into infinite loop.
 2001-10-10 GMY Fix Linux compile errors (NAV2_LINUX)
                Modify to handle Cassini and VGR image space.
		Add Cassini and VGR image space test cases to unit test.
 2016-02-18 WLB Added enable/disable-log to tstnav2.pdf

PARAMETERS: