📋 本篇内容概览
1️⃣ 安装前的环境准备2️⃣Python 包安装（两种方式）3️⃣DLL 配置（Windows 必做）4️⃣基础用法：读图与显示5️⃣语法差异：变量在左边6️⃣与 OpenCV 互转7️⃣实战：边缘检测8️⃣HalconXL：处理超大图像9️⃣从 HDevelop 导出 Python 代码🔟 常见问题 FAQ
机器视觉领域，Halcon 的地位不用多说。但很多人不知道的是，Halcon 早就支持 Python 了，而且不是那种"调调接口意思意思"的支持，是真正的原生 Python 接口。
聊聊怎么在 Python 里用 Halcon，包括一个很多人不知道的骚操作——用 HalconXL 处理超大图像。
1️⃣ 安装前的准备
环境要求：
- Python >= 3.8
- HALCON >= 20.11
- 64 位操作系统
先装 Halcon 本体。从 MVTec 官网下载安装 HALCON 软件。装完之后，命令行里能跑 hdevelop 就算成功。
2️⃣ Python 包安装
两种方式，选一种就行。
方式一：官方包
pip install mvtec-halcon==你的版本号
# 比如你装的是 HALCON 24.11，版本号就是 24110
pip install mvtec-halcon==24110
方式二：社区封装
💡 说明：这个包封装得更 Pythonic，用起来舒服一些。
3️⃣ DLL 配置（Windows 必做）
⚠️ 很多人踩坑
装完 Python 包还不够，还得把 Halcon 的 DLL 文件拷到 Python 环境里。
找到你的 Halcon 安装目录，一般是：
C:\Program Files\MVTec\HALCON-XX.XX-Progress\bin\x64-win64
把里面这些 DLL 拷贝到你 Python 虚拟环境的 python.exe 所在目录：
halcon.dllhalconcpp.dllhconcsharp.dllhalconxl.dll
嫌手动拷麻烦？直接把 Halcon 的 bin 目录加到系统 PATH里也行。
4️⃣ 基础用法
装好了，试试看：
import halcon as ha
# 读图
image = ha.read_image('test.jpg')
# 开窗口显示
window_id = ha.open_window(0, 0, 512, 512, father_window=0, mode='visible', machine='')
ha.disp_obj(image, window_id)
ha.wait_seconds(3) # 等 3 秒，不然窗口一闪而过
💡 说明：注意那个 wait_seconds，在 VSCode 里跑的时候，没这行窗口会直接消失。
5️⃣ 语法差异：变量在左边
这是 Halcon Python 接口最容易踩的坑。
在 HDevelop 里写：
get_image_size(Image, Width, Height)
在 Python 里得改成：
Width, Height = ha.get_image_size(image)
💡 核心规则：输出变量放左边，输入变量放右边。记住这个规则，基本就不会出错。
6️⃣ 与 OpenCV 互转
实际项目里经常需要在 Halcon 和 OpenCV 之间切换，官方提供了互转接口。
Halcon 转 OpenCV（numpy 数组）
import halcon as ha
import cv2
from halcon.numpy_interop import himage_as_numpy_array
image = ha.read_image('test.jpg')
numpy_img = himage_as_numpy_array(image)
# Halcon 默认 RGB，OpenCV 默认 BGR，记得转
opencv_img = cv2.cvtColor(numpy_img, cv2.COLOR_RGB2BGR)
OpenCV 转 Halcon
import cv2
from halcon.numpy_interop import himage_from_numpy_array
opencv_img = cv2.imread('test.jpg')
halcon_img = himage_from_numpy_array(opencv_img)
💡 注意：Halcon 默认 RGB，OpenCV 默认 BGR，互转时记得做通道顺序转换。
7️⃣ 实战：边缘检测
来个完整的例子，用 Halcon 做 Canny 边缘检测：
import halcon as ha
import cv2
from halcon.numpy_interop import himage_as_numpy_array
# 读图
image = ha.read_image('test.jpg')
# 转灰度
gray = ha.rgb1_to_gray(image)
# Canny 边缘检测
edges = ha.edges_image(gray, 'canny', 1, 20, 40)
# 显示结果
window_id = ha.open_window(0, 0, 512, 512, father_window=0, mode='visible', machine='')
ha.disp_obj(edges, window_id)
ha.wait_seconds(5)
8️⃣ HalconXL：处理超大图像
🔥 重头戏
普通 Halcon 处理图像有尺寸限制，遇到卫星遥感图、大幅面工业检测图这种超大图像就力不从心。HalconXL 就是为这种场景设计的，它能处理的图像尺寸理论上没有上限。
怎么在 Python 里启用 HalconXL？
一行代码搞定：
import os
os.environ['HALCON_PYTHON_XL'] = 'true'
import halcon as ha
⚠️ 顺序很重要：必须在 import halcon之前设置这个环境变量，顺序反了就白搭。
也可以在系统环境变量里永久设置，但代码里写更灵活——你可以在需要 XL 的脚本里开，不需要的就用普通版。
完整示例：读取并处理超大图像
import os
os.environ['HALCON_PYTHON_XL'] = 'true'
import halcon as ha
# 读取一张超大的卫星图像
image = ha.read_image('huge_satellite_image.tif')
# 获取图像尺寸（XL 版本可以返回超大尺寸）
width, height = ha.get_image_size(image)
print(f'图像尺寸: {width} x {height}')
# 正常做图像处理，和普通版 API 完全一样
gray = ha.rgb1_to_gray(image)
edges = ha.edges_image(gray, 'canny', 1, 30, 60)
# 保存结果
ha.write_image(edges, 'tiff', 0, 'result.tif')
什么时候该用 XL？
9️⃣ 从 HDevelop 导出 Python 代码
如果你习惯在 HDevelop 里调算法，调好之后直接导出成 Python 就行：
① HDevelop 菜单栏 File → Export → Export Program② 语言选 Python③ 选个保存路径，搞定
导出的代码可以直接跑，省去手动翻译的麻烦。
🔟 常见问题
Q：import halcon 报错 DLL not found？
A：DLL 没拷对位置，或者版本不匹配。检查 Halcon 版本和 pip 安装的版本号是否一致。
Q：窗口显示一闪而过？
A：加 ha.wait_seconds() 或者用 ha.read_char()等待用户输入。
Q：HalconXL 和普通 Halcon 的 API 有区别吗？
A：没有。设置环境变量后，所有函数调用方式完全一样，只是内部处理能力变强了。
Q：HalconXL 需要额外的 License 吗？
A：需要。XL 版本的 License 和普通版是分开的，确保你有 XL 的授权。
📝 本篇小结
✅ Halcon Python 接口比很多人想象的成熟✅ DLL 配置是 Windows 上的必经之路✅变量在左边——记住这条规则就不会踩坑✅ HalconXL 处理超大图像，一行环境变量搞定✅ HDevelop 可直接导出 Python 代码
10个月宝宝每天需要喝多少奶粉？
