Help for MARSDEPTH

PURPOSE:

MARSEDEPTH is used to compute the excursion of all points in an XYZ image
from a plane.  The program fits a plane to an input target XYZ point and an
input surface normal vector UVW at the target XYZ.  Then it computes the 
vertical distances of all points in the input XYZ image from the fitted plane.
The output is a one-band image of the distances. 

Optionally, the excursion (or depth) analysis can be limited to the FOV 
(Field Of View) of a camera. To limit the output image to the FOV of a
camera, the user must provide MARSDEPTH with two optional inputs:  a
"prototype" image from the camera s/he is interested in, and a stand-off
value.  The prototype image is used simply to build a camera model.  The 
camera model from the prototype image file is reoriented and repositioned 
based on the given target XYZ position, the surface normal vector UVW at 
the target, and the stand-off distance.   The camera model is repositioned
at (targetUVW * standoff + targetXYZ), and reorient along (-targetUVW) 
direction perpendicular to the fitted plane.  Then we mask off the results 
according to whether they’re in the image FOV of the adjusted camera model.  
The output image contains the deviations from the given plane for each pixel,
from which a histogram can be determined.

To use MARSEDEPTH without a camera model and FOV filtration (simpler use),
the user needs to provide the following:
  - An input XYZ image
  - The XYZ position of a target point
  - The coordinate system in which target XYZ is given (defaults to SITE)
  - The UVW surface normal at target point should be up looking
    (defaults to (0,0,-1)
  - The coordinate system in which target UVW is given (defaults to SITE)
  - The intended direction of the target UVW vector:  Set keyword -NORMAL
    to indicate target UVW is a surface normal up-looking vector.  Set 
    keyword -APPROACH to indicate that target UVW is a surface normal but
    down-looking vector.  Defaults to -NORMAL because target UVW vector
    defaults to the up-looking vector (0,0,-1).
Keep in mind that a plane fitted to a point and a vector has a positive
and a negative side.  The positive side of the plane is the side where the
vector is.  The other side is the negative side of the plane.  Therefore,
in the case of this simple use of MARSDEPTH with (0,0,-1) target UVW 
vector and -NORMAL keyword, all points below the fitted plain (the side
closer to Mars) will have negative distances, and all points above the
plain (the side closer to sky) will have positive values.  To negate the
results in the output file, you can trick the program by providing an
up-looking target UVW vector and setting -APPROACH keyword.  You may also
negate the results by setting the target UVW vector to a down-looking 
vector, such as (0,0,1), and setting the keyword -NORMAL.  

To use MARSDEPTH with a camera model and its FOV filtration, the user
needs to provide the information mentioned above plus the following:
  - a prototype image file for using its camera model
  - stand-off distance (defaults to 0.2 and ignored if no proto. image)
  - FOV limit in degrees (defaults to 30.0 and ignored if no proto. image)
The "trick" mentioned above (in the case of the simple use of MARSDEPTH
without any prototype image) is a requirement here with prototype image.
The reason is that with camera model we need the target UVW vector to be
the view direction of the camera, which should be downward.  Stand-off 
should always be a positive number.  Therefore, with an optional
prototype image for camera model we need either
  - an up-looking target UVW vector like (0,0,-1)/SITE, and
  - APPROACH keyword set (-APPROACH), and
  - stand-off > 0 
or
  - a down-looking target UVW vector like (0,0,1)/SITE, and
  - NORMAL keyword set (-NORAML), and
  - stand-off > 0.


EXECUTION:

marsdepth inp=data.xyz out=data.depth \
          target_xyz=\(<x>, , \) target_uvw=\(, , \) \
          -site -normal
marsdepth inp=data.xyz out=data.depth \
          target_xyz=\(<x>, , \) target_uvw=\(, , \) \
          xyz_cs=<target xyz coord type> uvw_cs= \
          -site -normal
marsdepth inp=data.xyz out=data.depth \
          target_xyz=\(<x>, , \) target_uvw=\(, , \) \
          -site -appraoch
marsdepth inp=data.xyz out=data.depth \
          target_xyz=\(<x>, , \) target_uvw=\(, , \) \
          xyz_cs=<target xyz coord type> uvw_cs= \
          -site -approach
marsdepth inp=data.xyz out=data.depth \
          target_xyz=\(<x>, , \) target_uvw=\(, , \) \
          proto_image=<prototype image> standoff=0.2  FOV=30.0 \
          -site -approach
marsdepth inp=data.xyz out=data.depth \
          target_xyz=\(<x>, , \) target_uvw=\(, , \) \
          xyz_cs=<target xyz coord type> uvw_cs= \
          proto_image=<prototype image> standoff=0.2  FOV=30.0 \
          -site -approach
where:
data.xyz  is an input 3-band XYZ REAL image,
data_depth  is the output 1-band REAL image with depth information,
target_xyz  is a 3D XYZ coordinates of the target point,
target_uvw  is a 3D surface normal vector at the target point,
xyz_cs  is the coordinate type of the target_xyz point,
uvw_cs  is the coordinate type of the surface normal vector at the target,
-site  indicates using the SITE coordinate system,
-nomal  indicates that the provided target_uvw is in normal direction,
-approach  indicated that the provided target_uvw is in approach direction,
proto_image  is the optional input image used for its camera model,
stanfoff  is the stand-off distance for the camera model, and
fov  is the camera model FOV filtration limit in degrees.

In the first case, a plane is fitted to the target point (XYZ) and the 
surface normal at the XYZ. The values in the output image, are the distances
of their coresponding points from the input XYZ image to the fitted plane.
The positive side of the plane is where the normal vector is, and the other
side of the plave is the negative side.

The second case is similar to the first case, and the only difference is
that the coordinates types for both the target XYZ point an the surface
normal at the target point are given.  The coordinate types are given when
they are not the same as the default ones.

The third case is similar to the first case with the only difference being
-approach keyword set and not -normal.  In this case, the negative side of
the fitted plane is the side where the surface normal vector is, and the 
other side is the positive side.

The fourth case is similar to the second case with the only difference being
-approach keyword set and not -normal.  In this case, the negative side of
the fitted plane is the side where the surface normal vector is, and the 
other side is the positive side.

The fifth case is the third case with the added optional information (a
prototype image for its camera model, the stand-off distance and the FOV
filtration limit) to created a camera model Field Of View to eliminate
all the input image points outside of the FOV.

The sixth case is the fourth case with the added optional information (a
prototype image for its camera model, the stand-off distance and the FOV
filtration limit) to created a camera model Field Of View to eliminate
all the input image points outside of the FOV.

METHOD:

MARSEDEPTH is used to compute the excursion of all points in an XYZ image
from a plane.  The program fits a plane to an input target XYZ point and an
input surface normal vector UVW at the target XYZ.  Then it computes the 
vertical distances of all points in the input XYZ image from the fitted plane.
The output is a one-band image of the distances. 

The side of the plane pointed at by the surface normal vector is the positive
side of the plane, and the other side is the negative side of the plane.  The
distances on the positive side are positive, and the distances on the negative
side are negative.  If the -approach keyword is set, then the negative side of
the plane is the one pointed at by the surface normal vector, on the other
side is the positive side.

All the points is the input XYZ image file that are invalid, i.e. (0,0,0), are
ignored.  The points can additionally get filtered out based on the FOV of an
optional input camera model after being reoriented and repositioned.  Then all
the input XYZ image points outside of the FOV of the camera are ignored as
well.  When the optional camera model information are provided, the keyword
-approach should be set




OUTPUT FORMAT:

The output is a 1-band file in REAL format.

Without the optional camera model, the points in the output file are the 
distances of their matching points in the input XYZ image from the fitted
plane.

With the optional camera model, the points in the output file are the
distances of their matching points in the input XYZ image from the camera
along the camera approach (the negative of the surface normal vector).


HISTORY:
2020-07-10 Initial marsdepth by E. Sarkissian, under the cognizance of
Bob Deen

PARAMETERS: