Help for FFTPIC

PURPOSE:

"fftpic" processes input VICAR formatted complex fourier transformations
or complex pictures, extracting, reorganizing, and automatically scaling
various functions of the complex data for image display. Functions of 
the complex input that may be displayed include: amplitude, intensity 
(squared amplitude), phase (with or without sign), real part, and 
imaginary part. Linear or logarithmic scaling prior to output exists for 
all functions except phase.

NOTE: The input transform format is assumed to be that produced by VICAR
program FFT22.  See HELP FFT22 for more details.
EXECUTION:
               fftpic  IN  OUT  PARAMS
 where:

 IN denotes 1-3 input files: a primary input and one or two scratch files.
 
 OUT denotes 1-3 output files: the primary output and one or two scratch
  files.

  (Note that the scratch files may be specified as EITHER input OR
  output files, but not both.  TRANSFORM mode requires two scratch
  files, CPIC mode requires one.  See OPERATION, below.)
 
 PARAMS includes other available parameters, viz.:
 
MODE   SCALING   L_DISP   R_DISP   ORIGIN   NMIN    NMAX   SIGN   THRESHOL

Each is explained in their respective parameter section. (Use TUTOR mode.)
OPERATION:

It is assumed the input data set is a complex*8 matrix with a standard 
Vicar2 label.  The picture size to be processed is derived from the system 
label, so no size field is allowed. The output system label is automatically
updated based on operating mode and input size information.  The output
file is a byte image suitable for display.  (It is referred to as the
"Display" in the following text.)

"fftpic" operates in two modes: the "Transform" mode and the "Complex Picture"
(CPIC) mode.  These are explained below.

In the TRANSFORM display mode, the data are assumed to be organized as 
described in the 'FFT22' Help text.  However the user should be aware that
the FT generated by FFT22, is transposed with respect to normal usage.
In this mode, the image is rearranged so that the DC term (the [0,0] 
frequency) is at the center of the display.  In this mode, the redundant 
frequencies on the positive and negative X-axis are replicated for clarity, 
so the display contains one or two (depending on display types requested) 
more samples than does the input.

In the COMPLEX PICTURE mode, the display has the same size (in samples) 
and structure as does the input.

Depending on the mode specified, the complex input data are first processed
into one (Complex Picture mode) or two (Transform mode) intermediate data 
sets.  During this processing the specified display function(s) of the 
complex input is (are) generated, scaled, and stored as real*4 data. In 
the Complex Picture mode the entire input is processed uniformly into one 
intermediate data set. Hence, only one scratch file is required. 
On the other hand, in the Transform mode the input conjugate symmetry is 
used to divide the display into two halves which may have display types 
specified independently. Hence two scratch files are required. In the 
Transform mode only the left half plus one samples are processed.

In order to efficiently scale and pack the resulting data into byte format, 
a histogram (which may be logarithmic) is accumulated for the entire input.
Then the histogram is analyzed to determine a linear transformation on the
intermediate data for packing into the output. For phase information displays,
the packing transformation is predefined between -PI and +PI or 0 and + PI 
depending on whether or not 'SIGN' has been specified, respectively.

If the two halves of the transform display are in the same mode, the output
display exhibits conjugate central symmetry with spatial frequency. DC (i.e.
(0,0) spatial frequency) is located at line (NY/2 + 1) and sample (NX/2 + 1).
Positive and negative horizontal spatial frequency components are positioned
to the right and left of this point, respectively, along a horizontal axis
similarly, positive and negative vertical frequency components are located
above and below this point along a vertical axis.

NOTE:  the user should be aware that the vertical dimension is reversed
with respect to normal image processing convention:  the positive Y-axis
is upward, whereas for an image the increasing LINE dimension is downward.

If the two halves are in different modes, the display is organized by spatial
frequency components symmetrically about the vertical line with sample coor-
dinate (NX/2 + 1.5).  Therefore, DC for the right half is at line (NY/2 + 1)
and sample (NX/2 + 2), while DC for the left half is at line (NY/2 + 1) and
sample (NX/2 + 1).  Positive and negative vertical spatial frequencies are 
located above and below these DC points, respectively, for each half of
the display along vertical axis.  Positive horizontal spatial frequency
increases to the right for the right hand display and to the left for the left
hand display along a horizontal spatial frequency components are not explicit-
ly displayed in this case.  The scaling applied to both halves is the same
(determined from the composite histogram) except if one half is phase and the
other is amplitude (or another non-phase display).  In this case the predefined
phase scaling is used on the appropriate half and that derived from the
histogram on the other.
SCRATCH DATASETS:

These may be specified either as input files or as output files, but not
both.  The reason for this feature is that the initial version of FFTPIC
required that they be pre-allocated with the correct size, and hence were
input files.  Currently, Vicar2 allows run-time determination of file
size, so the scratch files are created by the program and were therefore
made output files.  However, for consistency with existing user practice
the option of input scratch files was retained.  In no case do they need
to be pre-allocated.
EXAMPLE:
 
        gen A 256 256
        fft22 A (B,SCR)
        fftpic C (OUT,X1,X2) 'L_AMPL 'R_PHASE 'LOG 'SIGN            THRES=.01 NMIN=5.0 NMAX=7.0 ORIGIN=(6,8)
 
The input to this example is a 256 by 256 sample (2048 bytes) transform. 
The default display mode (TRANSFORM) is used. The output display matrix 
consists of a logarithmic amplitude display (left half) and a linear 
phase display with the sign of the angle preserved (right half). A 
multiplication of 1/.01 is performed prior to clipping results less than 
1.0 in absolute value (i.e output = 100*input). The phase origin location 
will be at line 8 and sample 6. Finally, 5 percent of the non-phase 
information portion of the display will be saturated black (DN=0) and 7 
percent will be saturated white (DN=255).

TIMING:
	NONE AVAILABLE FOR THE VAX

WRITTEN BY:  T. C. RINDFLEISCH		  NOVEMBER 22, 1971
CONVERTED TO VAX BY:  Helen De Rueda      DECEMBER 19, 1983
CONVERTED TO VICAR2 BY:  L. W. Kamp       5 FEB 1985
Made portable for UNIX by: A. Scop (CRI)  5 SEP 1994
Bug fixes:  L. W. Kamp                    12 FEB 2010
CURRENT COGNIZANT PROGRAMMER:  L. W. Kamp

PARAMETERS: