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:
INP
Input image.
OUT
Output image.
SIZE
Standard VICAR size field.
SL
Starting line
SS
Starting sample
NL
Number of lines
NS
Number of samples
MISSION
mission override or if
no input
LIMITS
(lat,lon) region to grid
minlat,maxlat,minlon,maxlon
AUTO
Automatically determines
lat,lon limits of image.
DLA1
The spacing of latitude lines
equatorward of SUPPRESS (deg)
DLA2
The spacing of latitude lines
poleward of SUPPRESS (deg)
DLO1
The spacing of longitude lines
equatorward of SUPPRESS (deg)
DLO2
The spacing of longitude lines
poleward of SUPPRESS (deg)
SUPPRESS
Latitude above which DLO2 and
DLA2 values are used.
GLATITUD
Specifies latitude lines.
GLONGITU
Specifies longitude lines.
PRINT
Prints out grid intersections
(beware--massive printout)
DN
VALID=WHITE,BLACK
WHITE: Grid lines will be MAXDN
BLACK: Grid lines will be zero DN
ALTERNAT
Alternates Dn value of grid
between black and white.
MAXDN
Maximum DN value of
output image.
SCALEBAR
Adds kilometer per pixel
scale bar to output file
NONUMBER
Suppresses labeling of
grid intersections (with
lat-lon coordinates).
EAST
Longitude numbers on output
image will be EAST-longitude
EXPAND
Magnifies grid annotation
by integer factor
DLATITUD
DLAT=n causes every nth
intersection along latitude
lines to be labeled.
DLONGITU
DLON=n causes every nth
intersection along longitude
lines to be labeled.
NOGRID
Suppress lat/long grid
(must specify LIMB or
TERMINAT)
LIMB
draw planet limb?
LSPACE
spacing of limb points
TSPACE
spacing of terminator
points
DNLIMB
DN for limb points
TERMINAT
draw terminator?
DNTERM
DN for terminator points
SUBSOL
Subsolar lat/long (for
Terminator)
LAT_TYPE
Planetographic/centric lat's?
TARGET
Optional 12-char string
Target name (planet,
satellite, or asteroid)
SPICEMODE
Optional keyword
Location of SPICE kernels
(LOCAL or REMOTE)
CKNAME
Optional 4-char string
C-kernel name
CKID
Optional 4-char string
C-kernel ID
USERID
Optional 3-char string
User who created camera pointing
GROUPID
Optional 3-char string
Group which created camera pointing
INSTITUTE
Optional 4-char string
Facility which created camera pointing
PURPOSE
Optional 4-char string
Purpose for camera pointing
PROGRAM
Optional 6-char string
Program which created camera pointing
SPKID
Optional 4-char string
SP kernel for created camera pointing
REQNUM
Optional 4-char string
IPL request number for created camera pointing
CDATE
Optional 12-char string
Date and time camera pointing was created
See Examples:
Cognizant Programmer: