最近在弄视觉检测服务的部署环境项目方指定了Ubuntu 18.04作为运行系统算法程序要从Windows迁到Linux上核心依赖就是Halcon 21.05。说实话Windows下装Halcon就是双击exe一路Next换到Linux下才发现完全不是同一套玩法没有图形安装向导没有自动写注册表连依赖库都要自己一个个凑。折腾了一下午装了卸、卸了装踩了不少坑才把环境弄干净。这篇就把Ubuntu 18/Linux上安装Halcon 21.05的完整流程、依赖清单和典型报错整理出来。内容覆盖从下载安装包、解压安装、license授权到环境变量配置、代码接入验证的整个链路特别适合第一次在Linux上部署Halcon的机器视觉工程师也适合准备把现有项目从Windows移植到Linux服务器上的人参考。1. 先想清楚Linux版Halcon 21.05到底拿什么来安装很多人第一次在Linux上装Halcon会习惯性地去找deb包或者RPM包实际上MVTec官方对Linux平台的发行方式一直是tar.gz解压包不是apt能直接管理的格式。这就决定了整个安装过程的思路下载、解压到指定目录、手动配环境变量。搞清楚这个前提后面遇到问题就不容易慌。1.1 安装包形态与获取方式Halcon 21.05对应的安装包名一般是halcon-21.05.0.0-linux-x64.tar.gz有些渠道带构建日期后缀比如halcon-21.05.0.0-linux-x64-20210630.tar.gz不影响安装。下载需要到MVTec官网的下载中心要有账号试用license也要先在那边申请。这里要提醒一句下载时注意选Linux x64版别下成Windows版或者ARM版。判断方法很简单下载完成后执行uname -m输出是x86_64就对了如果是aarch64说明是ARM架构得去下载对应的ARM版本。如果是要部署到嵌入式设备或工控机ARM板上整个流程会不一样本篇以x64服务器场景为准。1.2 License形态决定安装路径在Linux上Halcon的授权分两种常见形态加密狗授权和license文件授权。个人开发、试用、以及大多数工业部署场景用的都是后者也就是一个.dat文件文件名通常叫license.dat。这个文件是安装环节的关键它决定Halcon能不能运行。安装Phase和后续HDevelop启动都会校验license如果license没放对位置哪怕安装目录再完整也白搭。申请试用license时要注意有效期MVTec的试用一般给一个月到期后HDevelop会直接拒绝运行。1.3 和Windows版的差异Windows版装完自动写注册表、自动配PATH、自动装好各种运行库Linux版没有这些东西。安装脚本只是把文件摊到目录里剩下的环境变量、软链接、动态库路径全部要手动搞定。另一个差异是权限模型。Windows下装软件一般写到Program Files普通用户也能跑Linux下如果装到/opt/halcon目录属主是root普通用户虽然能读能执行但有些临时文件写入和license更新操作会出问题。我建议装完后直接chown给实际使用账号后面少很多权限麻烦。1.4 磁盘空间和目录规划Halcon 21.05完整安装大概占2.5GB左右加上示例数据和解压临时文件建议预留4GB以上空间。安装目录我推荐/opt/halcon好处是路径固定、团队协作时好沟通也方便后续做软链接。有同事习惯装在自己家目录下比如~/halcon单人开发没问题但项目一换人、一换机器环境变量路径乱七八糟维护成本很高。放在/opt/halcon这种约定俗成的位置大家复制命令就能用。2. 环境关卡Ubuntu 18.04装机前需要做的检查与依赖补齐Ubuntu 18.04是个老系统基础软件源里的库版本偏旧Halcon 21.05编译时依赖的运行库有些在最小化安装里根本不带。这一步如果不提前做安装完了运行hdevelop十有八九会报error while loading shared libraries。2.1 系统基础状态检查装之前花两分钟确认系统状态避免装了半小时发现环境不对cat /etc/os-release free -h df -h /os-release确认是Ubuntu 18.04free确认内存够用Halcon跑起来建议至少2GB以上df确认根分区有4GB以上空闲空间。如果系统是CentOS或其他Linux发行版依赖命令和库名会有差异本篇以Ubuntu 18.04为准。2.2 需要提前装的运行库清单Halcon图形界面和运行时依赖一批X11相关库和OpenGL库。最省心的做法是直接跑下面这条命令sudo apt update sudo apt install -y libx11-6 libxext6 libxi6 libxt6 libxrandr2 libxrender1 libglu1-mesa freeglut3 libgomp1逐个解释一下为什么需要这些libx11-6、libxext6、libxi6、libxt6是X Window系统的基础库HDevelop的GUI界面依赖它们libxrandr2和libxrender1负责窗口缩放和渲染libglu1-mesa和freeglut3是OpenGL工具库图像缩放、轮廓显示用到libgomp1是GCC的OpenMP并行库Halcon多核计算依赖它。如果是纯服务器环境不打算打开HDevelop图形界面只需要通过Python或C调用算法接口那么前几个X11库可以暂时不装但libgomp1必须装不然后面程序跑起来会报错。2.3 下载完整性校验Linux下从网上下载的安装包经常因为网络中断导致文件损坏解压时报gzip: invalid compressed data。这种情况看着像解压命令用错了实际上是文件没下完。我习惯下载完先做MD5或SHA256校验MVTec官网每个安装包旁边有对应的校验值。命令是md5sum halcon-21.05.0.0-linux-x64.tar.gz sha256sum halcon-21.05.0.0-linux-x64.tar.gz把输出和官网给的值比对一致再解压。哪怕一次下载没问题我也建议保留校验这一步因为后面配置环境变量、调试问题时要排查的因素太多少一个变量就少一层麻烦。2.4 双系统和虚拟机环境特别提醒看到有人问“ubuntu18 如何升级到20的过程中黑屏”还有“虚拟机安装linux蓝屏”这里说一个相关但容易被忽视的点如果你是在VirtualBox或VMware里装Ubuntu 18再装HalconHDevelop的图形界面可能会非常卡甚至窗口一片黑。这不是Halcon本身的问题是虚拟机3D加速和OpenGL支持不完善。解决思路有两个一是给虚拟机开启3D加速装好虚拟机增强工具二是干脆不用图形界面通过远程X11转发或者直接用命令行接口。另外如果后续要接USB加密狗做授权虚拟机里需要把USB设备透传给客户机否则Halcon识别不到授权。3. 正片解压、安装、license 与环境变量全流程环境准备好之后进入实际安装环节。这里我把完整命令流程贴出来每一步都标注了含义和容易出错的地方照着敲就行。3.1 解压并放入指定目录先把安装包放到/tmp或者当前用户目录然后解压到/optsudo mkdir -p /opt sudo tar -zxf halcon-21.05.0.0-linux-x64.tar.gz -C /opt解压完成后/opt下会出现halcon目录里面的结构大致是bin、lib、include、doc、license、examples这些子目录。有同事问过为什么不直接解压后原地跑还要挪到/opt因为安装Package解压出来的目录本身就是完整的Halcon安装根目录不需要额外编译。把它放在/opt是约定俗成的路径管理方式方便多个用户共享也方便后续写环境变量脚本。3.2 执行安装脚本进入解压后的目录能看到一个install-linux.sh脚本执行cd /opt/halcon sudo ./install-linux.sh脚本运行时会提示选择安装目录和授权方式如果没有特殊需求一路默认即可。要说明的是这个安装脚本做的事情其实很轻量——主要是验证环境、创建一些默认配置、生成环境变量模板并不像Windows安装包那样往系统里塞很多东西。我试过在部分Ubuntu 18.04精简环境上这个脚本会因为缺少dialog工具而中止遇到这种情况先执行sudo apt install -y dialog再重新运行脚本。3.3 安装license文件接下来处理授权文件把license.dat放到/opt/halcon/license/下sudo mkdir -p /opt/halcon/license sudo cp /path/to/license.dat /opt/halcon/license/ sudo chmod 644 /opt/halcon/license/license.dat权限这块很多人会忽略。如果文件属主是root且权限是600普通用户启动Halcon时因为读不了license文件会报授权错误而且这种错误特别容易让人误以为是license本身过期了排查半天才发现是权限问题。3.4 环境变量配置环境变量是Linux版Halcon安装的重头戏。需要配置四个关键变量我建议写到系统级配置里这样所有用户都能用sudo tee /etc/profile.d/halcon.sh /dev/null EOF export HALCONROOT/opt/halcon export HALCONARCHx64-linux export PATH$HALCONROOT/bin/$HALCONARCH:$PATH export LD_LIBRARY_PATH$HALCONROOT/lib/$HALCONARCH:$LD_LIBRARY_PATH EOF解释一下每个变量的含义HALCONROOT是安装根目录HALCONARCH指定架构x64平台固定是x64-linuxPATH追加的是Halcon可执行文件路径这样能直接敲hdevelop启动图形界面LD_LIBRARY_PATH指向动态库目录C/Python调用Halcon库时系统从这里找.so文件。配置完后让环境变量在当前shell生效source /etc/profile.d/halcon.sh3.5 创建软链接为了让hdevelop、hdevelop_cl这些命令全局可用还可以把它们链到/usr/local/binsudo ln -s /opt/halcon/bin/x64-linux/hdevelop /usr/local/bin/hdevelop sudo ln -s /opt/halcon/bin/x64-linux/hdevelop_cl /usr/local/bin/hdevelop_cl其实PATH里已经包含了$HALCONROOT/bin/$HALCONARCH不加软链接也能直接执行。做这一步是为了防止某些代码或脚本里写死了/usr/local/bin保持路径访问的一致性。3.6 首次启动验证验证环境变量是否生效可以查看版本信息which hdevelop hdevelop正常的话HDevelop的图形界面会弹出来。如果是在没有显示器/桌面环境的服务器上这一步会失败或窗口黑屏但不用慌后面第五节讲命令行和代码层面的验证方法。4. 实战踩坑从“装完启动黑屏”到“license过期”的排查链路整个安装过程中最容易卡住人的不是安装本身而是装完之后的报错。这里按我实际遇到和帮同事远程排查过的顺序把典型问题完整地拆一遍。4.1 启动黑屏问题的本质排查有热搜词问“ubuntu18 如何升级到20的过程中黑屏怎么解决”虽然场景是系统升级但黑屏这个现象在装Halcon后也会遇到。我第一次在无桌面服务器上跑hdevelop窗口黑漆漆一片没有任何反馈第一反应以为是显卡驱动或OpenGL有问题。排查链路是这样的先确认DISPLAY变量是否存在执行echo $DISPLAY如果是空的说明当前shell没有X11图形环境然后确认是不是在SSH会话里SSH默认不转发图形界面。处理方式有三种一是本地有桌面环境就直接在图形终端里运行二是SSH加-X启用X11转发但延迟会比较高三是干脆不碰图形界面用命令行接口做验证。实际上Halcon的算法引擎和GUI是分离的生产环境里根本不需要启动HDevelop。后续我用Python直接调用Halcon算子验证比折腾图形界面靠谱得多。4.2 解压乱码与中文路径问题还有一个和安装包解压相关的坑来自热搜词里的“linux 解压文件乱码”。Halcon的官方包内部文件都是英文名正常解压不会乱码。但如果在网盘或国内渠道下载二次打包的版本外层套了一个中文文件名的zip在Linux下用unzip解压常有乱码因为zip里的编码通常是GBK而Linux默认UTF-8。处理方式是用unzip -O gbk指定编码unzip -O gbk halcon_中文路径包.zip如果unzip版本不支持-O参数可以用unar替代。比解压乱码更隐蔽的是中文路径问题。Halcon读取图片和模型文件时如果路径里带中文在一些老版本里会出现找不到文件的错误。Linux标准环境是UTF-8Windows出来的文件路径经常是GBK编码混用特别容易出问题。建议在整个项目目录上强制用英文路径避免跨平台迁移时踩坑。4.3 license失效的排查链路license类的报错很折磨人常见的报错是Local license is not valid for the current date。遇到这个报错我建议按下面顺序逐级排查第一步检查系统时间date如果是双系统Windows和Linux混用Linux的时间经常会被改成UTC或本地时间偏移出现系统时间比实际时间快几个月的现象。Halcon的license对时间漂移检测很严格UTC和本地时间配置不同步就会判为非法。第二步同步时间sudo timedatectl set-ntp true sudo timedatectl set-local-rtc 0set-local-rtc 0表示硬件时间使用UTC这是Linux的标准习惯。第三步检查license文件本身。用cat -A查看文件尾部如果有^M这样的换行符标记说明文件被Windows工具编辑过换行符没转干净。用dos2unix转换一下sudo dos2unix /opt/halcon/license/license.dat第四步确认license没有被杀毒软件或网盘同步工具改动。这个问题在Windows上常见Linux上少见但如果是双系统共享分区放着license文件也有一定概率被Windows那边的软件碰过。第五步确认系统里没有残留旧版本Halcon的环境变量引用。如果以前装过Halcon 20.11旧的环境变量没清干净新老版本互相覆盖license位置会报出各种诡异性错误。4.4 动态库缺失的lDD排查运行hdevelop或者编译程序时最常见的一句报错是error while loading shared libraries: libhalcon.so: cannot open shared object file这个问题几乎都是LD_LIBRARY_PATH没生效。可以先用ldd检查依赖ldd /opt/halcon/bin/x64-linux/hdevelop | grep not found如果列出的一堆库都是not found先source /etc/profile.d/halcon.sh再重试如果只是个别库缺失回到前面第2.2节的依赖安装命令补库。我遇到过一种情况source之后当前shell能跑但新开的终端窗口又报错。原因是终端窗口启动时读的是.bashrc而我把变量写到了.bashrc里但没保存成功。所以提醒一下环境变量写在/etc/profile.d/下对登录shell才保证生效如果总是用非登录shell跑命令就同步写一份到~/.bashrc。4.5 权限问题明明装了却permission denied普通用户运行Halcon时报Permission denied除了检查文件属主还可以看一下挂载选项。如果/opt所在的磁盘以noexec方式挂载任何可执行文件都跑不起来。用mount | grep /opt查看挂载参数有noexec就去/etc/fstab里改掉后重新挂载。5. 安装完不等于能用命令行和代码层的双重验证很多人装到hdevelop能启动就以为大功告成了结果写Python脚本调用import halcon时才发现问题。实际上安装完成的验证至少要覆盖四个层面每个层面独立排查。5.1 验证清单汇总为了直观我把不同使用方式对应的验证命令整理成一张表使用方式验证命令或代码预期结果HDevelop图形界面hdevelop能打开主窗口命令行批处理hdevelop_cl -e test.hdev能输出处理结果C程序调用编译HalconCpp示例链接成功程序运行不报so缺失Python接口调用import halcon执行read_image能读到指定路径的图像5.2 Python接口接入Halcon 21.05自带的Python接口在安装目录的lib/python下。配置PYTHONPATHexport PYTHONPATH/opt/halcon/lib/python:$PYTHONPATH然后写一段最简单的验证代码import halcon as ha # 读取示例图片 image ha.read_image(particle) print(type(image)) # 获取图像大小 width, height ha.get_image_size(image) print(fimage size: {width} x {height})如果import halcon报错找不到符号先检查LD_LIBRARY_PATH是否包含$HALCONROOT/lib/x64-linux再检查Python版本。Halcon 21.05对Python 3.6到3.9支持比较好Ubuntu 18.04默认Python 3.6正好在支持范围内。5.3 C编译连接C开发需要用到halconcpp接口。写一个最简单的读取图像程序#include HalconCpp.h using namespace HalconCpp; int main() { HObject image; ReadImage(image, particle); HTuple w, h; GetImageSize(image, w, h); std::cout width: w.I() , height: h.I() std::endl; return 0; }编译命令g -o read_image read_image.cpp -I/opt/halcon/include -I/opt/halcon/include/halconcpp -L/opt/halcon/lib/x64-linux -lhalconcpp -lhalcon编译成功后运行./read_image如果运行时报找不到共享库给二进制加上rpath可以省去每次设置环境变量的麻烦g -o read_image read_image.cpp -I/opt/halcon/include -I/opt/halcon/include/halconcpp -L/opt/halcon/lib/x64-linux -Wl,-rpath,/opt/halcon/lib/x64-linux -lhalconcpp -lhalcon用ldd read_image | grep halcon确认动态库路径显示/opt/halcon/lib/x64-linux/libhalcon.so就对了。5.4 命令行批处理生产环境真正的主力实际做视觉检测项目时大部分情况不需要打开HDevelop图形界面而是用hdevelop_cl以批处理方式执行写好的.hdev脚本或者用HDevEngine在Python/C程序里调用Halcon算子。hdevelop_cl的典型用法hdevelop_cl -e /path/to/your_procedure.hdev注意.hdev脚本里如果有视觉交互操作(如dev_open_window)会在无头服务器上报错写脚本时要用dump_image或者直接处理图像数据替代窗口显示。我个人更推荐用HDevEngine方式把算法流程封装成.hdev文件业务程序通过Python调用HDevEngine执行这样算法工程师用HDevelop调参软件工程师用Python做业务分工清晰。5.5 相机和硬件接口验证如果后续要接工业相机安装完之后要确认Halcon的采集接口是否正确加载。GigE相机可以用info_framegrabber算子检查接口import halcon as ha interfaces ha.info_framegrabber(GigEVision, info_boards, 0, []) print(interfaces)如果列表为空说明GigE接口没有正常加载可能是网络时间同步(PTP)没配置好也可能是libgomp1缺失导致采集插件加载失败。这一步在纯软件环境验证时可以先跳过到硬件调试阶段再处理。6. 长期维护视角卸载、升级与团队分发最后聊几个装了之后迟早用得上的操作怎么干净卸载、怎么升级、怎么把装好的环境快速复制给团队其他人。6.1 卸载方式与Windows的差别Halcon没有提供Linux卸载脚本删掉安装目录就是卸载sudo rm -rf /opt/halcon然后清理环境变量文件sudo rm -f /etc/profile.d/halcon.sh sudo rm -f /usr/local/bin/hdevelop sudo rm -f /usr/local/bin/hdevelop_cl如果有自定义的软链接一并删掉。之所以先删除环境变量再删除目录是因为目录一旦消失残留的PATH里指向空路径虽然不影响系统但后续排查问题时会误以为环境还有配置旧版本。6.2 版本升级时的步骤Halcon不同大版本不建议共存特别是21.05和之前版本的license机制有差异。我踩过一次坑系统里残留了20.11的环境变量新装了21.05之后启动时加载的库还是旧的报了一堆函数签名不匹配的错误。升级推荐三步走。第一步备份license文件和自己的脚本、算子库cp -r /opt/halcon/license ~/halcon_license_backup/第二步卸载旧版本执行上面6.1的清理步骤第三步安装新版本重新配置环境变量导入license。6.3 团队快速复制部署如果要在多台机器上部署同样的Halcon没必要每一台都从网上下载安装包慢慢装。我实际操作中是这样做的在一台标准机器上装好Halcon并验证通过后把整个/opt/halcon目录打包cd /opt sudo tar -zcf halcon21.05-custom.tar.gz halcon/同时把license.dat单独打包和环境变量脚本一起组成三个文件安装包、license文件、env脚本。新机器上解压、放license、source环境变量三步完成。如果需要频繁重建环境可以打个Docker镜像基础镜像用ubuntu:18.04把Halcon目录和环境变量通过Dockerfile固化进去注意license文件要放到镜像指定路径。这种方式对跑批量处理任务特别好用一条命令拉起一个带Halcon的容器。6.4 license管理的个人习惯我自己养成的两个习惯分享给大家一是在Git仓库里单独建一个config/halcon目录保存license和env脚本公司内部用私有仓库管理避免文件丢失后还要重新向MVTec申请二是定期检查license有效期在申请后就在日历里设置到期提醒免得项目上线当天发现授权过期手忙脚乱。还有个小技巧在环境变量里增加HALCONIMAGES指向项目图片目录起一个示例图片的快捷变量HDevelop里很多算子读写图像时会优先识别这个变量省得每次拼绝对路径。实际用下来确实能少敲不少命令特别是调试算法频繁读图的时候。