MB-System Unix Manual Page

mbnavedit

Section: MB-System 5.0 (l)
Updated: 3 June 2005
Index

NAME

mbnavedit - Interactive navigation editor for swath sonar data.

VERSION

Version 5.0

SYNOPSIS

mbnavedit [-Byr/mo/da/hr/mn/sc -D -Eyr/mo/da/hr/mn/sc -Fformat -G -Iinfile -N -P -T -X -V -H]

DESCRIPTION

MBnavedit is an interactive editor used to identify and fix problems with the navigation of swath sonar data.

In the default mode the edited navigation is output to a file with the suffix ".nve" appended to the input swath data filename. The program can also be operated in a "browse" mode where no navigation is output. If saved, the edited navigation can be merged with the swath data using the program mbprocess, which outputs a processed swath data file. The mbprocess program is also used to apply bathymetry edits, recalculate bathymetry, and apply other corrections to swath bathymetry data. Users may cause mbprocess to be run automatically by specifying the -X option when starting MBnavedit.

In previous versions of MB-System (version 4.6.10 or earlier), MBnavedit produced output swath data files directly by reading and storing all of the swath data information in memory (including non-survey data records). This approach limited the amount of data that could be handled at once, frequently requiring users to process files in small pieces. The current version only stores and outputs the navigation data. The previous form of MBnavedit is now distributed as MBnaveditold. The old version will continue to be supported for MB-System version 5.0. However, no improvements will be made to the old program, and it may be dropped from later MB-System distributions.

Once the navigation from a swath data file has been read in, MBnavedit displays autoscaled plots of the longitude, latitude, speed, heading, and sonar depth time series, along with a plot of the time interval between navigation values. The user may select outliers and interpolate over them or, in the case of heading or speed data, replace the erroneous values with estimates derived from "course-made-good" or "speed-made-good", respectively. Data can only be selected and altered in a single plot at a time (this avoids confusion and prevents mistakes).

The nature of the navigation data being edited depends upon the data format. Some data formats include the navigation in the same data records as the ping or survey data. This synchronous navigation implies that either in the sonar or in later processing, the raw navigation has been interpolated to yield values at the same time stamps as the sonar pings. Other data formats do not hold navigation values in the survey data records, and instead use separate navigation records with different time stamps. This asynchronous navigation requires that MBIO interpolate or extrapolate the navigation as the survey data records are read. For data formats with synchronous navigation, the navigation values edited using MBnavedit are those in the survey data records. For data formats with only asynchronous navigation, MBnavedit displays and operates on the values from the navigation records. The MBIO manual page includes a listing of which type of navigation is used by the supported data formats.

For some data formats, the user can also inspect plots of roll, pitch, and heaved data to determine if the ship's vertical reference sensors were working properly.

The edited data is usually output to a file, but the program can be operated in a "browse" mode where no data is output.

SMOOTHING NAVIGATION

Two algorithms for obtaining and using smooth navigation models are available. Replacing the original navigation with a smoothed version can be advantageous in some cases of very noisy navigation (typically from sonars on towed platforms or submerged vehicles). The first approach is simple dead reckoning from the initial position using the current (possibly edited) heading and speed values. The dead reckoning navigation can also incorporate user-specified longitude and latitude drift rates. The second algorithm is an inversion for a smooth navigation that minimizes speed and acceleration while fitting the original navigation in a least squares sense. The inversion weighting against speed and acceleration are user specified, and only unaltered navigation values are used in the inversion (this means that longitude and latitude values that have previously been selected and interpolated are not used to generate the smooth model).

HANDLING BAD TIME STAMPS

The time interval plot allows users to spot problems with time stamps and to change the time stamps, if necessary. The most obvious time stamp errors are multiple pings with the same time stamps (producing a zero time interval value), or sequential pings with decreasing time stamps (resulting in negative time interval values). MBnavedit provides two tools for dealing with zero or negative time intervals: time stamp interpolation or deletion of the affected pings. Control dialogs allow users to apply either to the entire buffer at once. Time stamp interpolation may also be accomplished by selecting the relevant values in the time interval display, and then selecting interpolation.

If the navigation is asynchronous, that generally means the time interval should be constant since navigation systems are set to output values at a uniform rate. A problem with the time stamps of asynchronous navigation should produce spikes in both the time interval plot and the speed-made-good plot, and can be solved by selecting the offending point in the time interval plot and interpolating to reset the time stamp.

If the navigation is synchronous with the sonar pings, then the time interval will likely vary because the ping rate for most sonars varies with the sonars altitude above the seafloor. In this case, time stamp problems will not produce spikes in the speed-made-good plot because the navigation has been interpolated using the existing time stamps. Time interval spikes may also reflect problems with the sonar (e.g. occasional failure to ping at the appropriate time) rather than erroneous time stamps.

AUTHORSHIP

David W. Caress (caress@mbari.org)

Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)

Lamont-Doherty Earth Observatory

OPTIONS

-B yr/mo/da/hr/mn/sc
Sets the starting time for data allowed in the input data; pings with times before the starting time will be ignored. Default: yr/mo/da/hr/mn/sc = 1962/2/21/10/30/0.

-D: Starts up the program in "browse" mode. If a file is opened in browse mode (either at startup or later), none of the edited data will be output to a file. The default is to output the edited data to a file.
-E: yr/mo/da/hr/mn/sc
Sets the ending time for data allowed in the input data; pings with times after the ending time will be ignored. Default: yr/mo/da/hr/mn/sc = 2062/2/21/10/30/0.
-F: format
Sets the format at startup for the input and output swath sonar data using MBIO integer format identifiers. This value can also be set interactively when specifying the input file. This program uses the MBIO library and will read or write any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. Default: format = 11.
-G: This flag causes MBnavedit to treat the Done button as equivalent to the Quit button. This option is used when MBnavedit is started automatically by some other process and only a single file is to edited.
-H: This "help" flag cause the program to print out a description of its operation and then exit immediately.
-I: infile
Sets the data file from which the input data will be read at startup. This value can also be set interactively. If the input file is named using the MB-System convention of an ".mbXX" suffix (the XX corresponds to the MBIO format id), then the output file name will have an "e.mbXX" suffix. Otherwise, the output file will be infile with ".ed" appended.
-N: Normally, all MB-System processing programs embed comment records describing the processing actions and parameters into output swath data files. This flag, when used in conjunction with the -X flag, causes MBnavedit to invoke mbprocess with it's -N option. In turn, this causes mbprocess to generate an output, processed swath data file without any comment records.
-O: outfile
Sets the output data file, overriding the file naming conventions discussed above in the -I option.
-P: Causes MBnavedit to load and work with navigation from survey data records even if the data format uses asynchronous navigation records. In this case, the only edits which will actually be applied to the output data are changes to the time stamps of the survey records.
-V: Normally, MBnavedit outputs information to the stderr stream regarding the number of records loaded and dumped. If the -V flag is given, then MBnavedit works in a "verbose" mode and outputs the program version being used, all error status messages, and a large amount of other information including all of the beams flagged or zeroed.
-X: This option causes mbprocess to run automatically on an input swath data file when the MBnavedit editing session is completed. The -X option effectively means that the corresponding processed swath data is generated or updated immediately. The program mbprocess will not be invoked if the editing session is in the browse mode.

INTERACTIVE CONTROLS

File: This menu brings up a popup window which allows the user to specify the input swath sonar data file, its MBIO format id, the output mode, and the output navigation file name. This program uses the MBIO library and will read any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. If the swath sonar data file is named using the MB-System suffix convention (format 11 files end with ".mb11", format 41 files end with ".mb41", etc.), then the program will automatically use the appropriate format id; otherwise the format must be set by the user. The default output navigation filename will be infile with ".nve" appended. Under most circumstances, users should use the default output filename because mbprocess expects this form. The popup window also allows the output mode to be set to "browse" so that the edited navigation data are not written to a file. When a valid file is specified and the OK button is clicked, as much data as will fit into the data buffer (25000 navigation points) is read and the navigition times series plots are displayed.
Controls: This button activates a pulldown menu with five buttons: Time Stepping, Nav Modeling, Time Interpolation, Delete Bad Times, and Position Offset. Each of these buttons brings up a dialog window containing widgets that set parameters or perform actions.
Controls->Time Stepping->Time Span Shown: This slider sets the number of seconds of data shown at a time. This value is also set by the Show Entire Buffer button (sets time shown to all available data) and the Pick Time Interval function (sets time shown to an interactively specified interval).
Controls->Time Stepping->Time Step: This slider sets the number of seconds to step when the Forward or Reverse buttons are pushed.
Controls->Navigation Modeling->Off: This toggle button turns navigation modeling off.
Controls->Navigation Modeling->Dead Reckoning: This toggle button enables dead reckoning navigation calculation. When this toggle button is highlighted, a dead reckoning navigation model is calculated from the initial position using the current heading and speed data and displayed as a blue line in both the longitude and latitude plots. The Show Dead Reckoning toggle buttons also appear (already enabled) for both the longitude and latitude plots among the plot display toggles on the left side of the main MBnavedit window.
Controls->Navigation Modeling->Smooth Inversion: This toggle button enables inversion for a smooth navigation model which fits the original positions in a least squares sense while minimizing speed and acceleration. When this toggle button is highlighted, a smooth navigation model is calculated and displayed as a blue line in both the longitude and latitude plots. The Show Smooth Inversion toggle buttons also appear (already enabled) for both the longitude and latitude plots among the plot display toggles on the left side of the main MBnavedit window.
Controls->Navigation Modeling->Dead Reckoning Longitude Drift: This slider sets the longitude drift rate in degrees/hour applied to the dead reckoning navigation calculation. If dead reckoning is enabled, changes to this slider cause the dead reckoning calculation to be redone and the results shown on the longitude and latitude plots.
Controls->Navigation Modeling->Dead Reckoning Latitude Drift: This slider sets the latitude drift rate in degrees/hour applied to the dead reckoning navigation calculation. If dead reckoning is enabled, changes to this slider cause the dead reckoning calculation to be redone and the results shown on the longitude and latitude plots.
Controls->Navigation Modeling->Speed Deviation: This text entry sets the penalty weighting against speed applied in the inversion for a smooth navigation. Higher values result in a smoother model; lower values result in a model that more closely follows the original navigation. The default value is 100. This value is not actually set until the Apply button to the left is clicked.
Controls->Navigation Modeling->Acceleration: This text entry sets the penalty weighting against accleration applied in the inversion for a smooth navigation. Higher values result in a smoother model; lower values result in a model that more closely follows the original navigation. The default value is 100. This value is not actually set until the Apply button to the left is clicked.
Controls->Navigation Modeling->Apply: This button causes the values in the Speed Deviation and Acceleration text entries to its right to be applied. If smooth inversion is enabled, then clicking this button will cause the inversion to be recalculated and the results displayed in the longitude and latitude plots.
Controls->Navigation Modeling->Dismiss: This button causes the Navigation Modeling dialog to disappear.
Controls->Time Interpolation->Apply: This button causes the time stamps of all data in the current buffer associated with negative or zero time intervals to be interpolated so that the time intervals are positive. The Time Interpolation dialog disappears after this action is taken.
Controls->Time Interpolation->Dismiss: This button causes the Time Interpolation dialog to disappear.
Controls->Delete Bad Times->Apply: This button causes all data in the current buffer associated with negative or zero time intervals to be deleted. The Delete Bad Times dialog disappears after this action is taken.
Controls->Delete Bad Times->Dismiss: This button causes the Delete Bad Times dialog to disappear.
Controls->Position Offset->Longitude Offset: This text widget allows the user to set the desired longitude offset in degrees.
Controls->Position Offset->Latitude Offset: This text widget allows the user to set the desired latitude offset in degrees.
Controls->Position Offset->Apply: This button applies the current longitude and latitude offsets to all of the navigation data. The Position Offset dialog disappears after this action is taken.
Controls->Position Offset->Dismiss: This button causes the Delete Bad Times dialog to disappear.
Next Buffer: This button causes the program to write out the data from the current buffer and then read in and display the next buffer. If there is no more data to be read in after the current buffer has been written out, then the input and output files are closed.
Done: This button causes the program to write out all of the data from the input file and then close the input and output files.
Forward: This button causes the set of displayed pings to step nstep pings forward in the current buffer. The right mouse button causes the same action.
Reverse: This button causes the set of displayed pings to step nstep pings backward in the current buffer. The middle mouse button causes the same action.
Quit: This button causes the program to exit gracefully. If a data file has been read, all of the data will be written to the output file before exiting.
About: This button causes a dialog to appear showing some information about the program.
Show All: This button causes the plots to expand to show all of the data in the current buffer.
Pick Zoom: This button allows users to focus the plots on a particular time interval. Once the button is pushed, the left mouse button is used to select the left edge of the time selection. Similarly, the middle mouse button selects the right edge of the time selection. Both ends of the time selection can be adjusted multiple times. Once the time interval of interest is selected to the users satisfaction, pressing the right mouse button will cause the plots to be redrawn with the selected beginning and ending times.
Interpolate: This button causes the selected data to be replaced by linear interpolation of the surrounding unselected data. If the selection extends to the edge of the data, the selected data will be replaced by the first unselected datum on the other side.
Interpolate Repeats: This button causes any repeated values in the selected data to be replaced by linear interpolation between the first of the repeated values and the next different value.
Revert Selection: This button causes the selected data to revert to their original values.
Use Solution: This button only appears when one of the two navigation modeling algorithms is activated from the Navigation Modeling dialog. This button causes any selected longitude or latitude values to be replaced by values from navigation modeling. Either dead reckoning or smooth inversion navigation modeling must be enabled. The longitude and latitude values are replaced in pairs (if a longitude value is selected, the corresponding latitude value will also be replaced, and vice versa). The typical sequence is to:
    1) adjust the modeling until an acceptable solution
       is achieved.
    2) click on the Select All toggle button
    3) click in either the longitude or latitude plot
       so that all values in that window are selected
    4) click on the Use Solution button so that the
       navigation model is adopted for all longitude
       and latitude values
Flag: This button only appears when the smooth inversion navigation modeling algorithms is activated from the Navigation Modeling dialog. This button causes any selected longitude or latitude values to be flagged to be ignored by the smooth inversion modeling algorithm. Flagged positions are shown in orange.
Unflag: This button only appears when the smooth inversion navigation modeling algorithms is activated from the Navigation Modeling dialog. This button causes any selected longitude or latitude values to be unflagged. Flagged positions are ignored by the smooth inversion modeling algorithm. Any positions which are unflagged will once again be used by the inversion. Flagged positions are shown in orange. Unflagged positions are shown in either black (if they are unchanged) or purple (if they have been altered by interpolation or application of a modeling solution).
Pick: Clicking on this toggle button sets the edit mode to "pick". In this case, clicking the left mouse button will cause the nearest data value to toggle between selected (red) and unselected.
Select: Clicking on this toggle button sets the edit mode to "select". In this case, clicking and dragging the left mouse button will cause any data value touched by the cursor to become selected.
Deselect: Clicking on this toggle button sets the edit mode to "deselect". In this case, clicking and dragging the left mouse button will cause any data value touched by the cursor to become unselected.
Select All: Clicking on this toggle button sets the edit mode to "select all". In this case, clicking in any of the editable plots will cause all of the data in that plot to be selected.
Deselect All: Clicking on this toggle button sets the edit mode to "select all". In this case, clicking in any of the editable plots will cause all of the data in that plot to be unselected.
Time Interval Plot: This toggle button turns the time interval plot on and off.
Show Original Data (Time Interval Plot): When this toggle button is on, the time interval plot includes a green line representing the original time interval values.
Longitude Plot: This toggle button turns the longitude plot on and off.
Show Original Data (Longitude Plot): When this toggle button is on, the longitude plot includes a green line representing the original longitude values.
Show Dead Reckoning (Longitude Plot): When this toggle button is on, the longitude plot includes a blue line representing the dead reckoning longitude values.
Show Smooth Inversion (Longitude Plot): When this toggle button is on, the longitude plot includes a blue line representing the smooth inversion longitude values.
Latitude Plot: This toggle button turns the latitude plot on and off.
Show Original Data (Latitude Plot): When this toggle button is on, the latitude plot includes a green line representing the original latitude values.
Show Dead Reckoning (Latitude Plot): When this toggle button is on, the latitude plot includes a blue line representing the dead reckoning latitude values.
Show Smooth Inversion (Latitude Plot): When this toggle button is on, the latitude plot includes a blue line representing the smooth inversion latitude values.
Speed Plot: This toggle button turns the speed plot on and off.
Show Original Data (Speed Plot): When this toggle button is on, the speed plot includes a green line representing the original speed values.
Show Speed-Made-Good (Speed Plot): When this toggle button is on, the speed plot includes a blue line representing the speed-made-good values derived from the longitude and latitude time series.
Use Speed-Made-Good (Speed Plot): When this button is pushed, any selected data in the speed plot will be replaced by the current estimates of speed-made-good.
Heading Plot: This toggle button turns the heading plot on and off.
Show Original Data (Heading Plot): When this toggle button is on, the speed plot includes a green line representing the original speed values.
Show Course-Made-Good (Heading Plot): When this toggle button is on, the heading plot includes a blue line representing the course-made-good values derived from the longitude and latitude time series.
Use Course-Made-Good (Heading Plot): When this button is pushed, any selected data in the heading plot will be replaced by the current estimates of course-made-good.
Roll, Pitch, and Heave Plots: This toggle button turns the roll, pitch, and heave plots on and off. Unlike the other plots, the data in these plots is not editable. These data are shown purely to allow users to determine if the vertical reference sensors were working properly at the time the data was collected (note: many swath data formats do not contain roll, pitch, and heave data).

MOUSE ACTIONS

Left Mouse Button: The left mouse button is used to pick data values. Unselected data values are shown as filled black squares and selected values as empty red squares. The manner in which data are selected or unselected is controlled by the edit mode, as set by the Pick, Select, Deselect, Select All, and Deselect All buttons.
Middle Mouse Button: The middle mouse button causes the set of displayed data to step backward in the current buffer by the amount of time set on the Time Step slider. The control button Reverse causes the same action.
Right Mouse Button: The right mouse button causes the set of displayed data to step forward in the current buffer by the amount of time set on the Time Step slider. The control button Forward causes the same action.

BUGS

This program doesn't handle the roll, pitch, and heave data in a general way. The main window for MBnavedit is too large for use on screens smaller than 1024 X 768 pixels.