Help for PTP

PURPOSE

PTP is a VICAR applications program which projects an image of a planet or
satellite so that the resulting image is that of the planet as seen from a
different perspective.  PTP's primary application is to register color triplets
in cases where the time between frames is large enough that noticeable changes
in perspective occur as a result of planet rotation and spacecraft motion.

EXECUTION:

     PTP  INP=PIC  OUT=OPIC  REF=RPIC
where 
   PIC  is the input image to be projected (byte or halfword), and
   OPIC is the output image
   REF  is the reference image,

PIC may be from any mission for which navigation data is available via the
MIPS SPICE server.  If PIC is from Voyager or an earlier mission, it must be a
geometrically corrected image.  If PIC is from Galileo or a later mission, it
must be a raw (uncorrected) image.  OPIC will be output in the same data format
as PIC.

In cases where the reference image is not available, it may be replaced by
supplying the program with enough information to identify it to the SPICE
server:

   PTP  INP=PIC  OUT=OPIC  RSCET=(yr,day,month,hr,min,sec,msec)            RCAM=n  TARGET=aaaaaaa
where
   RSCET is the SpaceCraft Event Time of the reference image,
   RCAM is the camera serial number of the reference image, and
   TARGET is the target name.

Note that the input and reference images may be from different missions.  I.e.,
it is possible to project a Cassini image to the same scale and orientation as
a Voyager image (for comparison).

OPERATION

Before running PTP, the input and reference images should be navigated to
correct the camera pointing (see programs NAV, NAV2, FARENC, MANMATCH,
and AUTOMATCH).

PTP reads the VICAR labels of the input and reference images (see INP and REF
parameters) to identify the project, camera ID, target ID, and Spacecraft-Event
Time.  Note that the target is not available in the Voyager label and must be
supplied via the TARGET parameter.

PTP retrieves the navigation data for the input and reference images from the
MIPS SPICE server using SCET, camera, and target to access the appropriate data.
If the reference image is not available, it may be replaced by identifying it
via the RSCET, RCAM, and TARGET parameters.

The camera pointing retrieved from SPICE may be overridden by supplying the
planet center via the PC and RPC parameters.

PTP uses a triaxial ellipsoid model of the planet, defined by three radii
(equatorial long axis, equatorial short axis, and polar).  The values are
obtained via a call to subroutine PBDATA.  This may be overridden by using the
RADII parameter.

The ROT parameter may be used to change the rotation rate or the planet.

GENERATING THE OUTPUT PROJECTION:

PTP projects the image by performing a geometric transformation similar to that
in MAP3.  If the keyword EXACT is specified, the projection is computed exactly
at every pixel.  Otherwise, the projection is calculated on a grid of tiepoints,
and bilinear interpolation is used to compute the projection at intermediate
points.

The initial grid spacing is 32 x 32 pixels.  In areas of the image where this
interpolation generates errors larger than 1/2 pixel (e.g. near the limb), the
grid spacing is reduced in successive steps (16x16, 8x8, 4x4) until a 1/2 pixel
accuracy is achieved.

In general, an output pixel will not project onto an input pixel, but will
project to a point between four input pixels.  The output sample value is
computed via bilinear interpolation over the these four pixels:

        DN = DN1 + (DN2-DN1)*ds + (DN1-DN2-DN3+DN4)*dl

If the 'INCLUDE keyword is specified, all output pixels not on the planet are
generated by offsetting the sky background of the input image by a constant
(the difference between the planet centers).  No perspective geometry is used,
and the planet ring system is treated as though no rotation has occured.
Also, there will be areas of the planet visible from the perspective of the
output image but not visible in the input image (e.g. the area may have rotated
behind the planet).  These areas are generated by using the corresponding
points in front of the planet.  Note that this is a "cludgy" solution.
Beware of odd side effects if the rotation is large.

If INCLUDE is not specified, the sky background is deleted (output
as 0 dn's).

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 (only CKNAME is applicable for Voyager):

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.

EXAMPLES

   (1)  PTP INP=1550856.IMG  OUT=OUT.IMG REF=1550854.IMG TARGET=GANYMEDE

        The input image (1550856.IMG) is projected to the same perspective as
        the reference image (1550854.IMG).  The output image is OUT.IMG.
        Since these are Voyager images, the target must be specified.

   (2)  PTP INP=1550856.IMG OUT=OUT.IMG RSCET=(1996,223,14,59,58,123)              RCAM=2  TARGET=GANYMEDE

        In lieu of the REF parameter, the reference image is identified by
        time (RSCET) and camera ID.

   (3)  ptp INP=n1354897340.1  OUT=cassini.img  REF=f1634146.img TARGET=JUPITER

	The input is a Cassini image of Jupiter while the reference image is
	a Voyager image taken at approximately the same longitude.  Since the
	reference image is in object space, the output image will be in object
	space, even though the input image is in image space.

PROGRAM HISTORY

ORIGINAL PROGRAMMER: Gary Yagi, January 4, 1986
CURRENT COGNIZANT PROGRAMMER: Gary Yagi
REVISION:
 29 Dec 11  LWK  Added call to init_spice, which is required for the new PBDATA.
 27 Feb 03  GMY  Upgraded to support Cassini.  Updated to reference SPICE
		 instead of SEDR for Voyager.  Delete RFRAME parameter.
		 Fix bug introduced in Y2000 date checking by initializing
		 ERT in label buffer.  Add RMISSION parameter.  Fix time
		 calculation in GET_TIME.
		 Use tri-axial ellipsoid model (replace RADIUS, RE,RP paramters
		 by RADII parameter.
 29 Jul 02  LWK  AR-AR-107379.  Cleaned up help text; also replaced SEARCV3
		 call (obsolete) with MP and SEARC_DISTOR.
 18 May 98  RRP  AR-9064. The icam2 check should be for camera number 1 and
                 2 and not 0 and 1.
 08 Aug 97  RRP  Added support for input image being Summastion Mode and
                 Reference being Full frame or vise-versa. (FR 89270)
 08 Oct 96  GMY  Implemented Flagstaff tiepoint algorithm (dynamically adjust-
                 able grid spacing).  Added SSI geometric correction (FR 89818)
 27 Aug 96  SMC  ...Added Support for GLL Summation Mode processing (DFR)
 10 Jul 96  SMC  ...Added old parameters RSCET, RFRAME, RCAM back in, use
                    TARGET to replace PLANET, CKNAME to replace SEDRSRC
 10 Jun 96  SMC  ...Consolidated Voyager processing method to be same as that
                    of the Gailileo's, so both will call getspice2.  At this
                    stage, getspice2 will call getspice if it detects Voyager
                    images.  Took out parameters RSCET, RFRAME, RCAM, PLANET,
                    SEDRSRC
 24 May 96  SMC  ...Added REMOTE Spice function for Gailileo image processing
 23 Aug 95  NDR  ...Ported to Unix
 1  Jun 90  JJL  ...Converted to GLL
 1  Jan 91  JJL  ...Halfword arithmetic throughout.
 20 Aug 89  GMY  ...Fix bug in ROT parameter
 17 Aug 89  GMY  ...Add check to insure input is byte image
 20 Jan 86  GMY  ...Add PLANET & ROT parameters
 16 May 88  GMY  ...Incorporate 'SEDRSRC keyword
 26 Jul 89  GMY  ...Make PC and RPC parameters optional
 04 Jan 86  GMY  ...Original Program.

PARAMETERS: