如何在MB-System中新建I/O模块

    本文档根据官方文档《Developer's Guide to Coding an MBSystem I/O Module》编写。主要内容为基于文档中新建一个MB-System的I/O模块的范例，理解MB-System如何处理侧扫声纳xtf格式文件。官方文档中的范例，即如何新建一个I/O模块处理WASSP多波束声纳数据已经说明非常详细，十分推荐仔细阅读。鉴于文档内容为我个人的理解，可能有错误。

    文档中新建MB-System的I/O模块的范例为P17~P98，P17之前的部分为MB-System的架构介绍及数据处理流程说明，亦是值得花时间学习。

    新建I/O模块具体流程如下（操作均在src/mbio/目录下进行）。

    

STEP 1 设立声纳系统名称、数据格式及ID

    1.声纳系统的名称可为任意25字符，例如BENTHOS代表Benthos1624侧扫声纳，记为MB_SYS_BENTHOS；

    2.数据格式的名称限定8个字符，对于新假如的格式，需加上前缀“MBF_”，例如：MBF_XTFB1624;

    3.数据格式拥有唯一的ID，例如：#define MBF_XTFB1624 211；

 

STEP 2 使用源码的模板构建新模块

     1.拷贝mbsys_templatesystem.h，重命名为：mbsys_benthos.h；

   拷贝mbsys_templatesystem.c，重命名为：mbsys_benthos.c；

   拷贝mbr_tempform.c，重命名为：mbr_xtf1624.c；

     2.在以上文件中进行全局替换：

   templatesystem->benthos

   TEMPLATESYTEM->BENTHOS

   tempform->xtfb1624

   TEMPFORM->XTFB1624

   我们将在以上三个文件中处理xtf格式侧扫声纳文件。

 

STEP 3 定义存储新声纳数据结构体

      1.在mbsys_benthos.h中添加记录侧扫声纳数据的结构体：struct mbsys_benthos_struct

     注：结构体的模板已由mbsys_templatesystem.h中的mbsys_templatesystem_struct中定义，而mbsys_benthos_struct为结合模板与xtf格式官方文档的产物，可以只根据我们需要的信息进行构建；（手册中的范例参考mbsys_wassp.h）

      2.要使用真实数据对定义的结构体进行验证，实际情况常出现构建的结构体与实际的声纳数据不符而导致数据读取的错误；

      注：以xtf侧扫声纳数据文件为例，以十六进制数据解析软件（在此我使用GNOME HEX EDITIOR）读取声纳数据文件，然 后结果与xtf格式官方文档XTFFILEHEADER进行对比，可以观察FileFormat、SystemType、REcordingProgramName、RecordingProgram Version、SonarName、SonarType等在程序中是否一致；

      注：手册中范例说得比较详细；

      3.基于对比的结构，合理调整1中构建的结构体，根据实际数据与数据格式文档确定解码方式；

      4.每个MBIO的结构体的通用项：int kind、double time_d、int time_i[7]，MOIO模块中的函数mb_get_time()、mb_get_date()等与此相关联；

      5.MB_DATA_DATA--Survey data

    MB_DATA_NAV--Navigation data

    MB_DATA_COMMENT--Comment string

      6.在手册中的范例里，构建记录声纳数据的结构体时引入了子结构体；

 

STEP 4 (a) mbr_xxx.c的初始化工作

     1.初始化：

    Mbr_register_xxx()、mbr_info_xxx()、mbr_dem_xxx()直接关联mb_read_init()及mb_write_init()；

    Mbr_dem_xxx()直接关联mb_close();

      2.mbr_registem_xxx()注册管理指针，使得mbr_xxx.c及mbsys_xxx.c中的各模块能由MBIO中更高级的I/O模块调用；

      3.①MBF_XTFB1624初始化完成之后：mb_extract()->mbsys_xxx_extract()；

    ②

 

         ③mbr_register_xxx()做好以上管理，但只有MBIO其他模块需要调用的部分需要注册；

      4.mbr_xxx.c中主要处理数据的函数为：mbr_rt_xxx()(读)、mbr_wt_xxx()(写)；

      5.mbr_info_xxx()主要为构建的结构体进行初始化赋值；

      6.文件访问方式：

         ①fopen()、fread()、fwrite()、fclose()；

         ②(推荐)mb_fileio_open()、mb_fileio_read()、mb_fileio_write()、mb_fileio_close()

         ③调用外部第三方I/O库读取某些特殊格式文件，如XDR、SURF等;

 

STEP 4（b）mbr_xxx.c中实现读写函数

一、1、主要的函数为mbr_rt_xxx()和mbr_wr_xxx()

             其中主要参数如下：

            ①verbose：输出log的详细程度？；

            ②mbio_ptr：指向通过MBIO定义的读/写文件的mb_io structure

            ③store_ptr：指向primary data structure（通常在mb_io structure中获得）；

            ④error：指向error的ID，可据此判断error可能的原因；

        2、mbio_ptr和store_ptr指针由mb_read_init()/mb_write_init()获得，verbose值由MB-System Program设定，error值返回具体的error状态信息；

        3、mbr_rt_xxx()从mbio_ptr指向的文件数据中读取数据并转换成store_ptr指向的数据structure；

        4、status和*error返回值分别表示成功与失败；

        5、store->kind的值表示读取的数据类型；

        6、mbr_wt_xxx()主要将当前store_ptr指向的数据按需求转换记录于mbio_ptr指向的的文件；

二 、1、mbr_rt_xxx()：读取文件->验证数据起点和size->将数据导入buffer->子函数解析处理具体数据、存储数据；

        2、mbr_xxx_rd_data()较为复杂：

①需要找到文件数据起点；

②处理文件头文件，如xtf文件中的XTFFILEHEADER的前端字节（起点、长度、同步、类型等）；

③读取多使用mb_fileio_get()，代码中的体现为：mb_io_ptr->filetype，参数设定为MB_FILETYPE_SINGLE，且允许对I/O文件进行优化系统的设置；

④buffer内存分配根据存储记录的数据增加而增加，buffer的指针和分配给它的内存都存储在mb_io_struct中；

⑤采用mb_get_binary_xxx()等读取不同类型的单个值，同类型还有mb_get_int()、mb_get_float()等；

⑥verbose>=2时，MB-System打印the entry并返回values

    verbose>=5时，函数将打印所有信息；

三、 1、异步即时插值（手册说明内容较少）

有些场景中缺少导航、姿态等信息，此时需要依靠异步记录的信息进行插值（处理各传感器时间同步问题？）；

 

四、 mbr_wt_xxx()及其子函数：

1、于mbr_rt_xxx()非常类似、调用函数将需要输出的数据导入buffer，然后输出于mbio_prt指向的文件中；

2、采用mb_put_binary_xxx()等将不同类型的数据单个值导入buffer中，同类型还有mb_put_int()、mb_put_float()；

 

STEP 5 在mbsys_xxx.c中构建数据接口

1. 实现mbr_register_xxx()中注册的用于mbio_struct的接口，如侧扫声纳中mbsys_benthos.c中的mbsys_benthos_xxx()等函数；

2. 代码中需要注意文件数据格式与MBIO API中数据格式的相互转换；

3. 关键函数：mbsys_xxx_extract()，数据提取；

 

STEP 6 将新构建的I/O模块集成与MBIO中:

     1.信息I/O模块构建完成后，应在以下文件中修改信息：mbsystem/src/mbio/mb_format.h、mb_format.c，以将新的模块导入MBIO库中；

     2.声纳名称定义于mb_format.h中，如：#define MB_SYS_BENTHOS 33；

     3.声纳数据格式及其ID定义于mb_format.h中，如：#define MBF_XTFB1624 211

     4.函数mbr_register_xxx()及mbr_info_xxx()在mb_format.h中定义；

     5.新格式的引用必须要在mb_format.c中的mb_format_register()中进行声明：

如：

     6.新格式的引用必须要在mb_fomat.c中的mb_format_info()中进行声明：

如：

      7.新格式的引用必须要做mb_format.c中的mb_get_format()中进行声明：

如：

STEP 7 更新MB-System的编译配置文件

1. 在mbsystem/src/mbio/Makefile.am中声明新模块：mbsys_xxx.h、mbsys_xxx.c、mbr_xxx.c；

如：include_HEADERS += mbsys_benthos.h

libmbio_la_SOURCES += mbsys_benthos.c

libmbio_la_SOURCES += mbr_xtfb1624.c

2、重新编译。

 

参考文献：

1、MB-System官网：

      https://www.mbari.org/products/research-software/mb-system/

2、《Developer's Guide to Coding an MBSystem I/O Module》：

      https://www.mbari.org/wp-content/uploads/2016/03/codinganmb-systemiomodulev4.pdf

3、Triton Imaging, Inc. eXtended Triton Format (XTF) Rev. 41：

       http://ge0mlib.com/papers/File_Formats/Xtf_rev41.pdf