=========================================== 
README  : Mal Geoscience RAMAC GPR tools
Language: Interactive Data Language (IDL)
Version : 1.00
Author  : John Maurer (john-maurer@users.sourceforge.net)
          2005-2006 University of Colorado
Date    : April 5, 2006
===========================================

The contained software tools have been created for opening, filtering, and
analyzing Mal Geoscience RAMAC (http://ramac.malags.com) ground-penetrating
radar (GPR) data. These tools are programmed using ITT Visual Information
Solution's (http://ittvis.com) Interactive Data Language (IDL)
(http://ittvis.com/idl/) for use within the Environment for Visualizing Images
(ENVI) software (http://ittvis.com/envi/). These tools were programmed and
tested on a Microsoft Windows personal computer using IDL 6.1 and ENVI 4.1 but
should work on other operating systems and software versions. 

These software tools are saved as IDL procedures (.pro files) and should be
moved to the ENVI "save_add" directory prior to use. The location of the ENVI
"save_add" directory may vary on different systems, but can generally be found
according to the following path on a Windows computer:

    C:\RSI\IDL61\products\ENVI41\save_add\

When ENVI user functions (.pro or .sav files) are placed in the ENVI
"save_add" directory, they are automatically compiled in the ENVI session's
RAM when ENVI starts. Also, once a user function has been added to ENVI, its
code can be modified at any time, recompiled from within the current ENVI
session, and then used in its modified form without having to restart ENVI.

Furthermore, these procedures can be made part of the ENVI menus. The ENVI
menu system is comprised of the "Main" menu that appears when you start ENVI
and the "Functions" menu that is accessed only from image display windows.
These two menus are defined by separate ASCII text files located in the ENVI
"menu" directory:

    C:\RSI\IDL61\products\ENVI41\menu\

The "envi.men" file in the above directory defines the Main menu, and the
"display.men" file defines the Functions menu. Each time a new ENVI session is
started, these two menu files are read and used to construct the ENVI menus
based on the content of the files. To add a new button to one of the two
menus, simply add a new line to one of the files and restart ENVI. See
"Modifying the ENVI Menus" in the ENVI Online Help for more details on the
specific syntax and format of modifying the menu files. Each of the contained
procedures documents in its header the necessary lines to add to the menu
files. In short, however, add the following text to the bottom of
"display.men" for the necessary tools to be displayed in the "Functions" menu
under a menu heading labeled "GPR":

C:\RSI\IDL61\products\ENVI41\menu\display.men:

0 {GPR}
  1 {Filter}
    2 {Subtract Mean Trace} {not used} {subtract_mean_trace}
    2 {Time-Varying Gain} {not used} {time_varying_gain}
    2 {DC Removal} {not used} {dc_removal}
  1 {Cursor Depth/Distance...} {not used} {cursor_depth_distance}
  1 {Create XYZ File...} {not used} {collect_input_create_xyz_file}
  1 {Compute Depth Statistics...} {not used}
{collect_input_compute_depth_statistics}

Next, add the following text to the "envi.men" file for the remaining tools to
be displayed on the main ENVI menu bar. These tools are added to this menu
since they can be applied to multiple GPR files and because these GPR files do
not need to be already open in ENVI for these procedures to run:

C:\RSI\IDL61\products\ENVI41\menu\envi.men:

0 {GPR}
  1 {Bulk Filter} {not used} {bulk_gpr_filter}
  1 {Create XYZ File} {not used} {collect_input_bulk_xyz_file}
  1 {Compute Depth Statistics} {not used}
{collect_input_bulk_depth_statistics}

The following should also be appended to the above "envi.men" file
underneath the existing main "File > Open External File" section for adding
a tool that can open the GPR data automatically:

C:\RSI\IDL61\products\ENVI41\menu\envi.men:

0 {File}
  1 {Open External File} {separator}
    2 {GPR}
      3 {RAMAC} {not used} {open_ramac_gpr_file}

Lastly, in order for the "Cursor Depth/Distance" tools to work, you must
also open the ENVI "Preferences" menu from the main ENVI "File" menu. On the
main tab entitled "User Defined Files", enter "gpr_cursor_info" in the bottom
text box that is labeled "User Defined Motion Routine". Click "OK" to save the
new preference and choose to save these updated preferences to a file if you
wish them to be saved after you close and restart ENVI. The information from
this procedure will not be displayed, however, until the "Cursor
Depth/Distance" function is called from either the Main or Function "GPR"
menus created above. See "cursor_depth_distance.pro" for further details.

Documentation regarding each of the contained software tools is included at
the top of each program as well as at the following website:

    http://gpr-idl-tools.sourceforge.net

For an example application that has employed these IDL procedures, see my
Masters thesis from the Department of Geography at the University of Colorado
at Boulder on "Local-scale snow accumulation variability on the Greenland ice
sheet from ground-penetrating radar (GPR)", available in both HTML and PDF
formats from the following location:

    http://cires.colorado.edu/~maurerj/gpr/gpr_cryosphere.html

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details
(GNU_License.txt).

You should have received a copy of the GNU General Public License along with
this program (GNU_License.txt; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.

============================================================================
John Maurer
M.A. - Department of Geography
Cooperative Institute for Research in Environmental Sciences (CIRES)
University of Colorado at Boulder
john-maurer@users.sourceforge.net
http://cires.colorado.edu/~maurerj
Advisor: Dr. Konrad Steffen (konrad.steffen@colorado.edu)
http://cires.colorado.edu/science/groups/steffen/
2005-2006 University of Colorado