mbnavlist(1)

NAME
mbnavlist - List navigation data in swath sonar data files.

VERSION
Version 5.0

SYNOPSIS
mbnavlist [-Byr/mo/da/hr/mn/sc -Ddecimate -Eyr/mo/da/hr/mn/sc -Fformat -Gdelimeter -H -Ifile -Kkind -Llonflip -Nnavchannel -Ooutput_format -Rwest/east/south/north -Sspeed -Ttimegap -V -Zsegment]

DESCRIPTION
mbnavlist prints the specified contents of navigation records in a swath sonar data file to stdout. By default, mbnavlist produces ASCII files in spreadsheet style, with data columns separated by tabs. Alternatively, other column delimiters can be used (-G option), or the output can be binary, with each field represented as a double precision float (-A option). The output stream can be decimated using the -D option. The output of mbnavlist can be piped to plotting and data analysis programs. The option -Ooutput_format can be used to control the data types that are sent to stdout. By default, mbnavlist extracts navigation from the data record type listed as the "navigation source" for a particular data format. Swath data formats may contain synchronous navigation (navigation is included in survey data records), asynchronous navigation (navigation comes in records separate from and at different times than the survey data records), or both (survey records contain merged navigation while the original asynchronous navigation is preserved in separate navigation records). Some data formats provide for multiple navigation sources, so that there are more than one channel of asynchronous data records. In this case one channel is always designated as the primary or active navigation channel. The -N option allows the user to specify that mbnavlist outputs navigation from the primary asynchronous navigation (-N0) or from one of three auxiliary navigation channels (-N1, -N2, or -N3). If the data format only uses asynchronous navigation, then the default navigation source will already be the primary asynchronous navigation and -N need not be used. If -N is used but the data file does not contain asynchronous navigation or the specified auxiliary navigation channels, then mbnavlist will output nothing. To determine if a datafile contains asynchronous navigation and/or auxiliary navigation, run mbinfo using its -N option to get counts of all data record types in the file. Just to make things more complicated, many data formats formats pass heading and attitude data in records separate from position, and often with different timestamps and sampling rates. If, for instance, the attitude data are sampled at 10 Hz but position is only sampled at 1 Hz, extracting roll using mbnavlist will, by default, either output roll values only at the sonar ping times (if the navigation source is the survey data) or at the position record times (if the navigation source is the asynchronous position data, but not at the attitude data times. Moreover, the attitude data will be interpolated onto the times of sonar pings or position fixes. In order to extract the full attitude data stream, the -Kkind option may be used, where kind is the identifier for the record type to be used as the trigger for output. Any desired values not contained in the selected record will be interpolated onto the times of the selected record. In order to identify the records available in a particular data file, use mbinfo with the -N option. This will show if a data file contains records of type MB_DATA_ATTITUDE, which has a record type identifier of 18, A list of the record type identifiers used within MB-System is given below, although not all of the record types have time stamps or can be used to define mbnavlist output. For example, requesting mbnavlist output associated with comment records will yield nonuseful results.

AUTHORSHIP
David W. Caress (caress@mbari.org)
  Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)
  Lamont-Doherty Earth Observatory

OPTIONS

-A
    Causes the output to be binary (native double precision floating point) rather than ASCII. Some output options cannot be represented as single binary floats (e.g. time strings and longitude or latitude broken into degrees and minutes. These values are output as multiple fields as appropriate. Default: ASCII output with fields separated by tabs.

-B  yr/mo/da/hr/mn/sc
    This option sets the starting time for data allowed in the input data. The -E option sets the ending time for data. If the starting time is before the ending time, then any data with a time stamp before the starting time or after the ending time is ignored. If instead the starting time is after the ending time, then any data between the ending and starting time will be ignored. This scheme allows time windowing both inside and outside a specified interval. Default: yr/mo/da/hr/mn/sc = 1962/2/21/10/30/0.

-D  decimate
    Sets the decimation of the output data. By default (i.e. decimate=1), every available data record is output. If decimate>1, then only every "decimate"th record will be output. Default: decimate=1.

-E  yr/mo/da/hr/mn/sc
    This option sets the ending time for data allowed in the input data. The -B option sets the starting time for data. If the starting time is before the ending time, then any data with a time stamp before the starting time or after the ending time is ignored. If instead the starting time is after the ending time, then any data between the ending and starting time will be ignored. This scheme allows time windowing both inside and outside a specified interval. Default: yr/mo/da/hr/mn/sc = 2062/2/21/10/30/0.

-F  format
    Sets the format for the input swath sonar data using MBIO integer format identifiers. 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. Default: format = 11.

-G  delimiter
    Sets the character(s) used to separate output fields when ascii columns are output. Default: tabs are used as delimiters.

-H  This "help" flag cause the program to print out a description of its operation and then exit immediately.

-I  file
    Sets the input filename. If format > 0 (set with the -F option) then the swath sonar data contained in file is read and processed. If format < 0, then file is assumed to be an ascii file containing a list of the input swath sonar data files to be processed and their formats. The program will read the data in each one of these files. In the file file, each data file should be followed by a data format identifier, e.g.:
         datafile1 11
         datafile2 24
    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: file = "datalist.mb-1".

-K  kind
    This option sets the type of data record used as the trigger for output. By default, data are output when the record type listed as the "navigation source" for a particular data format is encountered. The -K option causes output to be keyed to data records of type kind, where kind may be integer values such as:
         MB_DATA_DATA    1    /* general survey data */
         MB_DATA_CALIBRATE    4    /* Hydrosweep DS */
         MB_DATA_MEAN_VELOCITY    5    /* Hydrosweep DS */
         MB_DATA_VELOCITY_PROFILE    6    /* general */
         MB_DATA_NAV    12    /* Simrad, Reson 7k */
         MB_DATA_HEADING    17    /* Simrad, Hypack */
         MB_DATA_ATTITUDE    18    /* Simrad, Hypack, Reson 7k */
         MB_DATA_SSV    19    /* Simrad */
         MB_DATA_NAV1    28    /* ancillary nav system 1 */
         MB_DATA_NAV2    29    /* ancillary nav system 2 */
         MB_DATA_NAV3    30    /* ancillary nav system 3 */
         MB_DATA_MOTION    32    /* Reson 7k */
         MB_DATA_SIDESCAN2    37    /* Reson 7k, XTF */
         MB_DATA_SIDESCAN3    38    /* Reson 7k, XTF */
         MB_DATA_ROLL    40    /* Reson 7k */
         MB_DATA_PITCH    41    /* Reson 7k */
         MB_DATA_NMEA_RMC    48    /* NMEA */
         MB_DATA_NMEA_DBT    49    /* NMEA */
         MB_DATA_NMEA_DPT    50    /* NMEA */
         MB_DATA_NMEA_ZDA    51    /* NMEA */
         MB_DATA_NMEA_GLL    52    /* NMEA */
         MB_DATA_NMEA_GGA    53    /* NMEA */
         MB_DATA_ATTITUDE1    55    /* ancillary attitude system 1 */
         MB_DATA_ATTITUDE2    56      /* ancillary attitude system 2 */
         MB_DATA_ATTITUDE3    57    /* ancillary attitude system 3 */
    For example, using -K18 will cause mbnavlist to output at the times of attitude data records. One consequence will be that any roll, pitch, or heave values specified with the -O option will be output without modification, whereas other values (e.g. position) will be interpolated onto the time of the attitude record. This option supercedes the -N option.

-L  lonflip
    Sets the range of the longitude values returned. If lonflip=-1 then the longitude values will be in the range from -360 to 0 degrees. If lonflip=0 then the longitude values will be in the range from -180 to 180 degrees. If lonflip=1 then the longitude values will be in the range from 0 to 360 degrees. Default: lonflip = 0.

-N  navchannel
    Sets mbnavlist to look for navigation in navigation records rather than the record type listed as the "navigation source" for a particular data format. Swath data formats may contain synchronous navigation (navigation is included in survey data records), asynchronous navigation (navigation comes in records separate from and at different times than the survey data records), or both (survey records contain merged navigation while the original asynchronous navigation is preserved in separate navigation records). Some data formats provide for multiple navigation sources, so that there are more than one channel of asynchronous data records. In this case one channel is always designated as the primary or active navigation channel. The -N option allows the user to specify that mbnavlist outputs navigation from the primary asynchronous navigation (-N0) or from one of three auxiliary navigation channels (-N1, -N2, or -N3). If -N is used but the data file does not contain asynchronous navigation or the specified auxiliary navigation channels, then mbnavlist will output nothing. To determine if a datafile contains asynchronous navigation and/or auxiliary navigation, run mbinfo using its -N option to get counts of all data record types in the file. This option is superceded by the -K option.

-O  output_format
    Determines the form of the output. Output_format is a string composed of one or more of the following characters:
         c for sonar depth (meters)
         H for heading (degrees)
         h for course made good (degrees)
          J for a time string (yyyy jd hh mm ss.ssssss)
                     where jd is the julian day of the year
          j for a time string (yyyy jd dm ss.ssssss)
                     where jd is the julian day of the year
                     and dm is the minute of the day
         L for cumulative along-track distance (km)
         l for cumulative along-track distance (m)
         M for unix time in decimal seconds since 1/1/70 00:00:00
         m for time in decimal seconds since first record
         N for ping count
         P for pitch in degrees
         p for draft in meters
         R for roll in degrees
         r for heave in meters
          S for speed (km/hr)
          s for speed made good (km/hr)
          T for a time string (yyyy/mm/dd/hh/mm/ss)
         t for a time string (yyyy mm dd hh mm ss)
         U for unix time in integer seconds since 1/1/70 00:00:00
         u for time in integer seconds since first record
         V for ping interval (decimal seconds)
         X for longitude (decimal degrees)
         x for longitude (degrees + decimal minutes + E/W)
         Y for latitude (decimal degrees)
         y for latitude (degrees + decimal minutes + N/S) Default output_format = tMXYHs (time, unix time, latitude, longitude, heading, speed).

-R  west/east/south/north
    Sets the longitude and latitude bounds within which swath sonar data will be read. Only the data which lies within these bounds will be read. Default: west=-360, east=360, south=-90, north=90.

-S  speed
    Sets the minimum speed in km/hr (5.5 kts ~ 10 km/hr) allowed in the input data; pings associated with a smaller ship speed will not be copied. Default: speed = 0.

-T  timegap
    Sets the maximum time gap in minutes between adjacent pings allowed before the data is considered to have a gap. Default: timegap = 1.

-V  Normally, mbnavlist works "silently" without outputting anything to the stderr stream. If the -V flag is given, then mbnavlist works in a "verbose" mode and outputs the program version being used and all error status messages.

-Z  segment
    Causes the ascii output of different input swath files (e.g. when a datalist is specified with the -I option) to be separated by lines with segment. If segment is a single character, then the output is a multiple segment file of the sort accepted by the GMT program psxy. This option only works with ascii output, and is thus disabled when the -A option is specified. The most common usage is -ZI>.

EXAMPLES
Suppose one wishes to obtain a navigation list from a Simrad EM300 data file in the MBARI format (MBIO id 57) called mbari_1998_107_msn.mb57. To obtain a listing with time in unix second forms followed by longitude and latitude, the following will suffice:
     mbnavlist -F57 -i mbari_1998_107_msn.mb57 -OMXY | more The output will be as follows:
     889125106.792000 -155.898471 19.979325
     889125108.148000 -155.898586 19.979400
     889125109.496000 -155.898738 19.979454
     889125110.852000 -155.898876 19.979504
     889125112.207000 -155.899020 19.979544
     889125113.571000 -155.899204 19.979591
     889125114.921000 -155.899479 19.979485
     .....

MB-SYSTEM DATA RECORD TYPES
This list gives the data record types and numerical identifiers used within MB-System. Users can specify that mbnavlist output be keyed to the time stamps of particular record types by using the -Kkind option where kind corresponds to the desired record type identifier from this table.
     MB_DATA_KINDS    54
     MB_DATA_NONE    0
     MB_DATA_DATA    1    general survey data
     MB_DATA_COMMENT    2    general comment
     MB_DATA_HEADER    3    general header
     MB_DATA_CALIBRATE    4    Hydrosweep DS
     MB_DATA_MEAN_VELOCITY    5    Hydrosweep DS
     MB_DATA_VELOCITY_PROFILE    6    general
     MB_DATA_STANDBY    7    Hydrosweep DS
     MB_DATA_NAV_SOURCE    8    Hydrosweep DS
     MB_DATA_PARAMETER    9    general
     MB_DATA_START    10    Simrad
     MB_DATA_STOP    11    Simrad
     MB_DATA_NAV    12    Simrad, Reson 7k
     MB_DATA_RUN_PARAMETER    13    Simrad
     MB_DATA_CLOCK    14    Simrad
     MB_DATA_TIDE    15    Simrad, Reson 7k
     MB_DATA_HEIGHT    16    Simrad
     MB_DATA_HEADING    17    Simrad, Hypack
     MB_DATA_ATTITUDE    18    Simrad, Hypack, Reson 7k
     MB_DATA_SSV    19    Simrad
     MB_DATA_ANGLE    20    HSMD
     MB_DATA_EVENT    21    HSMD
     MB_DATA_HISTORY    22    GSF
     MB_DATA_SUMMARY    23    GSF
     MB_DATA_PROCESSING_PARAMETERS    24    GSF
     MB_DATA_SENSOR_PARAMETERS    25    GSF
     MB_DATA_NAVIGATION_ERROR    26    GSF
     MB_DATA_RAW_LINE    27    uninterpretable line for ascii formats
     MB_DATA_NAV1    28    ancillary nav system 1
     MB_DATA_NAV2    29    ancillary nav system 2
     MB_DATA_NAV3    30    ancillary nav system 3
     MB_DATA_TILT    31    Simrad
     MB_DATA_MOTION    32    Reson 7k
     MB_DATA_CTD    33    Reson 7k
     MB_DATA_SUBBOTTOM_MCS    34    Reson 7k
     MB_DATA_SUBBOTTOM_CNTRBEAM    35    Simrad
     MB_DATA_SUBBOTTOM_SUBBOTTOM    36    Reson 7k, XTF
     MB_DATA_SIDESCAN2    37    Reson 7k, XTF
     MB_DATA_SIDESCAN3    38    Reson 7k, XTF
     MB_DATA_IMAGE    39    Reson 7k
     MB_DATA_ROLL    40    Reson 7k
     MB_DATA_PITCH    41    Reson 7k
     MB_DATA_ABSORPTIONLOSS    42    Reson 7k
     MB_DATA_SPREADINGLOSS    43    Reson 7k
     MB_DATA_INSTALLATION    44    Reson 7k
     MB_DATA_WATER_COLUMN    45    Simrad
     MB_DATA_STATUS    46    Simrad, XTF
     MB_DATA_DVL    47    JSTAR
     MB_DATA_NMEA_RMC    48    NMEA
     MB_DATA_NMEA_DBT    49    NMEA
     MB_DATA_NMEA_DPT    50    NMEA
     MB_DATA_NMEA_ZDA    51    NMEA
     MB_DATA_NMEA_GLL    52    NMEA
     MB_DATA_NMEA_GGA    53    NMEA
     MB_DATA_SURVEY_LINE    54    Reson 7k
     MB_DATA_ATTITUDE1    55    ancillary attitude system 1
     MB_DATA_ATTITUDE2    56      ancillary attitude system 2
     MB_DATA_ATTITUDE3    57    ancillary attitude system 3

SEE ALSO
mbsystem(1), mbinfo(1)

BUGS
mbnavlist is not able to list all of the navigation information available in some swath data formats.