mbnavlist
Section:  MB-System 5.0  (1)
Updated:  8 April 2017 
Index


 
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
-Jprojection -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.

 
MB-SYSTEM AUTHORSHIP

David W. Caress




  Monterey Bay Aquarium Research Institute



Dale N. Chayes




  Center for Coastal and Ocean Mapping




  University of New Hampshire



Christian do Santos Ferreira




  MARUM - Center for Marine Environmental Sciences




  University of Bremen

 
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".
-J


projection



Including the 'X' and 'Y' characters in the -Ooutput_format string
causes longitude and latitude position values, respectively, to be output.
These longitude and latitude values represent position in geographic coordinates,
which for MB-System means longitude and latitude using the WGS84 geographic
coordinate system. The -J option can be used to specify
an alternate, projected coordinate system (PCS) used to represent positions in
"eastings" and "northings" (in meters relative to the PCS origin) rather than
longitude and latitude (in degrees).
When a PCS is defined with the -J option, users can output eastings by
including '^X' in the output_format string defined with the -O option.
Similarly, northings can be output using '^Y' in the output_format string.
Universal Transverse Mercator (UTM) is the most commonly used PCS in the
oceanographic community, but
MB-System supports a large number of other PCS's as well.
The underlying projection functions derive from the PROJ.4 library
created by Gerald Evenden of the U.S. Geological Survey and since extended
by Frank Warmerdam and others of the open source geospatial community.

The projection argument for the -J option can be either
a PCS identifier from the projection definition list provided at the
end of this manual page, or simply -JU to specify using
UTM in whatever zone is appropriate for the grid bounds specified
with the -R option.

For instance, to fully specify a particular northern UTM
zone, set projection = UTMXXN where XX gives
the UTM zone (defined from 01 to 60). As an example, a northern UTM
zone 12 projection can be specified using -JUTM12N.
Southern UTM zones are specified as UTMXXS. The European Petroleum
Survey Group (EPSG) has defined a large number of PCS's used worldwide
and assigned number id's to each; one can also specify the northern
UTM zone 12 projection using its EPSG designation,
or -Jepsg32612.
When the projected coordinate system is fully specified
by the -J option, then the grid bounds may be specified using
-R in either longitude and latitude or in eastings and northings.

Alternatively, one may indicate a UTM projection without specifying the
zone by using -JU. In this case, the
UTM zone will be inferred from the longitude and latitude of the first data
point. If the user requests easting or northing output in
the output_format string without specifying a particular PCS using the
-J option, then mblist
will use a UTM projection with the zone specified according to the position
of the first data point.
-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:

/
special character: this causes the value
indicated by the next character to be inverted. This applies only to simple
numeric values such as depth and
heading and not to values like time
strings or positions with hemisphere
characters.

-
special character: this causes the value
indicated by the next character to be
multiplied by -1. This applies only
to simple numeric values such as
depth and heading and not to values
like time strings or positions with
hemisphere characters.

^
special character: this causes the position
value indicated by the next 'X', or 'Y' 
character to be expressed as an easting or 
northing in the projected coordinate system 
(PCS) specified using the -J option.
If no PCS is specified, then a Universal
Tranvserse Mercator (UTM) projection will
be used with the zone defined by the
longitude of the first data point. This
applies only to position values.

c
for sonar transducer depth (m)

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 day of the year

j
for a time string (yyyy jd dm ss.ssssss)
where jd is the 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 (epoch) 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)

^X  for easting (meters in projected coordinate system defined by -J)

Y  for latitude (decimal degrees)

y  for latitude (degrees + decimal minutes + N/S)

^Y  for northing (meters in projected coordinate system defined by -J)



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>. If segment is the string "swathfile"
then the segment lines will consist of the '#' character followed
by the path for the source swath file. If segment is the string "datalist"
then the segment lines will consist of the '#' character followed
by the path for the source datalist file.


 
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.



 
Index

NAME

VERSION

SYNOPSIS

DESCRIPTION

MB-SYSTEM AUTHORSHIP

OPTIONS

EXAMPLES

MB-SYSTEM DATA RECORD TYPES

SEE ALSO

BUGS