ISIS 2 Documentation
Written by Jim Torson August 29, 2003 ---------------------
The input to the processing consists of PDS QUB files that are produced by software running at Arizona State University (ASU). The PDS QUB files are first translated to ISIS cube format, and then all the geometry processing described below is run within the ISIS environment.
Note that the ISIS geometry software is designed to process THEMIS IR/VIS EDR and RDR QUBE files. However, this sofware is NOT intended to process the THEMIS BTR, ABR or browse image files.
If you are not familiar with TAE, look at the ISIS web-based documentation, e.g.:
The document Overview of ISIS Architecture contains a description of how to use TAE. In particular, this describes how to obtain documentation on a particular program or procedure PDF.
You can also use the "isisdoc" program to produce a nicely-formatted plain-text file that contains the documentation for a particular program or procedure PDF. You can run "isisdoc" in TAE or just run it at the operating system command prompt. E.g., for the "thmvismc" procedure PDF that is in the standard ISIS system, type the following at the operating system prompt:
If you have a THEMIS geometry software update installed in the ISIS development area, the following command should be used:
This will produce a file called thmvismc.doc. This is the most complex of the four procedure PDFs because it deals with the VIS framelets.
The following are the four primary programs you need to be aware of. Each of these is a procedure PDF and associated Perl scripts that run a sequence of executable programs. Each is able to process a single input data file or set of input data files that are listed in a plain-text file.
The IR RDR QUBE files from ASU contain 16-bit pixel values with separate base/multiplier values for each band. When "thm2isis" translates one of these files to ISIS format, it calls the "bandfloat" program to apply the band-specific base/multiplier values to produce a 32-bit floating point ISIS cube file.
Note that "thmirmc" and "thmvismc" include SAMPINC/LINEINC parameters that control the sampling increment for determining the lat/lon range for the output map projection file. The default value for these parameters is 10, which is adequate for most cases. However, there might occasionally be a file in which this fails to accurately determine the lat/lon range. This would result in an output file that includes a spatial area slightly smaller than needed to include all the input data. This problem can be eliminated by setting SAMPINC/LINEINC to smaller values, e.g., 1. However, note that setting these values to 1 can result in the total projection process taking significantly longer to run, e.g., as much as five times longer.
Note also that "thmirmc" and "thmvismc" can optionally use the MOLA Mars DEM data for projecting to map coordinates. The default is to use the MOLA DEM data. This can increase the processing time by about 20%, but this results in better band-to-band registration. ("thmiric" is not able to use the MOLA DEM. Thus, the band registration in the IRIC files will not be as good as in the IRMC files.)
MAPPARS allows the user to specify the desired output map projection and its associated parameters that will be used by the "lev1tolev2" program to create the output map-projected file. When this is specified as the TAE Null parameter value (--), the MAPPARS value that will be used for calling "lev1tolev2" will be MAPPARS="SINU:clon,plattyp", which will create a Sinusoidal Equal-Area map with center longitude (clon) equal to the average of the longitude range of the output map. The projection latitude type (plattyp) will be the latitude system that is recorded in the LATITUDE_SYSTEM keyword in the ISIS_TARGET keyword Group in the input file. The value of this keyword is normally set by the LATSYS parameter when running "thm2isis" to translate the PDS QUBE file to ISIS format. If a non-null value is specified for MAPPARS, then this value will be used as the value of the MAPPARS parameter passed to "lev1tolev2". An extensive explanation of this parameter and its various options and defaults can be obtained by tutoring "mappars" in TAE and typing "help *". Note that when SINU or SIMP is specified as the projection name in the MAPPARS value, the default latitude type OGRAPHIC will be used if the projection latitude type is not specified, i.e., the standard MAPPARS default will be used rather than the latitude system that is specified in the input file LATITUDE_SYSTEM label keyword. If OCENTRIC latitudes (the usual standard for THEMIS) are desired, then OCENTRIC must be specified in the MAPPARS value.
The following discussion clarifies the OCENTRIC/OGRAPHIC handling:
ISIS handles the difference between OGRAPHIC/OCENTRIC latitudes in two totally separate and parallel ways: 1) The latsys chosen when running "levinit" (which is run by "thm2isis") governs the way that latitudes will be (a) reported to the user and (b) interpreted when input by the user So if you choose planetographic then for example "qview" will display the planetographic latitude of the cursor, and if you next ask for a map with lat=(15,30) it will be from 15 degrees planetographic latitude to 30 deg planetographic. The latsys specified when running "levinit" is recorded in the LATITUDE_SYSTEM label keyword in the ISIS_TARGET keyword Group. 2) Entirely separate from this, we now have two types of sinusoidal projection and two types of simple cylindrical projection. One has line number equally spaced in ographic latitude and the other equally spaced in ocentric latitude. Which one you get is controlled by the plattyp (projection latitude type - OGRAPHIC or OCENTRIC) in the MAPPARS string. In a Level 2 projected file, the projection latitude type is recorded in the PROJECTION_LATITUDE_TYPE label keyword in the IMAGE_MAP_PROJECTION keyword Group. Note that this keyword Group also includes the KEYWORD_LATITUDE_TYPE keyword. This value comes from the LATITUDE_SYSTEM keyword in the ISIS_TARGET Group, and it specifies the latitude system used for the values in the MINIMUM_LATITUDE and MAXIMUM_LATITUDE keywords in the IMAGE_MAP_PROJECTION Group. Thus, it is possible to have a file that is projected to one type (PLANETOGRAPHIC or PLANETOCENTRIC) but which has the minimum/maximum latitudes recorded in the other type. Yes, this is confusing. Why would anyone want this distinction? Well, it lets you put appropriate labels on, say, a MOLA product (cylindrical projection equisampled in ocentric latitude) and then work with it in ographic latitudes, e.g., ask for a Mercator map from -60 to +60 deg ographic. Or update labels on an old USGS archived product (sinusoidal projection equisampled in ographic latitude) to the new standard and then reproject to, say, 15 to 30 deg planetocentric latitude and a cylindrical-planetocentric projection, which would line up with a chunk of the MOLA archive. So there is a reason for this confusing behavior.
Of course the computed latitude and longitude values on the ground do not depend upon time. However, the other geometry values are a function of time and spacecraft position.
When "levpt", "levgeoplane", and "lev1stats" are run on an UNPROJECTED IR or VIS file, the geometry values are calculated for the FIRST band in the file. Thus, none of the values will be exactly correct for other bands in the file.
When "levpt", "levgeoplane", and "lev1stats" are run on an IRIC file, the geometry values are computed for the REFERENCE band that was used for producing the file. Thus, the lat/lon values should be correct for all bands in the file. However, even though the bands are spatially registered, the other geometry values will not be exactly correct for the other bands (because they observe a given point on the ground at different times).
When "levpt", "levgeoplane", and "lev1stats" are run on an UNPROJECTED file or an IRIC file, all of the geometry values can be computed for all spatial points within the file.
When "levpt" and "levgeoplane" are run on an IRMC or VISMC file, the geometry values are computed for the MIDDLE band in the file. (For a file with an even number of bands, the "middle" band is the number of bands divided by two.) In this case, lat/lon values are computed for all spatial points within the file. However, the other geometry values can only be computed for spatial points corresponding to actual image data for the middle band in the file.
A further complication arises with the VIS data. In general, any single band of an UNPROJECTED VIS file contains multiple "framelets" stacked vertically through the spatial area of the band image. Each framelet was observed at one instant of time, but different framelets were observed at different times. Also, in general there is some overlap in the area of ground covered by adjacent framelets. Thus, a given lat/lon point on the ground can correspond to two points in the UNPROJECTED VIS file.
When "levpt", "levgeoplane" and "lev1stats" are run on an UNPROJECTED VIS file, the geometry values are computed for the appropriate time and spacecraft position within each framelet for the "reference" band, i.e., first band in the file. This results in discontinuities for all geometry values (including lat/lon) at the boundaries between framelets.
When "levpt" and "levgeoplane" are run on a VISMC file, the lat/lon values are continuous and cover the entire spatial area of the file, including locations where the "reference" band (middle file band) do not contain image data from any framelets. The other geometry values can be computed only at spatial locations which contain image data from at least one framelet in the "reference" band. For spatial locations that correspond to image data from a single framelet, the geometry values are computed using the time and spacecraft position for the framelet. For spatial locations that correspond to image data from two framelets, the geometry values are computed using the time and spacecraft position for the EARLIER of the two framelets. Note that using TOP=NO (which is NOT the default parameter value) when running "thmvismc" will result in image data for the reference band that corresponds to the computed geometry values in the areas where framelets overlap.
There are two ways to obtain geometry values based on a band that is different from the "reference" band described above (first file band for an UNPROJECTED file, reference band for an IRIC file, middle file band for an IRMC or VISMC file). First, the "dsk2dsk" program can be run using the SFROM parameter to extract just the band of interest into a separate file. Then, compute the geometry values using this single-band file. Second, the "labels" program can be used to set the REFERENCE_INSTRUMENT_BAND keyword in the VOLATILE_INFO keyword Group to the desired band number. In this case, the value should be set to the desired INSTRUMENT band number (not the file band number). Then, compute the geometry values using this updated IRMC or VISMC file.
IMPORTANT NOTE #1: The Mars target definition file to be used is determined when you run "thm2isis" to translate the .QUB file into an ISIS format file. The "thm2isis" TARGDEF parameter specifies the target definition file to be used. The default value is the Null TAE parameter value, which will result in using the latest version of mars.def.N in $ISISDATA/targets/. When the mars.def.4 file is used, you will get coordinates consistent with the 2000 IAU report. Also, note that this will produce longitudes that increase to the EAST. The previous ".3" version of this file produced longitudes that increase to the WEST. You can specify a specific target definition file to be used by specifying it's name and location in the "thm2isis" TARGDEF parameter. For example, TARGDEF="$ISISDATA/targets/MDIM1.0.west.def" will give you coordinates that are consistent with MDIM 1.0.
The TARGDEF keyword in the ISIS_TARGET keyword Group in the ISIS file records the name of the target definition file that is being used.
IMPORTANT NOTE #2: When the software automatically uses the latest version of a file (e.g., thm2isis_translation.def.N or mars.def.N), it uses the following algorithm to find the "latest version". It first looks for a ".1" version. Then it looks for a ".2" version. If ".2" does not exist, it assumes ".1" is the latest version and uses it. Etc. This means that correctly finding the "latest version" depends upon all the previous versions also existing in the directory being searched.
Currently, the software ignores these three because the 8 microseconds is a negligible fraction of the 1/30 second line rate and the other two are (apparently) variable and unknowable. However, this can result in an incorrect absolute position of as much as four pixels.
Similar timing uncertainties probably are applicable to the VIS images.
The effect of these timing uncertainties is primarily to potentially introduce errors in absolute coordinates in the along-track direction. This in turn can result in misalignment when mosaicking multiple observations together.
The TIME parameter on "thm2isis" allows the user to apply a correction for this time delay, which can thus improve absolute coordinate accuracy and improve mosaic alignments.
UNCORRECTED_SCLK_START_COUNT (in the SPECTRAL_QUBE object) - The commanded time for the start of the observation. SPACECRAFT_CLOCK_START_COUNT (not in any Group or Object) - For IR, this is the time corresponding to the first line of data for Filter number 1 (even if Filter number 1 data are not contained in the file). For IR, it is always the same as UNCORRECTED_SCLK_START_COUNT. For VIS, this is the time corresponding to the first framelet of data for Filter number 1 (even if Filter number 1 data are not contained in the file). If Filter number 1 data are included in the file, then this will be the same value as UNCORRECTED_SCLK_START_COUNT. If Filter number 1 data are not contained in the file, then this could differ from UNCORRECTED_SCLK_START_COUNT by as much as four times the INTERFRAME_DELAY (usually 1.0 seconds).The output ISIS files contain THREE keywords that record spacecraft clock times:
UNCORRECTED_SCLK_START_COUNT (in the THEMIS_KEYWORDS Group within the QUBE Object) - A copy of the UNCORRECTED_SCLK_START_COUNT from the input file. SPACECRAFT_CLOCK_START_COUNT (in the THEMIS_KEYWORDS Group within the QUBE Object) - A copy of the SPACECRAFT_CLOCK_START_COUNT from the input file. ORIGINAL_SPACECRAFT_CLOCK_COUNT (in the ISIS_INSTRUMENT Group within the QUBE Object) - Derived from the SPACECRAFT_CLOCK_START_COUNT in the input file by adding the time adjustment specified by the TIME or TIMELIST parameters when running "thm2isis". (This allows the user to apply corrections for the time delay between the commanded start of observation and the actual start of observation.) This is the time that is used by the ISIS geometry software. (It is confusing that this adjusted time is recorded in a keyword whose name starts with "ORIGINAL_". However, this keyword name is used to be consistent with the corresponding keyword used in previous missions for recording the observation time.)
The Frames Kernel file that should be used is the latest that is available from the NAIF ftp site, which as of the time of writing this document is m01_v26.tf. This includes the latest values for the yaw rotation of the IR detector (-0.672 degrees) and the yaw rotation of the VIS detector (-0.25 degrees). (Previously, a USGS-modified version of m01_v23.tf needed to be used because the latest alignment angles had not yet been incorporated into the NAIF-supplied file.)
If you are maintaining your own thm_kernels.def.N file, you should make sure your file lists m01_v26.tf rather than some other version of this file.
The $ISISM01DATA directory contains the mars_iau2000_v0.tpc file, which contains Mars planetary constants for use by THEMIS. However, the ISIS software does not use this file. Instead, it uses the $ISISDATA/targets/mars.def.N file to obtain constants for Mars. The mars.def.4 file contains constants that are identical to the values in mars_iau2000_v0.tpc.
To allow dealing with these missing camera pointing data, the NAIF team has prepared special CK files that contain "fake" nadir pointing data. Images that have missing "real" camera pointing data can be projected using the "fake" nadir camera pointing data. The THEMIS IR and VIS instruments are usually pointing close to nadir, so using the nadir pointing data will produce projected images that are close to being "correct." However, there will probably be some errors in absolute coordinates because the true pointing is not exactly nadir.
There are two ways to use the "fake" nadir camera pointing data. First, the "thm2isis" KERNLST parameter can be set to $ISISM01DATA/thm_kernels_nadir.def.N rather than its default value. This kernel list includes only the "fake" nadir data and none of the "real" camera pointing data. This will thus force the use of the nadir data, even if "real" pointing data exists for the image.
In some cases, it might be useful to use the $ISISM01DATA/thm_kernels_both.def.N for the KERNLST. This file lists both the "real" camera pointing kernel files and the "fake" nadir pointing kernel files. In most cases, if "real" camera pointing is available then it will be used, and the nadir pointing will automatically be used if "real" pointing is not available. However, there might be some images for which "thm2isis" succeeds with finding "real" pointing but "thmirmc" or "thmvismc" fails because there is "real" pointing for only part of the image. These images will have to be processed using thm_kernels_nadir.def.N to force use of the nadir pointing. (For efficiency, "levinit" (called by "thm2isis" to select a single camera pointing file) does a partial check for pointing data and might choose a CK file that contains pointing for only part of the image.)
Note that the KERNLST keyword in the ISIS_GEOMETRY Group in the ISIS cube file records which kernel list was used. Also, the CAMERA_KERNELS keyword in this Group records the name of the CK file that was used, which will indicate whether "real" pointing or "fake" nadir pointing was used. The "fake" nadir files have "nadir" in the filename, e.g., m01_sc_map2_rec_nadir.bc.
The THEMIS software does not yet use the latest version of the NAIF routines, so you will need to use SPICE files that are in the appropriate format (Sun or PC) for the computer architecture.
The THEMIS SPICE files can be obtained at the NAIF ftp site:
Note that in addition to adding recent spacecraft (SPK) and camera (CK) SPICE kernel files, it is important to use the latest file that defines the mapping from Spacecraft Clock (SCLK) values into "real" time. These files have names of the form ORB1_SCLKSCET.nnnnn.tsc, where "nnnnn" is a version number. These are in the sclk subdirectory of the NAIF ftp site. While the mission is ongoing, a new version of this file is made available every 2-4 weeks. If you are not using a recent enough version of this file for the observation being processed, then an extrapolation will be used for the time mapping. This can lead to time errors and thus errors in absolute coordinates for the projected images.
The "thmiric", "thmirmc", and "thmvismc" scripts can be used to concurrently process different input IR and/or VIS files in the same directory. However, whenever concurrent ISIS processing is done in one directory, you should prevent conflicts with access to the ISIS Session Log File. By default, a session log of ISIS processing is written to the print.prt file. The ISIS_LOG_FILE environment variable can be set to the name of another file to be used for the session log file. This should be used to prevent multiple concurrent processes from attempting to write to the same session log file at the same time.
So, for mosaicking images near longitude=0, you need to get all you images to use the -180 to +180 system. You could do this by specifying LONSYS=180 when you run "thm2isis" on all your images. You could also just run "levinit" on the output of "thm2isis" to set the longitude system to -180 to +180 for each of the images. You could also just run the "labels" program to set the LONGITUDE_SYSTEM keyword in the ISIS_TARGET keyword Group to the integer value 180. (Running "labels" would be more efficient than re-running "levinit".)
In a similar manner, when an image is initialized for the +/- 180 system, by default it will be switched to the 360 system if it crosses longitude=180.
This automatic switching of the longitude system can be turned off by setting AUTOLON=NO when running "thmirmc" or "thmvismc". When doing this, the LATRANGE and LONRANGE parameters can also be set to specify the desired latitude/longitude range for the projected image. This can be useful for doing things such as producing images for mosaics of the polar regions in four separate quadrants using a consistent longitude system.
In a similar manner, "levpt", "lev1stats", and "levgeoplane" are not able to use the MOLA DEM. This can result in small errors in the geometry values that these programs calculate.
The TIME parameter on "thm2isis" allows the user to apply a correction for this uncertain time delay.
These pointing variations can also cause errors in projected IR images, but it is less of a problem with IR due to the lower spatial resolution and the Time Delay Integration (TDI), which effectively averages 16 observations taken over approximately 1/2 second.