phocube

This program, phocube, creates backplane bands that contain photometric, geometric, and spacecraft instrument information for an image file. The parameter options range from photometric angles (incidence, emission, and phase) to various azimuth angles, and options based on spatial (latitude, longitude, and resolution) information. This program will not work on Level1 images without a camera model, or on mosaics. The input image pixels are not propagated to the output file unless the user selects the "DN" option. The following is a partial list of how users have made use of band output:

• Evaluate the individual bands in order to establish subsequent image processing steps
• Specify as input to other ISIS programs such as fx and photomet
• Demonstrate the result of each selected option
• Determine how the images are mosaicked together after the Level2 images are created from the Level1 images with backplanes

All ISIS applications default to the following geometric reference if a camera model exists:

• Longitude Domain = 360, longitude range reported from 0 to 360
• Latitude System = Ocentric
• Longitude Direction = East, longitude increases to the east

There are instances where the local emission angle and the local incidence angle will have values over 90 degrees. ISIS allows the computation of emission and incidence angles greater than 90 degrees. This feature allows representation of viewing and illumination conditions where there is actual target body surface data beyond the limb or deep terminator boundary areas. Applications such as photomet that applies photometric functions honor the 90-degree boundary. Applications such as photrim can be applied to the phocube output to replace the angle values above 90 degrees to NULL. There are certain processes that need these data, therefore it is allowed.

This program requires a Level1 file that has a successful "spiceinit" applied to it, or a Level2 image cube file. For every valid input pixel, an output pixel is computed based on either the SPICE information, or the map projected spatial information, or a pre-defined equation.

The parameters "morphologyRank" and "albedoRank" are specifically designed to be used by the ISIS mosaic programs. A mosaic program will automatically compare two pixel values to determine how each pixel is mosaicked into an output file, which depends on whether a morphology-based or an albedo-based product is desired. The program computes a DN value for every input pixel based on the formulas listed below and outputs the value to a backplane band. These backplane bands are used by the ISIS mosaic programs. The following are equations for "morphologyRank" and "albedoRank" options:

MorphologyRank

Equation = PixelResolution/cos(EmissionAngle)

AlbedoRank

Equation = PixelResolution * [(1/cos(EmissionAngle)) + (1/cos(IncidenceAngle))]

All the options in phocube are applicable if the input file is a Level1 image and has a camera model associated with the file. If the input file is a map-projected Level2 image, only a few options are appropriate and available for selection.

The following options are available for Level1 images that contain a camera model:

• DN
• EMISSION
• INCIDENCE
• PHASE
• OFFNADIRANGLE
• LOCALEMISSION
• LOCALINCIDENCE
• LATITUDE
• LONGITUDE
• DETECTORRESOLUTION
• OBLIQUEDETECTORRESOLUTION
• PIXELRESOLUTION
• LINERESOLUTION
• SAMPLERESOLUTION
• NORTHAZIMUTH
• SUNAZIMUTH
• SPACECRAFTAZIMUTH
• SUBSPACECRAFTGROUNDAZIMUTH
• SUBSOLARGROUNDAZIMUTH
• MORPHOLOGYRANK
• ALBEDORANK
• BODYFIXED
• RADEC (Right Ascension, Declination )
• LOCALTIME
• SUNILLUMINATIONMASK
• SURFACEOBLIQUEDETECTORRESOLUTION

The following options are available for Level2 images:

• DN
• LATITUDE
• LONGITUDE
• PIXELRESOLUTION

The BandBin group keywords are updated in the labels of the output cube file. The keyword "Name" within the BandBin group, shown below, is populated with the name of each option selected by the user as bands. These bands can be referenced by their names in applications such as "mapmos" and "qview."

    Example:

    phocube from=EW0131773041G_cal.cub to=EW0131773041G_cal.pho.cub morph=true dn=true

    Sample of image label:

    Group = Dimensions
      Samples = 1024
      Lines   = 1024
      Bands   = 7 
    End_Group
    
    Group = BandBin
      Name   = ("750 BW 5", "Phase Angle", "Emission Angle", "Incidence Angle",
          Latitude, Longitude, Morphology)
      Number = (7, 7, 7, 7, 7, 7, 7)
      Center = (748.7, 748.7, 748.7, 748.7, 748.7, 748.7, 748.7)
      Width  = (5.1, 5.1, 5.1, 5.1, 5.1, 5.1, 5.1)
    End_Group
    

    Note:  The first band retained the BandBin Name value from the input file.
    The program has "Phase Angle," "Emission Angle," "Incidence Angle,"
    "Latitude," and "Longitude" options pre-selected.
    

If the backplane bands generated by phocube are used in the mosaic programs and the mosaic requires the input image pixel, the "DN" parameter name must be set to "true" in phocube. When backplane bands are used in the "fx" or "photomet" program, it is not necessary to propagate the input image to the output file.

Description

This is the input filename. The input image cube can be a Level1 or Level2 file. For a Level1 image, spiceinit must be successfully applied before running phocube.

Type	cube
File Mode	input
Filter	*.cub

Description

This is the output file name. The cube file will contain a band for each of the selected options. The BandBin Group in the image labels of the output cube file will be updated with the "Name" keyword containing the output band names (options) in the order that they are stacked within the cube.

Type	cube
File Mode	output
Pixel Type	real

Description

Specifies whether the geometric information will be obtained from the camera model or from the map projection. If this parameter is set to CAMERA, all band options are available for the user to select. If this parameter is set to PROJECTION, then only DN, LATITUDE, LONGITUDE, and PIXELRESOLUTION band options are available and all other options will be greyed out. If the user sets this parameter to CAMERA and the input file does not contain a camera model or SPICE information, then an error message will occur.

Type	string
Default	CAMERA
Option List:	Option Brief Description CAMERA Get the geometric information from camera model The geometric information is obtained from a camera model and all band options are available for selection. PROJECTION Get the geometric information based on map projection information The geometric information is obtained based on the label keyword values stored under the "Mapping" group in the image labels. Only DN, LATITUDE, LONGITUDE, and PIXELRESOLUTION band options are available. Exclusions PHASE EMISSION INCIDENCE LOCALEMISSION LOCALINCIDENCE LINERESOLUTION SAMPLERESOLUTION DETECTORRESOLUTION OBLIQUEDETECTORRESOLUTION SUNAZIMUTH SPACECRAFTAZIMUTH OFFNADIRANGLE SUBSPACECRAFTGROUNDAZIMUTH SUBSOLARGROUNDAZIMUTH MORPHOLOGYRANK ALBEDORANK NORTHAZIMUTH RADEC BODYFIXED LOCALTIME SUNILLUMINATIONMASK SURFACEOBLIQUEDETECTORRESOLUTION

Description

Controls the output of the values phocube calculates based on the DN from the first band. If this parameter is true, phocube will always attempt to calculate values for the requested bands. If this parameter is false, and the DN is a special pixel value, phocube will not calculate values, and will instead place ISIS Null values in all requested photometry bands. The DN bands, if requested, will be transferred to the output cube regardless of this setting.

Type	boolean
Default	TRUE

Description

This parameter specifies whether the input image pixel value (DN) will be propagated to the output file. The DN parameter must be set to "true," if the output product created is expected to contain the input image information.

Type	boolean
Default	FALSE

Description

If this parameter is true, all the DN values from all of the bands in the input image, subject to the input cube attribute, will be propagated to the output file. Calculations for the other bands that require a sensor model (e.g., phase) will be based on the first band, again subject to the cube attribute. This doesn't affect the values calculated for those bands when the input image bands are spatially aligned, but it is very import when the bands of the input image are not spatially aligned (e.g., Level 1, Odyssey, Themis IR). Use the input cube attribute to select the band used to calculate the other phocube values (e.g., ThemisIR.cub+9,1-5). The geometry of the first band or the first band in the input attribute, will be used to calculate the phocube values. NOTE: If the DN parameter is also set then ALLDNS will take precedence, and DN will be ignored.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Phase Angle will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Phase Angle" in the BandBin group, in band sequence of the output file. Phase angles are in degrees.

Type	boolean
Default	TRUE

Description

If this parameter is true, the Emission Angle will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Emission Angle" in the BandBin group, in band sequence of the output file. Emission angles are in degrees. There are certain cases where the emission angle is over 90 degrees. This is allowed as there are processes that need these data. See main description for details.

Type	boolean
Default	TRUE

Description

If this parameter is true, the Incidence Angle will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Incidence Angle" in the BandBin group, in band sequence of the output file. Incidence angles are in degrees. There are certain cases where the incidence angle is over 90 degrees. This is allowed as there are processes that need these data. See main description for details.

Type	boolean
Default	TRUE

Description

If this parameter is true, the Local Emission Angle will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Local Emission Angle" in the BandBin group, in band sequence of the output file. LocalEmissionAngle is in degrees. There are certain cases where the local emission angle is over 90 degrees. This is allowed as there are processes that need these data. See main description for details.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Local Incidence Angle will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Local Incidence Angle" in the BandBin group, in band sequence of the output file. LocalIncidenceAngle is in degrees. There are certain cases where the local incidence angle is over 90 degrees. This is allowed as there are processes that need these data. See main description for details.

Type	boolean
Default	FALSE

Description

If this parameter is true, the latitude value will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Latitude" in the BandBin group, in band sequence of the output file. Latitude is in degrees.

Type	boolean
Default	TRUE

Description

If this parameter is true, the longitude value will be computed for every pixel placed in a band in the output cube. The output cube labels will contain "Longitude" in the BandBin group, in band sequence of the output file. Longitude is in degrees.

Type	boolean
Default	TRUE

Description

If this parameter is true, the Pixel Resolution will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Pixel Resolution" in the BandBin group, in band sequence of the output file. PixelResolution is in meters.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Line Resolution will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Line Resolution" in the BandBin group, in band sequence of the output file. LineResolution is in meters.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Sample Resolution will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Sample Resolution" in the BandBin group, in band sequence of the output file. SampleResolution is in meters.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Detector Resolution will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Detector Resolution" in the BandBin group, in band sequence of the output file. DetectorResolution is in millimeters.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Oblique Detector Resolution will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Oblique Detector Resolution" in the BandBin group, in band sequence of the output file. ObliqueDetectorResolution is in millimeters.

Type	boolean
Default	FALSE

Description

If this parameter is true, the North Azimuth will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "North Azimuth" in the BandBin group, in band sequence of the output file. NorthAzimuth is in degrees.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Sun Azimuth will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Sun Azimuth" in the BandBin group, in band sequence of the output file. SunAzimuth is in degrees.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Spacecraft Azimuth will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Spacecraft Azimuth" in the BandBin group, in band sequence of the output file. SpacecraftAzimuth is in degrees.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Off Nadir Angle will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "OffNadir Angle" in the BandBin group, in band sequence of the output file. OffNadirAngle is in degrees.

Type	boolean
Default	FALSE

Description

If this parameter is true, the slope will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Slope" in the BandBin group, in band sequence of the output file. The slope is in degrees with 0 degrees being perfectly flat and 90 degrees being sheer vertical.

Note: The slope is measured relative to a sphere and not a more complex datum like the gravity model

If computing slopes, the input image must be a level1 image. To compute slopes for a level2 DEM use slpmap.

Type	boolean
Default	FALSE

Description

If this parameter is true, a local normal will be computed for every pixel based on the shapemodel of the cube, and placed in three bands (X, Y, Z) in the output cube. Meaning if your cube has an ellipsoid shapemodel rather than a DEM, the local normal and the ellipsoid normal will look the same. The output cube labels will contain three "Local Normal (coord)" keywords in the BandBin group, in band sequence of the output file.

Note: These X, Y, and Z bands are in the body fixed reference frame.

Type	boolean
Default	FALSE

Description

If this parameter is true, the ellipsoid normal will be computed for every pixel and placed in three bands (X, Y, Z) in the output cube. This normal will always be computed with a triaxial ellipsoid regardless of shapemodel. The output cube labels will contain three "Ellipsoid Normal (coord)" keywords in the BandBin group, in band sequence of the output file.

Note: These X, Y, and Z bands are in the body fixed reference frame.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Spacecraft Ground Azimuth will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Sub Spacecraft Ground Azimuth" in the BandBin group, in band sequence of the output file. SubSpacecraftGround Azimuth is in degrees.

Type	boolean
Default	FALSE

Description

If this parameter is true, the SubSolar Ground Azimuth will be computed for every pixel and placed in a band in the output cube. The output cube labels will contain "Sub Solar Ground Azimuth" in the BandBin group, in band sequence of the output file. SubSolarGroundAzimuth is in degrees.

Type	boolean
Default	FALSE

Description

This band is computed from the pixel resolution and emission angle using the following formula:

MorphologyRank = PixelResolution / cos(EmissionAngle)

The resulting output band can be used by automos to create a morphology-based mosaic product. This option uses the local emission angle if the input file is initialized (spiceinit) with an elevation model (DEM); otherwise, it uses the default calculation (from the ellipsoid). All computed cosines are tested for zero. If the result is zero, then the value is set to a constant value very close to zero.

Append the following parameters to the automos command line to utilize this backplane band:

priority=band type=keyword keyname=Name keyvalue=morphologyRank criteria=lesser.

See automos documentation for further details.

Type	boolean
Default	FALSE

Description

This band is computed from the pixel resolution, incidence angle and emission angle using the following formula:

AlbedoRank = PixelResolution * [(1 / cos(EmissionAngle)) + (1 / cos(IncidenceAngle))]

The resulting output band can be used by automos to create an albedo-based mosaic product. This option always uses the local emission angle and local incidence angle if the input file is initialized (spiceinit) with an elevation model (DEM); otherwise, it uses the default calculation (from the ellipsoid). All computed cosines are tested for zero. If the result is zero, then the value is set to a constant value very close to zero.

Append the following parameters to the automos command line to utilize this backplane band:

priority=band type=keyword keyname=Name keyvalue=albedoRank criteria=lesser.

See automos documentation for further details.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Right Ascension, and the Declination will be calculated for every pixel and each will be placed into their respective bands in the output cube. The output cube labels will contain "Right Ascension" and "Declination" in the BandBin group, in the band sequence of the output file. Right Ascension and Declination are in degrees.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Body Fixed Coordinates will be calculated for every pixel and the values for X, Y, and Z will each be placed into their own bands in the output cube. The output cube labels will contain "Body Fixed X", "Body Fixed Y", and "Body Fixed Z" in the BandBin group, in the band sequence of the output file. Body Fixed Coordinates are in kilometers.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Local Solar Time will be calculated for every pixel in the output cube. The output cube label will contain "Local Solar Time" in the BandBin group. Local Solar Time is in hours.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Solar Illumination Mask (or shadow mask), will be determined for every pixel. This option is primarily useful for small irregular bodies (e.g. comets, asteroids), where terrain is occluded from solar illumination at the surface intersection point at a given pixel. This information cannot be provided solely by incidence or local incidence angles as the occlusion occurs due to foreground terrain, such as lobes in comets, at much larger distances than the proximity of the initial surface point of intersection. The output cube label will contain "Sun Illumination Mask" in the BandBin group, in band sequence of the output file.

The output mask pixel is a boolean value computed using ray trace functions. Pixels are either 1 (illuminated) or 0 (shadowed). A look direction from the sun is computed to the spacecraft (camera) pixel intercept location on the surface. If the solar intercept point on the surface is not the same point as seen from the spacecraft/camera perspective, it is deemed occluded (shadowed). For tessellated plate shape models, which are often used to represent the shape of irregular bodies, both camera and solar surface intercept points must occur on the same triangle at approximately the same location.

If the surface point is occluded/shadowed, a 0 (false) value is written as the output pixel mask value indicating it is not illuminated by the sun. All other cases will result in setting the output pixel mask value to 1 (true) indicating illumination by the sun. Note this mask will also include (i.e., identify pixels in) the local incidence backplane where the angles are greater than 90 degrees.

Note: The computation of this backplane is not supported for all ISIS shape models or for the ellipsoid. At this time we know that it functions properly using the Bullet ray trace engine.

Type	boolean
Default	FALSE

Description

If this parameter is true, the Surface Oblique Detector Resolution will be computed for every pixel and placed in a band in the output cube. This value differs from the Oblique Detector Resolution due to use of the local emission angle for that data. It is computed using the emission angle computed from the ellipsoid, which will produce a smoother data plane. The output cube label will contain "Surface Oblique Detector Resolution" in the BandBin group, in band sequence of the output file. SurfaceObliqueDetectorResolution is in millimeters.

Note: The computation of this backplane is not supported for all ISIS shape models or for the ellipsoid. At this time we know that it functions properly using the Bullet ray trace engine.

Type	boolean
Default	FALSE

Within this example, phocube creates an output file with two bands that contain latitude information and computed morphologyRank values, which are shown below as separate snapshots under "Output Images." The input image file shown below under "Input Image" was not propagated to the phocube output file because DN is set to false. If the phocube output file is projected and mosaicked, the mosaic file will contain the latitude information for the first band and the "morphologyRank" values for the second band, but no image information from the input image will be included. The "DN" parameter must be set to "true" if the output product is expected to contain the input image.

phocube from=EW0131773041G_cal.cub to=EW0131773041G_cal.pho.cub phase=no emission=no incidence=no longitude=no morphologyRank=yes

phocube GUI

Example GUI Screenshot of GUI version of the application. For this example, only "LATITUDE" and "MORPHOLOGYRANK" are selected. The pre-selected options "PHASE," "EMISSION," "INCIDENCE," and "LONGITUDE" are deselected to avoid creating these unwanted backplanes.

Input image

Input file Parameter Name: FROM Screenshot of the input cube file.

Output image band 1 (latitude)	Output file band 1 (Latitude) Parameter Name: TO Screenshot of the first band in the output file. This file contains the latitude information with -72.2 degree as the minimum, and 6.27 degree as the maximum value.
Output image band 2 (morphologyRank)	Output file band 2 (MorphologyRank) Parameter Name: TO Screenshot of the second band in the output file. This file contains the computed morphologyRank values with 0.0 as the minimum, and 15.0 as the maximum value. The minimum and maximum values were manually selected to brighten the image for visual presentation. The actual range is between 2.8 and 41.5 DN values.

In this example, phocube creates an output cube file with a sun illumination backplane and a surface oblique detector resolution backplane. These backplanes are shown below as separate snapshots under "Output Images." The input image file shown below under "Input Image" was not propagated to the phocube output file because DN is set to false. The "DN" parameter must be set to "true" if the output product is expected to contain the input image.

phocube from=20190425T211232S312_map_iofL2pan.cub to=20190425T211232S312_map_iofL2pan.pho.cub specialpixels=no phase=no emission=no incidence=no latitude=no longitude=no sunilluminationmask=yes surfaceobliquedetectorresolution=yes

phocube GUI

Example GUI Screenshot of GUI version of the application. For this example, only "SUNILLUMINATIONMASK" and "SURFACEOBLIQUEDETECTORRESOLUTION" are selected. The pre-selected options "PHASE," "EMISSION," "INCIDENCE," "LATITUDE," and "LONGITUDE" are deselected to avoid creating these unwanted backplanes.

Input image

Input file Parameter Name: FROM Screenshot of the input cube file.

Output image band 1 (Sun Illumination Mask)

Output file band 1 (SunIlluminationMask) Parameter Name: TO Screenshot of the first band in the output file. This band contains sun illumination information. Occluded and illuminated pixel values are 0 and 1 respectively.

Output image band 2 (Surface Oblique Detector Resolution)

Output file band 2 (SurfaceObliqueDetectorResolution) Parameter Name: TO Screenshot of the second band in the output file containing Surface Oblique Detector Resolution information computed using the emission angle determined from the ellipsoid. This produces a smoother data plane compared to that created with the Oblique Detector Resolution option, which is computed using the local emission angle from the shape model.