Help for MAP3

PURPOSE
	MAP3 performs the necessary calculations of a rubber-sheet stretch
 on a picture to convert it from a perspective projection (in which 
 latitudes and longitudes are complicated functions of line and sample
 depending on the position and orientation of the camera) to a standard
 cartographic projection (in which longitude and latitude are simpler
 functions of line and sample that are independent of camera viewing
 geometry).  The following projections are currently implemented:
		Mercator
		Lambert Two-Standard Conformal Conic
		Oblique and Polar Orthographic
		Oblique and Polar Stereographic
		Cylindrical (Normal)
		Simple Cylindrical (Rectangular)
                Transverse Mercator
                Oblique Simple Cylindrical.
                Sinusoidal
                Oblique Sinusoidal
                Mollweid
                Perspective 
 EXECUTION
	      map3 INP OUT SIZE PARAMS
    -or-
	      map3 (INP,GEOM) OUT SIZE PARAMS

    SEE Parameter Section for explanation of parameters.

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.

 OPERATION
	MAP3 begins by examining the input picture label to determine if it
contains a map label for a perspective projection.  If so, the program will
not access the SPICE/SEDR and will extract the needed input navigation from
this label.
Then the program checks the label to see if the  frame comes from one of the
standard flights:  Mariner 9, Mariner 10, Viking  Orbiters 1 and 2 Voyager or
Galileo.  If so, and if SPICE/SEDR data is available, camera 
 pointing information and the latitudes and longitudes of the four corners and 
 center of the input frame are read from the SEDR.  Otherwise the parameter 
 list is checked to see if latitude and longitude of the center of the input 
 frame are specified.  The latitudes and longitudes are used only to determine 
 a projection type if the user does not specify one via parameters.  However, 
 the pointing information is vital and must be obtained by MAP3 somehow or it 
 will ABEND.  See VIEWING GEOMETRY PARAMETERS section for details.
	Next, the program mathematically specifies the output projection in
 full.  The required data consists of the projection type and projection-depen-
 dent information such as the center of projection, standard parallels,
 central meridian, angle of north in the output picture, and position in the
 output of the center of projection pole or equator, etc. See Reference (2)
 for a detailed description of which parameters specify which projection.  A
 description of the size and shape of the planet is also required at this
 stage.  MAP3 checks the parameter list for user specifications, then computes
 the remaining parameters (if any) using a set of default algorithms.
	Next, the program checks the parameter list for any user overrides or
 supplements to the camera optical geometry information and viewing geometry
 data.  Then the 'output' picture is spanned by a grid of tiepoints.
 At each point the projection descriptive data determines the latitude and
 longitude which must map there.  The camera optics and viewing geometry data
 are used to compute, from the latitude and longitude, the line and sample of
 the corresponding point in an undistorted (geometrically) input picture.  If
 instructed to do so, MAP3 transforms the undistorted input line and sample
 to a distorted (image space) line and sample.  The result of this process is a
 set of points in the output picture for which the corresponding input
 points are known, whether or not the input frame has been geometrically
 corrected.  Map3 then performs the GEOM operation on the input image to
 form the output image.
        The geom operation is performed upon each grid square independently.
 The operation depends upon the number of vertices of the square which
 fall on the planet:
 1. No vertices on the planet:
	The output is set to zero for this square.
 2. All 4 vertices are on the planet:
	The output is interpolated from the input using a polynomial model to
	map from output to input of the form:
       		line_in=c1*L+c2*s+c3*L*s+c4
       		samp_in=k1*L+k2*s+k3*L*s+k4
 3. One to three vertices are on the planet:
	Compute the exact transformation to map output to input.

 PARAMETERS
	MAP3 is designed to be easy to use, at least for standard flight
 pictures.  But it is also a flexible program performing a complex task.  It
 needs a large amount of auxiliary information concerning planet size and
 shape, camera optics, viewing geometry, and a precise specification of the
 projection desired.  For standard flights, the planetary data and camera
 specifications are built into MAP3.  SEDR's are usually available to provide
 viewing geometry parameters, and the projection description parameters may
 always be defaulted.  But to provide sufficient program flexibility to
 handle non-standard flight pictures, bad or missing SEDR's, and mosaicking
 capability, a very large number of parameters are available.
	Each of the following sections describes some subset of the parameters,
 grouped according to function.  Each section is preceded by an explanatory
 introduction.  The following conventions are observed.  Within each section
 numerical parameters are numbered consecutively.  Parameters required to be
 integers begin with N; floating point parameters begin with R. NOTE:  
ALL LATITUDES ARE  GEOCENTRIC; ALL LONGITUDES ARE WEST.  ALL PARAMETERS ARE
EXPLAINED IN DETAIL  IN THE PARAMS SECTION. 

 FLIGHT RELATED PARAMETERS
	MAP3 normally determines the flight from the picture label. It
 recognizes Mariner 9, Mariner 10, Viking Orbiter, Voyager and Galileo labels.
 If the label is bad or missing, the following parameters can be used to
 specify the flight.
 
          MM71  MVM73  VI76  VGR1  VGR2  GLL  noprojec
 
 If the picture label is not from one of the standard flights and these
 parameters are defaulted, a non-standard flight is assumed, requiring the
 user to enter all necessary information through the parameter list.
                   DAS         FDS          FSC
 PLANET DESCRIPTIVE PARAMETERS
	MAP3 must know the radii of the target body being projected.  In the
 case of Voyager, these are normally obtained from the SEDR.  For other
 flights, or to override the Voyager SEDR values, the following keywords can
 be used.
                    RADII        TARGET         LORA
 CAMERA DESCRIPTIVE PARAMETERS
	This group defines the camera optical system.  All can be defaulted
 for standard flights because correct values are built into MAP3.
 These should be specified (unless there is a default) if NOPROJEC is specified.
     CSCALE     FOCL     CLINE     CSAMP     CAMERA
     DISTOR     IMAGE    OBJECT

 VIEWING GEOMETRY PARAMETERS
	The camera viewing geometry is specified by a vector and rotation
 matrix.  The vector, called the RS vector, is the vector from the center of
 the planet to the spacecraft, specified in the planet coordinate system.  The
 matrix, called OM, rotates vectors from the planet coordinate system to the
 camera system.  Reference (3) contains a complete description of how camera
 optics data, planetary radii, and the RS vector and OM matrix allow a line
 and sample to be computed from a latitude and longitude.
	MAP3 can obtain RS and OM in several different ways.  They can be
 specified in the parameter list or computed by one of four different
 algorithms.  In addition, they can be obtained from the SPICE/SEDR for some 
 Voyager and for Galileo frames.
  The following sections describe these various methods.
     1.  Direct Specification by the User
         Parameters in this subsection can be used by themselves to
         completely specify RS and OM.  Or they can be used individually to
         override specific SEDR entries or to supply necessary information
         needed by the algorithms described in later subsections.
         CMATRIX     MEMATRIX     OMMATRIX      VRVECTOR     RSVECTOR     
                 SLAT         SLON          RMAG
     2. Default Algorithm
        In this algorithm (the default), the RS vector is computed from
        the ME matrix and the VR vector.  The OM matrix is computed from
        the C and ME matrices.  This algorithm is considered inferior
        because the camera pointing information in the C matrix usually
        does not have very great accuracy.  The C matrix and the VR vector
        are normally obtained from the SEDR.  The ME matrix is usually
        obtained from the SEDR also, except for Mariner 9, whose SEDR does
	not contain an ME matrix.  If an ME matrix is not obtained from the
	SEDR or parameter list, MAP3 will attempt to calculate it using
	built-in ephemeris data.  This is possible only for the five inner
	planets and the moon.  The following parameters can be used to
	override data used to calculate the ME matrix.
		TIME          RTAS          DECLINAT(Declination)
     3. QUAM Algorithm
	If the RS vector is known, the OM matrix can be computed from
	another vector, called RRP5, and the angle of north in the image
	plane, using an algorithm developed by Lynn Quam.  The RRP5 vector
	is the vector, in the planet coordinate system, from the planet
	center to the intersection of the camera's optical axis and the
	planet's surface (in other words to the point in the center of the
	input frame).
	      QUAM         CLAT        CLON        NORA
     4. FAR ENCOUNTER Algorithm
	Given the RS vector and the north angle, the OM matrix can be com-
	puted if the line and sample of the subspacecraft point in the input
	picture are known.  The RS vector is computed from SLAT, SLON, and
	RMAG (see subsection 1).  The algorithm, developed by Denis Elliott,
	is usually applicable only for pictures containing all or most of the
	planet, since only then can the line and sample of the subspacecraft
	point be determined directly from the input image.
		ISSCPT       NORA       OSSCPT
     5. TIEPOINTS Algorithm
	If the latitude and longitude of three or more points at specified
	lines and samples are known, as well as the RS vector, the OM matrix
	may be computed using still another algorithm, developed by Arnie
	Schwartz.  The RS vector is obtained in the same way as for the FAR
	ENCOUNTER algorithm.
			TIEPTS
 PROJECTION DESCRIPTIVE PARAMETERS
	The parameters in this group are used to describe the output
 projection to the program.  The projection type, scale, and position of the
 input frame in the output frame are under user control.  For oblique and
 polar orthographic and stereographic, the orientation of the input in the
 output is also under user control.
	Some of the parameters have slightly different meanings depending on
 the projection type.  So this section will be divided into projection-related
 subsections.  Some parameters will be discussed more than once.
	All parameters in all subgroups are optional.  The default philosophy
 is: "Where applicable, choose a center of projection in the center of the
 input picture.  Center the input in the output.  Where orientation is not
 fixed (Mercator and Lambert always have north at the top), preserve the
 orientation of the input in the output.  Subject to the above restrictions,
 which have priority, scale the output projection so that the input frame
 nearly fills the output frame without loss of data over the edge. Also make
 the scale come out so that it is one of nine standard numbers times a power
 of ten."

     1. Choice of Projection
	The parameters in this subgroup are used to specify the projection
	type.  If the user makes no choice the program decides as follows:
	For Standard flights with the SEDR available, the latitude of the
	center of the input image is obtained from the SEDR.  If the absolute
	value of the latitude is less than 30 degrees, a Mercator projection 
	results.  If it is greater than 65 degrees, a Polar Stereographic
	projection is used.  Otherwise a Lambert Two-Standard Conformal Conic
	is chosen, with standard parallels at 59 degrees.17 and 35 degrees.83
	or -35 degrees.83 and 59 degrees.17, depending on the sign of the 
	latitude.  If no SEDR is available (as for non-standard flight
	pictures) the program checks to see if CLAT was specified (see QUAM
	algorithm subsection).  If so, its value is used in the above test. 
	If not, an Orthographic projection is chosen.
        
        The choices of projection are:

        ORTHOGRA                 Oblique Orthographic
        ORTHOGRA POLE            Polar Orthographic
        STEREOGR                 Oblique Stereographic
        STEREOGR POLE            Polar Stereographic
        LAMBERT                  Lambert Two Standard Conformal Conic
        MERCATOR                 Mercator
        TMERCATO                 Transverse Mercator
        CYLINDRI                 Normal Cylindrical
        RECTANGU                 Simple Cylindrical or Rectangular
        OBCYLIND                 Oblique Simple Cylindrical
        SINUSOID                 Sinusoidal
        OBSINUSO                 Oblique Sinusoidal
        MOLLWEID                 Mollweide
        PERSPECT                 Perspective 

     2. Projection Scaling
	In all map projections, there is at least one point at which the scale
	of the projection equals the scale on the sphere.  The scale at such
	points, in km/pixel, determines the size of the input picture in the
	output area.  For the Mercator projection, scale is correct everywhere
	on the equator.  For the Lambert, it is valid all along both standard
	parallels.  For the Orthographic and Stereographic, it is valid at the
	center of projection.  If no scale is specified, one will be computed
	so that the input picture is as large as possible without loss of
	data.  Then this scale is rounded to one of nine standard values in
	such a way as to make the projection of the input frame slightly
	smaller.
				SCALE

     3. Projection Descriptive Parameters for Mosaicking
	The Mercator projection, for which the LINE, SAMPLE, LATITUDE, and
	LONGITUDE parameters can be used to place any desired point anywhere
	in the output, and the Polar Stereographic and Orthographic, for which
	the default is to center the input picture in the output frame REGARD-
	LESS of the position of the pole, are easy to use to produce large
	scale mosaics with the above parameters.  For such mosaics it is impor-
	tant that the scale, latitude and longitude of special points, meri-
	dians, or parallels, and orientation be constant in all projections.
	Then good results can be obtained by simple translation of the pro-
	jected pictures.  But for the Lambert and Oblique Stereographic and
	Orthographic projections, the previously discussed parameters are
	clumsy to use for mosaicking.  Frequently, the center of projection or
	central meridian is far outside the input frame.  Defaulting LINE and
	SAMPLE then leads to an all zero output frame.  To overcome the
	problem, users were formerly forced to compute line and sample
	parameters using the equations describing their projection.  A new 
	group of parameters, explained below, allows the user to specify an
	approximate line and sample for an arbitrary point unrelated to the
	center of projection or the central meridian.  The program then 
	computes values of the LINE and SAMPLE parameters consistent with the 
	user's specification and acts as if these values were present in the 
	parameter list (see the Lambert subsection for restrictions on the use 
	of the LINE parameters).  Note also that the value of SCALE is required
 	in order to perform the calculations.  For the Lambert case, this means
	that LIN1 and LIN2 may not be used if any of the keywords below are 
	present.
		The group below is collectively called "recentering parameters"
	because the center of projection is repositioned from its normal 
	default location.  The presence of any of the recentering parameters 
	implies the use of repositioning algorithms which, to repeat, have the 
	effect of overriding default values of LINE and SAMPLE.  Therefore, 
	LINE and SAMPLE should not be used if recentering is used.  The LINE 
	and SAMPLE values are computed so that a specified point projects as 
	close as possible to a specified output pixel, subject to the 
	constraint that the center of projection (pole for Lambert) projects 
	to an integral pixel. This restriction ensures that translational 
	offsets for various parts of a mosaic are all integral numbers of 
	pixels.
		PLAT     PLON     PLINE     PSAMPLE     RECENTER

     4. Lambert Projection Parameters
        LINE      The line in the output to which the pole will project.
        SAMPLE    The sample to which the central meridian projects,
                  specified by LONGITUDE.
        SCALE     The scale in km/pixel at the standard parallels.
        PAR1      The latitude in degrees of the northernmost of the two 
		  standard parallels. 
                  Default is 59.17 for northern hemisphere input frames 
		  and -35.83 for southern.  
        PAR2      The southernmost of the two  standard parallels. 
                  Default is 35.83 or -59.17. PAR1 and PAR2 must have the same 
		  sign or the projection is undefined.
        LIN1      The line in the output frame at which the northern standard 
		  parallel's projected arc is to intersect the central 
		  meridian.
        LIN2      The same as LIN1 but refers to the  southern standard 
		  parallel.
        LATITUDE  The projected parallel which will intersect the central 
		  meridian at line NL/2, where NL is obtained from the size 
		  field on the EXEC card.  R3 need not be a standard parallel. 
		  Default is to use the latitude of the center of the input 
		  picture for R3.  This can have unpleasant results (such as a 
		  completely black output picture) if the central meridian does
		  not appear in the output frame (see the mosaicking subsection
		  for ways to avoid this problem). 
        LONGITUD  The longitude, in degrees, to be used as the central
                  meridian.  The default is the longitude of the center of the
                  input picture.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.  It is suggested that you 
		  use this parameter along with PLAT and PLONG !  The line and
		  sample that goes with a certain latitude and longitude can 
		  be specified using PLINE, PSAMP, PLATITUD, PLONGITU. 
		  Otherwise these will default to the center of the output and 
		  the lat/lon in the center of the input image respectively.

        NOTES:
	The scale and vertical placement of the output image can be specified
	in a variety of ways.  Do not attempt to overspecify the projection.
	Further explanation will follow keywords below.
 	  LATITUDE     LONGITUD     SAMPLE     PAR1     PAR2     LIN1
		   LIN2		LINE
	In the Lambert projection, any two of the parameters SCALE, LINE, LIN1,
	and LIN2 are sufficient to specify the other two.  In view of this, 
	MAP3 proceeds as follows:

  	  If three or more of the above are specified, 
		the program ABENDS because it probably cannot satisfy all the 
		demands. The projection has been overspecified.
	  If two are specified, 
		their values are used and the remaining two are computed from 
		them.
	  If any of the line parameters are specified, but neither SCALE nor 
	  the other line parameters are, 
		the value of the specified parameter is used. Then SCALE is 
		computed in the usual default manner. Then the other two line 
		parameters follow.
	  If SCALE is specified but none of the line parameters, 
		the value of the LATITUDE parameter obtained from the parameter
		list or by default is used to compute the values of LINE, LIN1,
 		and LIN2 in a consistent manner.
	  If none of the parameters are specified, 
		SCALE is computed in the usual way and then the program 
		proceeds as if SCALE alone were specified.

	From the above discussion it should be clear that if any of LINE, LIN1,
	or LIN2 appear as parameters, the LATITUDE parameter is ignored.

     5. Mercator projection parameters:
        LINE      The line in the output to which LATITUDE will project.
                  Defaults to 1.0.
        SAMPLE    The sample in the output to which LONGITUDE will project.
                  Defaults to 1.0.
        LATITUDE  The latitude of LINE in the output.
                  Default computes latitude to center input in output.
        LONGITUDE The longitude of SAMPLE in the output.
                  Default computes longitude to center input in output.
        SCALE     The scale in km/pixel at the equator.        
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.  It is suggested that you 
		  use this parameter along with PLAT and PLONG !  The line and 
		  sample that goes with a certain latitude and longitude can 
		  be specified using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise 
		  these will default to the center of the output and the 
		  lat/lon in the center of the input image respectively.

     6. Cylindrical projection parameters:
        LINE      The line in the output to which LATITUDE will project.
                  Defaults to 1.0.
        SAMPLE    The sample in the output to which LONGITUDE will project.
                  Defaults to 1.0.
        LATITUDE  The latitude of LINE in the output.
                  Default computes latitude to center input in output.
        LONGITUDE The longitude of SAMPLE in the output.
                  Default computes longitude to center input in output.
        SCALE     The scale in km/pixel at the equator.        
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

     7. Simple Cylindrical (rectangular) projection parameters:
        LINE      The line in the output to which LATITUDE will project to.
                  Defaults to 1.0
        SAMPLE    The sample in the output to which LONGITUDE will project to.
                  Defaults to 1.0
        LATITUDE  The latitude of LINE in the output.
                  Default computes latitude to center input in output.
        LONGITUDE The longitude of SAMPLE in the output.
                  Default computes longitude to center input in output.
        SCALE     The scale in km/pixel at the equator.        
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

     8. Oblique Stereographic projection parameters.
        LINE      The line of the center of projection in the output.
                  Defaults to nlout/2.
        SAMPLE    The sample of the center of projection in the output.
                  Defaults to nsout/2.
        LATITUDE  The latitude of the center of projection.
                  Defaults to the latitude at the center of the input.
        LONGITUDE The longitude of the center of projection.
                  Defaults to the longitude at the center of the input.
        SCALE     Scale in km/pixel at the center of projection.
        NORTH     Angle of the projected spin axis of the north pole
                  measured in degrees clockwise from up in the output.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

     9. Oblique Orthographic projection parameters.
        LINE      The line of the center of projection in the output.
                  Defaults to nlout/2.
        SAMPLE    The sample of the center of projection in the output.
                  Defaults to nsout/2.
        LATITUDE  The latitude of the center of projection.
                  Defaults to the latitude at the center of the input.
        LONGITUDE The longitude of the center of projection.
                  Defaults to the longitude at the center of the input.
        SCALE     Scale in km/pixel at the center of projection.
        NORTH     Angle of the projected spin axis of the north pole
                  measured in degrees clockwise from up in the output.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

    10. Polar Stereographic projection parameters.
        LINE      The line in the output to which the pole will project. 
                  Defaults to nlout/2.
        SAMPLE    The sample in the output to which the pole will project. 
                  Defaults to nsout/2.
        LATITUDE  If latitude is + or - 90 degrees a 
                  polar projection results 
                  whether or not the parameter POLE is also specified. 
                  If POLE is specified, the sign of the LATITUDE 
                  parameter (if present) determines which pole is used 
                  as the center of projection.
        LONGITUDE The west longitude in degrees of the meridian which
                  will point up from the pole in the output. Default is to 
                  compute lon so that the upper left and upper right corners of
                  the input are projected to the same line in the output. 
                  This algorithm minimizes rotation from input to output 
                  regardless of the location of the pole in either picture.
                  This algorithm will not work if either of the upper corners 
                  of the picture is off the planet. In this case LONGITUD must 
                  be specified. Note that the default calculation of
                  orientation is, in a sense, more powerful for polar than 
                  oblique projections. In the oblique projections the algorithm
                  used minimizes rotation only if the center of projection 
                  lies within the input frame. A superior algorithm is 
                  available for the polar projections because of the many
                  simplifications of the projection equations due to the fact
                  that longitude meridians are all straight lines.
        SCALE     The scale in km/pixel at the center of projection. 
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

    11. Polar Orthographic projection parameters.
        LINE      The line in the output to which the pole will project.
                  Defaults to nlout/2.
        SAMPLE    The sample in the output to which the pole will project. 
                  Defaults to nsout/2.
        LATITUDE  If latitude is + or - 90 degrees a 
                  polar projection results 
                  whether or not the parameter POLE is also specified. 
                  If POLE is specified, the sign of the LATITUDE 
                  parameter (if present) determines which pole is used 
                  as the center of projection.
        LONGITUDE The west longitude in degrees of the meridian which
                  will point up from the pole in the output. Default is to 
                  compute lon so that the upper left and upper right corners of
                  the input are projected to the same line in the output. 
                  This algorithm minimizes rotation from input to output 
                  regardless of the location of the pole in either picture.
                  This algorithm will not work if either of the upper corners 
                  of the picture is off the planet. In this case LONGITUD must 
                  be specified. Note that the default calculation of
                  orientation is, in a sense, more powerful for polar than 
                  oblique projections. In the oblique projections the algorith 
                  used minimizes rotation only if the center of projection 
                  lies within the input frame. A superior algorithm is 
                  available for the polar projections because of the many
                  simplifications of the projection equations due to the fact
                  that longitude meridians are all straight lines.
        SCALE     The scale in km/pixel at the center of projection. 
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

    12. Oblique Simple Cylindrical projection parameters.
        LINE      Line in output to which latitude=0 will project.
                  Defaults to nl/2.
        SAMPLE    Sample in output to which longitude=180 will project.
                  Defaults to ns/2.
        LATITUDE  The new latitude of the position to which the North pole
                  will move in the oblique space.
                  Defaults to +90 degrees.
        LONGITUDE The new longitude of the position to which the North pole
                  will move in the oblique space.
                  Defaults to 0.0.
        PAR1      The new longitude in the oblique space to which
                  LONGITUDE will move.
        SCALE     The scale in km/pixel.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.
        
        Suggestions: Use RECENTER and PLAT,PLONG. If you use RECENT, then
        the program will know where you sent the pole (using LATI,LONG)
        and will assure that the PLAT,PLONG you specified maps to the
        center of the output. For example, if you specified:
                LATI=0 LONG=180 PAR1=180 
        the North pole would rotate to latitude=0 longitude=180.
        If you also specified:
                'RECENT PLAT=90. PLONG=60.
        then you would be assured to see the pole centered in the output
        but projected as though it were really at latitude=0 longitude=180.
    13. Sinusoidal projection parameters.
        LINE      The output line of the latitude specified by LATITUDE.
                  Defaults to the center of the output.
        SAMPLE    The output sample of the reference longitude 
                  specified by LONGITUDE.
                  Defaults to the center of the output.
        LATITUDE  The latitude placed at LINE in the output.
                  Defaults to the center of the input.
        LONGITUDE The REFERENCE longitude for the projection
                  ( that longitude which maps to a vertical line ).
                  Defaults to the center of the input.
        SCALE     The scale in km/pixel at the equator.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

    14. Oblique Sinusoidal projection parameters.
        LINE      Line in output to which latitude=0 will project.
                  Defaults to nl/2.
        SAMPLE    Sample in output to which longitude=180 will project.
                  Defaults to ns/2.
        LATITUDE  The new latitude of the position to which the North pole
                  will move to in the oblique space.
                  Defaults to +90 degrees.
        LONGITUDE The new longitude of the position to which the North pole
                  will move to in the oblique space.
                  Defaults to 0.0.
        PAR1      The new longitude in the oblique space to which
                  LONGITUDE will move.
        SCALE     The scale in km/pixel on the oblique equator.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.
        
        Suggestions: Use RECENTER and PLAT,PLONG. If you use RECENT then
        the program will know where you sent the pole (using LATI,LONG)
        and will assure that the PLAT,PLONG you specified maps to the
        center of the output. For example if you specified:
                LATI=0 LONG=180 PAR1=180 
        the North pole would rotate to latitude=0 longitude=180.
        If you also specified:
                'RECENT PLAT=90. PLONG=60.
        then you would be assured to see the pole centered in the output
        but projected as though it were really at latitude=0 longitude=180.

    15. Mollweide projection parameters.
        LINE      The output line of latitude 0.
                  Defaults to the center of the output.
        SAMPLE    The output sample of the reference longitude 
                  specified by LONGITUDE.
                  Defaults to the center of the output.
        LATITUDE  not used.
        LONGITUDE The REFERENCE longitude for the projection.
                  Will be a vertical line in the output.
                  Defaults to the center of the input.
        SCALE     The scale in km/pixel at latitude 40 deg 44 min N or S.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG !
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

    16. Transverse Mercator projection parameters.
        LINE      The output line of the latitude specified by LATITUDE.
                  Defaults to the center of the output.
        SAMPLE    The output sample of the reference longitude 
                  specified by LONGITUDE.
                  Defaults to the center of the output.
        LATITUDE  The latitude placed at LINE in the output.
                  Defaults to the center of the input.
        LONGITUDE The REFERENCE longitude for the projection
                  ( That longitude which maps to a vertical line ).
                  Defaults to the center of the input.
        SCALE     The scale in km/pixel at central meridian.
        RECENTER  Computes LINE and SAMPLE such that PLATITUD PLONGITU
                  go to that line and sample in the output.
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.

    17. Perspective projection parameters.
        In this projection the user may specify a "new camera" location (and
        even new camera descriptive parameters) to generate an output image
        corresponding to the perspective from the new location.  Changing
        the SCALE (specifying SCALE) changes the distance of the "new camera"
        to the planet.

        LINE      The output line of the center of projection. Is 
		  the line of
                  the new sub-spacecraft point in the output.
                  Defaults to center of output.
        SAMPLE    The output sample of the center of projection. Is 
                  the sample of the new sub-spacecraft point in the output.
                  Defaults to center of output.
        LATITUDE  The new sub-spacecraft point latitude in the output. 
                  Defaults to the input sub-spacecraft latitude.
        LONGITUDE The new sub-spacecraft longitude in the output.
                  Defaults to the input sub-spacecraft longitude.
        NORTH     The angle of the new north spin axis measured clockwise
                  from up in the output.
                  Defaults to the same as the input.
        SCALE     The scale in km/pixel in the output.
                  Defaults to the scale of the input picture.
        RECENTER  Computes LINE and SAMPLE such that the center of the input
                  maps to the center of the output.
                  It is suggested that you use this parameter along with
                  PLAT and PLONG if the field of view is so small that
                  the LATITUDE LONGITUD coordinate does not appear in
                  the input. 
                  The line and sample that goes with a certain latitude
                  and longitude can be specified
                  using PLINE,PSAMP,PLATITUD,PLONGITU. Otherwise these
                  will default to the center of the output and the lat/lon
                  in the center of the input image respectively.
PRECISION:

This portable version of MAP3 will produce basically the same output on
all of the MIPS-supported platforms.  This output will frequently not be
identical to the output of the unported version of MAP3, but the differences
will be trivial and should be improvements.

This section is required by the MSTP SRD for all programs that
do not meet the precision requirements given in the SRD.  The two requirements
not met by MAP3 are:
1) Integer data output by a ported program must be the same as that produced
   by the unported program.
2) Integer data output by a ported program must be the same on all of the
   MIPS-supported platforms.
All of the programs that do geometric transformations are going to have problems
meeting one or both of these requirements.   This includes MAP3, LGEOM, MGEOM,
GEOMA, and several others.  MAP3 was modified to increase the use of
Double Precision floating point arithmetic so that the second requirement is met
"well enough" and the first requirement is met "well enough". 
The definition of the above qouted term is given towards the end of this 
section.

In the port, MAP3 was modified to retain the full precision returned from
subroutine DSIMQ.  This was done to minimize the differences
produced on different platforms.  The results are somewhat more accurate
than those of the unported MAP3, but since the output DN values are rounded
to the nearest integer, the output images are essentially the same as for the
unported MAP3.

In computing the output pixel value (DN), MAP3 first determines if the pixel
lies on the planet.  If it does not, the output pixel value is set to 0.
If the pixel does lie on the (map-projected) planet, MAP3 uses subroutine 
CONVEV to compute the latitude and longitude from the output line and sample
coordinates.  Then it uses subroutine CORCAV to compute (in floating point)
the the input image line and sample coordinates from the latitude and
longitude.  Since the floating point line and sample coordinates generally lie
between the integer line and sample coordinates of four adjacent input pixels,
MAP3 uses bilinear interpolation to compute a pixel value for the floating
point location.  This is the value given to the output pixel. (This is a
simplification, but is adequate for this discussion of precision.) 

The image a2.map3 used in the MAP3 test pdf shows what type of
differences are likely to occur between the ported MAP3 and the unported MAP3.
The output file from the ported MAP3 is very slightly different
from the output file from the unported MAP3.  99.997% of the pixels are
identical.  All but one of the rest differ in value by 1.  The other pixel
differs in value by 129.

The cause of the differences is that the single precision computations
(unported MAP3) round differently than the double precision computations
(ported MAP3).  MAP3 rounds the results to the nearest integer.  Usually the
differences make no difference once the rounding occurs.  Only rarely do the
differences cause rounding up in one case and rounding down in the other, which
causes a difference of 1 in the output value.  In one case, the differences
caused the program to conclude the output pixel did not correspond to
an input pixel in one case but did in the other.  This occurred at the border 
of the non-zero section of the image  (planet limb or terminator.)
These two type of differences combines to produce
a slight but insignificant difference.  This difference is estimated at
less than 1% of the difference between using 'NOINTERP and using regular
interpolation, which is the definition I will use for "well enough".
I believe that such differences will not be humanly observable in an image
display.  

The image a2.map3 used in the MAP3 test pdf shows what type of what type of
differences are likely to occur (with the ported MAP3) between machines. 
The output file from the ported MAP3 on the DEC Alpha is very slightly different
from the output file on the Sun SparcStation.  99.997% of the pixels are
identical.  All but one of the rest differ in value by 1.  The other pixel
differs in value by 7.

In general, the differences between the results for the ported MAP3 on different
machines are comparable to the differences between the ported MAP3 and the
unported MAP3.  Both types of differences are on the order of the expected
rounding in single precision computations.  Although the bilinear interpolation
computation was upgraded to double precision, parts of the CONVEV and CORCAV
computation are in single precision.  
For a 1000 by 1000 byte image from 10 to 1000 slightly different pixels may be
expected.  This assumes matching SPICE data.  If the SPICE data differ 
significantly, the output images will not be comparable.
REFERENCES:

  1) MAP2 User's Guide 900-639, Vol. III (November 1973).
  2) JPL Publication 77-7, "Transformations from an Oblate Spheroid to a
     Plane and Vice Versa", (January 1977).
  3) "Digital Cartographic Projection", Proceedings of the Caltech/JPL
     Conference on Image Processing Technology, Data Sources and Software
     for Commercial and Scientific Applications, (November 1976).
  4) MIPS Map projection Software User's Guide D-11810, Ver. 1.1 (May 1994).

PROGRAM HISTORY:

 WRITTEN BY: A. R. Gillespie and C. A. Rofer     22 June 1972
 MODIFIED BY: Arnie Schwartz, Denis Elliott, Joel Mosher, Jean Lorre,
   Charles Avis, Helen (DeReuda) Mortenson, Florance Moss, John Reimer,
   Dave Glackin, Gary Yagi, Thuy Truong
 CURRENT COGNIZANT PROGRAMMER: Jean Lorre
 REVISION HISTORY:
     Nov 99  lwk  added some checks for silly values of NL, NS, SCALE, RADIUS;
                  added check for PAR1/2 for Lambert;  fixed problem with
                  Julian date ("Y2K" correction was being done twice)
     Nov 97  SP   Restored equation for RMAG_PERS for perspective projection.
                  This had been changed in Jan. 1997 erroneously, causing
                  distorted results, particularly when the new camera location
                  was close to the planet.
     Oct 96  SP   Correct handling of GLL summation mode.  Corrections for
                  handling DNTHRESH parameter and and interpolation.
                  Please note that even when the DNTHRESH parameter is 
                  defaulted, the associated algorithm will occasionally result
                  in minor changes (improvements) because pixels with a DN
                  value of 0 will not be used in the interpolation.  Differences
                  will typically be found where a zero pixel and a non-zero
                  pixel are adjacent.
     Aug 96  OAM  Added DNTHRESH parameter and subroutine setDnValue to
                  handle interpolation. 
     May 96  SP   Added proper initialization of variables.  Modified to
                  use GETSPICE2 and associated PDF parameters.
     Jan 96  SP   Reported to UNIX using many of changes from TLT but using
                  CONVEV instead of MP_XY2LL.  Modified to expect any second
                  input file to be in IBIS tiepoint format.
                  Added call to GLLGCOR to Farenc algorithm for Galileo support.
     AUG 94  TLT  Ported to UNIX (only suppports GLL input, does not support
                  output PERSPECTIVE projection).
                  Replaced CONVEV, TRANV, SEARCV2, MAPLABV2 w/ MP software.
                  Added keyword SPICE_SERVER.
     Sep 93  jjl  Permit space telescope data
     AUG 93  JJL  Permits perspective projection inputs.
     JUN 91  JJL  Extensive cleanup to help, test, added 6 projections.
     DEC 89  JJL  Perform own geom.
     Oct 89  JJL  Converted to project independent.
  29 OCT 89  GMY  Deleted FARENC keyword (invoked via ISSCPT or OSSCPT)
  23 Aug 89  GMY  Delete fiddling with FDS for WA of simultaneous exposure pair
  22 jun 89  jjl  Change flag to 1.0e+15 to fix lgeom artifact
  10 may 88  FFM  Add keyword 'SEDRSRC
  01 mar 88  GMY  Add check for NAV and NAV2 flags in SEDR when one or more
		  tiepoints is off planet.
  10-MAY-88  FFM  INCORPORATE "SEDRSRC" KEYWORD
  22-FEB-87  JAM  INCORPORATED SMT,SXP CHANGES 
                  SMT COMMENTED OUT CALLS TO SEDR73 AND ACOS3
                  SXP CHANGED OACALL TO VOLAB TO VOLABV2
  10-FEB-87  JAM  WARNING IF INPUT IS O.S. AND GEOM FILE INPUT
  28-DEC-86  JAM  INCORPORATE "NOPROJEC" KEYWORD
  23 Feb 86  JAM  FIX DISTAL
  23 Jan 86  JAM  Add 'IMAGE,'OBJECT
   4-JUL-85  JAM  START REORGANIZING PARAMETER PROCESSING
  28-JUN-85  JAM  REPLACE *CAL SUBROUTINES WITH R2LIB:CONVEV
  26-JUN-85  JAM  REPLACE TIECHK WITH R2LIB:TIECHV
  23-JUN-85  JAM  REPLACE FOMCL2 WITH R2LIB:FOMCLV
  23-JUN-85  JAM  REPLACE CORCAL WITH R2LIB:CORCAV
  22-JUN-85  JAM  REPLACE IPPCOR WITH R2LIB:IPPCOV
  15-JUN-85  JAM  CONVERT TO VICAR2
  23 APR 84  HBD  RESTRUCTURED SOME CODE AND DELETED SOME CALLS
                         TO OPEN AND CLOSE
   5 APR 84  HBD  DELETED CALLS TO OPEN BEFORE GLABEL CALLS
  24 MAR 84  JAM  CHANGE CALL TO LABEL FOR RECTANGULAR PROJECTION
  15 DEC 83  CCA  REMOVE IDS;MAKE DSRN 1=PDS (LABELED)
  02 AUG 83  JAM  CONVERT TO VAX
  02 MAY 83  JHR  BUGS
  10 JAN 82  JHR  CODE MODIFICATIONS, SLAT FROM SEDR79
                         CHANGED TO GEOCENTRIC
  12 APR 81  JHR  ADDED SIMPLE CYLINDRICAL PROJECTION
  10 MAR 81  JAM  READ OM MATRIX FROM VGR SEDR
  16 FEB 81  JAM  ALLOW MAP3 TO GET OMMATRIX FROM FARENC
   8 OCT 80  JJL  ADD KEYWORDS:
   8 OCT 80  JJL  OSSCPT,ISSCPT,LORA,GEODET,NAM2,HALF
  19 JUN 80  JAM  ADD VOYAGER FLIGHT INFORMATION
  28 MAY 80  JAM  CHANGE ROUTCO CALLS TO OUTCON
                         MUST INCLUDE OUTCON2 IN LINKEDIT
  25 MAY 80  JAM  PUT IN HALFWORD OPTION
     JAN 79  DLG  ADD VOYAGER MISSION MODULE
  30 AUG 78  DAE  TRIAXIAL SOLID
  03 JAN 77  DAE  USE EXACT EQUATIONS FOR SPHEROIDAL PLANETS
                  REDO DEFAULT NORTH ANGLE COMPUTATION
                  INSTALL RECENTERING OPTION FOR EASIER MOSAICING
  12 MAY 76  DAE  ADD FINAL VI76 CHANGES
  23 APR 76  DAE  RESTRUCTURE LINK EDIT TREE AND DISTOR SECTION
  05 FEB 76  DAE  CONVERT TO OS AND MAKE VO76 A STANDARD MISSION
  27 JUN 75  DAH  CHANGES FOR CONVERSION TO 360/OS
   1 MAR 75  DAE&AAS  VERSION XXX RELOCATABLE, FARENC & TIEPTS MODES
  01 JAN 73  AAS  LAMB.CONF.FIX/LABEL MISCOUNT PROBLEM/MULTPHASING
   SUPERMAP A.R.GILLESPIE
   ALGORITHMIC DEVELOPMENT - J.B.SEIDMAN
   MAP3 C.A.ROFER

PARAMETERS: