Home
About ISIS
Support
Download

ISIS

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation

phocube

Printer Friendly View | TOC | Home

Create photometric and geometric information bands for an image cube

Overview Parameters Example 1

Description

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:

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.

Categories

Related Applications to Previous Versions of ISIS

This program replaces the following applications existing in previous versions of ISIS:
  • lev1geoplane
  • levgeoplane
  • geoback

Related Objects and Documents

Applications

History

Unknown1999-02-11 Original version.
Stuart Sides2003-06-04 Converted to ISIS3, and made it create a cube rather than adding backplanes.
Stuart Sides2003-07-29 Modified filename parameters to be cube parameters where necessary.
Stuart Sides2005-09-09 Fixed problem where the program threw an error when it tried to propagate the pixel type from the input file.
Stuart Sides2005-09-09 Added the bandbin group to the cube labels.
Jeff Anderson2005-09-20 Fixed a bug with switched samples and lines.
Elizabeth Miller2005-10-05 Moved into Photometry and Radiometry category.
Elizabeth Miller2006-05-23 Modified to use ProcessByBrick instead of ProcessByLine to make faster.
Brendan George2006-09-21 Documentation fixes.
Steven Lambright2008-05-13 Removed references to CubeInfo.
Steven Koechle2008-08-19 Added new parameters: PIXELRESOLUTION, LINERESOLUTION, SAMPLERESOLUTION, DETECTORRESOLUTION, NORTHAZIMUTH, SUNAZIMUTH, SPACECRAFTAZIMUTH, OFFNADIRANGLE.
Steven Lambright2009-03-06 Fixed a bug that occurred when processing band-dependent cubes.
Kris Becker2009-05-29 Added the propagation of the input cube labels, objects, blobs, etc..., so the pedigree of the input source is retained.
Sharmila Prasad2009-07-17 Set the defaults for PIXELRESOLUTION, LINERESOLUTION, SAMPLERESOLUTION, DETECTORRESOLUTION, NORTHAZIMUTH, SUNAZIMUTH, SPACECRAFTAZIMUTH, and OFFNADIRANGLE to FALSE.
Mackenzie Boyd2010-10-29 Added parameters/bands SUBSPACECRAFTGROUNDAZIMUTH and SUBSOLARGROUNDAZIMUTH.
Travis Addair2011-02-10 Added parameters LOCALINCIDENCE and LOCALEMISSION.
Kris Becker2011-08-08 Added the option to propagate the input pixel value (DN) as the first band (however, this, by default, will not be invoked as default so as to preserve pre-existing behavior). Ensure the Center, OriginalBand, Name, and Width BandBin keyword values are populated properly and propagated to the output label (should support camera models). Added MORPHOLOGY and ALBEDO backplane options for special mosaic options.
Janet Barrett2012-02-22 Added the capability to run this program on image files where the camera information is missing. The ability to generate lat/lon bands for image files is highly useful when performing fx operations on the files. Other bands that can be created for a mosaic file include: Dn and PixelResolution. A new parameter, SOURCE, was added so that the user can specify if their image does not contain a camera model. This will result in the appropriate parameter choices being greyed out. If the user does not specify that their file does not contain a camera model, then they will receive an error if they choose to create a band that cannot be created for the file.
Debbie A. Cook2012-07-06 Updated Spice members to be more compliant with ISIS coding standards. References #972.
Ella Mae Lee2012-11-15 Improved documentation, fixes #1254.
Tracie Sucharski2012-12-06 Changed to use TProjection instead of Projection. References #775
Tracie Sucharski2013-01-10 Allow input cubes without the BandBin label group. Fixes #929.
Lynn Weller2013-02-25 Removed links to applications imbedded in text and replaced with italicized application name. Added application links to the "Related Objects and Documents" section of the documentation. Fixes mantis ticket #1525.
Kimberly Oyama2013-11-20 The error thrown when the input is a projected image was misleading. It has been fixed to be more helpful for the user. Fixes #923.
Makayla Shepherd2015-02-06 Updated documentation. Fixes #1001.
Makayla Shepherd2015-07-02 Added Ra/Dec and Body Fixed Coordinates options to help create new camera models and help with mission team operations. References #2277.
Tyler Wilson2016-08-17 Added an ObliqueDetectorResolution band. This is an improvement over the previous DetectorResolution function (particularly for images taken near the limb of the target). References #476, #4100.
Kaj Williams2017-06-09 Renamed albedo to albedoRank, and morph (or morphology) to morphRank (or MorphologyRank). Ref #4008.
Kaitlyn Lee2019-02-15 Allowed RA and DEC to be exported regardless if the pixel is off body. Fixes #4446.
Kaitlyn Lee2020-06-04 Added SPECIALPIXELS parameter to allow users to skip calculations on special pixels, excluding RA and DEC. This changed merged the two process functions, which were created to speed up the application when copying over DN values. After a few time tests, it doesn't look like the merge causes the application to run longer. Changed the process function to be a lambda function to get rid of global variables.
Kristin Berry2020-06-10 Added the LOCALTIME parameter to output a band with the local solar time for each pixel. Fixes #3850
Kaitlyn Lee2020-03-15 Converted application and tests for Gtest conversion.

Parameter Groups

Files

Name Description
FROM Input cube file
TO Output cube file
SOURCESpecifies the source of the geometric information

Photometry

Name Description
SPECIALPIXELSInclude special pixels in the ouptut image
DNPropagate the input pixel to the output file
PHASECreate a phase angle band
EMISSIONCreate an emission angle band
INCIDENCECreate an incidence angle band
LOCALEMISSIONCreate a local emission angle band
LOCALINCIDENCECreate a local incidence angle band
LATITUDECreate a latitude band
LONGITUDECreate a longitude band
PIXELRESOLUTIONCreate a pixel resolution band
LINERESOLUTIONCreate a line resolution band
SAMPLERESOLUTIONCreate a sample resolution band
DETECTORRESOLUTIONCreate a detector resolution band
OBLIQUEDETECTORRESOLUTIONCreate an oblique detector resolution band
NORTHAZIMUTHCreate a north azimuth band
SUNAZIMUTHCreate a sun azimuth band
SPACECRAFTAZIMUTHCreate a spacecraft azimuth band
OFFNADIRANGLECreate an offNadir angle band
SUBSPACECRAFTGROUNDAZIMUTHCreate a sub spacecraft ground azimuth band
SUBSOLARGROUNDAZIMUTHCreate a sub solar ground azimuth band
MORPHOLOGYRANKCreate a morphology rank band, used for ranking images based on favorable local emission angles.
ALBEDORANKCreate an albedo rank band, used for ranking images based on favorable emission and incidence angles.
RADECCreate bands for Right Ascension and Declination
BODYFIXEDCreate bands for the X, Y, and Z Body Fixed Coordinates
LOCALTIMECreate a band with local solar time
X

Files: FROM

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
Close Window
X

Files: TO

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
Close Window
X

Files: SOURCE

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
CAMERAGet the geometric information from camera model The geometric information is obtained from a camera model and all band options are available for selection.
PROJECTIONGet 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
Close Window
X

Photometry: SPECIALPIXELS

Description

If this parameter is true, calculations will be done on special pixels. If this parameter is false, special pixels will be skipped and set to NULL in the output image for all bands selected.

Type boolean
Default TRUE
Close Window
X

Photometry: DN

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
Close Window
X

Photometry: PHASE

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
Close Window
X

Photometry: EMISSION

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
Close Window
X

Photometry: INCIDENCE

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
Close Window
X

Photometry: LOCALEMISSION

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
Close Window
X

Photometry: LOCALINCIDENCE

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
Close Window
X

Photometry: LATITUDE

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
Close Window
X

Photometry: LONGITUDE

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
Close Window
X

Photometry: PIXELRESOLUTION

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
Close Window
X

Photometry: LINERESOLUTION

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
Close Window
X

Photometry: SAMPLERESOLUTION

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
Close Window
X

Photometry: DETECTORRESOLUTION

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
Close Window
X

Photometry: OBLIQUEDETECTORRESOLUTION

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
Close Window
X

Photometry: NORTHAZIMUTH

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
Close Window
X

Photometry: SUNAZIMUTH

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
Close Window
X

Photometry: SPACECRAFTAZIMUTH

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
Close Window
X

Photometry: OFFNADIRANGLE

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
Close Window
X

Photometry: SUBSPACECRAFTGROUNDAZIMUTH

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
Close Window
X

Photometry: SUBSOLARGROUNDAZIMUTH

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
Close Window
X

Photometry: MORPHOLOGYRANK

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
Close Window
X

Photometry: ALBEDORANK

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
Close Window
X

Photometry: RADEC

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
Close Window
X

Photometry: BODYFIXED

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
Close Window
X

Photometry: LOCALTIME

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
Close Window

Example 1

Create latitude and morphologyRank backplane bands

Description

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.

Command Line

phocube from=EW0131773041G_cal.cub to=EW0131773041G_cal.pho.cub phase=no emission=no incidence=no longitude=no morphologyRank=yes
Run phocube to create latitude and morphologyRank bands.

GUI Screenshot

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 image

Input file

Parameter Name: FROM

Screenshot of the input cube file.

Output Images

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.