photemplate

This program creates a PVL template file to be used in photometry-based applications, such as photomet. Each planet has different surface and atmospheric properties requiring different model specifications. It is important to set up the models with unique parameter values that apply to a specific planetary body. There are two types of correction models that can be specified in this program:

1. Photometric - describes the planetary surface of an image
2. Atmospheric - applies to the atmosphere through which an image was acquired

The normalization models are not specified in this program, but only three models (albedoatm, shadeatm, and topoatm) apply atmosperheric correction. Choose an atmospheric model only if one of the three normalization models listed above will be applied with the photomet program.

This program allows the use of a PVL file that contains preset parameter names for different photometric and atmospheric models. NOTE: if the user leaves the ZEROB0STANDARD parameter set to READFROMPVL and does not provide an input PVL file, then the ZEROB0STANDARD parameter will default to TRUE. Within the GUI, the user may select a PVL file and then use the drop-down menu to view the contents of the PVL file or to load the parameter values from the PVL file into the appropriate parameter names in the GUI. Note: If more than one model for "PhtName" or "AtmName" are in the PVL file, then the parameter values for the first model type encountered by the program will be loaded into the GUI. Review the parameter names and values to make sure the correct options and values are displayed before executing the program. Below are examples of parameter settings within a PVL file:

PVL file examples: 
     
  Example 1:				Example 2:		  

  Object = PhotometricModel		Object = PhotometricModel
   Group = Algorithm			  Group = Algorithm
      PhtName = Lambert 		    PhtName = Minnaert
    EndGroup				    K = 0.5
  EndObject				  EndGroup
					EndObject
  
	
  Example 3:				Example 4:		     
  
  Object = PhotometricModel		Object = PhotometricModel
    Group  = Algorithm  		  Group  = Algorithm
      PhtName = Hapkehen  		    PhtName = Lunarlambertmcewen
      Wh = 0.52 			  EndGroup
      Hh = 0.0  			EndObject
      B0 = 0.0
      Theta = 30.0
      Hg1 = 0.213
      Hg2 = 1.0
    EndGroup
  EndObject
  Object = AtmosphericModel
    Group = Algorithm
      AtmName = Hapkeatm2
      Hnorm = 0.003
      Tau = 0.28
      Tauref = 0.0
      Wha = 0.95
      Hga = 0.68
    EndGroup
  EndObject
  
  Example 5:
       
  Object = PhotometricModel
  # For Mars red filter images
  # The phase angles at which the coefficient values for the Lunar Lambert 
  # Empirical L and the Minnaert Empirical K approximation are 
  # calculated, along with the brightness (phase curve) values at those
  # points (ALL ON ONE LINE!)

    Group = Algorithm
      PhtName = LunarLambertEmpirical
      PhaseList = "0.,10.,20.,30.,40.,50.,60.,70.,80.,90.,100.,110.,120.,130.,
                  140.,150.,160.,170.,180."
      LList = "0.946,0.748,0.616,0.522,0.435,0.350,0.266,0.187,0.118,0.062,0.018,
              -0.012,-0.027,-0.035,-0.036,-0.037,-0.031,-0.012,-0.010"
      PhaseCurveList = "0.1578,0.1593,0.1558,0.1484,0.1391,0.1292,0.1194,0.1099,
                       0.1008,0.09176,0.08242,0.07234,0.06165,0.05106,0.04091,
		       0.03137,0.02171,0.01038,0."
    EndGroup

    Group = Algorithm
      PhtName = MinnaertEmpirical
      
      # The numbers below are entered on a single line in the text file for each
  # parameter name (see $ISISROOT/appdata/templates/photometry/marsred.pvl).
      
      PhaseList = "0.,10.,20.,30.,40.,50.,60.,70.,80.,90.,100.,110.,120.,130.,
                  140.,150.,160.,170.,180."
      KList = "0.518,0.595,0.660,0.709,0.753,0.796,0.837,0.875,0.904,0.922,
              0.926,0.935,0.954,0.986,1.019,1.063,1.099,1.095,1.090"
      PhaseCurveList = "0.1574,0.1582,0.1546,0.1470,0.1375,0.1273,0.1174,0.1077,
                       0.09797,0.08750,0.07594,0.06466,0.05471,0.04665,0.03935,
		       0.03339,0.02642,0.01482,0."
    EndGroup
  EndObject 

Below are equations for some of the photometric model functions, where phase is the phase angle, and u0 and u are the cosines of the incidence angle and emission angle, respectively:

SURFACE PHOTOMETRIC FUNCTION

Available photometric models and equations

Photometric Model Name	Function Equation
Lambert	u0
LommelSeeliger	u0/(u0+u)
Minnaert	u0**K * u**(K-1)
LunarLambert ("lunar" part is Lommel-Seeliger)	(1-L)*u0 + 2*L*u0/(u0+u)
MinnaertEmpirical	B(phase) * u0**K(phase) * u**(K(phase)-1)
LunarLambertEmpirical	B(phase) * ((1-L)*u0 + 2*L*u0/(u0+u))
Hapkehen (Hapke-Henyey-Greenstein)	No equation available
Hapkeleg (Hapke-Legendre)	No equation available
LunarLambertMcEwen	No equation available

References:

Chandrasekhar, S., 1960.  Radiative Transfer. Dover, 393 pp.
Hapke, B. W., 1981. Bidirectional reflectance spectroscopy 1: Theory. J. 
   Geophys. Res., pp. 86,3039-3054.
Hapke, B., 1984. Bidirectional reflectance spectroscopy3: Corrections for 
   macroscopic roughness. Icarus, 59, pp. 41-59.
Hapke, B., 1986. Bidirectional reflectance spectroscopy 4: The extinction 
   coefficient and the opposition effect. Icarus, 67, pp. 264-280.
Kirk, R. L., Thompson, K. T., Becker, T. L., and Lee, E. M., 2000. 
   Photometric modelling for planetary cartography. Lunar Planet. Sci., XXXI, 
   Abstract #2025, Lunar and Planetary Institute, Houston (CD-ROM).

See photomet documetation for additional information.

Description

Use this parameter to select an existing PVL filename that contains a description of the photometric properties of a planetary body. The information in this file will be merged with the information that is input through the user interface or command line to create the output PVL file.

Type	filename
File Mode	input
Default Path	$ISISROOT/appdata/templates/photometry
Internal Default	None Specified
Filter	*.pvl

Description

Use this parameter to select or enter the output filename. If the file already exists it will be overwritten. The ".pvl" extension is automatically appended to the filename if no extension is entered.

Type	filename
File Mode	output
Filter	*.pvl

Description

This is the name of the surface photometric function model to use to apply the photometric correction. Both the abbreviated names and the full model names are valid entries.

Type	combo
Default	FROMPVL
Internal Default	FROMPVL
Option List:	Option Brief Description FROMPVL Get photometric model from PVL file Get the photometric model from the PVL file. Add any missing parameters to the PVL file, or enter the values on the command line or use the GUI to enter the values. Exclusions THETA WH HG1 HG2 HH B0 BH CH L K PHASELIST KLIST LLIST PHASECURVELIST ZEROB0STANDARD HAPKEHEN Hapke-Henyey-Greenstein photometric model Derive model albedo using complete Hapke model with Henyey-Greenstein single-particle phase function whose coefficients are hg1 and hg2, plus single scattering albedo wh, opposition surge parameters hh and b0, and macroscopic roughness theta. For a smooth model with opposition effect use theta=0. Exclusions BH CH L K PHASELIST KLIST LLIST PHASECURVELIST Inclusions THETA WH HG1 HG2 HH B0 HAPKELEG Hapke-Legendre photometric model Derive model albedo using complete Hapke model with Henyey Legendre two-term Legendre polynomial phase function whose coefficients are bh and ch, plus single scattering albedo wh, opposition surge parameters hh and b0, and macroscopic roughness theta. Exclusions HG1 HG2 L K PHASELIST KLIST LLIST PHASECURVELIST Inclusions THETA WH BH CH HH B0 LAMBERT Lambert photometric model Simple photometric model which predicts that light incident on a surface is scattered uniformly in all directions; the total amount of reflected light depends on the incidence angle of the illumination. This function does not depend upon the outgoing light direction. Exclusions THETA WH HG1 HG2 HH B0 BH CH L K PHASELIST KLIST LLIST PHASECURVELIST LOMMELSEELIGER Lommel-Seeliger photometric model This model takes into account the radiance that results from single scattering (scattering of collimated incident light) and does not take into account the radiance that results from multiple scattering (scattering of diffuse light which has made its way indirectly to the same position by being scattered one or more times). This model depends on the incidence and emission angles. Exclusions THETA WH HG1 HG2 BH CH HH B0 L K PHASELIST KLIST LLIST PHASECURVELIST LUNARLAMBERT Lunar Lambert photometric model This model combines a weighted sum of the LommelSeeliger and Lambert models. Given a suitable value for the LunarLambert function weight, L, this model fits the true reflectance behavior of many planetary surfaces equally well as the Hapke model. This model also depends on the incidence and emission angles. Exclusions THETA WH HG1 HG2 BH CH HH B0 K PHASELIST KLIST LLIST PHASECURVELIST Inclusions L LUNARLAMBERTEMPIRICAL Lunar Lambert Empirical photometric model This model combines a weighted sum of the LommelSeeliger and Lambert models. Given a suitable value for the LunarLambert function weight, L, this model fits the true reflectance behavior of many planetary surfaces equally well as the Hapke model. This model also depends on the incidence and emission angles. Exclusions THETA WH HG1 HG2 BH CH HH B0 K L KLIST Inclusions PHASELIST LLIST PHASECURVELIST LUNARLAMBERTMCEWEN Lunar Lambert-McEwen photometric model This model was developed specifically for use with the Moon to be used in conjunction with the MoonAlbedo normalization model. Exclusions THETA WH HG1 HG2 BH CH HH B0 L K PHASELIST KLIST LLIST PHASECURVELIST MINNAERT Minnaert photometric model This model combines a weighted sum of the LommelSeeliger and Lambert models. Given a suitable value for the LunarLambert function weight, L, this model fits the true reflectance behavior of many planetary surfaces equally well as the Hapke model. This model also depends on the incidence and emission angles. Exclusions THETA WH HG1 HG2 BH CH HH B0 L PHASELIST KLIST LLIST PHASECURVELIST Inclusions K MINNAERTEMPIRICAL Minnaert Empirical photometric model This model combines a weighted sum of the LommelSeeliger and Lambert models. Given a suitable value for the LunarLambert function weight, L, this model fits the true reflectance behavior of many planetary surfaces equally well as the Hapke model. This model also depends on the incidence and emission angles. Exclusions THETA WH HG1 HG2 BH CH HH B0 K L LLIST Inclusions PHASELIST KLIST PHASECURVELIST

Description

The "macroscopic roughness" of the surface as it affects the photometric behavior, used for Hapkehen or Hapkeleg. This is the RMS slope at scales larger than the distance photons penetrate the surface but smaller than a pixel. The roughness correction, which will be evaluated if theta is given any value other than 0.0, but is extremely slow. See Hapke (1986).

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)
Maximum	90.0 (inclusive)

Description

The Hapke single scattering albedo of surface particles, see Hapke (1981).

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (exclusive)
Maximum	1.0 (inclusive)

Description

Asymmetry parameter used in Hapke Henyey Greenstein model for the scattering phase function of single particles in the surface. See Hapke (1981). The two-parameter Henyey Greenstein function is:

P(phase)=(1-hg2) * (1-hg1**2)/(1+hg1**2+2*hg1*cos(phase))**1.5 + hg2 * (1-hg1**2)/(1+hg1**2-2*hg1*cos(phase))**1.5

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	-1.0 (exclusive)
Maximum	1.0 (exclusive)

Description

The Hapke Henyey Greenstein coefficient for single particle phase function. Second parameter of the two-parameter Henyey-Greenstein model for the scattering phase function of single particles in the surface. This parameter controls the proportions in a linear mixture of ordinary Heneyey Greenstein phase functions with asymmetry parameters equal to +hg1 and -hg1. See HG1 for the full formula.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)
Maximum	1.0 (inclusive)

Description

The Hapke Legendre coefficient for single particle phase function. A two-term Legendre polynomial is used for the scattering phase function of single particles in the surface:

P(phase) = 1 + bh * p1(cos(phase)) + ch * p2(cos(phase))

Bh is not to be confused with the legendre coefficient bha of the phase function for atmospheric particles, used when atmname=anisotropic1 or anisotropic2.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	-1.0 (exclusive)
Maximum	1.0 (exclusive)

Description

The Hapke Legendre coefficient for single particle phase function. A two-term Legendre polynomial is used for the scattering phase function of single particles in the surface:

P(phase) = 1 + bh * p1(cos(phase)) + ch * p2(cos(phase))

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	-1.0 (exclusive)
Maximum	1.0 (exclusive)

Description

The Hapke opposition surge component. The width parameter for the opposition effect for the surface if Hapkehen or Hapkeleg is used. See Hapke (1984).

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)

Description

The Hapke opposition surge component. The magnitude of the opposition effect for the surface if Hapkehen or Hapkeleg is used. See Hapke (1984).

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)

Description

This specifies if the opposition surge component B0 is set to zero during the standard conditions phase. NOTE: The program will automatically default to "TRUE" if "ZEROBSTANDARD" is not defined by the user.

Type	string
Default	TRUE
Option List:	Option Brief Description READFROMPVL Get ZEROB0STANDARD value from the FROMPVL file Retrieve and set the ZEROB0STANDARD parameter from the FROMPVL file. If a FROMPVL file is not provided, then an error will occur. NOTE: If the user does not define a value for ZEROB0STANDARD in the input PVL file, then the ZEROB0STANDARD value will default to TRUE. FALSE B0 will not be set to zero for standard conditions phase This option specifies that the opposition surge B0 will not be set to zero during the standard conditions phase. TRUE B0 will be set to zero for standard conditions phase This option specifies that the opposition surge B0 will be set to zero during the standard conditions phase.

Description

The Lunar Lambert function weight that governs limb-darkening in the lunar lambert photometric function:

Func=(1-L)*u0 + 2*L*u0/(u0+u)

The values generally fall in the range from 0 (Lambert function) to 1 (Lommel-Seeliger or "lunar" function).

Type	string
Default	None Specified
Internal Default	None Specified

Description

The Minnaert function exponent that governs limb-darkening in the Minnaert photometric function:

Func = u0**K * u**(K-1)

The values generally fall in the range from 0.5 ("lunar-like", almost no limb darkening) to 1.0 (Lambert function).

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)

Description

The Minnaert Empirical and Lunar Lambert Empirical function phase angle list entered as a comma delimited string describing how the parameters of the empirical function vary with phase angle. See "$ISISROOT/appdata/templates/photometry/marsred.pvl" for an example.

Type	string
Default	No List
Internal Default	No List

Description

The Minnaert Empirical function exponent list of limb darkening values entered as a comma delimited string that describes how the parameters of the empirical function vary with phase angle. See "$ISISROOT/appdata/templates/photometry/marsred.pvl" for an example.

Type	string
Default	No List
Internal Default	No List

Description

The Lunar Lambert Empirical function parameter list of limb darkening values entered as a comma delimited string that describes how the parameters of the empirical function vary with phase angle. See "$ISISROOT/appdata/templates/photometry/marsred.pvl" for an example.

Type	string
Default	No List
Internal Default	No List

Description

The Minnaert Empirical or Lunar Lambert Empirical function phase curve list of brightness values corresponding to a set of phase angles defined in the PHASELIST parameter. See "$ISISROOT/appdata/templates/photometry/marsred.pvl" for an example.

Type	string
Default	No List
Internal Default	No List

Description

This is the name of the atmospheric photometric function model to be applied. The models ending with "1" use a first order scattering approximation. Those ending with "2" use a second order scattering approximation, and are slower but more accurate than the first order scattering approximation. The atmospheric correction can be used with only three atmospheric normalization models: albedoatm, shadeatm, and topoatm. See Kirk et al. (2001).

Type	combo
Default	NONE
Internal Default	NONE
Option List:	Option Brief Description NONE No atmospheric model No atmospheric correction will be applied. Exclusions HNORM BHA TAU TAUREF WHA HGA NULNEG ANISOTROPIC1 Anisotropic 1 atmospheric model Uses Chandrasekhar's solution for anisotropic scattering described by a one term Legendre polynomial. This model uses first order scattering approximation. Exclusions HGA Inclusions HNORM BHA TAU TAUREF WHA ANISOTROPIC2 Anisotropic 2 atmospheric model Uses Chandrasekhar's solution for anisotropic scattering described by a one term Legendre polynomial. This model uses second order scattering approximation. It is slower but more accurate than Anisotropic1. Exclusions HGA Inclusions HNORM BHA TAU TAUREF WHA HAPKEATM1 Hapke 1 atmospheric model Provides an approximation for strongly anisotropic scattering that is similar to Hapke's model for a planetary surface. The Chandrasekhar solution for isotropic scattering is used for the multiple scattering terms, and a correction is made to the singly scattered light for anisotropic particle phase function. A one-term Henyey Greenstein function is used. This model uses a first order scattering approximation. Exclusions BHA Inclusions HNORM HGA TAU TAUREF WHA HAPKEATM2 Hapke 2 atmospheric model Provides an approximation for strongly anisotropic scattering that is similar to Hapke's model for a planetary surface. The Chandrasekhar solution for isotropic scattering is used for the multiple scattering terms, and a correction is made to the singly scattered light for anisotropic particle phase function. A one-term Henyey Greenstein function is used. This model uses a second order scattering approximation. It is slower but more accurate than HAPKEATM1. Exclusions BHA Inclusions HNORM HGA TAU TAUREF WHA ISOTROPIC1 Isotropic 1 atmospheric model Uses Chandrasekhar's solution for isotropic scattering. This model uses first order scattering approximation. Exclusions HGA BHA Inclusions HNORM TAU TAUREF WHA ISOTROPIC2 Isotropic 2 atmospheric model Uses Chandrasekhar's solution for isotropic scattering. This model uses second order scattering approximation. It is slower but more accurate than Isotropic1. Exclusions HGA BHA Inclusions HNORM TAU TAUREF WHA

Description

This specifies if negative values after removal of atmospheric effects will be set to NULL. Negative values are only generated in modes that include atmospheric correction and occur when the optical depth "tau" is overestimated, so that the atmospheric radiance subtracted from the image is brighter than the darkest observed pixels. In this case "tau" should be decreased until no negative values are present in the output file.

Type	string
Default	READFROMPVL
Option List:	Option Brief Description READFROMPVL Get NULNEG value from the FROMPVL file Retrieve and set the NULNEG parameter from the FROMPVL file. An error is reported if a PVL file is not provided. NO Do not set negative values to NULL This option specifies not to set negative values to NULL after the removal of atmospheric effects. YES Negative values will be set to NULL This option specifies to set negative values to NULL after the removal of atmospheric effects.

Description

The normal optical depth of the atmosphere.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)

Description

The reference value of tau to which the image will be normalized. This would normally be 0.0 unless one is interested in simulating a hazy atmosphere scene.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)

Description

The coefficient of single particle Henyey Greenstein phase function. Henyey-Greenestein asymmetry parameter for atmospheric particle phase function, used in hapkeatm1 and hapkeatm2 atmospheric models. Not to be confused with corresponding parameter hg1 for the surface particles.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	-1.0 (exclusive)
Maximum	1.0 (exclusive)

Description

The single scattering albedo of atmospheric particles.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (exclusive)
Maximum	1.0 (inclusive)

Description

The coefficient of the single particle Legendre phase function. Coefficient of P1 (cosine) term of atmospheric particle phase function, used in anisotropic1 and anisotropic2 atmospheric models. Not to be confused with corresponding coefficient bh for the surface particles.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	-1.0 (inclusive)
Maximum	1.0 (inclusive)

Description

The atmospheric shell thickness normalized to the planet radius, used to modify angles to get more accurate path lengths near the terminator (Ratio of scale height to the planetary radius). The hnorm parameter is defined as "0.003" for Mars, which is the only planet for which the atmospheric modes are currently used.

Type	string
Default	None Specified
Internal Default	None Specified
Minimum	0.0 (inclusive)

This example shows the GUI and the parameter name settings. The helper option is used to load the preset parameter values if an existing PVL file is used, and then the required parameter names without any values are manually added.

photemplate

photemplate GUI

photemplate GUI Screenshot of GUI version of the application. The parameter values have been loaded and edited for the output PVL file.

Output PVL file	The output PVL file will contain the photometric parameters to be applied to the input cube. Load the PVL file parameters using the photemplate GUI and manually enter required parameter names without any values assigned.