PDS_VERSION_ID          = PDS3
RECORD_TYPE             = STREAM
OBJECT                  = TEXT
  PUBLICATION_DATE        = 2006-11-02
  NOTE                    = "
    SOFTINFO.TXT describes the contents of this directory."
END_OBJECT              = TEXT
END

This directory contains files related to example software applicable to
the data on this volume.  All code and files are provided "as is"
without any warranty but with the hope that they will be useful in
understanding the data provided on this volume.  These supplemental
files are beyond PDS archiving requirements and may not meet PDS
standards.

[SOFTWARE]              This directory
 |
 |- SOFTINFO.TXT        Description of and instructions for software in
 |                      this directory.  (this file)
 |
 |- [C]                 Directory containing C example code
 |   |
 |   |- TESTIN.LBL      Test waveform data file and associated label for
 |   |- TESTIN.DAT      the VGPWS_WF_LIST program.
 |   |
 |   |- TESTOUT.TXT     Test output for the VG1PWS_WF_LIST program.
 |   |
 |   |- VGPWS_WF_LIST.C Complete application for printing Voyager PWS
 |   |                  waveform samples as hexidecimal values.
 |   |
 |   |- VGPWS_WF_LIST.MAK
 |   |                  Makefile for compiling and testing
 |   |                  VGPWS_WF_LIST.C on POSIX compliant operating
 |   |                  systems
 |   |
 |   |- WFENGHDR.FMT    Format details of the TESTIN.DAT file header
 |   |
 |   |- WFROWPFX.FMT    Format details of the TESTIN.DAT record header
 |
 |
 |- [IDL]               Directory containing the VGPWS_WF_PLOT data
 |   |                  viewer
 |   |
 |   |- VGPWS_WF_PLOT.PRO
 |                      Example IDL program to extract Voyager PWS
 |                      waveform samples and plot the waveform and
 |                      relative power spectrum.
 |
 |
 |- [JAVA]              Directory containing Java VGHR data viewer
     |
     |- SOURCE.ZIP      Java source code for the VGHR program in
     |                  the form of a zipped Netbeans 6.1 project
     |                  (http://www.netbeans.org) directory.
     |
     |- VGPWS_HR.JAR    Java JAR file containing an application for
                        viewing and manipulating the data in this archive.
                        This is the same application used by the producers
                        of the data on this volume.



VGHR_HR Java Application
========================

  The Java JAR file VGPWS_HR.JAR contains the application VGPWS_HR which can
  be used on Java 1.5 or newer platforms to view time-domain waveform data
  or FFT-transformed frequency-domain spectrograms generated from the
  Voyager PWS waveform receiver data files on this volume.

  The Java Runtime Environment (JRE) is freely available for common
  platforms from http://java.sun.com/.

  On most platforms the application can be started by opening a command
  console, changing directory to the EXTRAS/SOFTWARE/JAVA directory on
  the volume, and issuing the command:

    java -Xmx256m -jar VGPWS_HR.JAR --localOnly

  The command line argument "-Xmx256m" instructs the Java virtual machine
  to allocate 256MB of memory for the application instead of the default
  64MB.  The option "--localOnly" limits the application to use only
  features relevant to the archived data on the local volume.

  The Java virtual machine will load the application with an empty plot
  and two tab selections at the top:  "plot" and "local."  Select the
  "local" tab and then click "load files" to bring up a file selector.
  Navigate to the archived files under DATA/Pn/Vsvvxx, where n is the
  spacecraft clock partition number, s is 1 or 2 for Voyager 1 or 2, vv
  is the volume sequence number and xx is the directory sequence number
  on the volume.  The binary data files are named Cmmmmmnn.DAT where
  mmmmm is the spacecraft clock mod 65536 counter and nn is the
  spacecraft clock mod 60 counter.  Multiple files may be selected but
  note that except for a few rare intervals near planetary encounters,
  these data are very sparsely sampled, so selecting any two consecutive
  available files is likely to result in a spectrogram consisting of one
  column of pixels at either end of an otherwise blank plot.

  A far easier way to browse these data is via the links in the html file
  EXTRAS/BROWSE.HTM.  These lead down to reduced resolution browse plots
  of individual data frames with links that will invoke the VGPWS_HR
  application for full resolution access and interactive analysis.
  Because the application utilizes a self-signed certificate, a warning
  message relating to the unverifiability of the security certificate
  will be presented by most browsers.  If you trust us, you can elect to
  run the application.

  After a waveform file is loaded in the application, a wide variety of
  analyses are possible.  By default, a left-click in the spectrogram
  display will show the corresponding time-domain waveform data in the
  lower panel.  Right-clicking on most features of the display will pop
  up a menu of relevant configurable parameters.  In the spectrogram
  display, one can select, for example, "horizontal slice" or "verticle
  slice" which will produce slices at a given frequency or time that
  update continuously as you drag the mouse through areas of interest in
  the spectrogram.  The "parameters" submenu leads to very detailed
  controls, although these configurations are not designed for casual
  users.

  Almost any aspect of the display is configurable, and a number of
  convenient controls are accessible via mouse events on the display
  itself.  Any axis may be zoomed by left-dragging a range on the
  corresponding axis:  time, frequency, or amplitude.  A subtle mouse
  "gesture," dragging a few pixels to the left (a left arrow will
  appear), may be used to undo the most recent zoom.  Another mouse
  gesture, dragging a few pixels down (a down arrow will appear) is used
  to zoom out.  Again, these mouse gestures are subtle and will not work
  if the mouse is dragged more than a few pixels.  If you move too far,
  the motion will be interpreted as a range to zoom instead of the "undo"
  or "zoom out" command.

  This application is an early release version of a very flexible display
  and analysis package currently under development.  For more information
  and updates, see http://www-pw.physics.uiowa.edu/das2/.

  This application utilizes open source libraries from a number of
  sources, including:

    The Apache Software Foundation, http://www.apache.org/

    The Batik SVG Toolkit provided by the Apache XML Project,
    http://xml.apache.org/batik/

    The iText Java-PDF library, http://www.lowagie.com/iText/

  We gratefully acknowledge the efforts of the Java open source
  community.


VGPWS_WF_LIST.C example C code
==============================

  The file VGPWS_WF_LIST.C contains example C code for a complete program
  to read and list data from Voyager 1 and Voyager 2 PWS waveform reciever
  archive files.

  In order to compile and test the example, you will need to copy
  all of the files in the EXTRAS/SOFTWARE/C directory to a writable
  directory.  For POSIX development environments, a makefile is provided
  to automate the creation and verification of the two executable
  programs.  To use the makefile (in the writable directory):

  % make -f VGPWS_WF_LIST.MAK

  If there are no compilation errors, then

  % make -f VGPWS_WF_LIST.MAK test

  The last 2 lines printed should indicate whether the executable was
  verified to be working correctly or not.


  Compile and Test Details
  ------------------------
  In case the makefile cannot be used, the details of compilation and
  testing are as follows on POSIX systems:

  In order to compile this code on POSIX systems, it may be necessary to
  rename the file and remove the CR character from the CRLF line
  termination.  Note that gcc does not require this step.

  % tr -d \\r < VGPWS_WF_LIST.C > vgpws_wf_list.c

  On systems with the gnu compiler tools the compile may be as simple as

  % gcc -O -o vgpws_wf_list vg1pws_wf_list.c

  The executables should be used to generate the output file verify.txt
  from the provided input data file:

  % vg1pws_wf_list < TESTIN.DAT > verify.txt

  Finally the newly created output file should be compared against the
  provided output file:

  % diff TESTOUT.TXT verify.txt

  If there are no differences, then your compiled example should be
  working correctly.


VGPWS_WF_PLOT.PRO example IDL code
==================================

  The file VGPWS_WF_PLOT.PRO contains example IDL code for an application
  to read and plot data from the binary archive files.  The application
  will prompt for a file name and then step through all available
  samples, showing the waveform and relative power spectrum for each
  line.

=========================================================================
