Help for MARSSLOPE

PURPOSE:
MARSSLOPE computes one of the following slope function types:
  Slope
  Slope Heading
  Slope Magnitude
  Slope Rover Direction
  Northerly Tilt
  Solar Energy

The inputs for MARSSLOPE are an XYZ image such as that created by the
MARSXYZ program, and a UVW image such as that created by MARSUVW.
These can each be single 3-band files or three 1-band files; see 
MARSXYZ and MARSUVW for details.

EXECUTION:
marsslope inp=xyz_data out=slope_data.vic uvw=uvw_data type=slope
marsslope inp=xyz_data out=slope_data.vic uvw=uvw_data type=heading
marsslope inp=xyz_data out=slope_data.vic uvw=uvw_data type=magnitude
marsslope inp=xyz_data out=slope_data.vic uvw=uvw_data 
        origin=\( 0.0,0.0,0.0\) type=direction
marsslope inp=xyz_data out=slope_data.vic uvw=uvw_data type=ntilt
marsslope inp=xyz_data out=slope_data.vic uvw=uvw_data type=solar sa=68.9

marsslope inp=\(x.vic,y.vic,z.vic\) out=slope_data.vic uvw=\(u.vic,v.vic,w.vic\) type=slope

where:
type is one of the following slope functions to be computed:
  slope     - Slope
  heading   - Slope Heading
  magnitude - Slope Magnitude
  direction - Slope Rover Direction
  ntilt     - Northerly Tilt
  solar     - Solar Energy

origin is an override for the input reference point. It is used only when 
calculating Slope Rover Direction (direction)

sa is a solar angle, which is the angle between the vector to the sun and 
its projection to the XY-plane at local noon. Ideally this should be the 
elevation of the sun at local noon, but approximations to this may be used. 
It is used only when calculating Solar Energy (solar).

TBD: The solar angle should be derived from SPICE eventually.


METHOD:

Input file contents:

INP:  marsxyz(or similar)-generated. It consists of either three separate 
one-band files (x, y, z), or a single 3-band file.  
Units of XYZ input file(s) are in meters, in the coordinate system specified 
by the COORD and COORD_SYS parameters.

UVW: marsuvw(or similar)-generated normalized normal vector. It consists of 
either three separate one-band files (x, y, z), or a single 3-band file.

Calculations:

Given XYZ = (x,y,z) is a point/location, and N = (u,v,w) is a normal vector,
and origin = (x0,y0,z0), the formulas for computing slope functions are:

Slope (slope):
  S = (180/PI) * ( (PI/2) + atan( w/ sqrt( u*u + v*v ) ) );
Pixels represent the slope of the surface at that point, in
degrees, with 0 being horizontal (surface parallel to the X-Y coordinate
plane).

Slope Heading (heading):
  S = (180/PI) * ( atan2(v,u) );
Pixels represent the direction in which the slope tilts, defined as the 
azimuth of the projection of the surface normal to the X-Y coordinate plane.

Slope Magnitude (magnitude):
  S = sqrt(u*u + v*v);
Pixels represent the magnitude of the slope as a value between 0 (flat) 
and 1 (vertical), equivalent to sin(slope).

Slope Rover Direction (direction):
   d = sqrt( (x-x0)*(x-x0) + (y-y0)*(y-y0) ),
   Vx = (x-x0) / d,
   Vy = (y-y0) / d,
   S = -(180/PI) * atan2( Vx*u + Vy*v, -w );
Pixels represent the component of slope (in degrees) in the radial direction 
towards or away from the specified origin (generally the rover position),
with positive tilting toward the origin (representing a climb from the 
rover's perspective).

Northerly Tilt (ntilt):
  S = (180/PI) * asin(u);
Pixels represent the component of slope (in degrees) that points north. 
This is defined as the complement of angle between the surface normal 
and a vector pointing north (i.e. (1,0,0) or along the +X axis in a 
local level frame), with a value equal (180/pi)*arcsin(nx) degrees, 
where nx is the X component of the surface normal.  90 degrees indicates 
the surface faces north (normal parallel to +X) while 0 indicates there 
is no north-facing component (e.g. flat or tilted east-west only).
Negative numbers indicate a south-facing surface.

Solar Energy (solar):
   S = u * cos(SA*PI/180) - w * cos((90-SA)*PI/180).
Pixels represent the relative amount of solar energy
available at that point due solely to rover tilt, defined as the dot
product between the surface normal and the vector to the sun at local
noon.


COGNIZANT PROGRAMMER: I. Yanovsky

HISTORY:
  2012-01-08 I. Yanovsky and B. Deen - Initial marsslope
  2019-12-10 W. Bunch - Initialized some variables; cleaned up some -Wall warnings; added unit test.
  2020-05-19 W. Bunch - Replaced sprintf calls.
  2020-07-08 rgd	Removed size limitations

PARAMETERS: