Halcon20.11图像拼接练习文件自制：从特征匹配到zip打包

简介：面向使用Halcon20.11进行图像拼接的开发者与学习者，压缩包围绕特征点匹配与投影变换展开，完整覆盖了从算法原理到实验验证的闭环。包内集成了Forstner和Harris两种经典角点检测算法，并以膀胱癌细胞3×3图像拼接作为实战案例，取得较理想效果；同时附带拼接特征点坐标推导公式，帮助读者理解坐标转换与单应性矩阵的数学基础。压缩包共含75个文件，整体大小约41.9MB，主要文件类型包括.hdev可视化例程、.bmp/.png/.jpg图像样本、基于C#的工程源码（.cs/.csproj/.sln）以及.txt技术说明，既有可直接运行的演示程序，也有便于二次开发的工程化封装。目前已有137人学习查看，适合正研究Halcon图像拼接、需要算法对照与真实案例参考的开发者。

1. 把图像拼接练好，比算子更重要的是素材可控

做机器视觉的同行应该都有同感：上手 Halcon 图像拼接（Image Stitching）的头一个晚上，往往不是卡在算法上，而是卡在现成的练习图不好找。网上下载的示例图要么重叠率过大、要么两张图亮度不一致，跑完proj_match_points_ransac后匹配点倒是不少，但拼接缝就是消不掉。Halcon20.11 环境里自己做一套带拍摄参数的练习文件，打成 zip 包随取随用，是把这块练扎实的常规做法。本文按「算法分工 -> 素材采集 -> zip 打包 -> HDevelop 跑通 -> 验证与排错」的顺序，给出一套可直接落地的方案；适合刚接触 Halcon 的算法工程师，也适合要给产线做自动化视觉方案、想快速评估拼接可行性的集成商。

2. Halcon20.11 图像拼接的原理拆解与最小验证

2.1 先搞清楚拼接任务在 Halcon20.11 里的算子分工

图像拼接算法及实现的完整流水线在 Halcon 里是四个环节：特征提取、特征匹配、变换模型求解、投影融合。不少教程把后面两步封装在一个高层算子里，出了问题根本不知道去哪查，所以自制练习文件的第一步，是把流水线拆开。

• 特征提取：常用points_foerstner、points_harris、points_sojka。拼接场景里我习惯先用points_harris，它对角点响应快，参数少，适合验证素材有没有足够的可匹配点；纹理复杂的场景再换 Foerstner。
• 特征匹配与误匹配剔除：proj_match_points_ransac是核心。它内部跑 RANSAC，把错误匹配点对剔除后估算单应矩阵，输出HomMat2D以及内点集Points1/Points2。
• 变换模型：通过Transformation参数指定。'similarity'只允许旋转、平移和等比缩放；'affine'加上各向异性缩放和斜切；'projective'最通用，能表达透视关系。相机正对平面场景时用前两者更快更稳，有视角变化时必须上'projective'。
• 投影融合：gen_projective_mosaic负责把多张图投影到同一坐标系并插值融合。它比手动hom_mat2d_projective_trans_image逐个投影省事，但参数里映射索引的写法在不同版本资料里有差异，后面单独说。

2.2 用最小脚本验证特征点密度，先别急着拼

我拿到一套练习图，第一件事不是拼图，而是确认两张图上能不能找到 20 对以上的可靠特征点。在 HDevelop 里跑这个最小片段，五秒内就能判断素材值不值得继续调：

* 读入左右两张练习图 read_image (ImageL, 'left_0001.png') read_image (ImageR, 'right_0002.png') * 提取 Harris 角点；参数按图宽高和位深适当调整 points_harris (ImageL, 1.0, 1.5, 0.05, 2000, 5, 'true', RowsL, ColsL) points_harris (ImageR, 1.0, 1.5, 0.05, 2000, 5, 'true', RowsR, ColsR) * 取角点位置的灰度值，作为 RANSAC 匹配的输入 get_grayval (ImageL, RowsL, ColsL, GrayL) get_grayval (ImageR, RowsR, ColsR, GrayR) * RANSAC 求射影变换矩阵 proj_match_points_ransac (ImageL, ImageR, RowsL, ColsL, RowsR, ColsR, \ GrayL, GrayR, 10, 100, 'projective', 1, 0.5, 'gold_standard', \ HomMat2D, Points1, Points2) * 输出内点数量 tuple_length (Points1, NumOk)

这段代码的逻辑很简单：先找角点，再取灰度，最后让 RANSAC 自己筛选匹配。几个关键参数的含义：

• points_harris第 6 个参数MinDistance = 5，表示角点之间的最小像素距离，太大会把密集纹理里的有效特征滤掉，太小会产生大量冗余点拖慢 RANSAC。
• proj_match_points_ransac里的QualityLevel = 10是候选点的质量门槛，数值越高参与匹配的点越少但越可靠。
• DistanceThreshold = 1是 RANSAC 判定内点的最大重投影误差，单位是像素。这个值调到 0.5 更严格，拼接更准；但相机畸变没校正时容易把好点也踢掉。
• NumMatches = 100是 RANSAC 迭代时抽取的初始匹配对数，练习素材不需要改。

跑完看NumOk：小于 15 说明素材问题大于算法问题。这时候别去调拼接参数，回拍摄环节补纹理、调曝光或增大重叠率才是正路。

2.3 变换模型与融合方式的选型参数表

同一套素材用不同变换模型，结果差别很大。以 Halcon20.11 的算子参数为准，我一般按下面这个表选：

融合插值方式是gen_projective_mosaic里的WarpingMethod：'bilinear'双线性插值适合大部分图像，边缘平滑但会损失一点锐度；'nearest_neighbor'保留原始像素值，适合二值图或要精确灰度的场合。练习文件里我会在配置里记下每套素材用的是哪种变换，方便对照实验结果。查算子帮助时，Halcon20.11 帮助文档汉化版本能快速定位参数说明，但参数细节和算子签名要以本地 F1 打开的英文文档为准，汉化资料在版本升级后偶尔滞后。

3. 自制练习文件的采集规范与 zip 压缩包打包

3.1 为什么要自制而不是直接下载现成图片

网上的拼接示例图大多是挑过的完美素材，重叠率、光照、纹理密度都很理想，拿来练习只能验证“算子能跑”，验证不了“算法在边界条件下的表现”。自制练习文件的价值在于可控：你可以故意拍一组只有 25% 重叠率的图测试下限，也可以拍一组左右曝光差两档的图练习亮度补偿。更重要的是，只有自己知道每张图的重叠率、焦距、畸变状态，才能把参数调优的过程跟图像特征对上。

我在项目里被拼图问题卡住时，也经常临时在实验室摆个 PCB 板用工业相机拍一套，模拟现场视角。这类本地素材随拍随用，打包成固定格式的 zip 放项目里，比每次翻网盘、找同事借图省时间得多。

3.2 拍摄练习素材的硬性条件

不用高端设备，手机或普通 USB 工业相机都行，但以下几条不满足，后面算法怎么调都白搭：

• 相邻两张图的重叠区域控制在 30% 到 50%。低于 20% 时 RANSAC 经常找不到足够多的匹配对；超过 70% 又浪费视野，融合效率低。
• 整个序列固定焦距、固定光圈、固定曝光。自动曝光会让相邻两张图亮度断层，混合区域出现明显的明暗分界，排查时会误以为是融合算法问题。
• 避免用广角端拍摄，画面边缘畸变大，'projective'变换也救不回来。拍之前先对着棋盘格做一次畸变校正，把校正后的图再喂给拼接脚本。
• 画面里必须有纹理细节。纯白墙、大面积无纹理区域是特征提取的死区，这种素材只有反例价值，可以作为负样本单独放一个negative_cases目录。

3.3 用 Python 按规范打包 zip

打包前先定目录结构，我习惯长这样：

stitch_assets/ images/ left_0001.png right_0002.png center_0003.png config.json README.txt

然后写一个 Python 脚本把整个目录打成Halcon20.11-图像拼接练习文件自制.zip：

import json import zipfile from pathlib import Path src = Path("./stitch_assets") out_path = Path("./Halcon20.11-图像拼接练习文件自制.zip") # 写入拍摄参数，后续 HDevelop 脚本直接从 zip 解压后读取 config = { "overlap": 0.4, "focus": 12.0, "exposure": "fixed", "width": 2448, "height": 2048, "transformation": "projective", } (src / "config.json").write_text( json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8" ) # ZIP_DEFLATED 压缩，compresslevel=6 是速度和体积的折中点 with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6) as zf: for p in sorted(src.rglob("*")): if p.is_file(): zf.write(p, p.relative_to(src))

这段代码里有几个细节值得解释：compresslevel=6对 PNG 这类本身已压缩的图片收益不大，但配置文件是纯文本，压缩率明显；打包前先把config.json写进去，是为了保证 zip 里的配置跟当前素材一致，避免以后翻出来不知道对应哪套图。归档路径用相对路径p.relative_to(src)，HDevelop 解压后目录结构不会带一层无关的文件夹。

注意不要用带空格和中文的临时目录打包，Windows 下某些解压工具和 Halcon 的list_files对中文长路径处理不一致，解压后报failed to copy spatial iop zip这类错误的概率会高很多。

3.4 配置文件的字段含义

config.json里的字段不是摆设。overlap留给脚本判断当前素材的重叠率处于什么区间，重叠率低时 RANSAC 的DistanceThreshold要适当放宽；transformation记录素材最适合的变换模型，练习时可以对比自动估算和预设模型之间的差异。把拍摄条件固化进 zip 包里，是整个自制练习文件最有价值的一点：任何一次实验都能精确复现当时的参数环境，这在团队协作时尤其有用。

4. 在 Halcon20.11 里读取 zip 并跑通完整拼接脚本

4.1 别指望 read_image 直接读 zip，先解压到工作目录

Halcon 没有内置的 zip 虚拟文件系统，read_image只能按操作系统真实路径访问文件。直接把 zip 内路径传给read_image会报找不到文件。常规做法是先解压到本地工作目录，再用list_files遍历。

Windows 10 及以上的机器自带tar命令，可以处理 zip 格式：

mkdir -p ./stitch_assets tar -xf Halcon20.11-图像拼接练习文件自制.zip -C ./stitch_assets

-C指定解压目标目录，-xf表示解压文件。装了 7-Zip 的环境也可以换成7z x Halcon20.11-图像拼接练习文件自制.zip -o./stitch_assets。解压完成后到目录下确认config.json在不在，在的话说明这次解压是完整的；如果连配置文件都没解出来，就是 zip 本身有截断或损坏，先回去重新打包。

4.2 逐张读图并拼接的 HDevelop 脚本骨架

解压后写一个可重复执行的 HDevelop 脚本。下面的骨架遍历images目录下所有 PNG，按文件名排序后逐张读取并拼接：

* 1. 遍历目录，筛选图像文件 list_files ('./stitch_assets/images', 'files', AllFiles) tuple_regexp_select (AllFiles, '.*\\.(png|jpg|bmp)$', ImageFiles) tuple_sort (ImageFiles, ImageFilesSorted) * 2. 第一张作为初始基准图 read_image (MosaicImage, ImageFilesSorted[0]) tuple_length (ImageFilesSorted, NumFiles) * 3. 逐个拼接后续图像 for i := 1 to NumFiles - 1 by 1 read_image (NextImage, ImageFilesSorted[i]) * 提取特征点并匹配，这里复用第 2 章的参数思路 points_harris (MosaicImage, 1.0, 1.5, 0.05, 2000, 5, 'true', RowsM, ColsM) points_harris (NextImage, 1.0, 1.5, 0.05, 2000, 5, 'true', RowsN, ColsN) get_grayval (MosaicImage, RowsM, ColsM, GrayM) get_grayval (NextImage, RowsN, ColsN, GrayN) proj_match_points_ransac (MosaicImage, NextImage, RowsM, ColsM, \ RowsN, ColsN, GrayM, GrayN, 10, 100, 'projective', 1, 0.5, \ 'gold_standard', HomMat2D, Points1, Points2) * 4. 当前拼接结果与下一张图融合 tuple_length (Points1, NumOk) if (NumOk < 15) continue endif gen_projective_mosaic ([MosaicImage, NextImage], MosaicImage, 1, \ HomMat2D, 'false', 'bilinear', [], []) endfor * 5. 保存最终结果 write_image (MosaicImage, 'png', 0, './result/panorama_001.png')

这个循环里最值得注意的逻辑判断是NumOk < 15：拼接失败时直接跳过当前图，不让坏结果污染已经拼好的部分。这在多图序列里比硬拼更重要，现场素材偶尔有一两张失焦、过曝，跳过去比强行拼出来一条扭曲断层要好。

gen_projective_mosaic在 Halcon20.11 不同资料里映射参数写法不完全一致，有的版本用MappingSource/MappingDest显式指定图序，有的版本像这里用自动估算。我的建议是跑之前按 F1 查一下本地文档，确认第四个参数接受的索引含义；这个算子的参数在不同培训教材里经常打架，以你本机装的版本为准。

4.3 三个必调参数及调整方向

这三个参数相互耦合：Threshold降下来，需要QualityLevel提高来过滤弱角点；DistanceThreshold收紧后，NumOk会下降，如果小于 15 就需要回采集环节补重叠率。练习时每次只动一个变量，记录NumOk和拼接耗时，才能积累出属于你自己这套素材的参数经验。

5. 验证拼接质量与 zip 物料包的常见排错

5.1 拼接结果的四个检查动作

拼完别只盯着全景图看个大概，按下面的顺序验收：

1. 看诊断信息里的NumOk，整个序列每张图的匹配对数都大于 20，结果才谈得上可靠。
2. 把 MosaicImage 缩放后看整体有没有重复纹理或重影，重影通常意味着两张图之间存在非平面视差，'projective'无法完全对齐。
3. 在重叠区域中心画一条竖直 ROI，沿 ROI 取灰度剖面，检查融合处有没有亮度跳变。
4. 用get_image_size确认输出宽高接近“各图原始宽高、有多张保留重复区域”的推算值，如果宽度反而小了，说明有图没合进去。

这套动作在两分钟内能给出拼接质量结论，比盯着边缘看十分钟凭感觉判断有效得多。

5.2 zip 解压与读取的常见报错定位

我碰到最多的其实是第一种，用微信或网盘中转的 zip 经常被截断。校验方法很简单：解压先看config.json在不在，再对比包里的图像数量跟README.txt里记录的是否一致。

5.3 让脚本自动读取 zip 里的拍摄参数

练习文件如果只是打包图片，价值少了一半。我习惯在 HDevelop 脚本里把config.json里记录的拍摄参数自动读进来，用overlap字段决定 RANSAC 的距离阈值。文本解析用基础文件算子就能完成：

open_file ('./stitch_assets/config.json', 'read', Handle) fread_string (Handle, ConfigStr) fclose (Handle) * 提取 overlap 字段的值；config.json 结构简单时用字符串切分足够 tuple_split (ConfigStr, ',', Fields)

实际工程代码里我会在上面的tuple_split之后再对Fields逐项按=切分，并用tuple_number把字符串转成数值。这样换一套素材时，只需替换 zip 压缩包里的config.json，拼接参数策略自动跟着变。调试时在控制台输出一行诊断信息，确认脚本读到的overlap跟打包时写进去的一致，验证逻辑闭环后再继续批量实验。

本文还有配套的精品资源，点击获取