Help for PHOTTESTM

PURPOSE:

PHOTTEST  is a VICAR program which generates synthetic photometric data and 
stores them in an IBIS2 photometric catalog (phocat), for use in testing 
photometric functions in program PHOTFIT2.
	

FUNCTION:

PHOTTEST computes reflectances for a set of points and writes them into the 
catalog (phocat).  The points can either be specified directly by parameters 
INC_ANG, EMI_ANG, and PHAS_ANG, or can be computed in a grid using parameters 
START and DELTA. Shifts can be added to the data with gaussian distribution to 
simulate observational errors which will be an absolute error. 
The parameters used to generate the data are written into the property label.


PHOCAT FILE:

The structure of the phocat file is desined in such a way that tiepoint files 
can be extended and containing all collumns of the old IBIS1 photometric 
catalog files. The program PHOTTEST used only one IMAGE_* group. but tiepoint 
files using some IMAGE_* groups containing informations relates to the image.
GENERAL_QLF containes informations relates to the object point (e.g.  CLASS_IDentifier). OBJECT_COORDINATES containes only coordinates of the object 
point (e.g. LATitude, LONGitude or the X,Y,Z-coordinates in planetocentric 
coordinate system).

The structure of the photometric catalog file is given by: 

abstract groups	      primitive groups    units	      formats	used in PHOTTEST

IMAGE_1 		line 		  pixels	REAL	 used
			samp		  pixels	REAL	 used
			ObjectLine	  pixels	REAL	  --
			ObjectSamp	  pixels	REAL	  --
			BoxLines	  pixels	REAL	  --
			LuminanceLat	  degrees	DOUB	  --
			LuminanceLong	  degrees	DOUB	  --
			IncidenceAngle	  degrees	DOUB	 used
			EmissionAngle	  degrees	DOUB	 used
			PhaseAngle	  degrees	DOUB	 used
			DN_BoxMean	  DN		DOUB	  --
			Radiance	W/cm**2/str/nm	DOUB	  --
			I/F		  --		DOUB	 used
			StandDev	  --		DOUB	 used

OBJECT_COORDINATES  	LAT		  degrees	REAL	  --
			LONG		  degrees	REAL	  --

GENERAL_QLF		--		  --		DOUB	  --
			CLASS_ID	  --		FULL	 used




EXECUTION:



In the SHELL-VICAR :

	 PHOTTEST 'OUT=PHOTCAT.DAT PARAMS'
  (no default values for the photometric parameters!)



In the command modus :

	TAE> PHOTTEST OUT=PHOTCAT.DAT PARAMS
   (no default values for the photometric parameters!)
 or
	TAE> PHOTTESTM OUT=PHOCAT.DAT PARAMS  
  (it helds for every photometric function its own parameter defaults)




In the tutor modus  --> menu-driven parameter input :

	TAE> tutor PHOTTESTM   
  (it helds for every photometric function its own parameter defaults)


tutor PHOTTEST

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 program, the menu points have the following meanings:

1. Select the first menu point to input the general parameters 
   such as the names of output catalog, the illumination conditions, and 
   so on.
2. Containing the parameters of the selected photometric function.
   The photometric function 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.
3. 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  
					phottestm.par' 

4. 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.

If you request help for the selection points in the Menu, you will get the help 
text contained in the respective sub PDFs.



HELPS :

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




REQUIREMENTS and DEPENDENCIES:

LIBRARIES TO RUN PROGRAM:	LIB_TAE, LIB_RTL, LIB_P2SIB, LIB_P1SIB

INCLUDE-FILES:			vicmain_c, math.h, defines.h, 
				ibisfile.h, ibiserrs.h, 
				pho.h, pho_global.pdf

SUBROUTINES:			pho_routines.com
				PHOPDF.COM

	
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 



INTERFACES:


INPUT:	


VICAR PDF-PARAMETERS:

Name	Type	count	Default	Description


1.) phottestm_general.pdf 	(menu point (1) of PHOTTEST)

OUT	char*32	 1	--	File name for the photometric catalog. 
							
PHO_FUNC char*32 1  HAPKE_86_LE2 Photometric function.

CLASS_ID int	1	1	class_id 

INC_ANG	real 	0:100	--	Incidence angles in degree.

EM_ANG	real 	0:100	--	Emission angles in degree.

PHAS_ANG real 	0:100	--	Phase angles in degree.

START		real 0:3	Starting point for grid in degrees.
				(INC_ANG,EM_ANG,PHAS_ANG)

DELTA		real 0:3	Increment for grid in degrees.
				(INC_ANG,EM_ANG,PHAS_ANG)

SIGMA		real		Simulated standard deviation.

SEED		int		Arbitrary seed for SIGMA.

PRINT		keyword		Screen output  of data generated.



2.) pho_"&PHO_FUNC".pdf	(menupoint (2) of PHOTTESTM) 
(photometry menu; the subPDFs pertaining to photometry are deliverd to the 
VICAR system by phopdf.com)

actuell  second menu	Name		default		Comment
(photom.function)	(funct.params)

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.21
			H_SHOE		0.07
			B_SHOE		2.012
			THETA		20.0
			LE1_SOIL	0.29
			LE2_SOIL	0.39

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





3.) common_save_par.pdf		(menupoint (3) of PHOTTESTM)
(see common_subpdf.com)

SAVE_PAR	string		Name for the TEA-parameter file


4.) common_proc_done.pdf	(menupoint (4) of PHOTTESTM)
(run the main program PHOTTEST; see common_subpdf.com)


	
OUTPUT:

FILES:				IBIS2 photometric catalog file 
				(see parameter OUT)

SCREEN OUTPUT:			Class identification, photometric function and 
				its parameters, # points, 
				mean error and  standard deviation depending of 
				parameter SIGMA,
				generated data (optional accordingly parameter 
				PRINT)



BACKGROUND AND REFERENCES :	see pho_routines.com and phopdf.com



SOFTWARE PLATFORM :		VICAR, TAE 5.2
				


HARDWARE PLATFORM :		VMS/UNIX(AXP/SOLARIS,SGI)
				No particular hardware required;
				tested on AXP/SOLARIS/SGI


PROGRAMMING LANGUAGE :		TCL , C	


HISTORY:			20-1-87 L.W.Kamp: 	original 
				Nov. '95 F.Oschuetz:	new written to be 
							portable to run on 
							AXP/SOLARIS/SGI 
							based on
							pho_routines.com and
							phopdf.com 


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

PARAMETERS: