/*=========================================================================
 *=========================================================================
  == [DISCLAIMER]: THIS SOFTWARE AND ANY ACCOMPANYING DOCUMENTATION IS   ==
  == RELEASED "AS IS".  THE U.S. GOVERNMENT MAKES NO WARRANTY OF ANY     ==
  == KIND, EXPRESS OR IMPLIED, CONCERNING THIS SOFTWARE AND ANY          ==
  == ACCOMPANYING DOCUMENTATION, INCLUDING, WITHOUT LIMITATION, ANY      ==
  == WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  ==
  == IN NO EVENT WILL THE U.S. GOVERNMENT BE LIABLE FOR ANY DAMAGES      ==
  == ARISING OUT OF THE USE, OR INABILITY TO USE, THIS SOFTWARE OR ANY   ==
  == ACCOMPANYING DOCUMENTATION, EVEN IF INFORMED IN ADVANCE OF THE      ==
  == POSSIBLITY OF SUCH DAMAGES.                                         ==
  =========================================================================
  =========================================================================*/

*************************************************************************
*                               ADTSTOOLS_README                        *
*************************************************************************
*                                                                       *
*  Author: John Querns, Veridian Inc (Veda)                             *
*    Date: 5 May 1998                                                   *
*                                                                       *
* If you have any questions, contact:                                   *
*                                                                       *
*          John F. Querns                                               *
*          Work : (937) 255-1116, ext. 2818                             *
*          email: jquerns@mbvlab.wpafb.af.mil                           *
*                                                                       *
* Or send an email to the SDMS Help Desk:                               *
*                                                                       *
*          email: sdms_help@mbvlab.wpafb.af.mil                         *
*                                                                       *
*************************************************************************

****************************
* ADTS 8-8-4 DOCUMENTATION *
****************************

Documentation on the ADTS (ATRWG) 8-8-4 format can be found in:

     ADTS884_README   {ASCII Text format}

You can also find an explanation at the SDMS Web site:

URL: 

 http://www.mbvlab.wpafb.af.mil/public/sdms/datasets/884explanation.htm


-----------------------------------------------------------------------------

****************************
* MULTI-POLARIZATION TOOLS *
****************************

Multi-polarization tools are those that read, extract, and/or convert
ADTS 8-8-4 formatted files that contain 4 sub-images, one for each
polarization (HH, HV, VH, and VV).  Current multi-polarization tools
include:

  [MultiPolarizationTools/conv884/convert884]:

    Input :  4-polarization ADTS image file in 8-8-4 format.
    Output:  1-polarization ADTS image file in one of the following formats:

              a) Raw 64-bit complex [32-bit real, 32-bit imag].
              b) Raw magnitude [32-bit real].
              c) Raw magnitude-squared [Sigma0, 32-bit real].
              d) Raw RCS image [32-bit real].

                 RCS image has "sigma_0_to_rcs" factor from header
                 applied.

             Optionally dumps headers (1 & 2) in ASCII format.

  [MultiPolarizationTools/disp884/disp884hdr]:

    Input : 4-polarization ADTS image file in 8-8-4 format.
    Output: Displays header files for each polarization-specific
            sub-image to standard output.

  [MultiPolarizationTools/dump884/dump884hdr]:

    Input : 4-polarization ADTS image file in 8-8-4 format.
    Output: Dumps header files for each polarization-specific
            sub-image to an output file.


----------------------------------------------------------------------------

*****************************
* SINGLE-POLARIZATION TOOLS *
*****************************

Single-polarization tools are those that read, extract, and/or convert
ADTS 8-8-4 formatted files that contain 1 polarization-specific image
(either HH, HV, VH, or VV).  Current multi-polarization tools include:

  [SinglePolarizationTools/cv884/cv884]:

    Input :  1-polarization ADTS image file in 8-8-4 format.
    Output:  1-polarization raw complex [32-bit real, 32-bit imag] image.

  [SinglePolarizationTools/ex884/ex884]:

    Input :  4-polarization ADTS image file in 8-8-4 format.
    Output:  1-polarization ADTS image file in 8-8-4 format.

  [SinglePolarizationTools/hdr884/hdr884]:

    Input :  1-polarization ADTS image file in 8-8-4 format.
    Output:  ADTS image headers (1 & 2) to standard output.

  [SinglePolarizationTools/raw884/raw884cnv]:

    Input :  1-polarization ADTS image file in 8-8-4 format
             with no header.
    Output:  1-polarization raw complex [32-bit real, 32-bit imag] image.


---------------------------------------------------------------------------

*************************** 
* Compiling/Linking Code  *
***************************

The ADTS toolkit includes Makefiles for each tool in the set.  To compile
and link each tool, you can do so either from the commandline or by using
the provided makefiles.  The following examples use the GNU C compiler,
"gcc", but you can use whatever C compiler you wish.  If you use the 
provided makefiles to compile and link your code and wish to use a C
compiler other than gcc, you will need to edit the appropriate *.mk file
and change the variable "CC" to your C compiler.


 ***********************************
 * METHOD 1: FROM THE COMMAND LINE *
 ***********************************

   a) Change directories to the appropriate tool.
   b) Enter the following at the command line:

      gcc -o {bin name} {src name} [object1 object2 libraries ...] 

        where: {bin name}   -- What you wish to call the output executable
               {src name}   -- Source code to compile and link
               [object 1]   -- Optional subroutine object code to link
               [object 2]   -- Optional subroutine object code to link
               [libraries]  -- Optional static libraries to link

        NOTE: You may need to compile the optional subroutine objects first
              using the "-c" option of your C compiler.

      EXAMPLE 1: To compile and link single polarization tool, "ex884"

                 % gcc -c getimgloc.c [enter]   <-- Creates getimgloc.o object code
                 % gcc -c read_switch.c [enter] <-- Creates read_switch.o object code
          
                 % gcc -o ex884 ex884.c getimgloc.o read_switch.o [enter]

      EXAMPLE 2: To compile and link multi polarization tool, "convert884"

                 % gcc -c dumphdr.c [enter]     <-- Creates dumphdr.o object code
                 % gcc -c getimgloc.c [enter]   <-- Creates getimgloc.o object code 
                 % gcc -c read_switch.c [enter] <-- Creates read_switch.o object code 
           
                 % gcc -o convert884 convert884.c \
                          dumphdr.o getimgloc.o read_switch.o -lm [enter]

                 "-lm" is a link to the C math libraries.


 *********************************
 * METHOD 2: USING THE MAKEFILES *
 *********************************

   a) Change directories to the appropriate tool.
   b) Enter the following at the command line:

      make -f {toolname}.mk [enter]

      where: "-f" is option that tells make command to use
             file that follows as the Makefile.

             {toolname} is the name of the appropriate tool

      EXAMPLES: cd to appropriate directory. Enter:

       a) Making "cv884"        --> make -f cv884.mk      [enter]
       b) Making "ex884"        --> make -f ex884.mk      [enter]
       c) Making "hdr884"       --> make -f hdr884.mk     [enter]
       d) Making "raw884cnv"    --> make -f raw884cnv.mk  [enter]
       e) Making "convert884"   --> make -f convert884.mk [enter]
       f) Making "disp884hdr"   --> make -f disp884hdr.mk [enter]
       g) Making "dump884hdr"   --> make -f dump884hdr.mk [enter]
