MB-System Unix Manual Page

mbsslayout

Section: MB-System 5.0 (1)
Updated: 17 September 2017
Index
 

NAME

mbsslayout - translate time-based sidescan sonar data into backscatter laid out into a regular array of pixels on the seafloor by projecting onto a topographic model.

 

VERSION

Version 5.0

 

SYNOPSIS

mbsslayout [
--verbose
--help
--input=datalist
--format=format
--platform-file=FILE
--platform-target-sensor=SENSORID

--output-source=record_kind
--line-nameroot=name
--line-time-list=filename
--line-route=filename
--line-check-bearing
--line-name1=name
--line-name2=name
--line-range-threshold=value
--topo-grid-file=filename
--altitude-altitude
--altitude-bottomppick
--altitude-bottompick-threshold=value
--altitude-topo-grid
--channel-swap
--swath-width=value
--interpolation=value

--nav-file=filename
--nav-file-format=format_id
--nav-async=record_kind
--sensordepth-file=filename
--sensordepth-file-format=format_id
--sensordepth-async=record_kind
--altitude-file=filename
--altitude_file-format=format_id
--altitude-async=record_kind
--heading-file=filename
--heading-file-format=format_id
--heading-async=record_kind
--attitude-file=filename
--attitude-file-format=format_id
--attitude-async=record_kind
--soundspeed-constant=value
--soundspeed-file=filename
--soundspeed-file-format=format_id
--soundspeed-async=record_kind
--timeshift-file=filename
--timeshift-constant=value
--timeshift-apply-nav
--timeshift-apply-sensordepth
--timeshift-apply-altitude
--timeshift-apply-heading
--timeshift-apply-attitude
--timeshift-apply-all-ancilliary
--timeshift-apply-survey
--timeshift-apply-all
]

 

DESCRIPTION

MBsslayout translates time-based sidescan sonar data into backscatter laid out onto a topographic model of the seafloor. The input should be a datalist referencing data files in a format containing time based sidescan sonar data (typically both port and starboard time series). Often the logged file will not include any form of swath bathymetry data. The output will be sidescan data for which each ping return is represented by a single array of pixels with acrosstrack and alongtrack locations, where in the acrosstrack direction the pixels are uniformly sized (and therefore uniformly spaced). The output will be written to files in the MBF_MBLDEOIH format (MBIO format id 71).

The time series sidescan is "laid out" onto the seafloor using the two-travel time of each sample, it's orientation (port or starboard), the speed of sound, the location and orientation of the sonar, and some knowledge or assumption about the seafloor topography. The "laying out" process involves defining a regularly spaced array of acrosstrack pixels for which the pixel size (in meters) and the number of pixels determines the width of the array; this array is centered under the sonar location in an assumption that the swath center is approximately beneath the sonar. The location of each original sidescan sample on the seafloor, and the corresponding pixel in the destination sidescan array, is calculated according to the parameters listed above. The sidescan samples are binned in the destination array, with averaging applied for destination pixels holding more than one sample. After the averaging is calculated, empty pixels surrounded by valid data can be filled by interpolation.

The maximum number of pixels in the output swath sidescan is 4001. By default, mbsslayout varies the pixel size between pings in order to accommodate the full sidescan swath width within 4001 pixels. The calculation of the swath width W is:
   W = 2.2 * sqrt(R * R - A * A)
where A is the sonar altitude and R is the maximum range:
   R = 0.5 * V * dt * N
Here dt is the sample interval in the time series sidescan, N is the maximum number of samples in a time series sidescan channel, and V is the speed of sound. Alternatively, the swath width can be specified to be a constant distance. Given the swath width W, whether it varies or is constant, mbsslayout uses an acrosstrack pixel size of:
   dx = W / 4000

The sidescan can be laid out using a flat bottom assumption, but is generally laid out onto a gridded topographic model derived from bathymetric mapping with other sensors. The gridded bathymetry data may be collected simultaneously with the sidescan from the same platform, or it may derive from other surveys. If no topographic model is specified, then the location of each sample is calculated assuming a flat bottom according to an altitude value. By default this altitude derives from the navigation available in the time series sidescan files, but it can also derive from picking the first bottom arrival in the time series sidescan data. In this case the altitude used is the average of the bottom picks from the port and starboard time series sidescan channels.

Navigation, attitude, altitude, and water sound speed values will by default, if available, derive from values contained in the time-based sidescan files. If necessary or desired, the ancillary values can be merged from separate files. Time latency corrections can be made to the ancillary data time series if needed.

Once the sidescan data have been laid out onto the seafloor and output to format 71 swath files, they can be further processed using MB-System tools such as mbbackangle followed by mbprocess.

 

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

--verbose

By default mbsslayout outputs minimal information to the shell. This option causes the program to output the control parameters at the start and various status messages as it runs.
--help

The --help option causes mbsslayout to print out a summary of its purpose and a listing of its control options, and then exit immediately.
--input=datalist

This option defines the input files containing the time series sidescan data. The datalist value typically denotes a datalist file containing a list of input swath data files and/or other datalist files. Alternatively, a single swath data file can also be specified.
--format=format

This option sets the MBIO format identifier for the input file specified with the --input option. By default, mbsslayout infers the format id from from the input filename via use of the MB-System suffix convention ("*.mbXXX") or of other recognized file suffixes.
--platform-file=FILE

This option specifies an MB-System platform file to be read and used to define the positional and angular offsets between sensors on the source survey platform. Often the embedded navigation and attitude (and other ancillary) data are already referenced to the relevant sidescan sonar; in this case no platform model is required during sidescan layout. However, if the available navigation and attitude data are referenced to another sensor or location on the survey platform, a platform model allows calculation of the actual location and orientation of the sidescan sonar during the layout process.
--platform-target-sensor=SENSORID

This option specifies which sensor in the platform model specified with the --platform-file option is the source of the time series sidescan data being processed by mbsslayout.
--output-source=record_kind

This option specifies the MB-System data record type in the input source data that contains the time series sidescan data being processed by mbsslayout. The source data record type will not always be considered survey data (MB_DATA_DATA, ID=1) and may instead by secondary sidescan (MB_DATA_SIDESCAN2, ID=38) or tertiary sidescan (MB_DATA_SIDESCAN2, ID=39). For instance, Edgetech sidescan data are recorded in the Jstar format in files with a *.jsf suffix, and these files typically contain two frequencies of sidescan data. The records containing the lower frequency time series sidescan data will be reported as MB_DATA_DATA, and those containing the higher frequency time series sidescan data will be reported as MB_DATA_SIDESCAN2. The MB-System program mbinfo will, with the -N option, output a complete list of the data record types in a swath file, revealing the number of MB_DATA_DATA, MB_DATA_SIDESCAN2, and MB_DATA_SIDESCAN3 records present.
--line-time-list=filename

Specifies an ASCII text file containing a list of times used to define the start and ends of survey lines, allowing mbsslayout to structure the output files according to those survey lines. The output filenames will be constructed using the sequential line numbers (starting from 000) The times are defined in decimal epoch seconds (seconds since 1970) with one time value on each line. Such a time list file can be constructed from an MB-System route file using the program mbroutetime.
--line-route=filename

Specifies an MB-System route file (typically generated using mbgrdviz) that defines the waypoints of a planned survey. The waypoints of this route are used in conjunction with the survey navigation to define the start and ends of survey lines, allowing mbsslayout to structure the output files according to those survey lines. Since the navigation of real surveys rarely passes through the planned waypoints exactly, the times at which waypoints are reached is calculated using a range threshold specified using the --line-range-threshold option. --line-range-threshold=value
Specifies the range threshold used to define when survey navigation reaches a survey line waypoint. The range (distance) of the survey navigation to the waypoint should decrease as the waypoint is approached. The waypoint is considered to be reached when the range stops decreasing and starts to increase, provided the range is less than the range threshold when that occurs. The default value is 50 meters.
--line-name1=name

If mbsslayout is requested to output sidescan in files corresponding to survey lines, as defined either by a route file (option --line-route) or a list of time stamps (option --line-time-list), then the output files will have names of the form "N1"_"N2"_XXXX.mb71, where "N1" is specified with --output-name1, "N2" is specified with --output-name2, and XXXX are the sequential line numbers (starting with "0000").
--line-name2=name

By default, mbsslayout outputs "laid-out" sidescan in format 71 files corresponding to the input files containing the time series sidescan data, where the output filenames consist of the original filename stripped of it's identifying suffix (e.g. ".jsf") and appended with _"N2".mb71. Here "N2" is specified with --output-name2. If mbsslayout is requested to output sidescan in files corresponding to survey lines, as defined either by a route file (option --line-route) or a list of time stamps (option --line-time-list), then the output files will have names of the form "N1"_"N2"_XXXX.mb71, where "N1" is specified with --output-name1, "N2" is specified with --output-name2, and XXXX are the sequential line numbers (starting with "0000").
--topo-grid-file=filename

This option specifies a topographic model in the form of a GMT topography grid file to be used for laying out the sidescan. Each time series sidescan sample is projected into the topographic model using the sonar navigation and attitude so that the location of the sample on the seafloor is correct with respect to the full three dimensional survey geometry. If a topography model is not specified with this option, then the sidescan will be laid out using a flat bottom assumption and an altitude value derived either from the survey navigation or by picking the initial bottom return in the time series sidescan data.
--altitude-bottomppick

Specifies obtaining the altitude value by picking the initial bottom return in the time series sidescan data. If no topographic model is specified with the --topo-grid-file option, then the sidescan will be laid out using using a flat bottom assumption and the altitude. The default altitude bottompick threshold is 0.5, meaning the bottom return is picked for each channel (port and starboard) at the first time the time series sidescan value reaches 0.5 times the maximum value. The altitude value used for the overall layout is the average of the values found for the port and starboard channels.
--altitude-bottompick-threshold=value

Specifies the threshold used to pick the initial bottom return in the time series sidescan data. The default threshold is 0.5. This option turns the bottompick altitude mode on, so it is unnecessary to also specify the --altitude-bottomppick option.
--channel-swap

This option causes mbsslayout to swap the port and starboard time series sidescan channels before laying out the sidescan data on the seafloor.
--swath-width=value

Specifies a constant output swath width in meters. By default, mbsslayout varies the swath width according to the maximum range and altitude of the sidescan data. See the description section for details of the default swath width calculation and the sidescan layout process.
--interpolation=value

Specifies the degree to which gaps in the output swath sidescan are filled by interpolation. The interpolation value corresponds to the maximum number of adjacent empty pixels that is filled by interpolation; larger gaps are not filled by interpolation and remain empty in the output swath sidescan. The default is to do no interpolation.
--nav-file=filename

Specifies an external file from which to merge sonar position (navigation), replacing any navigation data included in the input time series sidescan files. By default mbsslayout attempts to use navigation values included in the input data.
--nav-file-format=format_id

Specifies the format of an external navigation file from which position values are derived (as defined with --nav-file). Options for the format_id value are:

   1: ASCCI text file with lines of the form:
        time_d longitude latitude speed
      where time_d is time in decimal epoch seconds (seconds since 1970), longitude
      and latitude are in decimal degrees, and speed is in km/hour (and is optional).
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.

   2: ASCCI text file with lines of the form:
        year month day hour minute second longitude latitude
      where year, month, day, hour, and minute values are integers, the second
      value is decimal, and longitude and latitude are in decimal degrees.
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.

   3: ASCCI text file with lines of the form:
        year julian_day hour minute second longitude latitude
      where year, julian_day, hour, and minute values are integers, the second
      value is decimal, and longitude and latitude are in decimal degrees.
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.

   4: ASCCI text file with lines of the form:
        year julian_day day_minute second longitude latitude
      where year, julian_day, and day_minute values are integers, the second
      value is decimal, and longitude and latitude are in decimal degrees.
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.

   5: ASCCI text file in the 1990's era L-DEO processed nav format with lines
      of the form:
        yy+jjjhhmmssNddmmmmmmEdddmmmmmm
      where yy is the two digit year (after 1999 the "yy+" was replaced by a four
      digit year "yyyy"), jjj is the julian_day, hh is the hour, mm
      is minutes, and ss is seconds. The latitude is given as
      Nddmmmmmmand where N is 'N' for north and 'S' for south, dd are integer
      degrees, and mmmmmm is minutes * 10000. The longitude is given as
      Edddmmmmmmand where E is 'E' for east and 'W' for west, ddd are integer
      degrees, and mmmmmm is minutes * 10000.

   6 or 7: NMEA 0183 position strings
      Several NMEA and NMEA-like strings containing position are recognized,
      and can be parsed with and without line break characters. These strings
      include ZDA, GLL, GGA, DAT, and UNX.

   8: Simrad 90 format navigation files with lines
      of the form:
        ddmmyy hhmmssss ddmmmmmmmN dddmmmmmmmE
      where dd is day of the month, mm is the month, yy is the two digit year,
      hh is the hour, mm is the minute, and ssss is seconds * 100.
      The latitude is given as ddmmmmmmmN where dd are integer degrees, 
      mmmmmmm is minutes * 100000, and N is 'N' for north and 'S' for south latitude.
      The longitude is given as dddmmmmmmmE where ddd are integer degrees, 
      mmmmmmm is minutes * 100000, and E is 'E' for east and 'W' for west longitude.
      
      
      day_minute values are integers,
      the second value is decimal, and longitude and latitude are in decimal
      degrees. The longitude is given as
      Edddmmmmmmand where E is 'E' for east and 'W' for west, ddd are integer
      degrees, and mmmmm is minutes * 10000.

   9: ASCCI text file with white-space delimited lines of the form:
        yr mon day hour min sec time_d lon lat heading speed sensordepth*
      where yr is the four digit year, mon is the month, day is the day of the
      month, min is the minute, second is the decimal seconds, time_d is time in
      decimal epoch seconds (seconds since 1970), lon is the longitude
      in decimal degrees, lat is the latitude in decimal degrees, heading is in
      decimal degrees, speed is in km/hour, and sensordepth is in meters.
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.

   10: R2R (Rolling deck to Repository) navigation format with ASCCI text lines
      of the form:
         yyyy-mm-ddThh:mm:ss.sssZ lon lat quality nsat dilution height
      where the lon and lat fields are in decimal degrees with south latitudes
      and west longitudes negative, and the last four quantities relating to
      GPS fix quality.
--nav-async=record_kind

Specifies the type of data records from which position values are derived (as defined with --nav-file-format). Options for the record_kind include:

    MB_DATA_DATA:  1 (survey data)
    MB_DATA_NAV:  12 (navigation data)
    MB_DATA_NAV1: 29 (navigation data from navigation system 1)
    MB_DATA_NAV2: 30 (navigation data from navigation system 2)
    MB_DATA_NAV3: 31 (navigation data from navigation system 3)
What types of data records are present is format-dependent, as is the default choice of which record type is used as the navigation source by default. The program mbinfo can be used with the -N option to determine the numbers of different record types present in a data file.
--sensordepth-file=filename

Specifies an external file from which to merge sensor depth, replacing any sensor depth data included in the input time series sidescan files. By default mbsslayout attempts to use sensor depth values included in the input data.
--sensordepth-file-format=format_id

Specifies the format of an external sensor depth file from which sensor depth values are derived (as defined with --sensordepth-file). Options for the format_id value are:

   1: ASCCI text file with lines of the form:
        time_d longitude latitude speed
      where time_d is time in decimal epoch seconds (seconds since 1970), longitude
      and latitude are in decimal degrees, and speed is in km/hour (and is optional).
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.

   2: ASCCI text file with lines of the form:
        year month day hour minute second longitude latitude
      where year, month, day, hour, and minute values are integers, the second
      value is decimal, and longitude and latitude are in decimal degrees.
      South latitudes are negative. Longitude may be defined on either the
      -180.0 to +180.0 or 0.0 to 360.0 domains.
--sensordepth-async=record_kind

--altitude-file=filename

Specifies an external file from which to merge altitude, replacing any altitude data included in the input time series sidescan files. By default mbsslayout attempts to use altitude values included in the input data.
--altitude_file-format=format_id

--altitude-async=record_kind

--heading-file=filename

Specifies an external file from which to merge heading, replacing any heading data included in the input time series sidescan files. By default mbsslayout attempts to use heading values included in the input data.
--heading-file-format=format_id

--heading-async=record_kind

--attitude-file=filename

Specifies an external file from which to merge attitude (roll and pitch), replacing any attitude data included in the input time series sidescan files. By default mbsslayout attempts to use attitude values included in the input data.
--attitude-file-format=format_id

--attitude-async=record_kind

--soundspeed-constant=value

--soundspeed-file=filename

Specifies an external file from which to merge water sound speed, replacing any sound speed data included in the input time series sidescan files. By default mbsslayout attempts to use sound speed values included in the input data.
--soundspeed-file-format=format_id

--soundspeed-async=record_kind

--timeshift-file=filename

--timeshift-constant=value

--timeshift-apply-nav

--timeshift-apply-sensordepth

--timeshift-apply-altitude

--timeshift-apply-heading

--timeshift-apply-attitude

--timeshift-apply-all-ancilliary

--timeshift-apply-survey

--timeshift-apply-all

 

EXAMPLES

To be written.....

 

SEE ALSO

mbsystem(1), mbdatalist(1), mbprocess(1)

 

BUGS

Oh yeah.


 

Index

NAME
VERSION
SYNOPSIS
DESCRIPTION
MB-SYSTEM AUTHORSHIP
OPTIONS
EXAMPLES
SEE ALSO
BUGS


Last Updated: 17 September 2017