readgssi

Copyleft 🄯 2017-2022

Example Radargram

This program was written to read and process ground-penetrating radar files from instruments made by Geophysical Survey Systems Incorporated (GSSI), although I have no affiliation with nor endorsement for the afforementioned organization.

The demands of ice- and ground-penetrating radar (GPR) surveying, as in many types of scientific fieldwork, require that both quality control and time savings are critical to a successful field campaign. This software provides a way to quickly read, process, and display radar data produced by GSSI radar antennas and control units. readgssi was designed to be used in the field to quality-check entire folders of data files by converting radar profiles to portable network graphics (PNG) images, saving users valuable time versus performing the equivalent actions by hand in RADAN, especially in the case of projects with large file counts.

readgssi has the capability to read DZT and DZG files with the same pre-extension name and plot the data contained in those files. readgssi is also currently able to translate most DZT files to CSV and numpy binary (see future). The file read parameters are based on GSSI's DZT file description, similar to the ones available on pages 55-57 of the SIR-3000 manual. File structure is, unfortunately, prone to change at any time, and although I've been able to test with files from several systems, I have not encountered every iteration of file header yet. If you run into trouble, please create a github issue.

Full documentation, including a tutorial, is available at https://readgssi.readthedocs.io.

Questions, feature requests, and bugs: please open a github issue. Kindly provide the error output, describe what you are attempting to do, and attach the DZT/DZG file(s) causing you trouble.

requirements

Strongly recommended to install via anaconda:

Install via pip:

installation

Once you have anaconda running, installing is pretty easy.

You can install via the anaconda cloud:

conda create -n readgssi -c iannesbitt readgssi
# and then activate by doing:
conda activate readgssi

or via pip/PyPI:

conda config --add channels conda-forge
conda create -n readgssi python==3.7 pandas h5py pytz obspy
conda activate readgssi
pip install readgssi

That should allow you to run the commands below.

installing from source:

If you choose to install a specific commit rather than the latest working release of this software, you may download this package, unzip to your home folder, open a command line, then install in the following way:

pip install ~/readgssi

usage

To display the help text:

$ readgssi -h

usage:
readgssi -i input.DZT [OPTIONS]

required flags:
     OPTION     |      ARGUMENT       |       FUNCTIONALITY
-i, --input     | file:  /dir/f.DZT   |  input DZT file

optional flags:
     OPTION     |      ARGUMENT       |       FUNCTIONALITY
-o, --output    | file:  /dir/f.ext   |  output file. if not set, will be named similar to input
-f, --format    | string, eg. "csv"   |  output format (CSV and DZT are the only working formats currently available from the command line)
-p, --plot      | +integer or "auto"  |  plot size. will be x inches high or "auto". default: 10. see also -D to set DPI
-D, --dpi       | positive integer    |  set the plot DPI for figure making. defaults to 150
-T, --titleoff  |                     |  turn the plot title off (useful for figure making)
-x, --xscale    | string, eg. "dist"  |  x units. will attempt to convert the x-axis to distance, time, or trace units based on header values
-z, --zscale    | string, eg. "time"  |  z units. attempt to convert the x-axis to depth, time, or sample units based on header values
-e, --zoom      | list of +int [LRUD] |  set a zoom to automatically jump to. list order is [left,right,up,down] and units are the same as axis
-n, --noshow    |                     |  suppress matplotlib popup window and simply save a figure (useful for multi-file processing)
-c, --colormap  | string, eg. "Greys" |  specify the colormap (https://matplotlib.org/users/colormaps.html#grayscale-conversion)
-g, --gain      | positive float      |  gain constant (higher=greater contrast, default: 1)
-A, --absval    |                     |  Displays the absolute value of the vertical gradient of the array when plotting. Good for displaying faint array features.
-r, --bgr       | +integer or zero    |  horizontal background removal (useful to remove ringing). zero=full width; positive=window size (after stacking)
-R, --reverse   |                     |  reverse (flip array horizontally)
-w, --dewow     |                     |  trinomial dewow algorithm
-t, --bandpass  | +int-+int (MHz)     |  triangular FIR bandpass filter applied vertically (positive integer range in megahertz; ex. 70-130)
-b, --colorbar  |                     |  add a colorbar to the radar figure
-a, --antfreq   | positive integer    |  set antenna frequency. overrides header value
-s, --stack     | +integer or "auto"  |  set trace stacking value or "auto" to autostack to ~2.5:1 x:y axis ratio
-N, --normalize |                     |  distance normalize; reads .DZG NMEA data file if it exists; otherwise tries to read CSV with lat, lon, and time fields
-P, --pausecorr |                     |  pause correction; fixes decoupling of DZG and DZT trace numbers during survey pauses using low velocity GPS marks
-d, --spm       | positive float      |  specify the samples per meter (spm). overrides header value
-m, --histogram |                     |  produce a histogram of data values
-E, --epsr      | float > 1.0         |  user-defined epsilon sub r (sometimes referred to as "dielectric") if set, ignores value in DZT header
-Z, --zero      | +int or list of int |  timezero: skip samples before direct wave. samples are removed from the top of the trace. use list for multi-channel

naming scheme for exports:
  CHARACTERS    |      MEANING
    Ch0         |  Profile from channel 0 (can range from 0 - 3)
    Dn          |  Distance normalization
    Tz233       |  Time zero at 233 samples
    S8          |  Stacked 8 times
    Rv          |  Profile read in reverse (flipped horizontally)
    Bgr75       |  Background removal filter with window size of 75
    Dw          |  Dewow filter
    Bp70-130    |  triangular FIR filter applied from 70 to 130 MHz
    G30         |  30x contrast gain
    Abs         |  Color scale represents absolute value of vertical gradient
    Z10.20.7.5  |  zoom from 10-20 axis units on the x-axis and 5-7 on the z-axis

From a unix command line:

readgssi -i DZT__001.DZT

Simply specifying an input DZT file like in the above command (-i file) will display a host of data about the file including:

name of GSSI control unit
antenna model
antenna frequency
samples per trace
bits per sample
traces per second
L1 dielectric as entered during survey
sampling depth
speed of wave at given dielectric
number of traces
number of seconds

basic functionality

CSV output

readgssi -i DZT__001.DZT -o test.csv -f CSV

Translates radar data array to CSV format, if that's your cup of tea. One might use this to export to Matlab. One CSV will be written per channel. The script will rename the output to 'test_100MHz.csv' automatically. No header information is included in the CSV.

readgssi -i DZT__001.DZT -s 8 -r 0 -o test.csv -f CSV

Applies 8x stacking, and background removal filters before exporting to CSV (see explanations below).

DZT output (experimental)

readgssi -i DZT__001.DZT -R -Z 0 -o test.DZT -f DZT

This exports the array as a second DZT file after reversing the direction of the survey line.

The following operations will stick when writing files:

stacking
filtering
distance normalization
reversing direction
zero (top of array will be shaved off; to avoid this, set -Z 0. this will be fixed in the future.)
manually setting header values, ror example samples per meter (-d 10), epsilon_r (-E 3.1), and antenna frequency (-a 100)

The following operations will not stick:

absolute value of gradient
gain
zoom
plot feature

Readgssi

Install / Use

README