GDAL BSB 驱动完全指南：读取 Maptech/NOAA 海图格式（.KAP/.NOS）的原理与实践

GIS遥感数据工程【免费下载链接】gdalGDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.项目地址https://gitcode.com/gh_mirrors/gd/gdal点击查看免费下载导读BSBMaptech/NOAA BSB Nautical Chart Format是航海电子海图的经典栅格格式被 NOAA 等机构广泛用于分发官方海图数据。本文围绕 GDAL 仓库中该格式的官方驱动文档doc/source/drivers/raster/bsb.rst展开完整讲解 BSB 驱动的文件选择规则、版本支持、调色板配置BSB_PALETTE、元数据项BSB_KNP / BSB_KNQ / BSB_CUTLINE以及源码级实现原理。读完本文你将能够熟练使用 GDAL 命令行与 API 打开、检视并转换 BSB 海图数据并理解其底层解压算法、GCP 地理配准与坐标参考系统推导机制。一、BSB 格式概述与驱动定位BSB Nautical Chart 是一种面向栅格海图的专有格式历史上由 NOAA 与 Maptech 推广使用。GDAL 中的 BSB 驱动驱动名BSB为该格式提供只读访问支持具体能力包括读取栅格像元数据与颜色表colour table将海图头部记录的参考点解析为 GCPGround Control Points用于地理配准支持读取 1.1、2.0、3.0 三个版本均已在 GDAL 中验证通过内置为 GDAL 默认驱动之一built_in_by_default无需额外配置即可使用。需要注意的是BSB 驱动只支持读取不支持写入。在源码 bsbdataset.cpp 中创建功能的宏BSB_CREATE被显式注释禁用// Disabled as people may worry about the BSB patent // #define BSB_CREATE这与 BSB 格式的专利背景直接相关详见下文“专利背景”小节。文件扩展名与选择规则一个最常见的困惑是.BSB文件无法被 GDAL 直接选中。驱动要求用户选择同名的.KAP文件KAP 是 BSB 海图常用的封装文件扩展名内部包含文本头部与压缩像元数据。驱动注册时也将默认扩展名声明为kap见 bsbdataset.cpp 中的注册代码poDriver-SetMetadataItem(GDAL_DMD_EXTENSION, kap);此外该驱动还支持GEO/NOS 格式由 Softchart 提供。这类文件通常以.nos为扩展名并伴随一个包含地理配准信息的.geo文件。需要注意当前实现中.geo文件实际被忽略即 GEO 配准信息并未被真正读取使用详见下文“NOS 文件与 .geo 配准”。驱动能力声明根据原文档的Driver capabilities部分与源码注册信息BSB 驱动支持能力说明依据地理配准Georeferencing通过 GCP 及推导出的仿射变换提供GDAL_DCAP_RASTER、GDAL_DCAP_VIRTUALIO注册于 bsbdataset.cpp虚拟文件系统VirtualIO支持/vsizip/、/vsimem/等 VSI 路径注册项GDAL_DCAP_VIRTUALIO YES更新Update不支持Open()中GA_Update访问会被拒绝并报告“Update not supported by driver”写入/创建不支持宏被禁用源码注释在BSBDataset::Open()中对更新访问的处理为if (poOpenInfo-eAccess GA_Update) { ReportUpdateNotSupportedByDriver(BSB); return nullptr; }二、驱动识别机制如何判定一个文件是 BSBIdentify与Open都基于IdentifyInternal()完成格式探测bsbdataset.cpp。识别逻辑包含以下关键步骤头部长度检查文件前 1000 字节必须可读否则判定失败。关键字扫描在前 1000 字节内查找以下任一魔数BSB/标准 BSB/KAP 文件NOS/NOS 格式文件WX\8NO1 文件的标识——它本质上是NOS/的 ASCII 码整体偏移 9 的结果对应BSBGetc()中nByte nByte - 9的解码逻辑。误判防护为避免把其他二进制文件误认成 BSB识别逻辑还会检查RA行数/列数声明或[JF标记若这些标记距头部起始超过 100 字节且整个头部都不含VER/、KNP/、KNQ/、RGB/等 BSB 特征字段则拒绝识别。这一防护对应 GitHub issue #2881。文件级别的同一套识别逻辑也存在于底层读取库 bsb_read.c 的BSBOpen()中两者行为一致保证识别与打开结果一致。三、快速上手打开与转换 BSB 海图由于驱动已内置直接使用 GDAL 命令行工具即可。使用 gdalinfo 检视# 注意必须选择 .KAP 文件而不是 .BSB gdalinfo chart.kap输出中可以看到栅格尺寸来自BSB/头部字段中的RA单波段、ByteGDT_UInt8数据类型、调色板索引解释PaletteGCP 数量与坐标元数据项BSB_KNP、BSB_KNQ存在时及BSB_CUTLINEGDAL 3.1 且含PLY/头部时。使用 gdal_translate 转换# 转换为 GeoTIFF将 GCP 转为仿射地理变换 gdal_translate chart.kap chart.tif # 指定输出参考系例如 WGS84 经纬度 gdal_translate -a_srs EPSG:4326 chart.kap chart_ll.tif # 转换为 PNG保留调色板外观 gdal_translate -of PNG -expand rgba chart.kap chart.pngBSB 驱动把参考点REF/字段解析为 GCP并在打开数据集时尝试用GDALGCPsToGeoTransform()推导仿射变换即地理变换因此多数情况下gdal_translate可直接完成地理配准输出。底层只读 API 与示例工具该驱动底层的读取库是一份独立于 GDAL 的 C API见 bsb_read.h核心函数仅三个BSBInfo *BSBOpen(const char *pszFilename); int BSBReadScanline(BSBInfo *psInfo, int nScanline, unsigned char *pabyScanlineBuf); void BSBClose(BSBInfo *psInfo);仓库还附带了一个独立示例程序 bsb2raw.c用于把 BSB 文件转为 raw 栅格并生成.aux说明文件演示了这套 API 的典型用法bsb2raw src_file dst_file该程序逐行调用BSBReadScanline()读取全部扫描线并写出同时把颜色表写入.aux文件。其构建集成在 frmts/bsb/CMakeLists.txt 中非插件模式下编译。四、BSB_PALETTE切换海图配色方案海图文件内通常同时携带多种配色方案用于日间、夜间、灰度等不同显示场景以不同前缀字段命名。GDAL 通过配置选项BSB_PALETTE选择要使用的颜色表默认值为RGB见 bsb_read.c 中CPLGetConfigOption(BSB_PALETTE, RGB)。原文档列出的常见取值包括取值用途海图显示惯例RGB标准 RGB 真彩色调色板默认DAY日间显示配色DSK桌面Desk显示配色NGT夜间Night显示配色NGR夜间灰度配色GRY灰度配色PRC过程/打印相关配色PRG程序/页面相关配色使用方法通过环境变量或 GDAL 配置机制设置# 使用夜间配色打开 export BSB_PALETTENGT gdalinfo chart.kap # 单次命令临时指定 BSB_PALETTEDAY gdal_translate chart.kap chart_day.tif源码中的调色板匹配逻辑在BSBOpen()中头部分行读取时会把与目标调色板前缀匹配的字段RGB/、DAY/、NGT/等解析为颜色表条目格式为RGB/index,red,green,blue例如 bsb_read.c 中写入颜色表字段的示例RGB/%d,%d,%d,%d → RGB/1,233,115,193解析时对字段索引有边界校验iPCT必须在 0~128 之间否则报告“corrupted BSB file”。颜色表最大支持128 个条目每条 3 字节 RGB。值得注意的一个细节在 bsbdataset.cpp 的BSBRasterBand构造函数中颜色表的第 0 个条目被丢弃所有条目整体下移一位// Note that the first color table entry is dropped, everything is // shifted down. for (int i 0; i poDSIn-psInfo-nPCTSize - 1; i) { GDALColorEntry oColor {poDSIn-psInfo-pabyPCT[i * 3 0 3], ...}; oCT.SetColorEntry(i, oColor); }这与读取扫描线时的索引校正见下文“RLE 解码”配合BSB 像元索引从 1 开始读取后统一减 1 映射到 GDAL 的 0 基索引。五、元数据项BSB_KNP、BSB_KNQ 与 BSB_CUTLINE打开数据集后BSB 驱动会报告以下元数据项原文档 的 Metadata 部分BSB_KNPKNP/头部字段的内容提供坐标参考系统CRS相关信息。典型的KNP/行形如KNP/SC25000,GDWGS84,PRMercator PP31.500000,PI0.033333,SP,SK0.000000,TA90.000000 UNMetres,SDHHWLT,DX2.500000,DY2.500000其中SC为比例尺分母GD为基准面datumPR为投影projectionPP为中央经线等投影参数。源码在ScanForGCPs()中扫描头部并提取if (STARTS_WITH_CI(psInfo-papszHeader[i], KNP/)) { pszKNP psInfo-papszHeader[i]; SetMetadataItem(BSB_KNP, pszKNP 4); }BSB_KNQKNQ/头部字段的内容同样与坐标参考系统相关。源码中KNQ/被用来提取 Lambert 投影的第二、第三标准纬线参数P2、P3。BSB_CUTLINEGDAL 3.1当文件头部包含PLY/字段海图边框多边形记录时驱动会将其解析为WKT 格式的 POLYGON坐标顺序为经度、纬度作为BSB_CUTLINE元数据项输出。PLY/行的格式为PLY/1,32.346666666667,-60.881666666667 PLY/n,lat,longScanForCutline()遍历所有PLY/行并按“经度 纬度”顺序组装出形如下列的 WKTPOLYGON ((112.72859333333334 -8.25404666666667, ...))自动化测试 autotest/gdrivers/bsb.py 中的test_bsb_cutline()使用australia4c.kap验证了这一行为。六、地理配准源码剖析GCP 与坐标系推导BSB 海图的地理配准是驱动最有技术含量的部分全部集中在BSBDataset::ScanForGCPs()及其辅助函数中bsbdataset.cpp。1. GCP 来源一BSB 文件的 REF/ 字段标准 BSB/KAP 文件通过REF/行声明参考点格式为REF/n,pixel,line,lat,long例如源码注释中的示例REF/1,115,2727,32.346666666667,-60.881666666667。ScanForGCPsBSB()将这些行逐一解析为 GDAL GCP像素坐标、行列号与经纬度。2. GCP 来源二NOS 文件的 .geo 配准文件ScanForGCPsNos()会尝试打开与.nos同名的.geo文件自动区分.GEO/.geo大小写从中解析Point开头的行PointXlong lat line pixel Point1-22.0000 64.250000 197 744即每个参考点由 经度、纬度、行、列 四个值组成。若找不到.geo文件驱动会报告“Couldnt find a matching .GEO file”。注意虽然驱动会尝试读取.geo但原文档明确指出“.geo 文件当前被忽略”——这也是该格式支持上存在的一个已知局限使用时建议以.KAP文件为准。3. 国际日期变更线重绕Dateline WrapScanForGCPs()在收集完 GCP 后会调用GDALHeuristicDatelineWrapGCPs()进行经度重绕的启发式处理当 GCP 经度范围以本初子午线-180~180或日期变更线0~360为中心展开时若其中一个视角范围超过 270° 而另一个很小则自动把 GCP 经度统一重绕到连续的一侧确保跨日期变更线的海图在投影后保持连续。4. 从 KNP/KNQ 推导投影坐标系ScanForGCPs()还会解析KNP/的GD、PR与PP以及KNQ/的P2、P3据此构造 PROJCS WKT。源码中已覆盖的投影类型包括PR取值生成的投影关键参数MERCATORMercator_2SPGlobal Mercator中央经线取第一个 GCP 的经度TRANSVERSE MERCATORTransverse_Mercator中央经线取PP比例因子 1UNIVERSAL TRANSVERSE MERCATORTransverse_Mercator比例因子 0.9996东偏移 500000中央经线取PP源码注释提醒这并非真正的 UTM 分带POLYCONICPolyconic中央经线取PPLAMBERT CONFORMAL CONICLambert_Conformal_Conic_2SP双标准纬线取KNQ/的P2、P3中央经线取PP基准面方面GDEuropean 1950会被映射为 ED50EPSG:4230含 TOWGS84 转换参数未匹配时默认 WGS84。随后驱动通过OGRCreateCoordinateTransformation()把 GCP 从经纬度转换到推导出的投影坐标系并用GDALGCPsToGeoTransform()生成仿射地理变换。测试 autotest/gdrivers/bsb.py 的test_bsb_tmerc()使用transverse_mercator.kap精确验证了横轴墨卡托中央经线 18.0582833333333°场景下地理变换与PROJCS[unnamed, ..., PROJECTION[Transverse_Mercator], ...]的推导结果。七、像元解码原理RLE 游程解码与索引表1. 头部结构BSBOpen()逐行解析文本头部BSBReadHeaderLine()合并以空格续行的字段直到遇到0x1A 0x00序列数据段起始标记。随后读取一个字节表示颜色位深nColorSize1~7 位并兼容部分 USGS 文件把该值写成 ASCII 数字的情况。若未找到VER/字段则默认版本按 2.0 处理。2. 行偏移索引表每个 BSB 文件通常在文件末尾保存一个 4 字节大端序CPL_MSBPTR32整数指向行偏移索引表的起始位置。BSBOpen()读取该索引表并逐一校验每个扫描线的起始偏移若索引表比声明的高度少一行如 NOAA 的 1115A_1.KAP驱动会自动修正高度psInfo-nYSize--若索引表无效则回退为“顺序扫描”模式从首个数据行起靠扫描线行号标记确定下一行偏移。相关配置选项BSB_DISABLE_INDEX默认NO可以强制禁用索引表解析改为纯顺序读取模式。3. RLE 游程解码扫描线数据采用基于颜色位深的游程编码RLE。BSBReadScanline()的核心思路是每个数据字节同时携带颜色值高位与重复计数低位当计数溢出高位标志0x80置位时用后续字节按 128 进制扩展计数nValueShift 7 - psInfo-nColorSize; byValueMask (unsigned char)((((1 psInfo-nColorSize)) - 1) nValueShift); byCountMask (unsigned char)(1 (7 - psInfo-nColorSize)) - 1;解码过程中驱动还会处理两类已知容错场景行宽少 1 像素部分 BSB 3.0 产品如 NDI/CHS 的 354704.KAP的扫描线恰好少一个像素此时补 0行内数据缺失若无索引表且当前行数据不足驱动会试探下一位置是否是合法的下一行号标记若是则结束本行否则把后续字节当作本行数据继续解码对应 issue #2782见测试rgbsmall_with_line_break.kap。4. 行号校验与 BSB_IGNORE_LINENUMBERS每个扫描线前都有一个变长编码的行号标记旧版从 0 开始2.0 及以后从 1 开始0 表示缺失行。BSBSeekAndCheckScanlineNumber()会校验文件中的行号与期望值一致若不一致可设置配置选项BSB_IGNORE_LINENUMBERSTRUE忽略行号继续尝试读取export BSB_IGNORE_LINENUMBERSTRUE gdal_translate chart.kap chart.tif该选项也写在了源码的错误提示中“Set BSB_IGNORE_LINENUMBERSTRUE configuration option to try file anyways”。5. 波段组织BSBDataset::Open()创建单波段SetBand(1, ...)波段数据类型为GDT_UInt8块大小为“整行”nBlockYSize 1颜色解释为GCI_PaletteIndex并提供GDALColorTable。读取每行后IReadBlock()会把所有大于 0 的像元值减 1与上文颜色表下移配合值为 0 的像元缺失值填充保持不变。八、构建、注册与测试验证构建集成BSB 驱动通过 frmts/bsb/CMakeLists.txt 的add_gdal_driver(...)构建支持以**插件PLUGIN_CAPABLE**方式加载无第三方依赖NO_DEPS。非插件模式下还会额外编译示例程序bsb2raw。驱动注册函数GDALRegister_BSB()见 bsbdataset.cpp在启动时由 gdalallregister.cpp 调用注册信息包括长名Maptech BSB Nautical Charts帮助主题drivers/raster/bsb.html默认扩展名kap能力栅格、VirtualIOGDAL_DCAP_VIRTUALIO YES。自动化测试仓库在 autotest/gdrivers/bsb.py 中为 BSB 驱动提供了完整的 pytest 测试套件测试数据位于 autotest/gdrivers/data/bsb/覆盖场景包括测试数据文件验证内容test_bsb_1rgbsmall.kap基础打开与像元校验和30321test_bsb_2rgbsmall.kap创建拷贝仅当编译时启用创建功能test_bsb_3rgbsmall_index.kap文件末尾索引表的读取issue #2782test_bsb_4rgbsmall_with_line_break.kap行数据中嵌入 0 字符的容错test_bsb_5/6rgbsmall_truncated*.kap截断文件的错误处理test_bsb_tmerctransverse_mercator.kap横轴墨卡托地理变换与 SRS 推导test_bsb_cutlineaustralia4c.kapBSB_CUTLINEWKT 输出test_bsb_with_errant_0x1A_character_in_headerNZ52201_truncated.KAP头部中异常0x1A字符的容错issue #8765运行方式pytest autotest/gdrivers/bsb.py九、专利背景与格式开放性问题BSB 格式历史上受美国专利 5,727,090保护。根据 bsb_read.c 头部注释的说明该驱动基于 Mike Higgins 对格式的逆向工程工作The BSB format is subject to US patent 5,727,090; however, that patent apparently only coverswritingBSB files, not reading them, so this code should not be affected.即该专利仅覆盖写入BSB 文件的程序读取不受影响——这也是 GDAL 只提供读取支持、并禁用BSB_CREATE写入功能的直接原因。这一背景解释了两个设计决策驱动注册时仅设置pfnOpen与pfnIdentify不设置pfnCreateCopy写入路径BSBCreateCopy、BSBWritePCT、BSBWriteScanline等函数完整保留在源码中但整体被#ifdef BSB_CREATE包裹且默认不编译。十、常见问题与排错清单Q1选择.BSB文件打不开必须选择同名的.KAP文件。.BSB文件不能被直接选中。Q2打开报“This does not appear to be a BSB file, no BSB/ header.”确认文件头部 1000 字节内含BSB/、NOS/或WX\8NO1魔数也可能是文件损坏或并非 BSB 格式。Q3报错“Got scanline id ... when looking for ... Set BSB_IGNORE_LINENUMBERSTRUE”文件行号与期望不符。设置BSB_IGNORE_LINENUMBERSTRUE后可尝试继续读取。Q4颜色显示不对想换配色使用BSB_PALETTE配置项切换如export BSB_PALETTEDAY。Q5NOS 文件的配准信息不可用.geo文件当前被忽略建议使用对应的.KAP文件获取地理配准。Q6打开后没有地理变换若头部缺少KNP/等参考系字段、或 GCP 数量不足驱动无法推导地理变换此时可通过gdal_translate -gcp/-a_srs手动补充配准信息。结语BSB 驱动是 GDAL 中一个“小而专”的经典栅格驱动它用约两千行代码完成了一套含 RLE 解码、索引表、GCP 地理配准、投影推导与多种容错策略的完整只读方案并通过 autotest/gdrivers/bsb.py 对真实海图样本做了充分验证。无论是 NOAA 官方发布的.KAP海图还是 Softchart 的.NOS文件掌握本文介绍的打开方式、BSB_PALETTE配置与BSB_KNP/BSB_KNQ/BSB_CUTLINE元数据即可顺利接入 GDAL 生态进行检视、转换与二次开发。赞分享GIS遥感数据工程【免费下载链接】gdalGDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.项目地址https://gitcode.com/gh_mirrors/gd/gdal点击查看免费下载相关推荐CANN ops-math Im2col 算子深度解析滑动窗口图像到列的 NPU 实现与调用指南CANN ops math Im2col 算子深度解析滑动窗口图像到列的 NPU 实现与调用指南 Im2colImage to Column是卷积类网络在GIS遥感数据工程GDAL PRFPHOTOMOD Raster File / MegaTIFF栅格驱动格式结构、读取原理与实战应用GDAL PRFPHOTOMOD Raster File / MegaTIFF栅格驱动格式结构、读取原理与实战应用 导读 PRFPHOTOMOD RasGIS遥感数据工程GDAL EDIGEO 驱动完全指南读取法国 PCI 数字地籍交换格式GDAL EDIGEO 驱动完全指南读取法国 PCI 数字地籍交换格式 本指南以 GDAL 仓库自带的 EDIGEO 驱动文档 https://link.giGIS遥感数据工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考