JavaScript is not enabled, using print styling. Please note, this may disable the navigation menu.

phoemplocal

Fit empirical photometric functions to Hapke model at a single point

This program finds lunar-Lambert or Minnaert photometric functions to approximate a more realistic but complex Hapke model. The fit is performed at a single geometry rather than for a range of phase angles. The user specifies the phase, incidence and emission angles of the mean ground plane (datum), as well as the root mean squared (RMS) slope relative to the datum. Artificial data are then created, with slopes drawn from an isotropic Gaussian distribution relative to the datum. The simpler model is fit at these orientations (phase, incidence, and emission angles) to the Hapke model by adjusting the limb-darkening and the overall brightness so that the sum-squared-residual between the two is minimized. Both the parameter (which, for both types of simple model, mainly controls limb darkening) and the brightness (normalized as an empirical phase curve) are reported.

Phoemplocal requires the user to input a set of parameters for the Hapke model, and the results for a single point are returned by the program. The input parameter values and the results for the limb-darkening parameter (L), best fit multiplier, and the RMS error of fit are reported to an output file. The results can be used for photoclinometry application.

Related Applications to Previous Versions of ISIS

This program replaces the following application existing in previous versions of ISIS:

pho_emp_local

History

Randy Kirk	1999-11-16	USGS Flagstaff Original Version
Janet Barrett	2003-01-13	Ported pho_fit_local from the VAX and renamed it pho_emp_local in isis2
Sharmila Prasad	2011-08-04	Isis3 Original version, pho_emp_local ported from isis2 to isis3 phoemplocal
Randy Kirk	2011-09-25	Updated documentation for the phoemplocal program
Ella Mae Lee	2013-01-28	Updated documentation for phoemplocal, and added glossary links and examples, fixes #450
Lynn Weller	2013-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.

Parameters

Files

The output file will contain the phase angle, best-fit limb darkening parameter, best-fit brightness both in absolute units and relative to the zero phase model and RMS residual to the fit.

Type	filename
File Mode	output
Internal Default	None Specified
Filter	.txt .pvl

If this option is selected, the results will be appended to an existing file specified as the "TO" file. If "APPEND" is not selected, the output information defaults and overwrites the existing "TO" file.

Type	boolean
Default	FALSE

User Note

The text entered by the user is added to the output file. The note should include some helpful information that lets the user know what types of data the results would be applied to, such as the planet and instrument filter. The input parameter settings should also be included in the note as a record.

Type	string
Internal Default	None Specified

Hapke

A Hapke (1981; 1984; 1986) photometric model is always used as the model to which empirical functions are fitted. The options correspond to variants of the Hapke model with different types of model for the single particle phase (scattering) function.

Type

combo

Default

HAPKEHEN

Internal Default

HAPKEHEN

Option List:

Option

Brief

Description

HAPKEHEN

Henyey-Greenstein photometric model

This is the two-parameter version of the Henyey-Greenstein single particle phase function, with parameters HG1 and HG2.

Exclusions

HAPKELEG

Hapke Legendre photometric model

This is a two-term Legendre Polynomial expansion of the single particle phase function, with parameters BH and CH.

Exclusions

The Hapke single-scattering albedo of surface particles, see Hapke (1981). Not to be confused with albedo WHA of the atmospheric particles.

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

The Hapke opposition surge width. The width parameter for the opposition effect for the surface if hapkehen or hapkeleg is used, see Hapke (1984).

Type	double
Internal Default	None Specified
Minimum	0.0 (inclusive)

The Hapke opposition surge strength. The magnitude of the opposition effect for the surface if hapkehen or hapkeleg is used, see Hapke (1984).

Type	double
Internal Default	None Specified
Minimum	0.0 (inclusive)

The small scale surface roughness value in degrees. "Macroscopic roughness" of the surface as it affects the photometric behavior, used for hapkehen or hapkeleg. This is the root mean squared (RMS) slope at scales larger than the distance photons penetrate the surface but smaller than a pixel, see Hapke (1986). The roughness correction is evaluated if theta is given any value other than 0.0, but is extremely slow.

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

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	double
Internal Default	None Specified
Minimum	-1.0 (exclusive)
Maximum	1.0 (exclusive)

The Hapke Henyey-Greenstein coefficient for a single particle phase function. The 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 Henyey-Greenstein phase functions with asymmetry parameters equal to +hg1 and -hg1. See HG1 for the full formula.

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

The Hapke Legendre coefficient for a 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))

Where p1 and p2 are the first and second order Legendre polynomials. 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	double
Internal Default	None Specified
Minimum	-1.0 (exclusive)
Maximum	1.0 (exclusive)

The Hapke Legendre coefficient for a 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))

Where p1 and p2 are the first and second order Legendre polynomials.

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

Empirical

Specify a photometric function to fit to the Hapke model. The lists of brightness and limb-darkening values can be used with the LunarLambertEmpirical or MinnaertEmpirical photometric functions in the photometric normalization program photomet.

Type

combo

Internal Default

LunarLambert

Option List:

Option	Brief	Description
LUNARLAMBERT	LunarLambert photometric function	Fit the LunarLambert photometric function to the Hapke Model to derive the parameters for the LunarLambertEmpirical photometric function. The LunarLambertEmpirical model as defined by McEwen (1991) and used by the program Photomet is func=b(phase) * ((1-l(phase))u0 + 2l(phase)*u0/(u0+u)) where phase is the phase angle, and u0 and u are the cosines of the incidence and emission angles respectively.
MINNAERT	Minnaert photometric function	Fit the Minnaert photometric function to the Hapke Model to derive the parameters for the MinnaertEmpirical photometric function. The MinnaertEmpirical model as defined by McEwen (1991) and used by the program photomet is func=b(phase) * u0*k(phase) u**(k(phase)-1) where phase is the phase angle, and u0 and u are the cosines of the incidence and emission angles, respectively.

Atmospheric Scattering Model

If an option other than NONE is selected, an atmospheric scattering and surface photometric properties are included as part of the physical model to which the empirical model is fitted. Six available atmospheric models are categorized into three classes that differ in their treatment of the single particle scattering function for atmospheric particles. Each of these classes of model can be evaluated to a first order (faster) or second order (more accurate) approximation. Atmospheric scattering in all these models both attenuates the surface signal and adds its own (uniform) contribution to the image radiance. Therefore, unless NONE is selected, it makes sense to also set ADDOFFSET=YES so that the additive contribution of the atmosphere will be modeled by an additive constant in the fit. This approach is useful in preparing for photoclinometry (shape from shading), for which images are normally preprocessed by subtracting a uniform haze component that corresponds to the additive term in the fit with ADDOFFSET=YES.

Type

combo

Default

NONE

Internal Default

NONE

Option List:

Option	Brief	Description
NONE	No atmospheric scattering model	The radiance from the Hapke surface is not modified by atmospheric scattering. Exclusions TAU WHA HGA HNORM ADDOFFSET BHA
ISOTROPIC1	First order isotropic	Atmospheric particles are assumed to scatter light isotropically. The effects of this scattering are calculated exactly to first order. Exclusions HGA BHA Inclusions TAU WHA HNORM ADDOFFSET
ISOTROPIC2	Second order isotropic	Atmospheric particles are assumed to scatter light isotropically. The effects of this scattering are calculated exactly to second order. Exclusions HGA BHA Inclusions TAU WHA HNORM ADDOFFSET
ANISOTROPIC1	First order anisotropic	Atmospheric particles are assumed to scatter light according to a Legendre polynomial model with a single term. The effects of this scattering are calculated exactly to first order. Exclusions HGA Inclusions TAU WHA BHA HNORM ADDOFFSET
ANISOTROPIC2	Second order anisotropic	Atmospheric particles are assumed to scatter light according to a Legendre polynomial model with a single term. The effects of this scattering are calculated exactly to second order. Exclusions HGA Inclusions TAU WHA BHA HNORM ADDOFFSET
HAPKEATM1	First order Henyey-Greenstein	Atmospheric particles are assumed to scatter light according to a single parameter Henyey-Greenstein function (see the description of the surface scattering parameter HG1 for the equation that combines two such functions for surface particles). The effects of this scattering are approximated by using a first order solution for multiple scattering by isotropic particles and making a correction to the distribution of singly scattered radiation. The model is called HAPKEATM1 because this correction for the single particle phase function is similar to the one developed by Hapke (1981) for surface scattering. Exclusions BHA Inclusions TAU WHA HGA HNORM ADDOFFSET
HAPKEATM2	Second order Henyey-Greenstein	Atmospheric particles are assumed to scatter light according to a single parameter Henyey-Greenstein function (see the description of the surface scattering parameter HG1 for the equation that combines two such functions for surface particles). The effects of this scattering are approximated by using a second order solution for multiple scattering by isotropic particles and making a correction to the distribution of singly scattered radiation. The model is called HAPKEATM2 because this correction for the single particle phase function is similar to the one developed by Hapke (1981) for surface scattering. Exclusions BHA Inclusions TAU WHA HGA HNORM ADDOFFSET

This is the normal atmospheric optical depth.

Type	double
Internal Default	None Specified
Minimum	0.0 (inclusive)

This is the single-scattering albedo of atmospheric particles, not to be confused with the albedo WH of surface particles.

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

Parameter used in the Henyey-Greenstein single particle phase function for atmospheric particles when ATMNAME=HAPKEATM1 or ATMNAME=HAPKEATM2. This is the asymmetry parameter for a single term Henyey-Greenstein model:

p(phase) = (1-hga**2)/(1+hga**2+2*hga*cos(phase))**1.5

Not to be confused with corresponding parameter HG1 for the surface particles.

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

Coefficient of the first order Legendre polynomial in the single particle phase function for atmospheric scattering. When ATMNAME=ANISOTROPIC1 or ATMNAME=ANISOTROPIC2, a two-term Legendre polynomial expansion is used to represent the scattering phase function of single particles in the atmosphere:

p(phase) = 1 + bha * p1(cos(phase))

Where, P1 is the first order Legendre polynomial, and not to be confused with the corresponding parameter BH for the surface.

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

Atmospheric shell thickness normalized to planet radius, used to correct the path lengths of atmospheric transmission for the spherical geometry of the planet. Default 0.003 is for Mars.

Type	double
Internal Default	None Specified
Minimum	0.0 (inclusive)

If true, the additive contribution of the atmosphere will be modeled by an additive constant in the fit of the empirical function at each phase angle.

Type	boolean
Default	false

Mean Ground Plane (Datum) Geometry

This is the emission angle of the ground plane obtained from a representative point on an image. The emission angle is the measurement between the local vertical and the vector from the point on the ground to the spacecraft.

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

This is the phase angle obtained from a representative point on an image. The phase angle is a measurement between the vector from the representative point to the sun and the vector from that point to the spacecraft.

Type	double
Internal Default	None Specified
Minimum	0.0 (inclusive)
Maximum	180.0 (inclusive)

This is the incidence angle of the ground plane obtained from a representative point on an image. The incidence angle is the measurement between the local vertical and the vector from the point on the ground to the sun.

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

The fit will be performed over a set of synthesized data with different orientations. Each component (E-W and N-S) of slope of these data points is normally distributed with a mean of zero and a standard deviation given by this parameter. The fit results should be only weakly dependent on this parameter.

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

Random Number Generator

If enabled, this program uses the user defined number as the starting seed for the random number generator which is used to generate slopes at which the fit is performed, allowing the same random number sequence to be used multiple times for testing purposes. If disabled, the random number sequence will be initialized from the system clock and the numbers will be different each time the program is run.

Type	boolean
Default	false
Inclusions	SEED_NUMBER

Starting seed number for random number generator

Type	integer
Internal Default	None Specified

Example 1

Create a PVL file with phoemplocal

This example shows the GUI and the input setting for each parameter name in the phoemplocal program.

Command Line

Run phoemplocal to generate a PVL file with the parameter values for the LunarLambertEmpirical photometric model and no atmospheric scattering.

phoemplocal 
           to=my_phoemplocal.pvl note="This is a test, wh.52, hh=.17 b0=.025 theta=30 
	   hg1=.213 hg2=1 for lunarlambert empirical model and no atmosphere" wh=.52 
	   hh=.17 b0=.025 theta=30 hg1=.213 hg2=1 model=lunarlambert emission=15 phase=30 
	   incidence=30 rms_slope=.5

GUI Screenshot

phoemplocal GUI

phoemplocal GUI

Screenshot of GUI version of the application. The parameter values are entered by the user, and the results are output to a text file.

Data File

Links open in a new window.

Output PVL file	The output PVL file contains the photometric parameter settings for the LunarLambertEmpirical photometric function. The contents of this file can be used as input for photoclinometry application.

phoemplocal

Categories

Related Applications to Previous Versions of ISIS

Related Objects and Documents

Applications

History

Parameters

Files

TO Output text filename

APPEND Option to append results to output file

User Note

NOTE User note to add to the output text file

Hapke

PHTNAME Surface photometric model

Exclusions

Exclusions

WH Single scattering albedo

HH Hapke opposition surge width

B0 Hapke opposition surge strength

THETA Surface roughness in degrees

HG1 Hapke Henyey-Greenstein coefficient

HG2 Hapke Henyey-Greenstein coefficient

BH Hapke Legendre coefficient

CH Hapke Legendre coefficient

Empirical

MODEL Photometric function to fit to the Hapke model

Atmospheric Scattering Model

ATMNAME Atmospheric scattering model to be used

Exclusions

Exclusions

Inclusions

Exclusions

Inclusions

Exclusions

Inclusions

Exclusions

Inclusions

Exclusions

Inclusions

Exclusions

Inclusions

TAU Normal atmospheric optical depth

WHA Single-scattering albedo

HGA Henyey-Greenstein coefficient for atmospheric particles

BHA Atmospheric particle Legendre coefficient

HNORM Atmospheric shell thickness

ADDOFFSET Allow additive offset in fit

Mean Ground Plane (Datum) Geometry

EMISSION Emission angle

PHASE Phase angle

INCIDENCE Incidence angle

RMS_SLOPE Root mean squared slope

Random Number Generator

SEED User specified seed

SEED_NUMBER Starting seed number

Example 1

Create a PVL file with phoemplocal

Command Line

GUI Screenshot

phoemplocal GUI

Data File