在机器视觉圈子里Halcon 的江湖地位不用我多讲。做工业定位、缺陷检测、测量类项目的朋友算法原型阶段几乎都绕不开它。我这边好几个项目组算法机和检测机统一跑的是 Ubuntu 18.04前段时间正好需要把视觉库从旧版本切到 Halcon 21.05顺便把 Python 接口也一起接上。整个过程如果只装主程序其实不难真正烦人的是环境变量配错导致 hdevelop 起不来license 文件权限不对导致找不到许可证还有网络源不稳定导致依赖装到一半卡死这类问题。这篇文章就把我在 Ubuntu 18.04 上安装 Halcon 21.05 的完整过程写出来。内容包括版本选择、安装包结构、依赖处理、license 配置、环境变量设置、Python 接口接入最后附一份常见报错排查清单。适合刚接触 Linux 下 Halcon 的视觉工程师参考也适合要给多台算法机批量部署环境的同学直接抄作业。1. 安装前必看版本选择与准备工作1.1 为什么是 Ubuntu 18.04 Halcon 21.05先说版本周期。MVTec 从 20.11 那代开始一年发两个版本5 月份发布的是 Progress 版本11 月份发布的是 LTS 版本。Progress 版本会带一些新功能和算子但官方支持周期短LTS 版本主打长期稳定适合直接上产线。21.05 严格来说是个 Progress 版本它比 20.11 LTS 多了不少东西比如深度学习和 3D 测量相关的算子有更新但如果你是大规模商用项目我会建议优先考虑 21.11 LTS 或更新的版本。那为什么还要写 21.05原因很实际很多朋友是从官网申请收到的是 21.05 的 eval 试用包或者项目组里早期买的加密狗授权绑定在 21.05 上。这种情况下该装还是得装而且 21.05 的安装方式和思路放到 20.11、21.11 上完全通用。Ubuntu 18.04 的 glibc 版本是 2.27gcc 默认 7.3这两个条件都在 Halcon 21.05 的 Linux 二进制支持范围内。HDevelop 界面基于 Qt5Ubuntu 18.04 自带 Qt5.9兼容性没问题。很多老项目组到现在都还坚持用 18.04稳定性是一方面另一方面是产线上那套驱动和权限体系已经调顺了没人愿意为了尝鲜去动底层系统。1.2 下载安装包并检查系统环境Halcon 安装包不是从软件源直接 apt 来的需要去 MVTec 官网注册账号在下载专区申请试用版或者登录商业授权账户下载。下载 Linux 版本时你会看到两种包halcon-2105-linux-x64-deb.tar.gz专门给 Debian/Ubuntu 系列用的 deb 包集合推荐。halcon-2105-linux-x64.tar.gz通用二进制包适合 CentOS、openSUSE 等其他发行版需要手动配置。下载之前先在终端里确认几件事cat /etc/os-release uname -m free -h df -h /opt主要看三点系统是不是 64 位、内存够不够跑 HDevelop建议 4G 以上、/opt 目录所在分区剩余空间是否充足。Halcon 完整安装后大约占用 3-4GB如果 /opt 是独立分区且快满了先清理或者换路径。还需要确认 apt 源能正常访问。Ubuntu 18.04 的默认源有时候很慢建议在动手前先执行 sudo apt update如果特别卡把 /etc/apt/sources.list 换成国内镜像源再更新。这个问题看似无关紧要但依赖安装到一半超时中断比安装本身更让人抓狂。2. 安装包结构与依赖准备2.1 解压安装包认清楚每个 deb 是干什么的下载完的 tar.gz 包用 tar 解压tar -xzf halcon-2105-linux-x64-deb.tar.gz cd halcon-21.05.0.0-linux-x64-deb ls -l正常情况下会看到一个 install_linux.deb.sh 脚本和一堆 deb 文件。我把核心的几个 deb 的作用整理了一下deb 包作用必装程度halcon21.05-runtime运行时库部署算法时只需要装这个必装halcon21.05主程序包包含 HDevelop、工具、库文件、文档必装halcon21.05-examples示例程序与示例图片学习阶段很有用强烈建议halcon21.05-sonetcadapter深度学习相关适配器组件可选用深度学习再装如果你是从 Windows 那边把压缩包传过来的偶尔会遇到解压后文件名为乱码的情况。tar.gz 包本身一般没事乱的通常是 zip 包里的中文文件名。真遇到乱码也别慌Linux 下用 unzip 处理的话可以试试 unzip -O GBK 指定编码7z 也可以但归根结底不如重新下载一个 tar.gz 包省心。2.2 依赖库到底需要哪些怎么处理Halcon 的 deb 包对系统的依赖其实不算苛刻核心依赖是 libc6、libstdc6、libgcc1图形界面部分依赖 Qt5 的核心库和 OpenGL 相关库。Ubuntu 18.04 桌面版默认带 Qt5但如果你装的是 server 版或者精简版缺依赖的概率就大了。处理依赖我建议直接用 apt 而不是裸 dpkg。dpkg -i 不会帮你自动拉依赖装到一半报错还得回头再查很浪费时间。下面两种安装方式我推荐第二种# 方式一直接用官方脚本简单但过程不太可控 sudo ./install_linux.deb.sh # 方式二手动逐个安装依赖交给 apt 自动处理推荐 sudo apt install -y ./halcon21.05-runtime_*.deb sudo apt install -y ./halcon21.05_*.deb sudo apt install -y ./halcon21.05-examples_*.deb注意 apt install ./包名.deb 这种写法./ 前缀不能丢它会告诉 apt 安装本地文件。装完如果有依赖问题apt 会给出提示这时候执行 sudo apt --fix-broken install 可以自动补装缺失的依赖。如果你所在的机器完全不能连外网那就只能提前把依赖 deb 包下载好用 dpkg -i 按依赖顺序安装过程比较痛苦。所以我一直建议装 Halcon 的机器最好保证能访问外网至少装完依赖之前别断网。3. 核心安装操作从装包到启动 HDevelop3.1 正式安装安装到哪个目录去了按上面的命令装完之后Halcon 会默认安装到 /opt/halcon 目录。可以用 ls /opt/halcon 确认正常情况下你会看到 bin、lib、include、license、examples、doc 这些子目录。这个目录结构后面配置环境变量会反复用到先有个印象bin可执行文件比如 hdevelop 就在 bin/x64-linux/hdeveloplib动态库和静态库以及 Python 接口目录license许可证文件目录examples官方示例和示例图片doc文档装完之后先别急着打开license 和环境变量没配置好HDevelop 大概率是起不来的。3.2 license 文件配置与目录权限license 文件是所有坑里最隐蔽的一个。很多人明明把 license.dat 放进目录了启动 hdevelop 还是提示找不到许可证问题往往出在权限上。先创建目录再把 license 文件放进去sudo mkdir -p /opt/halcon/license sudo cp license.dat /opt/halcon/license/eval 试用版一般会给你一个 license.dat商业授权如果用的是加密狗这里先不用放文件后面单独说驱动。放好之后重点来了一定要把目录权限放开sudo chown -R $USER:$USER /opt/halcon/license chmod 755 /opt/halcon/license如果 license 目录属于 root普通用户启动 hdevelop 时没有写权限程序会去检查许可证状态发现读不了或者写不了临时状态直接报 No valid license found。这个坑我见过太多次了。3.3 环境变量配置让系统找到 HDevelop环境变量是 Linux 下 Halcon 的核心配置不对hdevelop 命令找不到动态库加载失败各种问题都来了。我先给出一份完整的配置再解释每一项的作用。编辑 ~/.bashrcexport HALCONROOT/opt/halcon export HALCONARCHx64-linux export HALCONIMAGES$HALCONROOT/examples/images export HALCONEXAMPLES$HALCONROOT/examples export PATH$HALCONROOT/bin/$HALCONARCH:$PATH export LD_LIBRARY_PATH$HALCONROOT/lib/$HALCONARCH:$LD_LIBRARY_PATH配置生效source ~/.bashrc解释一下几个变量HALCONROOTHalcon 的安装根目录软件内部很多模块都依赖这个路径定位资源。HALCONARCH架构目录名x64-linux 是标准 64 位 Linux 架构。装完 21.05 之后/opt/halcon/lib 下除了 x64-linux有时还会有类似 x64-linux-gcc73、x64-linux-gcc93 这种带编译器标记的目录。一般直接用 x64-linux 就能跑如果跑起来报二进制版本相关错误再回头看看有哪些目录可选。HALCONIMAGES示例图片路径配合 HDevelop 打开示例时有用途。PATH把 hdevelop 所在目录加进去方便直接敲命令启动。LD_LIBRARY_PATH动态库搜索路径不加这个程序启动时会提示找不到 libhalcon.so 之类的库。这里多提一句环境变量配在 ~/.bashrc 里只对当前用户生效。如果好几台算法机都是同一个运维账号这样没问题。但如果一台机器上多个 Linux 用户都要用 Halcon建议配到 /etc/profile.d/halcon.sh 里所有用户都能读到后面我会单独讲。3.4 验证安装启动 HDevelop 并跑通一张示例图环境变量配好之后验证安装最简单粗暴的方式就是启动 HDevelophdevelop如果终端能打开 GUI 界面说明环境没问题。接下来随便加载一张示例图试试在 HDevelop 里新建脚本执行read_image (Image, printer_chip/printer_chip_01) threshold (Image, Region, 0, 128) connection (Region, ConnectedRegions) select_shape (ConnectedRegions, SelectedRegions, area, and, 500, 99999)示例图片路径不用写绝对路径HALCONIMAGES 已经指明了。能顺利出图并显示区域安装基本就算成功。如果 hdevelop 命令找不到多半是 PATH 没生效先检查 source 是否执行再检查 ~/.bashrc 内容有没有保存。4. 开发环境联动Python 接口与外部工程集成4.1 配置 HALCON/Python 接口现在很多项目组都喜欢把 Halcon 的算法包到 Python 服务里通过 Flask 或 gRPC 暴露接口。21.05 的 Python 接口在 /opt/halcon/lib/python 目录下需要你把对应 Python 版本的路径加到 PYTHONPATH。查看该目录ls /opt/halcon/lib/python你会看到按 Python 版本区分的子目录比如 py3.6、py3.7、py3.8、py3.9。Ubuntu 18.04 系统自带的 Python 是 3.6在 ~/.bashrc 里追加export PYTHONPATH/opt/halcon/lib/python/py3.6:$PYTHONPATH如果你用的是 Anaconda 环境情况会有点微妙。Anaconda 的 Python 版本可能是 3.7 或 3.8先看 conda 环境里 python --version 是多少再把 PYTHONPATH 指到对应目录。有一点要注意不要在同一个进程里混用系统 Python 和 Anaconda 的库否则 import halcon 时可能出现 libpython 版本冲突直接报段错误这种问题排查起来非常难受。4.2 一个最小可用的 Python 调用示例配置好之后开个终端验证一下import halcon as ha print(ha.__version__)如果没报错说明接口已经通了。接下来写一个最基础的读图加阈值分割的脚本import halcon as ha image ha.read_image(/opt/halcon/examples/images/printer_chip/printer_chip_01.png) region ha.threshold(image, 0, 128) connected ha.connection(region) areas ha.area(connected) print(区域面积列表:, areas)21.05 的 Python 接口同时支持小写下划线风格和 HOperatorSet 风格上面的写法是小写风格读起来直观很多。如果你是从老版本迁移过来的项目代码里可能用的是 HImage、HRegion 这类类封装风格那部分 API 也还在只是官方更推荐新写法文档里的示例基本都是新的。4.3 从 HDevelop 导出算法代码到外部工程还有一个非常实用的功能HDevelop 的 File - Export。你在 HDevelop 里把算法验证完可以直接导出 Python、C、C# 代码。导出 Python 脚本后再套一层 Web 服务就能上线导出 C 代码后配合 CMake 工程就可以和现有的视觉软件框架集成。我自己的习惯是算法探索阶段全程在 HDevelop 里做确认参数没问题后再导出到工程里。不要一上来就在 Python 里写图像处理流程HDevelop 的可视化调试能力是命令行环境比不了的算子文档、变量检查、区域叠加显示这些都是效率利器。5. 常见问题排查从启动闪退到 license 失效5.1 hdevelop 启动没反应或闪退遇到 hdevelop 双击没反应先在终端里执行 hdevelop看有没有报错输出。绝大多数情况是缺动态库用 ldd 查一下ldd /opt/halcon/bin/x64-linux/hdevelop | grep not found如果看到 libQt5Core.so.5 之类的 missing说明系统缺 Qt 相关库补装即可sudo apt install -y libqt5core5a libqt5widgets5 libqt5gui5 libqt5network5如果看到 libGL 相关的 not found补装 OpenGL 库sudo apt install -y libgl1-mesa-glx libglu1-mesa还有一种容易被忽略的情况你是在 SSH 远程终端里执行 hdevelop但当前会话没有显示环境程序起不来。用 SSH 连接时记得加 -X 参数开启 X11 转发或者保证 DISPLAY 环境变量指向有效的图形会话。5.2 license 相关报错速查下面这个表是我整理的 license 问题排查思路基本覆盖了 80% 的情况现象可能原因排查命令No valid license foundlicense.dat 没放对路径ls -l /opt/halcon/license/License file not readable文件权限不足ls -l /opt/halcon/license/license.datLicense expiredeval 授权过期或系统时间不对date 查看系统时间Cannot access license manager加密狗驱动未安装systemctl status aksusbdLicense not valid for this version21.05 的授权给了其他版本确认授权版本号特别提一下系统时间。如果机器时间被改成和真实时间差很多Halcon 会认为 license 已过期或者未生效。遇到这个问题先校正时间sudo apt install -y ntpdate sudo ntpdate ntp.aliyun.com5.3 加密狗USB License驱动安装商业项目用加密狗是常态。Halcon 的加密狗基于 Sentinel HASP 方案Linux 下需要安装配套驱动MVTec 官方下载页或者驱动包里能找到 Linux 版本的 Sentinel Runtime。解压后一般能看到一个安装脚本常见的是 dinsttar -xzf HASP_Linux_x64.tar.gz cd HASP_Linux_x64 sudo ./dinst安装完成后检查守护进程状态systemctl status aksusbd再插上加密狗用 lsusb 确认有没有识别到 HASP 设备。如果驱动服务没跑起来hdevelop 启动时就会卡在 license 检查上。这里有个细节每次系统内核更新之后驱动可能需要重新编译或者重新安装遇到升级内核后加密狗失效的情况先重装一次驱动。5.4 Ubuntu 20.04/22.04 上能不能用这套流程如果你的机器不是 18.04 而是 20.04 或 22.04二进制兼容性一般没问题glibc 是向后兼容的21.05 的二进制在较新系统上通常能跑。需要注意的依然是 HALCONARCH 的选择新系统上 GCC 版本高建议优先试试 x64-linux-gcc93 这类目录如果启动报编译工具链相关错误再切换。另外提醒一句如果你 18.04 用得挺好只是因为“想升级”就去 do-release-upgrade升级过程中黑屏、显卡驱动不兼容的概率确实不低。我见过好几个工程师因为升级系统浪费一整天最后又回滚。产线机器追求的是稳定极少有业务需求逼着你非要升级系统的。真要考虑新系统特性不如拿一台新机器重新装然后把 Halcon 环境重新部署一遍风险小得多。6. 工程师的实用习惯让 Halcon 在 Linux 下更顺手6.1 全局环境变量 vs 用户级环境变量前面我们把环境变量写进了 ~/.bashrc这在单用户场景下没毛病。但项目组里经常是数值工程师、算法工程师、部署工程师共用一台机器靠各自 .bashrc 配置很容易出现“我能用你不能用”的混乱局面。更好的做法是在 /etc/profile.d/ 下建一个 halcon.shsudo nano /etc/profile.d/halcon.sh内容就是前面那六个 export然后sudo chmod x /etc/profile.d/halcon.sh之后所有用户重新登录都会自动加载这份配置。这种方式同样适用于开机自启动的算法服务你能保证服务启动时能拿到正确的 HALCONROOT 和 LD_LIBRARY_PATH而不用依赖某个特定用户的登录状态。6.2 多版本切换与彻底卸载万一你想在同一台机器上保留 21.05 又尝试 21.11环境变量的玩法就要小心了。Halcon 的多版本共存并不复杂核心是切换 HALCONROOT。但有个雷区HALCONARCH 和 license 必须和版本匹配绝不能把 21.05 的 license.dat 扔到 21.11 的目录里指望它生效。卸载时先用 dpkg 移除dpkg -l | grep halcon sudo dpkg -r halcon21.05主程序移除后runtime 和 examples 可以分别处理。如果想彻底清理再把 /opt/halcon 目录删掉即可。务必备份好 license卸载重装时能省不少事。6.3 我自己的部署习惯最后分享几个我踩过坑之后沉淀下来的小习惯。第一装完 Halcon 之后我会立刻把 license 目录做一次备份放在 /opt/backup 下并且把 license 文件的权限记录到项目文档里。否则三个月后重新装机找不到原始 license.dat 会非常被动。第二我会在 /opt/halcon/examples/images 里放一张自己常用的测试图配合一个简单的 HDevelop 脚本。每次在新机器上装完只要打开这个脚本跑一遍就能确认安装、license、环境变量全部正常。检查环境这件事越自动化越好不要每次都从零开始敲命令。第三如果项目组是多台算法机批量部署我建议把整个 /opt/halcon 打成一个 tar.gz 包在其他机器上直接解压再加上 license 和环境变量比每台机器都走一遍 apt 安装快得多。这个思路在离线内网环境下尤其好用。