deltack Documentation

deltack - Make angular adjustments to camera pointing and create CK
deltack performs an angular camera adjustment based upon line/sample
differences that are usually a result of pointing errors or incorrect
boresight coordinates.  deltack is a batch method to update the camera
kernel (CK) given several different input scenarios.

The formal adjustment is made through the use of the DLINE/DSAMP
parameters.  This specifies a spatial offset that will be used to
compute an angular camera adjustment (negative values of DLINE
and DSAMP move the pointing up and left, respectively).  All other
use scenarios essentially result in values computed for DLINE/DSAMP
to make the angular adjustments.

The user may provide a lat/lon (LAT/LON) and the expected image
line/sample (TLINE/TSAMP) coordinate for that geodetic location.  This
situation utilizes existing kernel data as stored in the label (from
levinit) and computes the precise mapping to line/sample (ILINE/ISAMP).
(Note the mapping line/sample is functionally equivalent to the
ILINE/ISAMP user parameters.)  From the TLINE/TSAMP parameters, it will
then "tack" the given latitude (LAT) and longitude (LON) to these new
image locations.  This works only if the given LAT/LON pair can be
resolved using the current state of the SPICE kernel data.  If the
LAT/LON geodetic does not map to a line/sample, then an alternative
method must be used.

If geodetic locations cannot be determined (typically due to
insufficient SPICE data or large pointing errors), then a combination
of a line/sample (ILINE/ISAMP) pair and the new line/sample
(TLINE/TSAMP) pair can be used to determine the angular offset.  This
essentially accomplishes the same thing as the previous approach
without reliance on any SPICE data.  It computes the updated angles
strictly from line/sample image coordinates.

All options result in the generation of a new SPICE CK kernel that
*replaces* the current kernel.  The name of the CK1TO file used to
store the adjusted pointing of the instrument/camera is recorded in the
ISIS label in the CAMERA_KERNELS keyword in the ISIS_GEOMETRY group
found in the QUBE object label keyword section.

The parameter CK1TO specifies the name of a file to write the resulting
type 1 SPICE camera kernel (CK).  This file is designed to replace the
existing CK file found in the CAMERA_KERNELS keyword in the ISIS labels
as mentioned above.  deltack will update the labels with the CK1TO file
name thus replacing the existing file name in that keyword.  This will
result in the file being immediately ready to map project or (hopefully)
properly resolve geodetic locations.

It is up to the user to determine the best CK1TO naming scheme.  It is
important to consider whether or not to use a complete path to the CK
file name or simply the filename.  It will be recorded in the label
as provided by the caller.  If a complete path, sometimes referred to
as an absolute path, then ISIS expects the file to exist in the
directory as specified.  If just the file name is provided with
no directory path specified, it must exist in the directory ISIS
applications are executed from - not always the same directory where
the file resides.  If the ISIS file location is to remain fixed, then
it is a good idea to also fix the CK file to the same path.  This can
be accomplished easily if deltack is run in the directory where the
file is located.  CK1TO should contain the full path to the present
working directory ($PWD).  Use CK1TO="$PWD/ckfile.bc".  The $PWD will
be expanded at runtime and the absolute path will be recorded in the
ISIS labels in expanded form.

USE CASES
There are many circumstances when deltack may be useful.  Frequently,
the spacecraft and/or camera pointing data are in error particularly
immediately after observations are acquired and before refinements to
ephemerides occur.  This application is intended to address isolated
instances of these problems and is inadequate for large scale,
systematic errors.  Also, deltack requires that at least one
line/sample coordinate map to a latitude/longitude to provide the
primer for angular adjustments.

Below are a few of these situations.

CASE 1) FITTING LIMBS
deltack is useful for fitting flyby observations.  The technique used
involves finding the limb by fitting it to an image of the emission
angle.  The emission angle has the property that it approaches 90.0
degrees at the limb.

The ISIS application "levgeoplane" is used to create an image of the
emission angle from exiting pointing information.  It can then be
overlayed over the original image using "qview".  Using the linking,
blinking and registering features of qview, the deltack ILINE/ISAMP
and TLINE/TSAMP option to create the CK file.  See the discussion
below on how to use qview for this procedure.

The steps for this technique are:

levinit from=N1483151512_1.IMG.cal.lev1.cub \
        targdef=$PWD/iapetus.def.1 \
        kernlst=$ISISCSSDATA/css_kernels.def.5
levgeoplane from=N1483151512_1.IMG.cal.lev1.cub \
            to=N1483151512_1_emission.cub \
            lat=no lon=no ema=yes

#  Load N1483151512_1.IMG.cal.lev1.cub first in qview, then
#  N1483151512_1_emission.cub and register limb adjusting only
#  emission image
qview from=(N1483151512_1.IMG.cal.lev1.cub, N1483151512_1_emission.cub)

#  Apply the observed registration offsets
deltack from=N1483151512_1.IMG.cal.lev1.cub iline=434 isamp=325 \
        tline=453 tsamp=649 ck1to=$PWD/N1483151512_1.bc


CASE 2) FITTING TO MAP PROJECTED IMAGE
Fitting to an existing map projected image is made possible using the
ISIS application "lev2tolev1".  This application converts an ISIS level
2 map projected image to the perspective of the camera when the
observation was acquired.  "qview" can be used as in the limb fitting
case above to determined the offsets.  (See the description below on
how to use qview to register the two images.)

Here are the steps to apply this technique:

levinit from=N1477472486_3.cub kernlst=$ISISCSSDATA/css_kernels.def.5
lev2tolev1 from=W1477472486_3_GlobalSimp.cub  from2=N1477472486_3.cub
geom from=W1477472486_3_GlobalSimp.cub  to=NA_Control.cub

#  Load N1477472486_3.cub first in qview, then NA_Control.cub and
#  register
qview from=(N1477472486_3.cub, NA_Control.cub)

#  Make adjustment to pointing
deltack from=N1477472486_3.cub iline=132 isamp=930 tline=305 tsamp=785 \
        ck1to=$PWD/N1477472486_3.bc

#  Verify images
lev2tolev1 from=W1477472486_3_GlobalSimp.cub  from2=N1477472486_3.cub
geom from=W1477472486_3_GlobalSimp.cub  to=NA_Verify.cub

CASE 3) BRUTE FORCE FITTING
There are several options that can be used to obtain better pointing,
but are not as accurate.  Here are a few options that show other
techniques:

a)  Use deltack to associate the latitude/longitude (LAT/LON) location
of a known feature with a specific line/sample (TLINE/TSAMP).  Pay
particular attention when specifying LAT/LON values.  They must be
given in the same system used in "levinit".  This will be 0 - 360 or
-180 to 180, positive EAST or WEST longitudes and planetocentric or
planetographic latitudes.  See the labels under the ISIS_TARGET group
in the QUBE object of the labels for this information.

Furthermore, the LAT/LON values given *must* resolve to a line/sample
(ILINE/ISAMP) coordinate in order for this technique to work.

deltack from=image.cub LAT=-23.543884 lon=121.005533 \
        tline=223 tsamp=506 ck1to=$PWD/image.bc

b)  Use deltack to indicate the movement of a specific line/sample
to another line/sample location.  The input line/sample coordinate is
provided in the ILINE/ISAMP parameters.  The coordinate to "move"
this reference point is provided in the TLINE/TSAMP parameters.  This
technique does not require a LAT/LON mapping at either coordinates.
Only a valid CKLINE/CKSAMP are required.

deltack from=image.cub iline=784 isamp=213 tline=545 tsamp=323 \
        ck1to=iamage.bc
	
c)  Specify an relative offset, specify a line and sample offset in
DLINE and DSAMP parameters.  This also does not require a LAT/LON at
any coordinate.

deltack from=image.cub dline=-30 dsamp=60.5 ck1to=image.bc


USING QVIEW TO REGISTER IMAGES
qview possesses registering features that assists in the above
techniques.  It uses the linking, registering and blinking features
along with the pan, zoom and tracking options to align two images.
Both images are assumed to have the same number of lines and samples.
Below are the steps that outline this process:

1) Load the image you want to generate a CK file for as the first
image.  This image will be associated with the TLINE/TSAMP coordinates.
This is typically the "Display 1" image.

2) Load the truth or emission cubes as the second image.  This image
will be associated with the ILINE/ISAMP coordinates.  This is typically
the "Display 2" image.

3) Once the two images are loaded ensure that both have the same zoom
factor. This can be accomplished by clicking the "World" button, second
from right at top of display.  Then for each image, locate a common
feature and click on it only once!  Ensure both images still have the
same resolution!  Also, apply any stretch operations at this time.

4) Once the images are crudely aligned, select the "Link" option in the
main menu and link the two images.  At this time, you can make
adjustments to the zoom factor of the images to get better coverage or
visability of commonality between the two images.  Since the images are
linked, what you do to one image will also occur with the second.

5) Now select the "Link" option again, this time checking the "Register"
option.  Be sure to enter the name of a file in the "Control Point File"
option.  It is not used but is required for this qview feature.

6) At this point you can select the "Blink" option from the main qview
menu and start the blinking of the two images.  The blinking speed can
be slowed down to an acceptable rate to make comparisons easier.  The
two images are now alternating rapidly in "Display 1".

7) In the truth or emission image, "Display 2" select the "Pan" button.
The pan buttin is second from left at top of each display window and
appears as a four-directional arrow.

8) Select the "Tracking" button which is the far right button at top
of each display window on the first image window.  Line/sample and, at
times, latitude/longitude values are displayed in the lower left
portion of each window.  When tracking is turned on, both are updated
simultaneously, mapping to locations relative of both images.

9) In the truth or emission display, you may now click the left mouse
button in any portion of the display to move it one pixel in toward the
location of the cursor in the display window.  Continue this process
until you are satisfied with the registration.

10) To save a point, hit " S". The line/sample locations of
the first and second image are written to the file provided in the
"Control Point File" window.  It has the form:

1  www.wwww xxx.xxxx yyy.yyyy zzz.zzzz

Where www.wwww is the line location of the first image (TLINE),
      xxx.xxxx is the sample location of the first image (TSAMP),
      yyy.yyyy is the line location of the second image (ILINE),
  and zzz.zzzz is the sample location of the second image (ISAMP).

11) Finally, exit qview and run deltack on the first image to make
the adjustment:

deltack from=image.cub iline=yyy.yyyy isamp=zzz.zzzz \
        tline=www.wwww tsamp=xxx.xxxx ck1to=$PWD/image.bc
	

NOTE:  While in registering mode, DO NOT HIT THE WORLD BUTTON!  It will
completely undo all registering activities and you will have to start
all over.

COMPUTATIONAL DETAILS
Below is a detailed account of the computational steps performed by
deltack.

RA    = Camera Right Ascention angle
DEC   = Camera Declination angle
TWIST = Camera Rotation angle

1)  Reads input parameters from user.
2)  Open input file and load the kernels found in the label.
3)  If LAT/LON is given but not ILINE/ISAMP, compute ILINE/ISAMP.
    If this fails, must abort processing.
4)  Compute DLINE/DSAMP (movement left and up is negative):
       DLINE = TLINE - ILINE
       DSAMP = TSAMP - ISAMP
5)  Extract camera angles (RA, DEC, TWIST) for a given line/sample at
    CKLINE/CKSAMP.
6)  Form the 3x3 matrix M as:
      M = {Z ROT BY TWIST} {X ROT BY 90-DEC} { Z ROT BY 90+RA}
7)  Form the vector Vc in Camera coordinates:
      Vcx = - DLINE * IFOV
      Vcy = - DSAMP * IFOV
      Vcz = SQRT( 1 - Vcx*Vcx - Vcy*Vcy)
8)  Rotate the camera vector to Celestial coordinates giving Vs:
      Vs = M^-1 * Vc
9)  Compute new matrix C-Matrix:
      IF (Vcy > 0) THEN RAmod = DEGREES(acos(Vsx/sin(acos(Vsz))))
      ELSE RAmod  = 360 - DEGREES(acos(Vsx/sin(acos(Vsz))))
      DECmod = 90 - DEGREES(acos(Vsy))
      TWISTmod = TWIST + DROTA
10) Write CK to the output CK1TO file
11) Update the labels by writing the CK1TO file to the
    QUBE/ISIS_GEOMETRY/CAMERA_KERNELS keyword.

Programmer: Kris Becker, USGS, Flagstaff, Az
Version:    $Revision: 1.3 $ $Date: 2006/07/19 03:06:17 $

Provide the ISIS file that is
to have the camera adjustment
applied to

NONE

Sample coordinate of current
position on input image

--

Line coordinate of current
position on input image

--

Sample coordinate to move
ISAMP position to

--

Line coordinate to move
ILINE position to

--

Offset in sample to adjust
camera pointing.  (Negative
values moves it left on the
image)

--

Offset in line to adjust
camera pointing.  (Negative
values moves it up on the
image)

--

Latitude of identifyable
feature on image. Use with
TSAMP/TLINE values to adjust
pointing.

--

Longitude of identifyable
feature on image. Use with
TSAMP/TLINE values to adjust
pointing.

--

Adjustment in rotation angle
for the camera coordinates
USE WITH EXTREME CAUTION!!

0.0

Name of CK file to write
updated pointing data to

NONE

Sample coordinate used to
acquire initial camera
pointing.
DEFAULT:  NSAMPS/2

--

Line coordinate used to
acquire initial camera
pointing.
DEFAULT:  NLINES/2

--

ADDITIONAL NOTES:

Parm	Description
FROM	This is the ISIS cube file that is to have the camera angles modified. It must be initialized to a level 1 image using levinit. In order for this application to work, it must have at least one pixel location where geodetic (i.e., LAT/LON) values can be determined. This location need not be any of the points used in ILINE, ISAMP, TLINE or TSAMP. The parameters CKLINE and CKSAMP are to be used for this purpose. It is required to prime the process of updating the pointing.
ILINE	This is the reference line coordinate in the image that is to be used to move the pointing to a new line coordinate (TLINE). This parameter is optional and is also computed from the LAT/LON parameters in certain modes. For example, the user can provide a TLINE/TSAMP and LAT/LON combination. This is handled by taking the LAT/LON value and computing ILINE and ISAMP from it. The ILINE/ISAMP coordinates are then used in conjunction with TLINE/TSAMP to compute the camera adjustment. This parameter must be used in conjunction with the ISAMP parameter completely specify the current pointing coordinate. The relationship between this parameter and DLINE, which is the actual parameter used to make the angular adjustment in camera pointing is: DLINE = TLINE - ILINE
ISAMP	This is the reference sample coordinate in the image that is to be used to move the pointing to a new sample coordinate (TSAMP). This parameter is optional and is also computed from the LAT/LON parameters in certain modes. For example, the user can provide a TLINE/TSAMP and LAT/LON combination. This is handled by taking the LAT/LON value and computing ILINE and ISAMP from it. The ILINE/ISAMP coordinates are then used in conjunction with TLINE/TSAMP to compute the camera adjustment. This parameter must be used in conjunction with the ILINE parameter completely specify the current pointing coordinate. The relationship between this parameter and DSAMP, which is the actual parameter used to make the angular adjustment in camera pointing is: DSAMP = TSAMP - ISAMP
TLINE	This parameter is the line coordinate to move pointing to from an ILINE reference point. This is essentially a tack point for the ILINE (and ISAMP) and LAT/LON locations as provided by on input. It must be used in conjunction with the TSAMP parameter to completely specify the new pointing coordinate. The relationship between this parameter and DLINE, which is the actual parameter used to make the angular adjustment in camera pointing is: DLINE = TLINE - ILINE
TSAMP	This parameter is the sample coordinate to move pointing to from an ISAMP reference point. This is essentially a tack point for the ISAMP (and ILINE) and LAT/LON locations as provided by on input. It must be used in conjunction with the TLINE parameter to completely specify the new pointing coordinate. The relationship between this parameter and DSAMP, which is the actual parameter used to make the angular adjustment in camera pointing is: DSAMP = TSAMP - ISAMP
DLINE	DLINE is used to determine the angular adjustment in the camera pointing. A negative value given for DLINE moves the pointing up in the visable image frame. A positive value moves it down. The main help section describes how DLINE is used to compute the camera pointing adjustment. This parameter must be used in conjunction with DSAMP to completely defined the angular camera adjustment. DLINE and DSAMP may be the only adjustment parameter needed to completely defined the adjustment. If DLINE and DSAMP are provided, ILINE/ISAMP, TLINE/TSAMP and LAT/LON are not needed and ignored. In other words, DLINE and DSAMP take precedence of all other parameters.
DSAMP	DSAMP is used to determine the angular adjustment in the camera pointing. A negative value given for DSAMP moves the pointing left in the visable image frame. A positive value moves it right. The main help section describes how DSAMP is used to compute the camera pointing adjustment. This parameter must be used in conjunction with DLINE to completely defined the angular camera adjustment. DSAMP and DLINE may be the only adjustment parameter needed to completely defined the adjustment. If DSAMP and DLINE are provided, ILINE/ISAMP, TLINE/TSAMP and LAT/LON are not needed and ignored. In other words, DSAMP and DLINE take precedence of all other parameters.
LAT	This parameter, used in conjunction with LON, can be used to compute ISAMP and ILINE. LAT and LON provide the ability to associate the precise location of a known feature to make camera adjustments. A combination of LAT/LON and TLINE/TSAMP completes a camera adjustment. In order for this adjustment option to work, the LAT/LON coordinate must resolve to a line/sample coordinate. The line/sample coordinate associated with this LAT/LON coordinate is equivalent to the ILINE/ISAMP parameters.
LON	This parameter, used in conjunction with LAT, can be used to compute ISAMP and ILINE. LAT and LON provide the ability to associate the precise location of a known feature to make camera adjustments. A combination of LAT/LON and TLINE/TSAMP completes a camera adjustment. In order for this adjustment option to work, the LAT/LON coordinate must resolve to a line/sample coordinate. The line/sample coordinate associated with this LAT/LON coordinate is equivalent to the ILINE/ISAMP parameters.
ROTATE	This paramter is provided to rotate the camera angles around the boresight. A negative value rotates the image couter-clockwise. Positive values rotate the image clockwise around the boresight.
CK1TO	This is the name of the file where the new camera pointing is written. This file is a type 1 SPICE CK file and is written using the NAIF toolkit. Great consideration should be given to the full name given to this output file as it is also written to the FROM file labels. The name as given by the user is written to the QUBE/ISIS_GEOMETRY/CAMERA_KERNELS label keyword. This step alone simplifies the steps required to utilize the SPICE CK file. It is highly recommended that users specify complete paths for this file. The easiest way to do this is to use the $PWD environment varaible. The net effect of this is that one can copy the FROM cube file to any other directory location and still be able to reference it when initialized for geometric operations. Another option is to create a directory precisely for storing these files if many will be created. The other option is to give just the filename with no absolute directory specification. This will require that any time the cube file is copied so must the CK1TO file. If the file already exists, it is overwritten, otherwise it is created. Note that the directory specified in the CK1TO path must be writable by the user. It is also implied that the FROM file must also be writable as its label is updated by deltack.
CKLINE	This parameter is optional but important to prime the data used to establish nominal pointing data from which to calculate angular adjustments. This value defaults to NLINES/2, the center of the spatial image size. This point MUST resolve to a LAT/LON location via the ISIS level 1 software system. If the LAT/LON coordinate cannot be computed at this location, CKLINE, and, optionally, CKSAMP can be used to specify a spatial coordinate that does map to a LAT/LON location.
CKSAMP	This parameter is optional but important to prime the data used to establish nominal pointing data from which to calculate angular adjustments. This value defaults to NSAMPS/2, the center of the spatial image size. This point MUST resolve to a LAT/LON location via the ISIS level 1 software system. If the LAT/LON coordinate cannot be computed at this location, CKSAMP, and, optionally, CKLINE can be used to specify a spatial coordinate that does map to a LAT/LON location.