Help for OVERLAY

PURPOSE:

OVERLAY is a VICAR program which superimposes a latitude-longitude grid 
on a planetary image.  If the image is a perspective one ("object space"), 
then the option also exists to draw a limb and/or terminator.  The target
body is assumed to be a sphere or oblate-spheroid, as determined by its 
polar and equatorial radii.

    OVERLAY INP=PIC OUT=OPIC user-parameters

were PIC is an optional input image and OPIC is the output image.

PIC must have a standard VICAR map label, as generated by MAP3, PERSLAB,
or project-specific logging programs such as NIMSCMM.

The image must be in either byte or 16-bit integer (halfword) data format.

OPIC will be the same data format as PIC.  If PIC is omitted, then the
latitude-longitude grid will be displayed over a background of 0 DN and
the output data format will be byte.

The grid is normally displayed in west-longitude, planetocentric latitudes.
Note, however, that the grid overlay may be optionally displayed in east-
longitude (see EAST keyword).

If the image is in Perspective projection, then the option exists to draw
the limb or terminator.  In this case, the position of the Sun (specified
as the sub-solar point on the target body) must be available.  This can
either be supplied by the user with the SUBSOL parameter, or else retrieved
from the label if the input image is an unresampled product of one of the
supported set of flight projects.  (See HELP MISSION for a list of the
latter.)

SPECIFYING THE LATITUDE-LONGITUDE GRID:

All latitudes must be planetocentric.  All longitudes must be entered as 
west-longitudes.

The latitude-longitude grid overlay is determined by specifying its limits
(minimum and maximum latitudes and longitudes), latitude and longitude
spacing, and contrast (black, white, or modulating grid lines), and the
size and spacing of the grid annotation.  Note that the grid can be turned
off altogether using the 'NOGRID keyword;  in this case, the user must
specifiy either LIMB or TERMINAT (or both), or the program will have
nothing to do and quit.

    (1) Grid limits:  The execution of OVERLAY can be speeded up by limiting
	the calculation of latitude and longitude lines to the region within
	the picture's field-of-view.  These limits may be specified explicitly
	via the LIMITS parameter.  Alternatively, the program can be asked
	to determine these limits automatically via the AUTO keyword.  The
	AUTO keyword should only be used for high-resolution frames, where
	the target-body completely fills the field-of-view.

	LIMITS=(r1,r2,r3,r4) - specifies the minimum latitude, maximum latitude,
			       minimum longitude, and maximum longitude boun-
			       daries of the grid overlay.
	'AUTO		     - determine latitude-longitude limits automatically

    (2) Grid spacing:  The grid spacing along latitude and longitude lines
	is specified via the DLA1, DLO1, DLA2, DLO2 parameters, where DLA1
	and DLO1 specify the spacing near the equator, and  DLA2 and DLO2
	specify the spacing near the poles.  The SUPPRESS parameter specifies
	the latitude boundary between the equatorial and polar regions.  The
	grid spacing (expressed in degrees) is usually increased in the polar
	region to prevent overcrowding of grid lines (the exceptions are the
        polar projections, for which the opposite holds true).  The default
        values for these parameters are only appropriate for image or object
        space full-disk (far-encounter) images.

	Alternatively, the latitude and longitude lines may be specified
	explicitly via the GLATITUD and GLONGITU parameters.

	SUPPRESS=r - latitude at which grid spacing switches from r1 to r2
	DLA1=r1	   - latitude spacing btwn grid lines, equatorward of r (deg)
	DLA2=r2    - latitude spacing btwn grid lines, poleward of r (deg)
	DLO1=r1    - longitude spacing btwn grid lines, equatorward of r (deg)
	DLO2=r2	   - longitude spacing btwn grid lines, poleward of r (deg)

	GLATITUD=(r1,r2,r3,...) - draws grid lines along latitudes r1,r2,r3,...
	GLONGITU=(r1,r2,r3,...) - draws grid lines along longitudes r1,r2,r3...
        'PRINT	   - prints grid intersections, etc. (massive printout)

    (3) Grid contrast:  The grid may be drawn in black, white, or data-
	dependent combination of the two, or the grid can ALTERNATe between
	black and white.

	MAXDN=n1     - specifies maximum DN of output
	'dn          - specifies DN of grid.  Valid values are WHITE (DN=n1)
		       and BLACK (DN=0)
	'ALTERNAT    - alternat DN of grid between black and white.

    (4) Grid annotation:

	'NONUMBER	- suppresses all grid annotations.
	'SCALEBAR	- adds scale bar to output image for km per pixel
	'EAST		- annotates grid using east-longitudes.
	EXPAND=n	- specifies scale factor for increasing size of 
			 annotations.
	DLATITUD=n	- annotates every nth grid intersection along latitude 
			 lines.
	DLONGITU=n	- annotates every nth grid intersection along longitude
			 lines.
EXAMPLES:

  1)  OVERLAY  PIC  OPIC  GLAT=(-32.,-20.,-8.,0.,7.,19.,22.,30.) GLON=115.

      The target body is assumed to be Jupiter, and the grid lines have been 
      selected to mark several of Jupiter's belts and zones and the central 
      meridian.

  2)  MAP3  OUT=PIC  NL=1000  NS=1000  'JUPITER  'POLE  'ORTHO  	LINE=1436.0  SAMP=671  LATI=-90.0  LONG=85.877  SCALE=75.0

      OVERLAY  PIC  OPIC DLA1=20  DLA2=10  DLO1=30  DLO2=60   SUPP=80.  	DLAT=3  DLONG=4

      A latitude-longitude grid representing a polar-orthographic projection
      of the south-polar region of Jupiter will be drawn in white, over a
      black background.  Since there is no associated input image, the pro-
      jection information must be input manually to MAP3 in a preceding step.

      Between latitudes -80 and the equator, the latitude lines are spaced
      20 degrees apart (centered on the equator), and the longitude lines are
      spaced 30 degrees apart.  Poleward of -80 degrees, there will be no
      latitude lines and the longitude lines will be 60 degrees apart.

      The numbers denoting lat-long line intersections will be at every third
      latitude and every fourth longitude intersection.
PARAMETERS FOR RETRIEVING CAMERA POINTING FROM SPICE:

The following parameters permit the user to retrieve a specific instance of
camera pointing from the SPICE kernels:

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.

The above parameters are optional, and if defaulted (or if no data is found for
the requested version), the program will attempt to locate the "best" data
available for the given image.  See the level 2 help (via the TAE tutor mode)
for further details.

Examples:  'LOCAL CKNAME=NAIF specifies that SPICE data be retrieved from
          local kernels using camera pointing from predicts or AACS telemetry.

           'REMOTE CKNAME=FARE INSTITUTE=MIPS SPKID=N015 USERID=ADC retrieves
          the camera pointing created by Amy Culver at MIPS using the SP kernel
          GLL_LONG_2.BSP from file MIPS_FARENC.CK via the SPICE server.  (whew!)

It takes longer to search for SPICE data on the basis of provenance
information.  If all provenance parameters are specified, for example, the
program first searches through all the C kernels for an exact match.  If no
match is found, the search is relaxed by removing the CDATE criteria.  If no
match is found, the REQNUM criteria is removed.  Etc.

PROGRAM HISTORY

WRITTEN BY: JOEL MOSHER,   27 MARCH 1984
COGNIZANT PROGRAMMER: Gary Yagi
REVISIONS:
 FEB 23 84  JAM   Original OVERLAY created by modifying PHOTFUNC.
 MAR  2 84  JAM   Add no input picture option.
 MAR  7 84  JAM   Fixed errors in longitude lines removed redundant grid points
 MAR  8 84  JAM   Calculate points to put lat-lon numbers
 MAR 14 84  JAM   Added MODULATE, LINC, and SINC keywords.
 OCT 27 85  JAM   Convert to VICAR2
 MAR  1 86  JAM   Fixed error in no input mode, added MAPLAB
 MAR 10 86  JAM   Added FIXRECT
 MAY 17 86  JAM   Added GLAT,GLON, rewrote point & number selection algorithms.
 MAY 27 87  JAM   VICAR2 parameter processing.
 MAR 11 88  GMY   Major code reorganization and clean-up:
		    0) Rewrote Help File.
		    1) Modularized algorithms.
		    2) Fixed size field implementation.
		    3) Fixed TARGET parameter.
		    4) Fixed calculation of OM from C and ME.
		    5) Fixed extraction of subspacecraft point from SEDR.
		    6) Fixed extraction of radii from SEDR.
		    7) Removed all redundant parameters.
		    8) Replaced MODULATE algorithm with ALTERNATE algorithm.
		    9) Fixed no input image option.
		   10) Fixed annotation so equation is labeled.
		   11) Fixed spacing of annotation.
		   12) Fixed problem of extra grid line at SUPPRESS latitude.
 JUN 12 88  FFM  Rename parameter SEDR to SFILE.
 MAY 12 88  FFM  Incorporate SEDRSRC keyword.
 JUN 07 88  GMY  Fix processing of SIZE parameter.
 Jan 22 89  GMY  FRs 37250,37251,37298,42709,42701.
 Jul 19 89  MEM  Instead of drawing annotation at each intersection,
		        merely draw it once for every grid line.
 Jul 27 89  MEM  When the picture scale is specified, draw a scale bar
			in the lower left-hand corner.
 DEC    90  JJL  Conversion to project independent routines.
 Mar 30 92  JFM  Corrected handling of FINDLAT capture of constant latitudal
                 grid lines for Lambert Conformal Conic and Sinusoidal
		 projections near the poles, where projected image does not
		 file the image file (FR 66586).
 Apr 02 92  JFM  Scale in lower-left corner of output made optional (FR 66545).
 Apr 17 92  JFM  Longitude and latitude annotation placements check against
		 boundaries of image (FR 66549).
 May 26 92  JFM  SFILE parameter removed; HELP file slightly revised;
		 RADIUS, REQUATOR, RPOLE limits removed; Error in no input
	  	 image grid computation corrected (FR 68870, 75745, 76934).
 mar 93     jjl  Removed SFILE parameter
 feb    93  jjl  Added transverse mercator and perspective projections.
 OCT    94  LWK  Added LIMB/TERMINATOR options
 MAR    95  LWK  Made program portable.  Removed all SPICE/SEDR and label-
		processing code (except as needed to determine subsolar point),
		require input image to have map label.
 JUL    96  OAM  Modified to call getspice2 instead of getspice.
                 Included provenance parameters in overlay.pdf.
 jun 98  lwk  added code to get subsolar lat/lon from nims label;  fixed 
	calculation of terminator points:  allow for sections where limb is 
	out of image but terminator is in it;  added code to LIMBPT to stop 
	searching for point at suitable distance once the N.pole is reached 
	-- program was in an infinite loop here for one case;  non-visible 
	points were being selected for lat's where no limb is visible;  and
	if limb didn't reach to N.pole, terminator stopped too;  replaced 
	FIXRECT by CONVEVR, to ensure that *every* call to CONVEV is followed 
	by a fix-up for Rectangular projection;  added Planetographic option 
	for NIMS (LAT_TYP keyword);  fixed longitude lines so that they are 
	more likely to agree with the the numbers in the annotation and are
	always at integer locations (as long as DLO1/DLO2 are integer!)
 Jun98  RRP  Broke long statements into smaller one to make it compile
	under hp platform. AR-9644
 9oct00 lwk- remove lat_typ dependence for Simp.Cyl.
 Aug 02 GMY - Minor changes to compile on Linux:  Change & to * in subroutine
	calls.  Change all trig calls such as cosd(theta) to cos(theta*dtr)
17dec02 lwk - put in check for infinite loop in FINDLON similar to the
	one in FINDLAT
13feb03 lwk- merged my changes with RRP/GMY/KLEM's

PARAMETERS: