Help for FICOR77

PURPOSE:

ficor77 is a Vicar applications program which removes vidicon camera
induced radiometric distortion from Voyager images.

EXECUTION STATEMENT:

    ficor77 INP=(PIC,C1,C2,...,D1,D2,...) OUT=OPIC  user-parameters...

The input files consist of the image to be corrected (PIC), radiometric
files (C1,C2,...) as generated by the program MJSPFCF, and dark-current
frames (D1,D2,...).  PIC must appear as the first input.  The remaining
input files may appear in any order.  At least one radiometric file and
dark-current frame must be specified.

PIC must be an 800x800 (geometrically uncorrected) Voyager image in byte
data format.  The dark-current may consist of a single frame or the sum
of multiple dark-current exposures (byte or halfword format).  If a
summed dark-current is input, the parameter NUMDC must be used to
specify the number of frames summed together.

The output file (OPIC) consists of the radiometrically corrected image.
OPIC is normally output in halfword data format.  To specify byte or
floating point output data format, use the OFORMAT parameter to specify
BYTE or REAL.

BACKGROUND INFORMATION:

"ficor77" will radiometrically correct the input image, converting the input
DN values to some specified radiometric unit.  The program requires a
radiometric file containing calibration data acquired via the same camera
and filter position as the input image (PIC), and dark-current data acquired
via the same camera and scan-rate.

The dark-current (offset) consists of thermally induced charge which must
be subtracted from the signal.  This charge accumulates on the vidicon,
and increases linearly with time.  Dark-current build-up occurs during the
time between frame erasure and read-out.  It is therefore a function of
image scan-rate.  Also, simultaneous-exposure wide-angle frames will have
a greater dark-current build-up than normal-exposure frames since they
are read out during the next frame cycle (the narrow-angle frame is read
out first).

To measure the dark-current, zero-exposure (dark-current) frames are
acquired during cruise and encounter.  Because the rate of dark-current
build-up is time variant and highly sensitive to temperature changes,
the user should specify a dark-current frame with an FDS time reasonably
close to the FDS time of the input image.

The radiometric file contains calibration data obtained from a light-transfer
sequence (see program MJSPFCF for details).  For each pixel, the file
contains the nominal camera output S0,S1,S2,...,Sn (in units of DN) at each
of a sequence of exposures E0,E1,E2,...,En (in foot-Lambert-msecs).

The data samples S0,S1,S2,...,Sn are stored in the file for the low-gain
state, and have been scaled up by a factor of 9 as a result of application
of a 3x3 low-pass filter (used to suppress shot noise).  The dark-current
is subtracted from these data samples before insertion into the file.
(See the documentation of VICAR program MJSPFCF for details).

The first record of the radiometric file contains the number of data points
in the file (n), and luminance values L0,L1,L2,...,Ln corresponding to
exposures E0,E1,E2,...,En for a reference shutter speed of 1 second.
The remaining records contain the data samples Si for each pixel.  Each
ordered pair (Li,Si) comprises a data point on the light-transfer curve which
characterizes that pixel's response to exposure to a light source.

OPERATION:

"ficor77" assumes that the first input file is the image to be radiometrically
corrected (PIC).  Upon entry, "ficor77" extracts the camera ID (serial number),
filter position, gain-state, scan-rate, and camera mode from the input picture
label.  (These values may be overridden via optional parameters CAMERA,
FILTER, GAIN, SCAN, and MODE.)

The remaining inputs are a list of radiometric and dark-current files, which
may appear in any order.  The program automatically selects the correct
radiometric file and dark-current frame by scanning this list for a radiometric
file with matching camera ID and filter, and a dark-current frame with matching
camera ID and scan-rate, as indicated in the picture labels for these files.
(The camera ID, gain-state, scan-rate, and operating mode obtained from the
dark-current picture label may be overridden via optional parameters DCCAM, 
DCGAIN, DCSCAN, and DCMODE.)

For each pixel of the input image, the radiometric correction process
consists of the following steps:

  1) The DN values D and DC for the pixel are extracted from the input
     image and dark-current frame respectively.  If the input image
     (or dark-current) was taken in high-gain, the DN value is converted
     to equivalent low-gain DN by dividing by the gain ratio (see GAIN
     parameter).  The pixels are also scaled by 9 (see DIV parameter) to
     match the scale of the samples in the radiometric file.  If the
     input dark-current frame represents a sum of multiple dark-currents,
     the dark-current DNs are scaled by dividing by the number of frames
     summed together (see NUMDC parameter).

  2) The dark current is removed:  S = D - DC

  3) The resulting signal (S) is converted to luminance:  A piece-wise
     linear model of the light-transfer function is used, such that each
     data point (Li,Si) is assumed to lie on the curve, and the curve is
     assumed to be linear between data points.  Let
		S  < S < S
		 i        i+1
     The signal is converted to luminance by interpolating between the
     data points:

		    L    - L 
		     i+1    i
		L = -----------(S - S ) + L
		    S    - S         i     i
	             i+1    i

     where L is in units of foot-Lamberts.

  4) The output pixel is scaled to radiometric units R (Ref. 4).  The
     user determines the output picture scale by specifying one of the
     following (see IOF and CONV parameters.):

	A1 = number of 'I over F' units per DN, where 10,000 I/F units
             would be produced by normal incidence of sunlight on a 
	     a Lambert disk at the planet's distance from the sun.

 	A2 = number of nanowatts per cm**2 per steradian per nanometer
             wavelength per DN.

     If A1 is specified, then

		        to     S1	
		R = L * --- * ---- * (D/5.2)**2
			 t     A1
     where

	to = reference shutter speed of the data points (msec),
	t  = shutter speed of the input image (msec).
	S1 = filter-dependent conversion factor from ft-Lamberts to
	     I/F units for a reference distance of 5.2 AU from the Sun.
	D  = planet distance from the Sun (in AU).  D is 5.2 AU for Jupiter,
	     9.51 AU for Saturn, 19.122 AU for Uranus, 30.21 AU for Neptune.

     For Voyager 2, the planet-of-encounter is determined by searching the
     frame label for a valid PICNO, Spacecraft-Event-Time (SCET), or Earth-
     Received-Time (ERT), in that order.  This may be overridden via the
     PLANET keyword.

     For Voyager 1, the planet-of-encounter is always set to Jupiter, and this
     may not be overridden.

     NOTE: Prior to March 1988, the correction for solar distance (D/5.2)**2
     was not applied, and all frames were scaled to Jupiter's distance from
     the sun.  The program "fixvgr" was used to scale the frames to Saturn or
     Uranus, and to correct for errors in the ground calibration values of
     S1 (see below).

     If A2 is specified, then

			 S2
		R = L * ----
			 A2

     where S2 is the filter-dependent conversion factor from ft-Lamberts
     to units of nanowatts/cm**2/steradian/nanometer.

     For images taken during ground calibration, the keyword LC should be
     used to specify Xenon light-cannon (rather than solar) illumination.
     Values for S2 are retrieved from tables stored in the program for
     each camera-filter combination for both solar and light-cannon
     illumination.

  5) The output DN is converted to the specified data format.  For byte
     output, the DN range is ALWAYS 0 to 255.  Values outside this range are
     truncated to 0 or 255, as appropriate.   For halfword (16-bit integer)
     and real output, the default range is -32768 to +32767 (i.e. the full
     halfword range).  Although a negative DN value has no physical meaning,
     this may occur if the dark-current frame has a higher dark-current
     level than that of the input image.  Negative DNs may be set equal
     to zero via the NONEG keyword.  The upper limit may be modified
     via the MAXDN parameter.

OUTPUT SCALE CORRECTION:

As of March 1988, the output DN scale is corrected using factors derived
from analysis of calibration plaque data (see Ref. 4) and comparisons with
ground-based data (see Ref. 5).  This scale correction may be suppressed
via the NOCORRECT parameter.

The following scale correction is applied to each pixel:

			R' = S*R

where the constant S is a function of camera and filter position.
S is retrieved from a table stored in the Scale Correction File (SCF).
This file may be specified by the SCF parameter.  (Note: The constants
in the file have the target-to-Sun distance correction built into them).

The scale correction is identical to the correction applied by program
"fixvgr", except that "fixvgr" rescales the output DN values to 1 'IOF' unit
per DN.  Images which have been scale-corrected by "ficor77" need not be
processed by "fixvgr".  If processed by "fixvgr", no re-scaling is done unless
the constant has been changed.  Images scale-corrected by "ficor77" may be
identified by the following picture label:

  (e.g) COMMENT=' PICTURE MULTIPLIED BY  0.93   FICOR	2/02/86 VERSION'
	SCALE='URANUS'

where 0.93 is the constant S, URANUS is the planet-of-encounter, and
2/02/86 is the version date of the SCF.  See the help file for program
"ficorgen" for source documentation of the current and past scale correction
values.

PARAMETERS:

All user parameters are optional, and are entered in one of the following
forms:
		KEYWORD=string
		KEYWORD=n
		KEYWORD=r
		'KEYWORD
where 'string' is an ASCII character string, 'n' is an integer value and
'r' a real value.  The following is a summary of the parameters.  Use the
TUTOR mode for a more complete description.

	CAMERA STATE PARAMETERS
	-----------------------
	EXPO=r		- Override input image exposure time (msec)
	FILTER=n        - Override input image filter position (-1<n<8)
	GAIN=n		- Override input image gain (N=0 low, N=1 high)
	MODE=n		- Override input image mode (1-7)
	SCAN=n		- Override input image scan rate
	CAMERA=n	- Override input image camera serial number

	DCGAIN=n	- Override dark current gain
	DCMODE=n	- Override dark current mode
	DCSCAN=n	- Override dark current scan rate
	DCCAM=n		- Override dark current image camera serial no.

	'NOCHECK	- Bypass matching of camera parameters; the calibration
			  file must be the second input and the dark-current
			  must be the third input.

	OUTPUT IMAGE SCALE
	------------------
	CONV=r		- Number of nanowatts per cm*2 per steradian per
			  nanometer wavelength per output DN.
	IOF=r		- Number of "I over F " units per output DN.
        SCL=string	- Scale Correction File
	'planet		- where planet is JUPITER, SATURN, URANUS, or NEPTUNE.
	'NOCORRECT	- Suppress FIXVGR scale correction

	DATA FORMAT KEYWORDS
	--------------------
	'BYTE		- Output image in byte format
	'HALF		- Output image in halfword format
	'REAL		- Output image in floating point format
	'NONEG		- Set all negative output DN to zero
	MAXDN=n 	- Maximum DN in the output image
	NUMDC=n		- Number of dark-current frames summed together

	MISCELLANEOUS
	-------------
	'DBUG		- Some diagnostics output
	'LC		- Input image taken under light-cannon illumination
	DIV=r		- Calibration file scale factor

EXAMPLES:

"ficor77" is most commonly used as follows:

	ficor77 (PIC,CAL,DC) OPIC GAIN=0

The calibration file (CAL) must be for the same camera and filter as PIC.
The dark-current file (DC) must be for the same camera and scan-rate.
The output frame (OPIC) will be in halfword (16-bit integer) format.

The value of IOF is chosen to maximize use of the output 16-bit DN range
(0-32767).  The default value for IOF (IOF=1) is appropriate for most
targets.  For targets of low albedo (e.g. Saturn's rings), IOF is chosen
within the range  0.01 < IOF < 1.0.

Most of the remaining parameters are used to work around occasional errors
in picture label information.  Since high-gain images were acquired for
only a small percentage of VGR-1 Jupiter frames, the parameter GAIN=0 is
regularly used to override the camera gain-state value to low-gain.

ERROR MESSAGES:

All error messages are preceded by three asterisks (***).  An error is fatal
only if it is immediateley followed by the message:
		"***FICOR task cancelled"

TIMING:

"ficor77" requires 21 CPU seconds on the VAX 8600.  It will complete within
30 seconds (wall-clock) on a single-user system and about 3 minutes on a
system supporting 20 users.  The program reports its progress by printing
the line count at 100-line intervals.

REFERENCES:

1) JPL Technical Memorandum 33-628 "A User's Guide to the Mariner 9
   Television Reduced Data Record", 1973.

2) JPL Document 618-802 "Voyager Imaging Science Subsytem Calibration
   Report", M. Benesh and P. Jepsen, 31 July 1978.

3) P. Jepsen, et.al., "Voyager Image Processing at the Image Processing
   Laboratory", Journal of the British Interplanetary Society, Vol. 33,
   pp 315-322, 1980.

4) G.E.Danielson, et.al., "Radiometric Performance of the Voyager Cameras",
   JGR Vol 86, NO.A10, pp 8683-8689, 30 Sep 1981.

5) T.V. Johnson, "Corrections to Danielson et.al. Calibration", memorandum
   to the Voyager Imaging Team, 16 Jan 1986.

PROGRAM HISTORY:

Written by: Joel A. Mosher	Jan 78
UCL Implementors: M.L. Kendall & R.F.T. BARREY	Jan 82
Cognizant programmer: Gary Yagi
Revisions:
  1985-10-01 FFM  ...Change to VICAR2 I/O and convert subroutine
	             LCOR from fortran to assembler
  1988-02-01 GMY  ...Major code clean-up and enhancements:
			0) Rewrite help file.
			1) Add FIXVGR scale correction factors.
			2) Delete redundant keywords SN,FP,HSAT,SUN
			3) Delete null keyword FICOR
			4) Fix OUTREAL keyword
			5) Fix bug reading last Cal-File record.
			6) Modified processing of negative DN (LCOR)
			7) Delete FORMAT keyword
			8) Fix bug in processing high-gain pictures
			9) Accept input of summed dark-current frames.
  1988-02-25 GMY  ...Fix SCAN=10, bad mode (FR 33244)
  1988-06-07 GMY  ...Fix processing of EXPO keyword.
  1988-12-21 GMY  ...Fix processing of parameters passed via procedures.
  1992-05-24 GMY  ...Update test script (FR 64507)
  1993-07-09 GMY  ...Check for input image with zero exposure (FR 79136)
  1994-10-31 AMS  ...(CRI) Made portable for UNIX
  1998-11-09 GMY  ...Updated test script to point to where test files are.
  1999-05-24 GMY  ...Corrected problem with negative and 0 DNs.
  2014-07-21 WLB  ...Initialized camera mode variables MODE and MODEDC to
                     get consistent results between linux and sun.
  2015-09-03 WLB  ...Replaced calls to entries with calls to subroutines.

RESTRICTIONS:

The vgrscf.dat input file is generated on the MIPLs only.
See "fixvgr" for more information.

PARAMETERS: