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.
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
Files:
APPEND
Description
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:
NOTE
Description
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:
PHTNAME
Description
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
BH
CH
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
HG1
HG2
Hapke:
WH
Description
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)
Hapke:
HH
Description
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)
Hapke:
B0
Description
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)
Hapke:
THETA
Description
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)
Hapke:
HG1
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:
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)
Hapke:
BH
Description
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:
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)
Hapke:
CH
Description
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:
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:
MODEL
Description
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
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:
ATMNAME
Description
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
Atmospheric Scattering Model:
TAU
Description
This is the normal atmospheric optical depth.
Type
double
Internal Default
None Specified
Minimum
0.0
(inclusive)
Atmospheric Scattering Model:
WHA
Description
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)
Atmospheric Scattering Model:
HGA
Description
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:
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)
Atmospheric Scattering Model:
BHA
Description
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 Scattering Model:
HNORM
Description
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)
Atmospheric Scattering Model:
ADDOFFSET
Description
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:
EMISSION
Description
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)
Mean Ground Plane (Datum) Geometry:
PHASE
Description
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)
Mean Ground Plane (Datum) Geometry:
INCIDENCE
Description
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)
Mean Ground Plane (Datum) Geometry:
RMS_SLOPE
Description
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:
SEED
Description
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
Random Number Generator:
SEED_NUMBER
Description
Starting seed number for random number generator
Type
integer
Internal Default
None Specified
Examples
Example 1
Create a PVL file with phoemplocal
Description
This example shows the GUI and the input setting for each parameter name
in the phoemplocal program.
Command Line
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
Run phoemplocal to generate a PVL file with the parameter values for the
LunarLambertEmpirical photometric model and no atmospheric scattering.
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.
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.
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.
