The CASPER Target tool allows the user to create a file with detailed geometric information for a single
pointing instance within a module.  This file is called the Physical Model Interface, or PMI.  The purpose
of this file is to allow the user to access geometric information available within CASPER for use in
external models, such as, for example, physical models of the signal expected for a given exposure and
geometry.
 

• Creating a PMI file:

To create a PMI file, you must first design an observation, or module, within the Target tool.  One instrument field of view must be drawn on the Target plot.  The module may consist of multiple pointings, but only one is selected for each PMI file.  Once you have an observation drawn in Target, select "Make PMI File" from the File menu of the Target tool.  This will give you a series of prompts for information that CASPER needs to create the file.  You will be asked to select one of the drawn fields of view and to fill it with a number of line of sight vectors.  You will be prompted for the number of vectors to fill the field of view.  For example, to generate 100 line of sight vectors within the square ISS field of view, you may select 10 vectors along each dimension of the FOV.  CASPER will display a stippled pattern of dots representing these vectors within the FOV once the PMI data has been calculated.  This data can be saved to a file in your personal casper_save/pmi/ directory for later access either with the CASPER PMI Viewer or with your own software.
• Data in PMI file:

The PMI file consists of a header followed by geometric information for each of the line-of-sight vectors.
• PMI Header:

The header contains the following information in an IDL structure named HEADER:
N_LOS            The number of lines of sight in the file.
N_WIDTH        The number of lines of sight along the width of the FOV.
N_LENGTH        The number of lines of sight along the length of the FOV.
ET                    The ephemeris time of the data, in seconds relative to J2000.
REF                   The inertial coordinate system used (string).
DATE                The date of creation of the file.
USERNAME    The name of the user who created the file.
CASPERVERSION    The version of CASPER used when creating the file.
FOVNAME                    The CASPER name of the FOV (e.g. ISSNA is Imaging Narrow Angle).
FOVIDNUMBER           The CASPER ID code for the instrument.
FOVLENGTH                The length of the FOV in radians.
FOVWIDTH                    The width of the FOV in radians.
DESCRIPTION                A 40 character (maximum) description of the file contents, entered by the user.
TARGETCODE                The NAIF ID code for the target body.
TARGETRAD                   The NAIF radii of the target body (3 components).
TARGETPOLE                The Right Ascension, Declination, and prime meridian of the target spin
                                            pole (3 components) at the time ET.
TARGETSPIN                    Target spin rate in rad/sec.
DIST_2_TARG                Distance from spacecraft to target body center in km.
INST_2_INERT                Rotation matrix from spacecraft coordinates to inertial coordinates.
INERT_2_TARG             Rotation matrix from inertial coordinates to target body coordinates.
INST_2_TARG                Rotation matrix from spacecraft coordinates to target body coordinates.
RA                    Right ascension of the instrument boresight, in degrees.
DEC                  Declination of the instrument boresight, in degrees.
XYZ                  Cartesian unit vector of the instrument boresight, in the inertial coordinate system.
RTARG_BC    Position of the target body relative to the solar system barycenter, in km (3 components).
VTARG_BC    Velocity of the target body relative to the solar system barycenter, in km/s (3 components).
RSC_BC        Position of the spacecraft relative to the solar system barycenter, in km (3 components).
VSC_BC        Velocity of the spacecraft relative to the solar system barycenter, in km/s (3 components).
RSUN_BC      Position of the Sun relative to the solar system barycenter, in km (3 components).
RSC_TARG    Position of the spacecraft relative to the target body, in km (3 components).
The last 6 entries are all in the inertial coordinate system.
 
• PMI Bundle:

The next part of the PMI file consists of a "bundle" of line-of-sight vectors.  These are stored as an array of structures in IDL called bundle.  The array has length N_LOS, and each entry in the array has the following structure fields:
ID                    An ID code specifying what the vector intercepts within the field of view.  The codes have the following values:
0: free space - no intersection of the vector with any target body known by CASPER.
100: rings - the vector intersects the CASPER definition of the target body rings on the illuminated
        face.
200: target body - the vector intersects the NAIF surface of the target body on the day side.
105: dark side rings - the vector intersects the rings on the unlit face of the rings.
205: night side target body - the vector intersects the target body on the night side.
RA    The Right Ascension of the line of sight, in degrees.
DEC    The declination of the line of sight, in degrees.
XYZ    Cartesian unit vector parallel to the line of sight, in the inertial coordinate system.
ALT    The minimum distance above the target body surface of the line of sight, perpendicular to the line
            of sight, in km.  If the line of sight intercepts the rings, then ALT contains the radius of interception
            in the ring plane.
LAT    Target body latitude of the intercept point, in degrees.
LONG    Target body West longitude of the intercept point, in degrees.
PHASE    Phase angle of the intercept point, in degrees.
SOLAR    Solar elevation angle of the intercept point, in degrees.
EMISSION    Emission angle of the intercept point, in degrees.
 
• Viewing a PMI File:

CASPER provides a rudimentary PMI viewer under the Utilities menu of the CASPER widget.  However, the main purpose of the PMI is to allow users to access the data independently of CASPER through the file.  The CASPER PMI viewer displays a plot of the phase, solar, and emission angles, altitude, and intercept ID code for each vector in the bundle as functions of Right Ascension and Declination, or target body latitude and longitude.

• Using a PMI file:

CASPER comes with a simple IDL routine that reads CASPER PMI files.  This routine is called pmi_reader.pro and is located in the casper/src/fov/ subdirectory of your CASPER installation.  It is not a widget routine, and is not called by any other parts of CASPER.  It is meant to be copied to your own personal directory, and used and modified as needed to read in PMI files and send the relevant data to your own external models.