Help for GPWSMASK

PURPOSE:
"gpwsmask" (Galileo PWS Mask Program) formats Galileo PWS time-frequency
spectrograms for film recording.  The input spectrogram is framed in a
mask consisting of reference marks, annotation, and calibration wedges.

EXECUTION:

	gpwsmask  INP=(SPG,ANTENNA)  OUT=MASK
where
    SPG is the input spectrogram in byte data format.
    ANTENNA is the input file containing Antenna switch position of every
            MOD91 of input file.  
    MASK is the output masked image in byte data format.
The resulting output MASK is suitable for film recording via program BARNE.

REFERENCES:

  GLL SIS 232-09, "PWS High-Rate Experiment Data Record".
  D-3463, "MIPL Software Requirements for Galileo Plasma Wave Subsystem (PWS)
     Systematic Processing".

The appendices to SIS 232-09 (PWS EDR Software Interface Specification) contain
information regarding telemetry and instrument modes which effect the generation
of PWS frequency-time spectrograms.  Detailed requirements for spectrogram
generation are documented in D-3463.

OPERATION:

The input spectrogram is generated from the raw PWS data as follows:

	gpwsformat  INP=RAW  OUT=(FMT,ANTENNA)	!Format raw data for FFT
	fft11  INP=FMT  OUT=FFT			!1-dimensional FFT
	fft1pix  INP=FFT  OUT=FTPIC		!Amplitude image
	flot  INP=FTPIC  OUT=ROT  'COUNTER	!Rotate 90 deg counterclockwise
        stretch  INP=ROT  OUT=STR  ASTR=(.5,.5) !Apply linear stretch
	size  INP=STR  OUT=SPG  parameters....  !Scale vert and/or hori scale
	gpwsmask  INP=(SPG,ANTENNA) OUT=MASK	!Create mask

"gpwsformat" is used to format the raw PWS data (EDR) into record lengths which
are powers of 2 (128, 256, 512, or 1024 bytes).  A 1-dimensional fast-Fourier
transform is then applied in the sample (horizontal) direction via program
"fft1".  The resulting fourier transform (FFT) is in complex data format.
Program "fft1pix" is used to extract the amplitude information from the
transform and scale the result to byte data format.  The amplitude image is
rotated 90 degrees counterclockwise via "flot" so that in the resulting
spectrogram (ROT), the horizontal axis represents the time scale and the
vertical axis represents frequency.  The spectrogram is contrast enhanced via
program "stretch".  Program "size" is used to adjust the vertical (frequency)
and/or horizontal (time) scales.  The resulting spectrogram (SPG) is input
to "gpwsmask", which creates a masked image suitable for input to program
"barne".

The following paragraphs explain how to adjust for the vertical and horizontal
scales of the spectrogram via program "size":

For certain telemetry and instrument mode, an FFT is applied to each 2.5 blocks
of data instead of each block of data.  In order to keep the same temporal
resolution, the spectrogram (SPG) must be magnified 2.5 times in the sample
direction.

Depending of the telemetry and instrument mode, the files output by GPWSFORMAT
will have record lengths of 128, 256, 512, or 1024 bytes (samples).  This
results in spectrograms with corresponding frequencies of 64, 128, 256, or 512.
In order to keep the same linear height on the output plots, spectrograms at
frequencies of 256, 128, and 64 must be zoomed up 2, 4 and 8 times in the line
direction.

The following table provides the information necessary for properly scaling the
spectrogram via program "size":

               |        | # BLOCKS  | ROTATED | OUTPUT  |
	TELEM  |  INST  |    PER    |   FFT   |  SPG    | SIZE
        MODE   |  MODE  | TRANSFORM |  SIZE   |  SIZE   | PARAMETERS
       ------------------------------------------------------------------------
	  MPW  |  1,2,3 |     1     |  64x910 | 512x910 | LZOOM=8
       HCJ/HPJ |   1,2  |     1     |  64x910 | 512x910 | LZOOM=8
       HCJ/HPJ |    3   |    2.5    | 256x364 | 512x910 | LZOOM=2 SZOOM=2.5
          MPP  |   1,2  |     1     | 128x910 | 512x910 | LZOOM=4
          MPP  |    3   |    2.5    | 256x364 | 512x910 | LZOOM=2 SZOOM=2.5
       XPW/XRW |   1,2  |     1     | 256x910 | 512x910 | LZOOM=2
       XPW/XRW |    3   |    2.5    | 256x364 | 512x910 | LZOOM=2 SZOOM=2.5
       HPW/HRW |   1,2  |     1     | 512x910 | 512x910 | Do not run SIZE
       HPW/HRW |    3   |    2.5    | 256x364 | 512x910 | LZOOM=2 SZOOM=2.5
       PW4/PW8 |    1   |    2.5    | 256x416 | 512x1040| LZOOM=2 SZOOM=2.5
          PW4  |    2   |     1     | 256x1040| 512x1040| LZOOM=2
          PW8  |    2   |     1     | 512x1040| 512x1040| Do notrun SIZE
       PW4/PW8 |    3   |    20     | 256x364 | 512x910 | LZOOM=2 SZOOM=2.5

For example, if the input EDR is acquired at MPP mode 3, SIZE should be
executed as follows:

	size  INP=STR  OUT=SPG  LZOOM=2  SZOOM=2.5  'NOIN

Note that whether interpolation or no-interpolation ('NOIN parameter) is
performed during magnification is TBD.

For telemetry modes PW4 and PW8, in instrument modes 1 and 2, each input EDR
results in 7 spectrograms, each representing a time interval of 8 2/3 seconds
(13 minor frames).  For all other modes, each input EDR results in a single 
spectrogram, representing a time interval of 66 2/3 seconds (1 RIM).  See 
program "gpwsformat" for details.

DESCRIPTION OF REFERENCE MARKS:

The spectrogram plot is framed by reference marks in the amplitude and frequency
directions.  Tick marks are placed along the horizontal (time) axis at 2/3
second intervals (1 minor frame).  For PW4/PW8 modes 1 and 2, each tick mark is
labeled.  For all other telemetry formats and instrument modes every tenth
tick-mark is annotated.

A large tick mark is drawn when the RIM count changes, and annotated with
"RIM XX" where "XX" is the new RIM count.

The antenna switch position is indicated beneath the reference marks: E = 
electric field, B = magnetic field, U = unknown.

The vertical axis represents up to 512 frequencies increasing from 0 at the
bottom.  The axis is labeled with frequencies appropriate to the instrument
mode.  The vertical axis is labeled "FREQUENCY IN KHZ" or "FREQUENCY IN HZ",
depending on the instrument mode.

DESCRIPTION OF MASK ANNOTATION:

Annotation included in the mask are spacecraft-event-time, spacecraft clock,
instrument mode, telemetry mode, antenna switch position, and a real-time/
playback indicator.

The details are described in the document "Software Requirement Document for
Galileo PWS Systematic Processing" (D-3463).

PROGRAM HISTORY:

Written by Florance Moss, 1 August, 1990.
Current Cognizant Programmer:  Florance Moss
Revisions: 4-03-91 Remove personal directory in test file
           1-12-93 HBM Fix SCLK RIM and MOD91 label items
           6-08-95 AS ...CRI... Made portable for UNIX
           8-11-95 AS ...CRI... As per FR87104, fixed missing vertical
                                annotation 

PARAMETERS: