Section: Devices and Network Interfaces (4)
Updated: 20 August 1991


mr1file - file format for Hawaii MR1 post-processing software  


#include <local/mr1pr.h>  


An MR1 file is used for the storage of binary ping data operated upon by the MR1 post-processing system. The file is portable among machines of varying architecture by virtue of its XDR implementation. It is composed of a file header which describes the number of pings contained in the file followed by the pings themselves. Each ping contains a header structure followed by a stream of sensor (i.e., towfish compass, depth, pitch and roll), bathymetry and sidescan data of arbitrary length.

Following is a partial listing of the contents of the file mr1pr.h which define the file and ping header structures and a few relevant constants:

/* magic number */
#define MR1_VERSION_1_0                (6666)          /* obsolete version */

#define MR1_VERSION_2_0                (6667)          /* current version */

typedef struct mf_struct {
       int mf_version;                 /* file format version number */

       int mf_count;                   /* number of objects */

       char *mf_log;                   /* processing log */

} MR1File;

typedef struct sns_struct {

        float sns_int;                  /* sample interval (secs) */

        int sns_nsamps;                 /* number of samples */

        float sns_repval;                       /* single representative value of the sensor

                                        for an entire ping, usually derived from

                                        the full set of samples for that ping */

} Sensor;

typedef struct ps_struct {
       float ps_xmitpwr;                       /* transmitter power (1=full) */

       float ps_gain;                  /* gain setting */

       float ps_pulse;                 /* pulse length (millisecs) */

       float ps_bdrange;                       /* bottom detect range (m) */

       int ps_btycount;                        /* number of bathymetry samples */

       int ps_btypad;                  /* number of trailing bathymetry pad samples */

       float ps_ssoffset;                      /* across-track distance to first sidescan sample */

       int ps_sscount;                 /* number of sidescan samples */

       int ps_sspad;                   /* number of trailing sidescan pad samples */

} PingSide;

typedef struct png_struct {
       struct timeval png_tm;          /* timestamp */

       float png_period;                       /* ping period (secs) */

       double png_slon;                        /* ship longitude (deg) */

       double png_slat;                        /* ship latitude (deg) */

       float png_scourse;              /* ship course (deg) */

       float png_laybackrng;           /* towfish layback range (m) */

       float png_laybackbrg;           /* towfish layback bearing (deg, where 0=shipaxis,

                                        pos=port, neg=starboard) */

       double png_tlon;                        /* towfish longitude (deg) */

       double png_tlat;                        /* towfish latitude (deg) */

       float png_tcourse;              /* towfish course (deg) */

       Sensor png_compass;             /* towfish compass heading (deg, where 0=N, 90=E)

                                        with no magnetic correction applied to either

                                        the representative value or the sample array */

       Sensor png_depth;               /* towfish depth (m) */

       Sensor png_pitch;               /* towfish pitch (deg) */

       Sensor png_roll;                        /* towfish roll (deg) */

       int png_snspad;                 /* number of invalid trailing pad sensor samples */

       float png_temp;                 /* water temperature (deg) */

       float png_atssincr;             /* across-track sidescan sampling increment (m) */

       float png_alt;                  /* towfish altitude (m) */

       float png_magcorr;              /* magnetic correction (deg) */

       float png_sndvel;                       /* sound velocity (m/sec) */

       PingSide png_sides[ACP_NSIDES];

} Ping;

/* error codes */
#define MR1_SUCCESS                    (0)

#define MR1_FAILURE                    (1)

#define MR1_FILTERWAIT         (2)

#define MR1_MISC                       (3)

#define MR1_BADARG                     (4)

#define MR1_MEMALLOC           (5)

#define MR1_OPEN                       (6)

#define MR1_READ                       (7)

#define MR1_WRITE                      (8)

#define MR1_SYSVIPC                    (9)

#define MR1_X11                        (10)

#define MR1_SIGNAL                     (11)

#define MR1_PIPE                       (12)

#define MR1_FCNTL                      (13)

#define MR1_FORK                       (14)

#define MR1_DUP2                       (15)

#define MR1_CHDIR                      (16)

#define MR1_EXEC                       (17)

#define MR1_PDB                        (18)

#define MR1_EOF                        (19)

#define MR1_BADDATA                    (20)

Each ping consists of a Ping structure followed by the single-precision floating point ping data samples. The samples are stored in the following order: (i) towfish compass, (ii) towfish depth, (iii) towfish pitch, (iv) towfish roll, (v) port bathymetry, (vi) port sidescan, (vii) starboard bathymetry, and (viii) starboard sidescan. The numbers of towfish compass, depth, pitch and roll samples are contained in the sns_nsamps fields of the png_compass, png_depth, png_pitch and png_roll Sensor structures embedded within the Ping structure. The numbers of bathymetry and sidescan samples for each side are contained in the ps_btycount and ps_sscount fields of the png_sides[ACP_PORT] and png_sides[ACP_STBD] PingSide structures embedded within the Ping structure. Each bathymetry sample is composed of two consecutive floating point numbers - the first number indicates the horizontal across-track distance from the acquisition device, and the second number indicates the vertical depth at that distance. Each sidescan sample consists of a single floating point reflection intensity value. Note that although the sample padding described in the mr1pr(3) manual page may be present within an in-memory image of an MR1 data set, such padding will never be stored into an MR1 disk file.

IEEE NaN (not-a-number) is used by this format to indicate that the value of a particular header field (e.g., towfish altitude) or data sample is unknown. It is common for most of the sensor samples (e.g., roll) in files derived from HAWAII-MR1, for instance, to be stored as NaNs because that instrument logs such samples at an irregular rate. Those samples are then transformed into a set of regularly logged samples by filling the gaps between the real samples with NaN placeholder values, with the expectation that in some later processing stage those placeholder values will be turned into real numbers via some form of interpolation.

I/O routines which read and write the structures described here are available from the mr1pr(3) library.  








This document was created by man2html, using the manual pages.