shadowtau Documentation

shadowtau - get shadow stats.
This program uses level-surface and shadow image values to determine the
local atmospheric optical depth.  The surface and atmosphere models use
the same assumptions as the "photomet" photometric correction software
so the resulting optical depth estimate will be useful for processing
images with that software.  (In other words, the optical depth calcula-
ted by this program is model-dependent but it is exactly the model-dep-
endent value that will avoid nulling out shadows in "photomet".)

PROGRAMMER: K Teal Thompson, U.S.G.S., Flagstaff, AZ

Input cube name

NONE

Output cube name

NONE

Input subcube specifier

Alternate user datfile

"$ISISDATA/photom.mars.sav"

Only used with GENMOD=ALBAT, or
TOPAT.  If you use an atmosphere
model, you need to set: tau wha
bha hnorm
I1	1st approx. Isotropic
	Atmosphere Scattering
I2	2nd approx. Isotropic
A1	1st approx. Anisotropic
	Atmosphere Scattering
A2	2nd approx. Anisotropic
H1      1st approx. Hapke
        Atmosphere Scattering
H2      2nd approx. Hapke
        Atmosphere Scattering

--

Photometric function used in the
surface/atmosphere model:
LUNLAM, LL_EMP,
MIN, MN_EMP,
HAPHEN, HAPLEG, HAPH_S, HAPL_S,
LAMBER, LOMSEL, NONE

LUNLAM

Incidence angle to match
for GENMOD=MIXED only

for Minnaert function

1.0

for Lunar-Lambert function

1.0

Reference incidence angle
For photometry, not trim
Default of 0.0 for nonatmosphere
Use 30 for atmosphere models

0.0

Average albedo of the input
image for topographic norm-
alization with or without
atmosphere, and mixed.

Normal atmosphere optical depth
Use with an atmosphere model.
Mandatory.

--

Reference optical depth of
atmosphere.  Use with an
atmosphere model.
Optional.

Single-scattering albedo of
atmospheric particles. Use
with an atmosphere model.
Mandatory.

--

Reference single-scattering
albedo of atmospheric particles
Use with an atmosphere model.
Optional.

P1 (cosine) term of atmospheric
particle phase function.  Use
with an atmosphere model.
Mandatory.

--

Hapke term of atmospheric
particle phase function.  Use
with an atmosphere models H1
& H2.

--

Reference P1 (cosine) term of
atmospheric particle phase
function.  Use with an atmos-
phere model.
Optional.

atmospheric shell thickness
normalized to planet radius.
Use with an atmosphere model.
Mandatory.

--

Choose a program option
PHOTOM, ALBEDO, or NOALBEDO

PHOTOM

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Used to convert radiance to
  reflectance or apply
  calibration fudge factor
  Used only with MOONOPT=ALBEDO

--

Wavelength in micrometers
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

Empirically derived coefficient
  Used only with MOONOPT=ALBEDO

--

ADDITIONAL NOTES:

Parm	Description
FROM	Filename of input textfile. Input file must have image-id, inc, ema, phase, dn-flat, dn-shadow on each line.
TO	Filename of output textfile. Output file will have image- id,inc, ema, phase, dn-flat, dn-shadow plus tau and albedo on each line.
SFROM	SFROM specifies the subcube using a single string for all three dimensions of the cube. The order of the three dimensions is always "samples:lines:bands". If a dimension is left blank, all the data for that dimension is selected. The default value of NULL for SFROM selects the entire cube. Any application below can be used for any dimension. To select specific data from any dimension: "10-100(3):11,12,15-20:1-10(2)" = This example will select every third sample starting with sample 10 thru 100. It selects lines 11 and 12, and 15-20. It selects every other band, starting with band 1 thru 10. There are special characters that can be used for selecting a subcube efficiently, such as "*","#", and "~". For examples type "help sfrom" in TAE. **NOTE** For more examples and explanation of the many features of the SFROM parameter, tutor the sfrom.pdf or refer to Introduction To ISIS, Section 6, of the ISIS User's Manual **
DATAFILE	Alternate user datfile to use instead of ISISDATA/photom.sav
INC	INC is used as an incidence angle boundary. For any pixel point of the input cube that is greater than INC it is set to zero, "cut-off". This effects the terminator of the planet in the cube. The value should not be set above 90 degrees.
EMA	EMA is used as an emission angle boundary. For any pixel point of the input cube that is greater than EMA it is set to zero, "cut-off". This effects the limb of the planet in the cube. The value should not be set above 90 degrees.
RLAT	User's requested latitude range for trimming. This is the only option used for trimming mosaic's that don't have the photometric angles in the backplanes.
RLON	User's requested longitude range for trimming. This is the only option used for trimming mosaic's that don't have the photometric angles in the backplanes.
GENMOD	Any photometric function can be used with any model (oper- ational mode). PICS and existing ISIS PHOTOMPR/PHOTOM modes are mainly intended to give output containing the surface normal albedo under reference conditions. If you use one of the models that includes an atmosphere model, ALBAT, TOPAT, or MIXED, you need to set ATMOS parameter. In "photomet", some models have been added: NONE No photometry (trim only) ALBEDO Albedo normalization in absence of atmosphere. Con- sistent dividing out of photometric model at given angles and putting it back in at reference incidence but zero phase. Let the reference incidence default to zero. For Hapke model only, the photometric function multiplied back in will be modified to take out opposition effect. This re- quires saving the actual value of B0 while temporarily set- ting it to zero in the common block to compute the overall normalization. TOPO Topographic normalization in absence of atmosphere. Normalize to user-specified incidence, emission, and phase, defaulting to zero emission and phase=incidence. Imple- mented in two passes as per Kirk's previous USER mode. Example pdf: procedure local albedo real body !Do first pass with albedo option photomet from=c4400357.lv1 to=c4400357.1stpass l=.44 genmod=albedo atmos=i1 func=lunlam incref=0.0 !Do divide filter boxfilter from=c4400357.1stpass to=c4400357.filter filter=div samp=51 line=51 band=1 !Get average dn after the divide filter for topo model avg_sd from=c4400357.filter option=avg avg=albedo !Do second pass with topo option photomet from=c4400357.filter to=c4400357.ll.top.lv1 l=.44 genmod=topo func=lunlam albedo=&albedo incref=30.0 end-proc ALBAT Albedo normalization with atmosphere. Desired output is normal albedo at user-specified incidence (defaulting to zero) and atmosphere removed. TOPAT Topographic normalization with atmosphere. Desired output is normal albedo at user-specified incidence/emission /phase AND optical depth. Defaults are emission=0, phase= incidence, and optical depth on output equals that on input (i.e., atmosphere isn't actually removed). User can specify reference optical depth of zero if removal of atmosphere is desired. LUNAR Special lunar mode similar to current ALBEDO mode that does iterative, self-consistent solution for normal albedo and appropriate phase correction for that normal albedo. This can be made specific so it only calls the appropriate empirical-lunar photometric function and it only gives normal albedo at 30 degrees incidence, as per the pre- sent version (if photometric function and reference inci- dence are specified, they are ignored in this mode). The algorithm is complex but this should be fairly simple to program based on the old code and the advantage that in the current code we have direct access to all the information at once (i.e., DN at the same time as the phase angle). MIXED Mixed albedo/topo w/o atmosphere This mode will do albedo normalization over most of the pla- net but near the terminator it will normalize topographic contrast to avoid the "seams" we are currently getting with the plain albedo normalization. The two effects will be joined seamlessly. In addition to the parameters for no- atmosphere albedo normalization (i.e., the photometric par- ameters and the choice of angles for normal albedo calcula- tion) this mode needs two more parameters. INCMAT is the incidence angle at which the RMS contrast from albedo matches the RMS contrast from topography. ALBEDO, the av- erage normal albedo, is also needed.
ATMOS	Only used with GENMOD=ALBAT, or TOPAT. If you use an atmos- phere model, you need to set: tau wha bha hnorm, for I1, I2, A1, & A2. User needs to set: tau wha hga & hnorm for H1 & H2. I1 1st approx. Isotropic Atmosphere Scattering I2 2nd approx. Isotropic Atmosphere Scattering A1 1st approx. Anisotropic Atmosphere Scattering A2 2nd approx. Anisotropic Atmosphere Scattering H1 1st approx. Hapke Atmosphere Scattering H2 2nd approx. Hapke Atmosphere Scattering
FUNC	Any photometric function can be used with any model (oper- ational mode). Unlike in PICS and existing ISIS PHOTOMPR/ PHOTOM, in which the models are mainly intended to give out- put containing the surface normal albedo under reference conditions, in photomet, the photoemtric function can also be used to produce the atmosphere hemispheric albedo, in any model that performs the atmosphere calculations: ALBAT, TOPAT. PHOTOMETRIC FUNCTIONS Functions whose parameters are input in TAE parameter LUNLAM Lunar-Lambert function l MIN Minnaert function k Functions whose parameters are input via ASCII file. Set up a parameter file for each target/body you process. LL_EMP Lunar-Lambert empirical MN_EMP Minnaert function HAPHEN Hapke - Henyey - Greenstein wh - Single-scattering albedo, called w in McEwen paper. hh - Compaction parameter - called h in McEwen. b0 - Opposition surge amplitude theta - Average slope of surface, also called macro- scopic roughness hengreen1 - assymetry factor of the particle phase function, called g in McEwen paper. hengreen2 HAPLEG Hapke - Legendre HAPH_S Hapke - Henyey - Greenstein smooth HAPL_S Hapke - Legendre smooth LAMBER Straight Lambert Law LOMSEL Straight Lommel-Seeliger NONE Trim only
INCMAT	Incidence angle to match for GENMOD=MIXED only
ALBEDO	Average albedo of the input image for topographic normaliz- ation with and without atmosphere correction and for the mixed general model which uses topographic normalization. Use with GENMOD = TOPO, TOPAT, MIXED. Program "avg_sd" can be run to get the average albedo.
TAU	Normal optical depth of atmosphere
TAUREF	Reference optical depth of atmosphere
WHA	Single-scattering albedo of atmospheric particles, not to be confused with that of the surface particles.
WHAREF	Reference single-scattering albedo of atmospheric particles, not to be confused with that of the surface particles.
BHA	P1 (cosine) term of atmospheric particle phase function, not to be confused with BH for the surface particles.
HGA	Hapke term of atmospheric particle phase function. Use with an atmosphere models H1 & H2.
BHAREF	Reference P1 (cosine) term of atmospheric particle phase function, not to be confused with BH for the surface parti- cles.
HNORM	atmospheric shell thickness normalized to planet radius, used to modify angles to get more accurate path lengths near the terminator. (ratio of physical depth to the radius)
MOONOPT	Choose the option the program will use. MOONOPT=PHOTOM will perform the photometric correction. ALBEDO will perform the photometric correction plus an albedo-dependent phase angle correction. NOALBEDO will perform the correction without applying the additive value B. If MOONOPT = ALBEDO, an additional albedo-dependent phase angle correction, which varies with the value of each input DN is performed. You must run "shadowtau" with FUNC = MOONPR and choosing MOONOPT = ALBEDO option. The final output value when the ALBEDO option is chosen is the reflectance at incidence and phase angles of 30 degrees and emission angle of 0 degrees. The parameters D, E, F, G2, XMUL, WL, H, BSH1, XB1, and XB2 are used only if MOONOPT = ALBEDO. The program will enter a default value for each of these parameters if the planet is the "moon" and the user leaves the parameter blank. The lunar defaults are as follows: D = 0.14 E = -0.3575 * WL - 0.0607 if WL is less than 1.0; otherwise -0.4179 F = 0.55 G2 = -0.9585 * WL + 0.98 if WL is less than 1.0; otherwise 0.02 XMUL = 1.0 WL = will be read from the cube label H = 0.048 BSH1 = 19.89 - 59.58 * WL + 59.86 * WL**2 - 20.09 * WL**3 XB1 = -0.0817 XB2 = 0.0081 If MOONOPT = NOALBEDO, the following correction will be per- formed: OUTPUT BRIGHTNESS = INPUT BRIGHTNESS * A
D	Empirically derived coefficient
E	Empirically derived coefficient
F	Empirically derived coefficient
G2	Empirically derived coefficient
XMUL	Used to convert radiance to reflectance or apply calibration fudge factor.
WL	Wavelength in micrometers
H	Empirically derived coefficient
BSH1	Empirically derived coefficient
XB1	Empirically derived coefficient
XB2	Empirically derived coefficient