readADCP

Description

readADCP is a comprehensive command-line utility for reading, processing, and visualizing data from RDI ADCPs (Acoustic Doppler Current Profilers). It can read RDI’s ASCII output format, apply various temporal and spatial filters, perform corrections, average data, and generate time-series profiles or georeferenced maps of the current field.

The tool can output various data types, including velocity magnitude, direction, backscatter, or error velocity, into a JHC-formatted 2D image file (.prof). It can also stack or map this data onto a georeferenced grid.

Usage 

readADCP -in <infiles> -out <outfile> [OPTIONS]

Key Options

Input/Output

| Option | Description | |—|—| | -in <infilename(s)> | Required. One or more input RDI ASCII ADCP files. | | -out <outfile> | Required. The prefix for the output filenames. | | -nav <navfile> | Use an external OMG-HDCS navigation file for positioning. | | -use_adcp_nav | Use the navigation data embedded within the ADCP files. | | -att <attfile>| Use an external OMG-HDCS attitude file for heading information. | | -tidefile <tide.nav> | Use an external navigation file to provide tidal height corrections. | | -dtm_ref <terrain.r4> | Use a DTM file to remove data below the seafloor. | | -map <mapfile.map> | Georeference and stack the output profiles onto a map grid. | | -export_r4 | In addition to the 8-bit image, export the profile data as a floating-point (.r4) file. | | -winADCP | Enable special parsing mode for files generated by RDI’s WinADCP software. | | -dump_CURR / -dump_BINS | (with -winADCP) Dumps current or bin data to ASCII files for each ensemble. |

Data Selection and Filtering

| Option | Description | |—|—| | -start <Y J H M> | Set the start time for processing (Year, Julian Day, Hour, Minute). | | -end <Y J H M> | Set the end time for processing. | | -startYMD <Y M D H M>| Set start time using Year, Month, Day, Hour, Minute. | | -endYMD <Y M D H M> | Set end time using Year, Month, Day, Hour, Minute. | | -duration_min <mins> | Set the processing duration in minutes from the start time. | | -bounds_from <navfile>| Use the time window from another navigation file. | | -mindepth <m> / -maxdepth <m> | Set the minimum and maximum depth range to process. | | -bottom_ref| Interpret -mindepth and -maxdepth as distances from the seafloor instead of the surface. | | -onlyuseshipheading <min> <max> | Only process data where the ship’s heading is within the specified range (0-360). | | -allowable_sum_percent_good <%> | Set the minimum threshold for the sum of “percent good” values from all beams (max 400). | | -maximum_believable_magnitude <mm/s> | Reject velocity data with a magnitude greater than this value. Default is 10000. |

Processing and Display

| Option | Description | |—|—| | -showMAG | (Default) Display velocity magnitude in the output profile. | | -showBS | Display backscatter intensity. Use with -BSrange. | | -showAZI| Display velocity direction (azimuth). | | -showVERT| Display the vertical velocity component. | | -showERR | Display the error velocity. | | -showTAN / -showRAD | Display tangential or radial velocity components relative to the map orientation. | | -maxcurrent <m/s> | Set the maximum current for scaling the output image colors (for MAG, TAN, RAD, VERT). | | -BSrange <min> <max> | Set the min/max backscatter values for color scaling. | | -ensem_stack <num> | Average (stack) data over a specified number of ensembles before writing to the output file. | | -headbias <deg> | Apply a constant heading correction in degrees. | | -delay <sec> | Apply a time delay in seconds to the data. | | -do_Sv | Convert raw backscatter (DN) to absolute volume backscatter (Sv). | | -layers <num> | Set the number of vertical bins in the output profile. Default is 100. |

How It Works

  1. Read Data: The tool reads the specified ADCP files, which can be in standard RDI ASCII format or a WinADCP variant. It also loads any auxiliary files provided (nav, attitude, tide, DTM).
  2. Time Filtering: It processes each ADCP ensemble (ping), checking if its timestamp falls within the user-defined time window.
  3. Data Filtering: For each depth bin within an ensemble, it checks if the data is valid based on user thresholds like allowable_sum_percent_good and maximum_believable_magnitude.
  4. Georeferencing: If navigation data is provided, the tool interpolates it to find the precise geographic position of each ensemble.
  5. Profile Generation: It creates a vertical profile for the chosen data type (e.g., Magnitude). The data is vertically binned into a profile with a number of layers defined by -layers.
  6. Interpolation: The tool can interpolate between valid data points in the vertical profile to fill small gaps.
  7. Output:
    • Profile Mode: The generated vertical profile for each ensemble is written as a single column in the output .prof image file, creating a time-series visualization.
    • Map Mode (-map): If a map is provided, the tool projects each ensemble’s profile into the appropriate geographic bin on the map. All profiles falling into the same map column are averaged together to produce a 2D cross-section of the current field.
  8. Stacking: If -ensem_stack is used, data is first averaged over the specified number of ensembles before being written to the output file.

This process transforms raw, time-ordered ADCP profiles into a spatially or temporally coherent image that is useful for analysis.