Help for PERSLAB

PURPOSE:
Places a perspective map projection label onto an object space image.
In general this is not desired for flight projects because the image
navigation is contained in the SEDR/SPICE data base and is subject
to change. For Space Telescope and other imagery there is no spice 
so this provides an alternative. Many programs will honor this label
and not request spice information.

USAGE & EXECUTION:
perslab inp=(in1,in2,...inn) out=in1_modified parameters

for example:

FOR SPACE TELESCOPE AND OTHER NON FLIGHT PROJECTS:
The input files in2,in3... contain ascii header info which contains
navigation information from which spice can be requested to compute
complete navigation. If these ascii files are missing then the spice
cannot be called and the user must supply all the parameters himself.
For the following example perslab first puts into the label 
everything it knows.
Then Farenc creates a file called farenc.pos containing the planet center.
Then perslab reads the farenc file and adds this to the label.
Both perslab calls are identical.

TEST FOR WFPC1
vfits2 inp=a_fits_image  out=w.half
perslab inp=(w.half,w.hdr,w.dat) out=x.img
farenc inp=x.img area=(60,60,680,680)
perslab inp=(w.half,w.hdr,w.dat) out=x.img

TEST FOR WFPC2
vfits2 inp=a_fits_image  out=w.real
flot inp=w.real out=f.real 'vert
astrtchr inp=f.real out=f.byte percent=2.
perslab inp=(f.byte) out=x.img
farenc inp=x.img area=(60,60,680,680)
perslab inp=(f.real) out=x.img

TEST FOR WFPC2 where no labels exist but the camera and time are known.
vfits2 inp=a_fits_image  out=w.real
flot inp=w.real out=f.real 'vert
astrtchr inp=f.real out=f.byte percent=2.
perslab inp=(f.byte) out=x.img project=WFPC2 camera=2   juldate=(1994,196,11,33,2) planet=jupiter north=313.3   project=WFPC2 camera=2
farenc inp=x.img area=(60,60,680,680)
perslab inp=(f.real) out=x.img project=WFPC2 camera=2   juldate=(1994,196,11,33,2) planet=jupiter north=313.3   project=WFPC2 camera=2

OVERRIDING ALL PARAMETERS
perslab inp=something out=x.img    planet=jupiter sclat=45.    sclon=234. sunlat=.5 sunlon=99. centline=456 centsamp=66    range=987654. north=2. focal=1400. scale=65. oaline=300.    oasamp=301. datetime=(92,350,14,14,17)

 VOYAGER TEST
perslab inp=mipl:[mipl.vgr]f1636832.fic out=x.img source=FARE

 GALILEO TEST
perslab inp=mipl:[mipl.gll]venus.img out=x.img

You now can run other programs as below:

 TEST OF PHOTFUNC
photfunc inp=x.img out=v2$scratch:c.img minn=.7 maxcor=5.

 TEST OF MAP3
Uses a zonal flow model and a reference time one day later. Note that
perslab stores the space telescope date in the label for retrieval.
map3 inp=x.img out=v2$scratch:p.img 'orth north=0     scale=200 reftime=(92,351,14,14,17,0)

NEW FEATURES SINCE LAST DELIVERY

Version (January 22, 1997):
* The program now informs the user that it's making 90-degree adjustment to the
NORTH_ANGLE when processing data of project GLL, VGR-1, VGR-2 or CASSI.  The
actual adjustment was actually made on 7/15/96, but it seems nice to let the
user  know.

OPERATION:
Perslab reads the input label and any additional input ascii files for
information about image navigation.

For flight projects it reads the sedr/spice files.

For WFPC it looks for specific label entries and computes the rest
using the NAIF spice subroutines.

SPICE and SEDR PARAMETERS

All of the following parameters except TARGET are for SPICE and SEDR operation 
only.  These SPICE parameters will only affect the GLL and VGR processing.

TARGET
SPICEMODE
CKNAME
CKID
USERID
GROUPID
INSTITUTE
CDATE
REQNUM
PURPOSE
PROGRAM
SPKID 

SPICE Operations
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.

FOR USERS OF PREVIOUS VERSION OF PERSLAB

Parameter PLANET is replaced by TARGET; SOURCE by CKNAME in order to eliminate 
the duplication with getspice2's parameters

HISTORY:
08-28-02 VRH  Have 90 added to NORTH_ANGLE for CASSI also. AR107373
02-14-97 SMC  Terminated all necessary XV* calls & Free MP buffer        FR89945
01-22-97 SMC  * "Normalize" MP_LABEL's NORTH_ANGLE to fall within 0-359. FR89954
              * Insert correct value to MP_LABEL's A_AXIS_RADIUS         FR89954
07-16-96 SMC  Added SPICE parameters, replace parameter PLANET by TARGET;
              SOURCE by CKNAME
07-16-96 SMC  use XVPARM to obtain parameter NORTH instead of XVPARMD
07-15-96 SMC  Corrected the NORTH_ANGLE for GLL and VGRs by adding 90 to it.
07-13-96 SMC  Convert Planet ID to that of GLL's when processing VGR, FR89379
              Open INP file as READ instead of WRITE.

8-15-93  J Lorre. 
COGNIZANT PROGRAMMER:  Jean Lorre