Help for PHODEM

FUNCTION:

PHODEM is a program to demonstrate the usage of menu-driven input of the large 
number of different PDF parameters related to photometric calculus into the 
application program (including their various permitted ranges and 
default settings).  

The MDF is used to organize PDF parameters into different "menus".  The goal of 
such menus is to organize input parameters into parameter groups related to 
specific topics (e.g. I/O-parameters, photometric parameters, SPICE parameters)
in order to facilitate the preparation and the execution of a program to the 
user.

This programs uses most of the sub PDFs delivered by the routine PHOPDF.  It is 
very similar to the test program of this PDF.

This demo program shows to the software user how to
	-navigate through a menu;
	-switch between the interactive operation modes of TAE (i.e. Command  
	  Line Mode [TCL], Tutor Mode, and Menu Mode);
	-save the parameter set for later re-processing;
	-delete temporary parameter files.

This program demonstrates to the software developer how to
	-integrate the sub PDFs of PHOPDF into their main program
	-set the different defaults for parameters (with different or the same 
	  name) related to different photometric functions for a tutor-session 
	  or the batch mode;

The programmers are welcome to cut out and vary these PDFs and the MDF for use 
in their own programs using other defaults, additional parameters, and 
different or additional submenues.But be carefully for creating names for 
global variables, because these global defintions are for the hole 
VICAR-session.   Note that the default values of the sub-PDFs (e.g. of the 
photometry menus from PHOPDF) will be overwritten by the default values of the 
main-pdf (in this case by PHODEM.PDF).

PHODEM  simulates a program to read the parameters from an IBIS2 parameter file 
(see the pho_par_file package) and for reading MARS94/96-SPICE informations. 
However, this is just a simulation.  There is no real IBIS2-processing nor real 
SPICE reading done in this demo!


EXECUTION:

There are separate PDFs for each selection point seen in the main menu.  On 
selection of a particular menu point you will enter the normal tutor mode of 
this PDF.  In this demo program, the menu points have the following 
(dummy/simulated!) meanings:

1. Select the first menu point to input the general parameters for a program
   such as the names of input/output images, the illumination conditions, and 
   so on.

2. In the second menu point you can input (dummy) parameters
   related to SPICE (navigation data, pointing data, instrument data, etc.)

3. In this case, the PDF pertaining to this menu point and the name of this 
   menu point are changing depending on your input of the parameter PHO_FUNC
   in the first menu point.
   There are a few special entries of this parameter:
   - to run the program without using a photometric function you have
     to select PHO_FUNC = "NONE",
   - to read in the photometric function and its associated parameters from a 
     photometric parameter IBIS2-file you have to select PHO_FUNC = "PAR_FILE", 
     and
   - to enter photometry parameters by yourself using the tutor mode
     you have to select the desired photometric function.

4. Select this menu point to specify the name of the parameter file which is 
   generated by the program (the default name in VICAR programs: LAST.PAR).
   This is useful because in a Menu there is no 'save'-command to save a 
   parameter file with a user-specified name (e.g. "save proc_name.par").

   EXECUTION :

   USER ACTION				RESULT

   don't call this menu point		last.par

   exit this menu point with 'exit'	last.par

   exit this menu point with 'run'	the user-specified name or the 'name 
					of the application procedure .par' as 
					it is given by the parameter 'save_par'

 5. This menu point is to be entered to execute the main program.

You can repeat all steps and reenter all menu items except the step that leads 
to the execution of the program.



HELPS :

- You will get the common help contained in the ".mdf" file (phodem.mdf) by 
  typing "help *" in the menu,
- but you will get the help text contained in programs main-PDF (phodem.pdf) by 
  processing of "help-help" applied to the program (should be verry similary).
- If you request help for the selection points in the Menu, you will get the 
  help text contained in the respective sub PDFs.



OPERATION:

Although the main purpose of this program is to demonstrate the use of menus in 
VICAR photometry programs, the main part of the demonstration program PDODEM 
actually
- reads in the photometric parameters and the illumination conditions,
- computes the bidirectional reflectance, the photometric function and the 
  photometric correction factor to change radiance values from measured viewing 
  and illumination conditions to new artificial target viewing and illumination 
  conditions.  

No image processing is being done.  Results are written to the screen.



SUBROUTINES REQUIRED TO RUN PROGRAM:	pho_routines package
					PHOPDF package

INCLUDE FILES REQUIRED TO RUN PROGRAM:	pho.h, pho.fin
					pho_global.pdf


VICAR PARAMETERS:

NOTE: All parameters (including those from the photometry subPDFs) have to be 
defined in the mainPDF (PHODEM.pdf).

PARAMETERS SORTED BY SUB-PDFS :

Name of PDF file	PDF parameters	default	    comments
(will appear as a	within this	setting	
separate sub-menu)	particular 
			sub-menu			


1) GENERAL INPUT / OUTPUT :
	
phopdf_general	 	INP

			OUT

			PHO_FUNC	MINNAERT The photometric function
						(see PHOPDF)
									
						Permitted values :

						NONE, 
						PAR_FILE, 
						LAMBERT, 
						MINNAERT, 
						IRVINE, 
						VEVERKA, 
						BURATTI1, 
						BURATTI2, 
						BURATTI3, 
						MOSHER, 
						LUMME_BOWEL_HG1, 
						HAPKE_81_LE2, 
						HAPKE_81_COOK, 
						HAPKE_86_HG1, 
						HAPKE_86_HG2, 
						HAPKE_86_LE2, 
						HAPKE_HG1_DOM, 
						REGNER_HAPKE_HG1, 
									
ATMO_CORR_REGNER
				INC_ANG
				EM_ANG
				PHAS_ANG


2) SPICE PARAMETERS :
dummy parameters and logical/environments as proposed for the MARS94/96 mission)
						
phopdf_spice			GECALDIR	M94GEOCAL
				GECALDAT	HRSC_GEOCAL_DATE
				BSPFILE		HWSPICE_BSP
				SUNFILE		HWSPICE_SUN
				BCFILE		HWSPICE_BC
				TSCFILE		HWSPICE_TSC
				TIFFILE		HWSPICE_TI
				TPCFILE		HWSPICE_TPC
				TLSFILE		HWSPICE_TLS


3) PHOTOMETRY MENU :

Note: the subPDFs pertaining to photometry are deliverd to the VICAR system by 
PHOPDF.  They may not be changed, however, the default values may be set, reset 
or overwritten by the main-PDF (PHODEM in this case).  All PDF parameters must 
be defined in the main program's PDF in oder to access the different sub-menues 
correctly.  

actuell  third menu	Name		default		Comment

PHO_PAR_FILE		PHO_PAR_FILE		parameters from IBIS 
						pho_par_file

NONE			none			do not apply any 
						photometric processing

LAMBERT			ALBEDO		1.0

MINNAERT		ALBEDO		1.0
			EXPONENT	0.6

IRVINE			EXPONENT	0.9
			IRV_EXP1	0.118
			IRV_EXP2	0.0039

VEVERKA			A_VEVERKA	0.997
			B_VEVERKA	0.6
			C_VEVERKA	0.003
			D_VEVERKA	0.14

BURATTI1		ALBEDO		0.5
			B_VEVERKA	0.6
			E_BURATTI	0.14

BURATTI2		ALBEDO		0.5
			B_VEVERKA	0.6
			C_VEVERKA	0.003
 			E_BURATTI	0.14

BURATTI3		ALBEDO		0.5
			B_VEVERKA	0.6
			C_VEVERKA	0.003
			D_VEVERKA	0.14
			E_BURATTI	0.14

MOSHER			A_VEVERKA	0.5
			B_VEVERKA	0.6
			C_VEVERKA	0.003
			D_VEVERKA	0.14
			MO_EXP1		0.5
			MO_EXP2		0.1

LUMME_BOWEL_HG1	W_SOIL	0.3
			H_SHOE		0.06
			DEN_SOIL	0.8
			THETA		20
			HG1_SOIL	-0.26

HAPKE_81_LE2		W_SOIL		0.3
			H_SHOE		0.06
			LE1_SOIL	0.3
			LE2_SOIL	0.3

HAPKE_81_COOK		W_SOIL		0.3
			H_SHOE		0.06
			LE1_SOIL	0.3
			LE2_SOIL	0.3
			COOK		0.9

HAPKE_86_HG1		W_SOIL		0.3
			H_SHOE		0.06
			B_SHOE		2.0
			THETA		15.0
			HG1_SOIL	-0.26

HAPKE_86_HG2		W_SOIL		0.21
			H_SHOE		0.07
			B_SHOE		2.0
			THETA		20.0
			HG1_SOIL	-0.29
			HG2_SOIL	0.39
			HG_ASY_SOIL	1.0

HAPKE_86_LE2		W_SOIL		0.3
			H_SHOE		0.06
			B_SHOE		2.0
			THETA		20.0
			LE1_SOIL	0.3
			LE2_SOIL	0.3

HAPKE_HG1_DOM		W_SOIL		0.3
			H_SHOE		0.06
			B_SHOE		1.0
			THETA		20.0
			HG1_SOIL	-0.26
 			H_CBOE		0.06
			B_CBOE		1.0

REGNER_HAPKE_HG1	W_SOIL		0.3
			H_SHOE		0.06
			B_SHOE		2.0
			THETA		20.0
			HG1_SOIL	-0.26
			W_ATM		0.78
			TAU_ATM		0.05
			HG1_ATM		0.35

ATMO_CORR_REGNER	W_SOIL		0.3
			H_SHOE		0.06
			B_SHOE		2.0
			THETA		20.0
			HG1_SOIL	-0.26
			W_ATM		0.78
			TAU_ATM		0.05
			HG1_ATM		0.35


4) PAR-FILE NAME

pho_save_par		SAVE_PAR		name of the TAE-parameter file
						containing all parameters 
						needed to running the program
						default:
						name of the main program 
						with the extention ".par"


5) RUN  MAIN PROGRAM

pho_proc_done		-			runs the program


GLOBAL VARIABLE:
The following global variables defined by the pho_global.pdf must be referenced:

	Name		Type			Description

	PHO_FUNC_type 	string			It containes the names of the 
						valid photometric functions (to 
						pass into the menu).

	pho_PROC_NAME 	string			Name of the main program 



	

BACKGROUND AND REFERENCES:	TAE Command Language (TCL)
				Programmers's Manual
				Version 5.1
				NASA Goddard Space Flight Centre, 1991

SOFTWARE PLATFORM :		VICAR 13, TAE 5.2
				(VMS/AXP/SUNOS/SOLARIS)

HARDWARE PLATFORM :		No particular hardware required;
				tested on VMS/AXP/SUNOS/SOLARIS

PROGRAMMING LANGUAGE :		TCL , C	

HISTORY:			Friedel Oschuetz, July '94, original

COGNIZANT PROGRAMMER:		Friedel Oschuetz
				Institute of Planetary Exploration
				DLR
				12484 Berlin (FRG)

PARAMETERS: