用全流程解析)
開頭做機(jī)器視覺項(xiàng)目的人手里總有幾個(gè)壓箱底的工具?？的鸵?VisionPro 9.0 的 QuickBuild 是我日常搭檢測流程最快的方式而 Halcon 23.11 又是很多復(fù)雜視覺算法繞不開的后手。如果這兩個(gè)東西能在同一個(gè)項(xiàng)目里配合起來那就意味著我們不用為了跑一個(gè) Halcon 模型專門去寫一套獨(dú)立上位機(jī)也不用在兩個(gè)軟件之間來回倒圖像。這其實(shí)不是個(gè)特別小眾的需求。實(shí)際產(chǎn)線上經(jīng)常出現(xiàn)這種組合界面、流程、通訊、日志全在 VisionPro QuickBuild 里但某個(gè)環(huán)節(jié)的模板匹配、缺陷檢測或者深度學(xué)習(xí)判斷只能靠 Halcon 來做。能不能在 QuickBuild 的 C# 腳本里直接加載 Halcon 模型、執(zhí)行推理、再把結(jié)果拿回 VisionPro 的顯示層答案是可以而且配置鏈路沒有想象中復(fù)雜。這篇就按我實(shí)際調(diào)試通過的完整流程來寫適合有 VisionPro 基礎(chǔ)但沒怎么碰過 Halcon .NET 接口的人也適合被項(xiàng)目逼著做二次開發(fā)的上位機(jī)工程師。1. 為什么要繞這么一圈QuickBuild 里跑 Halcon 的動(dòng)機(jī)與方案選型1.1 實(shí)際項(xiàng)目里的剛需場景先說清楚什么時(shí)候需要這么干。VisionPro 自帶工具其實(shí)很成熟定位、缺陷檢測、OCR 都?jí)蛴玫?xiàng)目一旦碰到下面幾類情況單靠 QuickBuild 自帶的工具會(huì)很吃力第一算法已經(jīng)在 Halcon 里驗(yàn)證好了比如現(xiàn)場用了 Halcon 的 shape-based matching或者用了 Halcon 23.11 的深度學(xué)習(xí)推理模型重寫成 Cognex 工具配方不現(xiàn)實(shí)第二需要對比不同算法結(jié)果做二次判斷比如 VisionPro 負(fù)責(zé)整體流程Halcon 負(fù)責(zé)一個(gè)特定 ROI 的判斷兩邊結(jié)果要關(guān)聯(lián)起來第三客戶指定要用 Halcon 算法交付時(shí)得把整套驗(yàn)證邏輯原樣搬進(jìn)產(chǎn)線。這種情況如果硬拆成兩個(gè)獨(dú)立程序麻煩事就來了圖像采集、觸發(fā)、與 PLC 的握手、配方保存、結(jié)果記錄全都得做兩遍還要處理兩個(gè)進(jìn)程之間的數(shù)據(jù)同步。QuickBuild 本身已經(jīng)把采集、顯示、通訊這些活干好了我們只差一個(gè)能塞進(jìn)流程里的“Halcon 執(zhí)行器”。在 C# 腳本里調(diào)用 Halcon 模型正是把這個(gè)執(zhí)行器補(bǔ)上。1.2 兩條技術(shù)路線對比腳本調(diào)用 vs 獨(dú)立 C# 程序不少人第一反應(yīng)是寫一個(gè)獨(dú)立的 C# 上位機(jī)程序里面同時(shí)引用 VisionPro 類庫和 HalconDotNet然后自己搭流程顯示界面。這條路自由度最高但代價(jià)也最大你要重新實(shí)現(xiàn) QuickBuild 里的圖像顯示、工具條管理、配方存儲(chǔ)、界面表格還得處理各種線程刷新問題。除非客戶要求一個(gè)完全定制的 UI否則不建議這么干。另一條路就是這篇文章寫的繼續(xù)用 QuickBuild 做宿主只把 Halcon 模型調(diào)用封裝成一個(gè) C# 腳本步驟。QuickBuild 9.0 支持在 Job 里插入包含腳本的工具比如 CogToolBlock 里的 Script 步驟腳本可以引用外部 DLL相當(dāng)于在現(xiàn)有流程里開了一個(gè)“插件口”。這個(gè)方案最大的好處是工程輕量視覺流程、顯示和通訊全部復(fù)用 QuickBuild 的能力我們只需集中處理算法橋接這一件事。1.3 我最終采用的方案結(jié)構(gòu)結(jié)合上面的對比我最終采用的是 CogToolBlock C# 腳本的結(jié)構(gòu)QuickBuild 負(fù)責(zé)采集和圖像輸入CogToolBlock 接收圖像腳本步驟負(fù)責(zé)把 VisionPro 圖像轉(zhuǎn)成 Halcon HImage調(diào)用 Halcon 模型再把結(jié)果寫入 ToolBlock 輸出。如果后續(xù)要在多個(gè)工位復(fù)用只需要復(fù)制這個(gè) CogToolBlock替換模型路徑和參數(shù)就行不需要改上層任何邏輯。這里也要提一個(gè)選擇細(xì)節(jié)Halcon 模型的調(diào)用方式有兩種一種是直接在 C# 腳本里操作算子另一種是用 HDevEngine 加載 HDevelop 寫好的 .hdvp 流程。前者適合純模板匹配這種單算子場景后者適合算法流程復(fù)雜、中間有多個(gè)預(yù)處理步驟的場景。這篇主要演示直接調(diào)用算子因?yàn)槔斫馄饋碜钪庇^后面也會(huì)提到 HDevEngine 的寫法。2. 前置環(huán)境準(zhǔn)備與版本匹配容易踩坑的一步2.1 軟件版本清單我這次用的組合是 VisionPro 9.0、Halcon 23.11、Visual Studio 2019 開發(fā)環(huán)境。Halcon 23.11 是 MVTec 在 2023 年發(fā)布的版本API 上和 22、23 的早期版本差別不大但要注意它默認(rèn)的 .NET 接口對應(yīng)的 Framework 版本比舊版更高。VisionPro 9.0 的腳本宿主是 .NET Framework所以引用 HalconDotNet.dll 時(shí)要確認(rèn)版本兼容別拿一個(gè) .NET Core 版本的 DLL 去引用。操作系統(tǒng)方面Windows 10/11 64 位系統(tǒng)為主。如果現(xiàn)場工控機(jī)是 32 位系統(tǒng)那后面所有路徑都要換成 x86 版本的 Halcon 運(yùn)行庫這個(gè)我在第 5 部分會(huì)重點(diǎn)強(qiáng)調(diào)。2.2 Halcon 23.11 安裝與 License 說明Halcon 23.11 安裝時(shí)默認(rèn)會(huì)裝到C:\Program Files\MVTec\HALCON-23.11安裝包里有幾個(gè)關(guān)鍵目錄根目錄下的bin\x64-win64放的是原生 C DLL比如halcon.dll、hdevengine.dllbin\dotnet里放著 .NET 接口的HalconDotNet.dll和hdevengine.dll。如果你的項(xiàng)目要引用優(yōu)先從bin\dotnet目錄里找不要從別的版本文件夾里隨便拿一個(gè)出來。License 這塊別忽略。Halcon 23.11 安裝后需要有效的許可證開發(fā)階段常見的是軟件許可證SLM 或試用 License運(yùn)行階段在工控機(jī)上需要配置好 License 文件。許可證的問題通常會(huì)延遲到模型加載時(shí)才暴露也就是代碼能編譯、程序能啟動(dòng)但一執(zhí)行ReadShapeModel就報(bào) License 錯(cuò)誤。所以我建議在環(huán)境準(zhǔn)備階段先單獨(dú)建一個(gè)控制臺(tái)程序只執(zhí)行一句HOperatorSet.GetSystem(runtime )確認(rèn) Halcon 環(huán)境沒問題后再進(jìn) QuickBuild。2.3 VisionPro 9.0 QuickBuild 與 C# 的關(guān)聯(lián)VisionPro 9.0 的 QuickBuild 界面里直接創(chuàng)建 Job 后工具流中的 CogToolBlock 自帶腳本編輯器。腳本使用的是 C# 語言編輯器左側(cè)能看到項(xiàng)目引用的 DLL右側(cè)有一個(gè)文本編輯區(qū)。很多人第一次找這個(gè)入口會(huì)愣一下不是在工具屬性里寫腳本而是右鍵 CogToolBlock 或在工具內(nèi)部標(biāo)簽頁里找到“Scripts”標(biāo)簽頁進(jìn)入腳本編輯面板。另外一個(gè)容易忽略的點(diǎn)是QuickBuild 腳本里可以使用 Cognex.VisionPro 命名空間也能 using 你自己引入的第三方命名空間但前提是第三方 DLL 被正確添加到了腳本項(xiàng)目的 References 里。這和其他 C# 項(xiàng)目完全一致只是入口從 vs. sln 變成了 QuickBuild 的腳本管理界面。2.4 需要注意的 .NET 版本與 x64/x86實(shí)際經(jīng)驗(yàn)告訴我版本和位數(shù)的問題優(yōu)先于代碼問題。Halcon 23.11 的 .NET 接口要求 .NET Framework 4.6.1 以上VisionPro 9.0 默認(rèn)的腳本宿主通常是 .NET Framework 4.7.2 或 4.8一般滿足要求。位數(shù)方面QuickBuild 9.0 默認(rèn)以 64 位進(jìn)程運(yùn)行那 Halcon 就要選擇x64-win64的原生 DLL同時(shí) HalconDotNet.dll 也要和運(yùn)行庫一致。有一個(gè)很隱蔽的坑是 PATH 環(huán)境變量。如果你電腦上裝了多個(gè) Halcon 版本或者把 Halcon 運(yùn)行庫拷到了別的目錄QuickBuild 腳本找到的halcon.dll可能是舊版運(yùn)行時(shí)會(huì)報(bào)版本沖突。我目前的處理方式是在腳本啟動(dòng)時(shí)把目標(biāo) Halcon 的bin\x64-win64目錄插入到 PATH 的最前面確保加載的是 23.11。3. 保姆級(jí)配置流程從 Halcon 模型導(dǎo)出到 QuickBuild 落地3.1 在 Halcon 中生成模板匹配模型并導(dǎo)出第一步是在 HDevelop 里把模型做好。以最常用的形狀模板匹配為例流程是讀取一張標(biāo)準(zhǔn)圖用create_shape_model創(chuàng)建模型然后用write_shape_model把模型保存為.shm文件。要注意保存路徑里不要帶中文不要帶空格否則后續(xù) C# 腳本加載時(shí)容易出一些莫名其妙的問題。# 在 HDevelop 窗口執(zhí)行的 Halcon 代碼 gen_empty_obj (ModelImages) read_image (Image, 標(biāo)準(zhǔn)圖路徑) reduce_domain (Image, ROI, ImageReduced) create_shape_model (ImageReduced, auto, 0, 360, auto, auto, use_polarity, auto, auto, ModelID) write_shape_model (ModelID, C:/halcon_models/connector_model.shm)導(dǎo)出之后最好再用find_shape_model在這張?jiān)瓐D上跑一遍確認(rèn)最小分?jǐn)?shù)、金字塔層數(shù)這些參數(shù)是合適的。模型文件本身不大但它是后續(xù)所有調(diào)用步驟里的核心輸入所以我會(huì)把它和 Halcon 腳本放在同一個(gè)固定目錄工控機(jī)上不改動(dòng)。3.2 在 Visual Studio 里先驗(yàn)證 HalconDotNet 引用進(jìn) QuickBuild 之前我強(qiáng)烈建議先用 Visual Studio 建一個(gè)控制臺(tái)工程把 Halcon .NET 調(diào)用跑通。新建工程時(shí)選擇 .NET Framework 4.7.2 或 4.8項(xiàng)目平臺(tái)選擇 x64。右鍵引用選擇瀏覽找到C:\Program Files\MVTec\HALCON-23.11\bin\dotnet\HalconDotNet.dll并添加。然后在Main方法里寫一個(gè)最小測試加載剛才導(dǎo)出的.shm模型讀取一張測試圖調(diào)用FindShapeModel輸出匹配到的行和列坐標(biāo)。這一步主要是驗(yàn)證三件事Halcon 運(yùn)行庫能否加載、License 是否正常、模型文件是否能被讀取。這三件事如果在 Visual Studio 里能全過后面的 QuickBuild 配置就只是搬運(yùn)工作。using HalconDotNet; class Program { static void Main() { HImage image new HImage(C:\halcon_models\test.png); HShapeModel model new HShapeModel(); model.ReadShapeModel(C:\halcon_models\connector_model.shm); HTuple row, col, angle, score; model.FindShapeModel(image, 0, 360, 0.7, 1, 0.5, least_squares, 5, 0.9, out row, out col, out angle, out score); Console.WriteLine($row{row[0].D}, col{col[0].D}, score{score[0].D}); } }3.3 在 QuickBuild 中添加 C# 腳本工具回到 QuickBuild在 Job 的工具流里添加一個(gè) CogToolBlock。打開 CogToolBlock 的配置界面左側(cè)工具列表里如果有已存在的工具通常會(huì)用灰色圖標(biāo)列出右側(cè)是輸入輸出定義。這次我們要做的是新增一個(gè)腳本類型子工具在 CogToolBlock 的腳本標(biāo)簽頁里添加一個(gè)步驟并編寫 C# 代碼。添加腳本后需要給這個(gè)腳本步驟增加兩個(gè)輸入輸出輸入就是上游傳下來的圖像我命名為InputImage輸出就是后面要用于判斷的OutRow、OutCol、OutScore。這些變量名在代碼里都會(huì)用到。注意 QuickBuild 的腳本編輯器有自己的“Terminals”概念需要在界面內(nèi)把輸入輸出變量綁定到 CogToolBlock 的 Inputs 和 Outputs 上否則代碼里訪問不到。3.4 圖像轉(zhuǎn)換CogImage8Grey 轉(zhuǎn) HImage這是最容易出錯(cuò)的一步。VisionPro 的CogImage8Grey和 Halcon 的HImage是兩種完全不同的圖像對象不能直接賦值。最簡單的轉(zhuǎn)換方法是借助 Bitmap。在 QuickBuild 腳本里我們可以從 ToolBlock 的輸入終端拿到CogImage8Grey轉(zhuǎn)換成Bitmap再用 Halcon 的HImage構(gòu)造函數(shù)包裝起來。using System.Drawing; using Cognex.VisionPro; using Cognex.VisionPro.ImageProcessing; using HalconDotNet; public HImage CogImage8GreyToHImage(CogImage8Grey cogImage) { Bitmap bmp cogImage.ToBitmap(); HImage hImage new HImage(bmp); bmp.Dispose(); return hImage; }這個(gè)寫法雖然簡單但要注意一個(gè)點(diǎn)ToBitmap()會(huì)把像素?cái)?shù)據(jù)完整復(fù)制一遍內(nèi)存開銷比直接傳指針大在 1280x1024 這樣的圖上還好如果相機(jī)是 500 萬、1200 萬像素每次復(fù)制都會(huì)帶來額外延遲。想追求性能就要用PixelData配合HImage.GenImage1來做后面第 4 部分我會(huì)給出替代寫法。3.5 在 C# 腳本中加載 Halcon 模型并推理圖像轉(zhuǎn)換完成后剩下的就是調(diào)用 Halcon 模型。如果是形狀模板匹配代碼就三行讀模型、找匹配、取結(jié)果。關(guān)鍵點(diǎn)是要把HShapeModel對象放在腳本類成員里避免每次執(zhí)行都重新從磁盤讀模型。Halcon 讀模型這個(gè)動(dòng)作雖然不算特別慢但在產(chǎn)線節(jié)拍里能省就省。private HShapeModel _model; private bool _modelLoaded false; private void LoadModelIfNeeded() { if (_modelLoaded) return; _model new HShapeModel(); _model.ReadShapeModel(C:\halcon_models\connector_model.shm); _modelLoaded true; }推理時(shí)將前面轉(zhuǎn)出來的HImage傳給FindShapeModel拿到結(jié)果后立刻釋放HImage對象。Halcon .NET 對象底層包著原生資源不釋放會(huì)撐高內(nèi)存特別是連續(xù)運(yùn)行幾百張圖之后內(nèi)存上漲會(huì)非常明顯。3.6 結(jié)果寫回 QuickBuild 輸出Halcon 的FindShapeModel返回的是HTuple需要轉(zhuǎn)成普通類型再寫回 QuickBuild 輸出。這里有個(gè)經(jīng)驗(yàn)不要直接把HTuple對象塞給 OutputsQuickBuild 界面顯示和配方保存都不認(rèn)識(shí)這個(gè)類型。正確做法是把元素取出來轉(zhuǎn)成 double 或 int再賦給 ToolBlock 的輸出終端。mToolBlock.Outputs[OutRow].Value Convert.ToDouble(row[0].D); mToolBlock.Outputs[OutCol].Value Convert.ToDouble(col[0].D); mToolBlock.Outputs[OutScore].Value Convert.ToDouble(score[0].D);這樣 QuickBuild 后續(xù)工具就能通過標(biāo)簽、顯示面板或者通訊寫入功能讀取這三個(gè)值整個(gè)過程和調(diào)用 VisionPro 自帶的工具沒有任何區(qū)別。4. 核心環(huán)節(jié)實(shí)現(xiàn)一個(gè)可直接復(fù)制的 C# 腳本樣例4.1 腳本類的主框架QuickBuild 的腳本工具不像普通 C# 類那樣有Main函數(shù)它更接近一個(gè)事件驅(qū)動(dòng)對象。核心方法一般叫RunTool或者ScriptTool具體名字取決于你在 CogToolBlock 里添加的腳本模板。為了方便說明我用通用結(jié)構(gòu)來寫核心思路是獲取輸入轉(zhuǎn)圖像加載模型推理寫輸出。using System; using System.Drawing; using Cognex.VisionPro; using Cognex.VisionPro.ImageProcessing; using HalconDotNet; public class ScriptClass { private HShapeModel _shapeModel; private bool _isModelLoaded; public void Run() { CogImage8Grey inputImage mToolBlock.Inputs[InputImage].Value as CogImage8Grey; if (inputImage null) { throw new Exception(輸入圖像為空或不是8位灰度圖); } HImage halconImage ConvertCogImageToHImage(inputImage); try { LoadModelIfNeeded(); HTuple row, col, angle, score; _shapeModel.FindShapeModel(halconImage, 0, 360, 0.7, 1, 0.5, least_squares, 5, 0.9, out row, out col, out angle, out score); if (score.Length 0) { mToolBlock.Outputs[OutRow].Value row[0].D; mToolBlock.Outputs[OutCol].Value col[0].D; mToolBlock.Outputs[OutAngle].Value angle[0].D; mToolBlock.Outputs[OutScore].Value score[0].D; } else { mToolBlock.Outputs[OutRow].Value -1.0; mToolBlock.Outputs[OutCol].Value -1.0; mToolBlock.Outputs[OutAngle].Value 0.0; mToolBlock.Outputs[OutScore].Value 0.0; } } finally { halconImage.Dispose(); } } private HImage ConvertCogImageToHImage(CogImage8Grey cogImage) { Bitmap bmp cogImage.ToBitmap(); HImage hImage new HImage(bmp); bmp.Dispose(); return hImage; } private void LoadModelIfNeeded() { if (_isModelLoaded) return; _shapeModel new HShapeModel(); _shapeModel.ReadShapeModel(C:\halcon_models\connector_model.shm); _isModelLoaded true; } }4.2 高性能圖像轉(zhuǎn)換的替代寫法如果你對性能有要求比如想讓每次檢測控制在十幾毫秒內(nèi)那盡量別走 Bitmap。Halcon 的HImage提供了直接從指針生成圖像的方式VisionPro 的CogImage8Grey內(nèi)部能取到像素?cái)?shù)據(jù)。這里需要注意的是VisionPro 圖像的像素?cái)?shù)據(jù)默認(rèn)在托管數(shù)組或者非托管內(nèi)存里我們需要保證在 Halcon 使用期間這塊內(nèi)存有效。private HImage ConvertCogImageToHImageFast(CogImage8Grey cogImage) { int width cogImage.Width; int height cogImage.Height; // 這里只是示意不同版本的VisionPro獲取像素?cái)?shù)組的方式略有差異 // 有的版本是PixelData屬性有的是GetPixelData方法按你本地的API來。 byte[] pixels cogImage.PixelData as byte[]; HImage hImage new HImage(); unsafe { fixed (byte* p pixels) { hImage.GenImage1(byte, width, height, (IntPtr)p); } } return hImage; }GenImage1的執(zhí)行效率和內(nèi)存占用比 Bitmap 中轉(zhuǎn)好很多但要注意兩個(gè)前提第一cogImage必須是連續(xù)的 8 位灰度數(shù)據(jù)不是 24 位彩色第二Halcon 的圖像坐標(biāo)原點(diǎn)在左上角VisionPro 的原點(diǎn)也在左上角這塊通常不用額外翻轉(zhuǎn)但如果你做了畸變校正或旋正要自己保證坐標(biāo)映射關(guān)系一致。4.3 把預(yù)處理和 AI 模型封裝成 HDevProcedure 的用法如果模型本身不是模板匹配而是一套完整的 Halcon 流程比如先灰度變換、再閾值分割、再跑深度學(xué)習(xí)分類直接在 C# 里逐行調(diào)用算子里很冗余。這時(shí)候可以把這個(gè)流程保存成 HDevelop 的.hdvp文件用HDevEngine來加載執(zhí)行。這種方式相當(dāng)于把 Halcon 內(nèi)部腳本當(dāng)成黑盒我只負(fù)責(zé)傳入圖像、傳出結(jié)果。private HDevEngine _engine; private HDevProcedure _procedure; private void InitHDevEngine() { _engine new HDevEngine(); _engine.SetProcedurePath(C:\halcon_models); _procedure new HDevProcedure(classify_defect.hdvp); } private void RunWithHDevEngine(HImage halconImage) { HDevProcedureCall call _procedure.CreateCall(); call.SetInputIconicParamObject(InputImage, halconImage); call.SetInputCtrlParamTuple(MinScore, 0.85); call.Execute(); HObject defectRegion call.GetOutputIconicParamObject(DefectRegion); HTuple isOk call.GetOutputCtrlParamTuple(IsOK); // 把結(jié)果轉(zhuǎn)成普通類型寫回QuickBuild輸出 }采用 HDevEngine 的好處是算法同事可以獨(dú)立維護(hù) HDevelop 腳本我們不直接改 C#減少溝通成本。壞處是每次執(zhí)行要經(jīng)過腳本解釋層性能比直接調(diào)用算子略微低一點(diǎn)。對于幀率要求不高的質(zhì)量檢測場景完全夠用。4.4 部署到現(xiàn)場時(shí)的文件整理在開發(fā)機(jī)上跑通還不算完工控機(jī)上部署是另一個(gè)坎。需要帶過去的文件包括Halcon 23.11 運(yùn)行庫至少包含bin\x64-win64下的 DLL 和 LicenseHalconDotNet.dll和運(yùn)行庫版本匹配的模型文件以及 QuickBuild 工程文件。最好把這些放到一個(gè)固定的目錄結(jié)構(gòu)里比如C:\VisionProjects\ConnectorInspect\ ├─ QuickBuild\ConnectorInspect.vpp ├─ Halcon\HALCON-23.11\ ... ├─ Halcon\HalconDotNet.dll └─ Models\connector_model.shm部署后務(wù)必先單獨(dú)運(yùn)行一個(gè) Halcon 自帶的驗(yàn)證工具或小的控制臺(tái)程序確認(rèn) License 生效再打開 QuickBuild。如果先開 QuickBuild 再發(fā)現(xiàn) Halcon 報(bào)錯(cuò)排查時(shí)會(huì)被 QuickBuild 的錯(cuò)誤彈窗干擾。5. 常見問題與排查技巧實(shí)錄5.1DllNotFoundException: halcon.dll這是出現(xiàn)頻率最高的問題原因基本都是 Path 環(huán)境變量里沒有 Halcon 的原生運(yùn)行庫目錄。HalconDotNet.dll 只是托管包裝層它內(nèi)部會(huì)通過 P/Invoke 加載halcon.dll。解決辦法是在系統(tǒng)環(huán)境變量 PATH 中加入C:\Program Files\MVTec\HALCON-23.11\bin\x64-win64同時(shí)確認(rèn)沒有其他 Halcon 版本的目錄排在前面。如果不想改系統(tǒng)環(huán)境變量也可以在 QuickBuild 腳本里動(dòng)態(tài)設(shè)置。在腳本類里加一個(gè)靜態(tài)構(gòu)造函數(shù)或初始化方法執(zhí)行Environment.SetEnvironmentVariable(PATH, halconBinDir ; Environment.GetEnvironmentVariable(PATH))。這個(gè)操作要在第一次調(diào)用 Halcon 算子之前完成否則 DLL 已經(jīng)被加載改了也無效。5.2 License 錯(cuò)誤模型加載階段報(bào) License error模型加載時(shí)報(bào)的 License 錯(cuò)誤代碼上沒有任何問題純粹是授權(quán)環(huán)境不對。Halcon 23.11 在安裝時(shí)會(huì)默認(rèn)申請?jiān)囉?License試用過期后必須重新導(dǎo)入有效 License。需要注意的是如果 QuickBuild 運(yùn)行的 Windows 服務(wù)和登錄用戶不同License 服務(wù)可能對另一個(gè)用戶不可見。這時(shí)可以試試在安裝目錄下執(zhí)行l(wèi)icense_manager或者直接重新運(yùn)行 License 導(dǎo)入向?qū)Т_認(rèn)當(dāng)前運(yùn)行用戶能看到有效授權(quán)。5.3 圖像內(nèi)容正常但匹配結(jié)果異常偏左/偏移這不是調(diào)用問題通常是圖像坐標(biāo)映射不一致。VisionPro 中圖像可能帶有一像素偏移的“原點(diǎn)設(shè)置”或者做過了校準(zhǔn)而 Halcon 默認(rèn)認(rèn)為圖像左上角為 (0,0)。解決方法是統(tǒng)一以像素坐標(biāo)為基準(zhǔn)先只在像素坐標(biāo)系下驗(yàn)證不要一上來就疊加機(jī)器人坐標(biāo)或 Calibration 坐標(biāo)。QuickBuild 里如果開了 Calibration要記得把輸出結(jié)果再經(jīng)過一次坐標(biāo)轉(zhuǎn)換而不是拿 Halcon 的像素結(jié)果直接當(dāng)世界坐標(biāo)用。5.4 圖像轉(zhuǎn) HImage 后顯示全黑或花屏全黑或花屏大概率是圖像通道不匹配。CogImage24彩色圖如果按 8 位灰度方式取數(shù)據(jù)會(huì)錯(cuò)亂。確認(rèn)交給 Halcon 的HImage類型和圖像復(fù)雜度一致灰度圖用byte彩色圖用rgb。如果用的是CogImage8Grey不會(huì)有這個(gè)問題但如果上游源圖像是CogImage24RGB就要先轉(zhuǎn)成灰度或者用HImage(bitmap)讓構(gòu)造函數(shù)自己去判斷通道。5.5 32 位與 64 位不匹配QuickBuild 9.0 默認(rèn)是 64 位進(jìn)程但如果你在 QuickBuild 的啟動(dòng)快捷方式上強(qiáng)制了 32 位兼容或者工控機(jī)上裝了 32 位 VisionPro那 Halcon 也要使用同位的運(yùn)行庫?？焖倥袛喈?dāng)前進(jìn)程位數(shù)可以在腳本里加一句話bool is64 Environment.Is64BitProcess;然后在消息或日志里輸出。如果 Halcon 用的是 x64 DLL 而進(jìn)程是 x86加載時(shí)會(huì)立刻報(bào) BadImageFormatException這個(gè)異常幾乎可以直接用來反向定位。6. 性能與穩(wěn)定性優(yōu)化建議6.1 模型只加載一次不要每次執(zhí)行都 Read這是最容易提升性能的一點(diǎn)。QuickBuild 腳本工具如果每次觸發(fā)都執(zhí)行ReadShapeModel一個(gè) 30W 像素的圖像匹配流程可能從 30ms 被拖到 90ms。把模型對象保存在腳本類成員變量里用標(biāo)志位控制只加載一次后續(xù)每次執(zhí)行只做FindShapeModel收益非?？捎^。對多模型切換的場景可以用Dictionarystring, HShapeModel緩存按配方名稱索引。6.2 圖像轉(zhuǎn)換用指針模式但要處理內(nèi)存生命周期圖像轉(zhuǎn)換方面建議根據(jù)項(xiàng)目需求選擇開發(fā)階段用 Bitmap 轉(zhuǎn)換簡單可靠正式跑節(jié)拍時(shí)換成GenImage1指針模式。指針模式的關(guān)鍵是GenImage1創(chuàng)建的 HImage 不會(huì)自動(dòng)管理原始字節(jié)數(shù)組的內(nèi)存如果原始像素?cái)?shù)據(jù)是局部變量方法返回后內(nèi)存可能已經(jīng)被回收但 Halcon 內(nèi)部還在用。所以要么確保cogImage的存活時(shí)間覆蓋FindShapeModel執(zhí)行完畢要么在GenImage1前把像素?cái)?shù)組拷到獨(dú)立緩沖區(qū)。IntPtr ptr System.Runtime.InteropServices.Marshal.AllocHGlobal(width * height); System.Runtime.InteropServices.Marshal.Copy(pixels, 0, ptr, width * height); HImage hImage new HImage(); hImage.GenImage1(byte, width, height, ptr); // 用完后手動(dòng)釋放 System.Runtime.InteropServices.Marshal.FreeHGlobal(ptr);6.3 多線程并行要注意 Halcon Cloud/HDVL 的限制如果一臺(tái)工控機(jī)要檢測多個(gè)產(chǎn)品同一時(shí)刻可能開多個(gè) QuickBuild Job每個(gè) Job 里都有 Halcon 模型調(diào)用。Halcon 運(yùn)行庫在單進(jìn)程內(nèi)通常能并行處理但如果 License 規(guī)格限制了并行實(shí)例數(shù)多個(gè)線程同時(shí)調(diào)用會(huì)互相等待甚至報(bào)錯(cuò)。遇到這種情況建議把模型推理放到一個(gè)獨(dú)立的串行隊(duì)列里只在拿到結(jié)果后再更新 UI。不要貿(mào)然用多線程去壓榨速度后續(xù)排查許可證并發(fā)問題非常痛苦。6.4 日志與圖像保存的配合項(xiàng)目調(diào)試期我會(huì)在 QuickBuild 腳本里加一個(gè)開關(guān)控制是否保存中間結(jié)果圖。具體做法是在Run()方法里用計(jì)時(shí)器記錄耗時(shí)同時(shí)把 Halcon 匹配分?jǐn)?shù)低于某個(gè)閾值的圖保存到指定目錄。這些圖對后續(xù)分析模型參數(shù)、調(diào)整最小分?jǐn)?shù)非常有幫助。但正式產(chǎn)線版本記得把這個(gè)開關(guān)關(guān)掉否則高頻保存圖片會(huì)嚴(yán)重?fù)p耗硬盤壽命。7. 一些實(shí)際操作后的體會(huì)我實(shí)際踩過幾次坑之后最大的體會(huì)是這個(gè)配置工作真正的難點(diǎn)不在 C# 代碼怎么寫而在環(huán)境一致性。只要 Halcon 的版本、位數(shù)、License、PATH 這四個(gè)環(huán)境變量一樣錯(cuò)位后面寫再多代碼都是白搭。所以我的建議是嚴(yán)格按照順序來先在 Visual Studio 里用控制臺(tái)程序驗(yàn)證 Halcon 調(diào)用再進(jìn) QuickBuild 接腳本最后才部署到工控機(jī)。每一步驗(yàn)證通過再走下一步比一口氣寫完然后反復(fù)猜問題要節(jié)省太多時(shí)間。另外給大家一個(gè)實(shí)用的小技巧在 QuickBuild 腳本里寫結(jié)果輸出時(shí)可以順帶把 Halcon 的執(zhí)行耗時(shí)寫進(jìn) ToolBlock 的另一個(gè)輸出變量比如OutTimeMs。這樣在 QuickBuild 的顯示界面里就能實(shí)時(shí)看到算法耗時(shí)調(diào)起參來非常直觀。別小看這個(gè)細(xì)節(jié)項(xiàng)目驗(yàn)收的時(shí)候一個(gè)醒目的耗時(shí)指標(biāo)能省掉不少給客戶解釋算法的口水。如果你以后遇到類似需求先在 Halcon 里把模型跑通再照著這條鏈路接到 QuickBuild 里整個(gè)過程不會(huì)超過半天。祝各位在項(xiàng)目里少走彎路一次點(diǎn)亮。 VisionPro QuickBuild中集成Halcon模型：C#腳本調(diào)用全流程解析
開頭做機(jī)器視覺項(xiàng)目的人手里總有幾個(gè)壓箱底的工具?？的鸵?VisionPro 9.0 的 QuickBuild 是我日常搭檢測流程最快的方式而 Halcon 23.11 又是很多復(fù)雜視覺算法繞不開的后手。如果這兩個(gè)東西能在同一個(gè)項(xiàng)目里配合起來那就意味著我們不用為了跑一個(gè) Halcon 模型專門去寫一套獨(dú)立上位機(jī)也不用在兩個(gè)軟件之間來回倒圖像。這其實(shí)不是個(gè)特別小眾的需求。實(shí)際產(chǎn)線上經(jīng)常出現(xiàn)這種組合界面、流程、通訊、日志全在 VisionPro QuickBuild 里但某個(gè)環(huán)節(jié)的模板匹配、缺陷檢測或者深度學(xué)習(xí)判斷只能靠 Halcon 來做。能不能在 QuickBuild 的 C# 腳本里直接加載 Halcon 模型、執(zhí)行推理、再把結(jié)果拿回 VisionPro 的顯示層答案是可以而且配置鏈路沒有想象中復(fù)雜。這篇就按我實(shí)際調(diào)試通過的完整流程來寫適合有 VisionPro 基礎(chǔ)但沒怎么碰過 Halcon .NET 接口的人也適合被項(xiàng)目逼著做二次開發(fā)的上位機(jī)工程師。1. 為什么要繞這么一圈QuickBuild 里跑 Halcon 的動(dòng)機(jī)與方案選型1.1 實(shí)際項(xiàng)目里的剛需場景先說清楚什么時(shí)候需要這么干。VisionPro 自帶工具其實(shí)很成熟定位、缺陷檢測、OCR 都?jí)蛴玫?xiàng)目一旦碰到下面幾類情況單靠 QuickBuild 自帶的工具會(huì)很吃力第一算法已經(jīng)在 Halcon 里驗(yàn)證好了比如現(xiàn)場用了 Halcon 的 shape-based matching或者用了 Halcon 23.11 的深度學(xué)習(xí)推理模型重寫成 Cognex 工具配方不現(xiàn)實(shí)第二需要對比不同算法結(jié)果做二次判斷比如 VisionPro 負(fù)責(zé)整體流程Halcon 負(fù)責(zé)一個(gè)特定 ROI 的判斷兩邊結(jié)果要關(guān)聯(lián)起來第三客戶指定要用 Halcon 算法交付時(shí)得把整套驗(yàn)證邏輯原樣搬進(jìn)產(chǎn)線。這種情況如果硬拆成兩個(gè)獨(dú)立程序麻煩事就來了圖像采集、觸發(fā)、與 PLC 的握手、配方保存、結(jié)果記錄全都得做兩遍還要處理兩個(gè)進(jìn)程之間的數(shù)據(jù)同步。QuickBuild 本身已經(jīng)把采集、顯示、通訊這些活干好了我們只差一個(gè)能塞進(jìn)流程里的“Halcon 執(zhí)行器”。在 C# 腳本里調(diào)用 Halcon 模型正是把這個(gè)執(zhí)行器補(bǔ)上。1.2 兩條技術(shù)路線對比腳本調(diào)用 vs 獨(dú)立 C# 程序不少人第一反應(yīng)是寫一個(gè)獨(dú)立的 C# 上位機(jī)程序里面同時(shí)引用 VisionPro 類庫和 HalconDotNet然后自己搭流程顯示界面。這條路自由度最高但代價(jià)也最大你要重新實(shí)現(xiàn) QuickBuild 里的圖像顯示、工具條管理、配方存儲(chǔ)、界面表格還得處理各種線程刷新問題。除非客戶要求一個(gè)完全定制的 UI否則不建議這么干。另一條路就是這篇文章寫的繼續(xù)用 QuickBuild 做宿主只把 Halcon 模型調(diào)用封裝成一個(gè) C# 腳本步驟。QuickBuild 9.0 支持在 Job 里插入包含腳本的工具比如 CogToolBlock 里的 Script 步驟腳本可以引用外部 DLL相當(dāng)于在現(xiàn)有流程里開了一個(gè)“插件口”。這個(gè)方案最大的好處是工程輕量視覺流程、顯示和通訊全部復(fù)用 QuickBuild 的能力我們只需集中處理算法橋接這一件事。1.3 我最終采用的方案結(jié)構(gòu)結(jié)合上面的對比我最終采用的是 CogToolBlock C# 腳本的結(jié)構(gòu)QuickBuild 負(fù)責(zé)采集和圖像輸入CogToolBlock 接收圖像腳本步驟負(fù)責(zé)把 VisionPro 圖像轉(zhuǎn)成 Halcon HImage調(diào)用 Halcon 模型再把結(jié)果寫入 ToolBlock 輸出。如果后續(xù)要在多個(gè)工位復(fù)用只需要復(fù)制這個(gè) CogToolBlock替換模型路徑和參數(shù)就行不需要改上層任何邏輯。這里也要提一個(gè)選擇細(xì)節(jié)Halcon 模型的調(diào)用方式有兩種一種是直接在 C# 腳本里操作算子另一種是用 HDevEngine 加載 HDevelop 寫好的 .hdvp 流程。前者適合純模板匹配這種單算子場景后者適合算法流程復(fù)雜、中間有多個(gè)預(yù)處理步驟的場景。這篇主要演示直接調(diào)用算子因?yàn)槔斫馄饋碜钪庇^后面也會(huì)提到 HDevEngine 的寫法。2. 前置環(huán)境準(zhǔn)備與版本匹配容易踩坑的一步2.1 軟件版本清單我這次用的組合是 VisionPro 9.0、Halcon 23.11、Visual Studio 2019 開發(fā)環(huán)境。Halcon 23.11 是 MVTec 在 2023 年發(fā)布的版本API 上和 22、23 的早期版本差別不大但要注意它默認(rèn)的 .NET 接口對應(yīng)的 Framework 版本比舊版更高。VisionPro 9.0 的腳本宿主是 .NET Framework所以引用 HalconDotNet.dll 時(shí)要確認(rèn)版本兼容別拿一個(gè) .NET Core 版本的 DLL 去引用。操作系統(tǒng)方面Windows 10/11 64 位系統(tǒng)為主。如果現(xiàn)場工控機(jī)是 32 位系統(tǒng)那后面所有路徑都要換成 x86 版本的 Halcon 運(yùn)行庫這個(gè)我在第 5 部分會(huì)重點(diǎn)強(qiáng)調(diào)。2.2 Halcon 23.11 安裝與 License 說明Halcon 23.11 安裝時(shí)默認(rèn)會(huì)裝到C:\Program Files\MVTec\HALCON-23.11安裝包里有幾個(gè)關(guān)鍵目錄根目錄下的bin\x64-win64放的是原生 C DLL比如halcon.dll、hdevengine.dllbin\dotnet里放著 .NET 接口的HalconDotNet.dll和hdevengine.dll。如果你的項(xiàng)目要引用優(yōu)先從bin\dotnet目錄里找不要從別的版本文件夾里隨便拿一個(gè)出來。License 這塊別忽略。Halcon 23.11 安裝后需要有效的許可證開發(fā)階段常見的是軟件許可證SLM 或試用 License運(yùn)行階段在工控機(jī)上需要配置好 License 文件。許可證的問題通常會(huì)延遲到模型加載時(shí)才暴露也就是代碼能編譯、程序能啟動(dòng)但一執(zhí)行ReadShapeModel就報(bào) License 錯(cuò)誤。所以我建議在環(huán)境準(zhǔn)備階段先單獨(dú)建一個(gè)控制臺(tái)程序只執(zhí)行一句HOperatorSet.GetSystem(runtime )確認(rèn) Halcon 環(huán)境沒問題后再進(jìn) QuickBuild。2.3 VisionPro 9.0 QuickBuild 與 C# 的關(guān)聯(lián)VisionPro 9.0 的 QuickBuild 界面里直接創(chuàng)建 Job 后工具流中的 CogToolBlock 自帶腳本編輯器。腳本使用的是 C# 語言編輯器左側(cè)能看到項(xiàng)目引用的 DLL右側(cè)有一個(gè)文本編輯區(qū)。很多人第一次找這個(gè)入口會(huì)愣一下不是在工具屬性里寫腳本而是右鍵 CogToolBlock 或在工具內(nèi)部標(biāo)簽頁里找到“Scripts”標(biāo)簽頁進(jìn)入腳本編輯面板。另外一個(gè)容易忽略的點(diǎn)是QuickBuild 腳本里可以使用 Cognex.VisionPro 命名空間也能 using 你自己引入的第三方命名空間但前提是第三方 DLL 被正確添加到了腳本項(xiàng)目的 References 里。這和其他 C# 項(xiàng)目完全一致只是入口從 vs. sln 變成了 QuickBuild 的腳本管理界面。2.4 需要注意的 .NET 版本與 x64/x86實(shí)際經(jīng)驗(yàn)告訴我版本和位數(shù)的問題優(yōu)先于代碼問題。Halcon 23.11 的 .NET 接口要求 .NET Framework 4.6.1 以上VisionPro 9.0 默認(rèn)的腳本宿主通常是 .NET Framework 4.7.2 或 4.8一般滿足要求。位數(shù)方面QuickBuild 9.0 默認(rèn)以 64 位進(jìn)程運(yùn)行那 Halcon 就要選擇x64-win64的原生 DLL同時(shí) HalconDotNet.dll 也要和運(yùn)行庫一致。有一個(gè)很隱蔽的坑是 PATH 環(huán)境變量。如果你電腦上裝了多個(gè) Halcon 版本或者把 Halcon 運(yùn)行庫拷到了別的目錄QuickBuild 腳本找到的halcon.dll可能是舊版運(yùn)行時(shí)會(huì)報(bào)版本沖突。我目前的處理方式是在腳本啟動(dòng)時(shí)把目標(biāo) Halcon 的bin\x64-win64目錄插入到 PATH 的最前面確保加載的是 23.11。3. 保姆級(jí)配置流程從 Halcon 模型導(dǎo)出到 QuickBuild 落地3.1 在 Halcon 中生成模板匹配模型并導(dǎo)出第一步是在 HDevelop 里把模型做好。以最常用的形狀模板匹配為例流程是讀取一張標(biāo)準(zhǔn)圖用create_shape_model創(chuàng)建模型然后用write_shape_model把模型保存為.shm文件。要注意保存路徑里不要帶中文不要帶空格否則后續(xù) C# 腳本加載時(shí)容易出一些莫名其妙的問題。# 在 HDevelop 窗口執(zhí)行的 Halcon 代碼 gen_empty_obj (ModelImages) read_image (Image, 標(biāo)準(zhǔn)圖路徑) reduce_domain (Image, ROI, ImageReduced) create_shape_model (ImageReduced, auto, 0, 360, auto, auto, use_polarity, auto, auto, ModelID) write_shape_model (ModelID, C:/halcon_models/connector_model.shm)導(dǎo)出之后最好再用find_shape_model在這張?jiān)瓐D上跑一遍確認(rèn)最小分?jǐn)?shù)、金字塔層數(shù)這些參數(shù)是合適的。模型文件本身不大但它是后續(xù)所有調(diào)用步驟里的核心輸入所以我會(huì)把它和 Halcon 腳本放在同一個(gè)固定目錄工控機(jī)上不改動(dòng)。3.2 在 Visual Studio 里先驗(yàn)證 HalconDotNet 引用進(jìn) QuickBuild 之前我強(qiáng)烈建議先用 Visual Studio 建一個(gè)控制臺(tái)工程把 Halcon .NET 調(diào)用跑通。新建工程時(shí)選擇 .NET Framework 4.7.2 或 4.8項(xiàng)目平臺(tái)選擇 x64。右鍵引用選擇瀏覽找到C:\Program Files\MVTec\HALCON-23.11\bin\dotnet\HalconDotNet.dll并添加。然后在Main方法里寫一個(gè)最小測試加載剛才導(dǎo)出的.shm模型讀取一張測試圖調(diào)用FindShapeModel輸出匹配到的行和列坐標(biāo)。這一步主要是驗(yàn)證三件事Halcon 運(yùn)行庫能否加載、License 是否正常、模型文件是否能被讀取。這三件事如果在 Visual Studio 里能全過后面的 QuickBuild 配置就只是搬運(yùn)工作。using HalconDotNet; class Program { static void Main() { HImage image new HImage(C:\halcon_models\test.png); HShapeModel model new HShapeModel(); model.ReadShapeModel(C:\halcon_models\connector_model.shm); HTuple row, col, angle, score; model.FindShapeModel(image, 0, 360, 0.7, 1, 0.5, least_squares, 5, 0.9, out row, out col, out angle, out score); Console.WriteLine($row{row[0].D}, col{col[0].D}, score{score[0].D}); } }3.3 在 QuickBuild 中添加 C# 腳本工具回到 QuickBuild在 Job 的工具流里添加一個(gè) CogToolBlock。打開 CogToolBlock 的配置界面左側(cè)工具列表里如果有已存在的工具通常會(huì)用灰色圖標(biāo)列出右側(cè)是輸入輸出定義。這次我們要做的是新增一個(gè)腳本類型子工具在 CogToolBlock 的腳本標(biāo)簽頁里添加一個(gè)步驟并編寫 C# 代碼。添加腳本后需要給這個(gè)腳本步驟增加兩個(gè)輸入輸出輸入就是上游傳下來的圖像我命名為InputImage輸出就是后面要用于判斷的OutRow、OutCol、OutScore。這些變量名在代碼里都會(huì)用到。注意 QuickBuild 的腳本編輯器有自己的“Terminals”概念需要在界面內(nèi)把輸入輸出變量綁定到 CogToolBlock 的 Inputs 和 Outputs 上否則代碼里訪問不到。3.4 圖像轉(zhuǎn)換CogImage8Grey 轉(zhuǎn) HImage這是最容易出錯(cuò)的一步。VisionPro 的CogImage8Grey和 Halcon 的HImage是兩種完全不同的圖像對象不能直接賦值。最簡單的轉(zhuǎn)換方法是借助 Bitmap。在 QuickBuild 腳本里我們可以從 ToolBlock 的輸入終端拿到CogImage8Grey轉(zhuǎn)換成Bitmap再用 Halcon 的HImage構(gòu)造函數(shù)包裝起來。using System.Drawing; using Cognex.VisionPro; using Cognex.VisionPro.ImageProcessing; using HalconDotNet; public HImage CogImage8GreyToHImage(CogImage8Grey cogImage) { Bitmap bmp cogImage.ToBitmap(); HImage hImage new HImage(bmp); bmp.Dispose(); return hImage; }這個(gè)寫法雖然簡單但要注意一個(gè)點(diǎn)ToBitmap()會(huì)把像素?cái)?shù)據(jù)完整復(fù)制一遍內(nèi)存開銷比直接傳指針大在 1280x1024 這樣的圖上還好如果相機(jī)是 500 萬、1200 萬像素每次復(fù)制都會(huì)帶來額外延遲。想追求性能就要用PixelData配合HImage.GenImage1來做后面第 4 部分我會(huì)給出替代寫法。3.5 在 C# 腳本中加載 Halcon 模型并推理圖像轉(zhuǎn)換完成后剩下的就是調(diào)用 Halcon 模型。如果是形狀模板匹配代碼就三行讀模型、找匹配、取結(jié)果。關(guān)鍵點(diǎn)是要把HShapeModel對象放在腳本類成員里避免每次執(zhí)行都重新從磁盤讀模型。Halcon 讀模型這個(gè)動(dòng)作雖然不算特別慢但在產(chǎn)線節(jié)拍里能省就省。private HShapeModel _model; private bool _modelLoaded false; private void LoadModelIfNeeded() { if (_modelLoaded) return; _model new HShapeModel(); _model.ReadShapeModel(C:\halcon_models\connector_model.shm); _modelLoaded true; }推理時(shí)將前面轉(zhuǎn)出來的HImage傳給FindShapeModel拿到結(jié)果后立刻釋放HImage對象。Halcon .NET 對象底層包著原生資源不釋放會(huì)撐高內(nèi)存特別是連續(xù)運(yùn)行幾百張圖之后內(nèi)存上漲會(huì)非常明顯。3.6 結(jié)果寫回 QuickBuild 輸出Halcon 的FindShapeModel返回的是HTuple需要轉(zhuǎn)成普通類型再寫回 QuickBuild 輸出。這里有個(gè)經(jīng)驗(yàn)不要直接把HTuple對象塞給 OutputsQuickBuild 界面顯示和配方保存都不認(rèn)識(shí)這個(gè)類型。正確做法是把元素取出來轉(zhuǎn)成 double 或 int再賦給 ToolBlock 的輸出終端。mToolBlock.Outputs[OutRow].Value Convert.ToDouble(row[0].D); mToolBlock.Outputs[OutCol].Value Convert.ToDouble(col[0].D); mToolBlock.Outputs[OutScore].Value Convert.ToDouble(score[0].D);這樣 QuickBuild 后續(xù)工具就能通過標(biāo)簽、顯示面板或者通訊寫入功能讀取這三個(gè)值整個(gè)過程和調(diào)用 VisionPro 自帶的工具沒有任何區(qū)別。4. 核心環(huán)節(jié)實(shí)現(xiàn)一個(gè)可直接復(fù)制的 C# 腳本樣例4.1 腳本類的主框架QuickBuild 的腳本工具不像普通 C# 類那樣有Main函數(shù)它更接近一個(gè)事件驅(qū)動(dòng)對象。核心方法一般叫RunTool或者ScriptTool具體名字取決于你在 CogToolBlock 里添加的腳本模板。為了方便說明我用通用結(jié)構(gòu)來寫核心思路是獲取輸入轉(zhuǎn)圖像加載模型推理寫輸出。using System; using System.Drawing; using Cognex.VisionPro; using Cognex.VisionPro.ImageProcessing; using HalconDotNet; public class ScriptClass { private HShapeModel _shapeModel; private bool _isModelLoaded; public void Run() { CogImage8Grey inputImage mToolBlock.Inputs[InputImage].Value as CogImage8Grey; if (inputImage null) { throw new Exception(輸入圖像為空或不是8位灰度圖); } HImage halconImage ConvertCogImageToHImage(inputImage); try { LoadModelIfNeeded(); HTuple row, col, angle, score; _shapeModel.FindShapeModel(halconImage, 0, 360, 0.7, 1, 0.5, least_squares, 5, 0.9, out row, out col, out angle, out score); if (score.Length 0) { mToolBlock.Outputs[OutRow].Value row[0].D; mToolBlock.Outputs[OutCol].Value col[0].D; mToolBlock.Outputs[OutAngle].Value angle[0].D; mToolBlock.Outputs[OutScore].Value score[0].D; } else { mToolBlock.Outputs[OutRow].Value -1.0; mToolBlock.Outputs[OutCol].Value -1.0; mToolBlock.Outputs[OutAngle].Value 0.0; mToolBlock.Outputs[OutScore].Value 0.0; } } finally { halconImage.Dispose(); } } private HImage ConvertCogImageToHImage(CogImage8Grey cogImage) { Bitmap bmp cogImage.ToBitmap(); HImage hImage new HImage(bmp); bmp.Dispose(); return hImage; } private void LoadModelIfNeeded() { if (_isModelLoaded) return; _shapeModel new HShapeModel(); _shapeModel.ReadShapeModel(C:\halcon_models\connector_model.shm); _isModelLoaded true; } }4.2 高性能圖像轉(zhuǎn)換的替代寫法如果你對性能有要求比如想讓每次檢測控制在十幾毫秒內(nèi)那盡量別走 Bitmap。Halcon 的HImage提供了直接從指針生成圖像的方式VisionPro 的CogImage8Grey內(nèi)部能取到像素?cái)?shù)據(jù)。這里需要注意的是VisionPro 圖像的像素?cái)?shù)據(jù)默認(rèn)在托管數(shù)組或者非托管內(nèi)存里我們需要保證在 Halcon 使用期間這塊內(nèi)存有效。private HImage ConvertCogImageToHImageFast(CogImage8Grey cogImage) { int width cogImage.Width; int height cogImage.Height; // 這里只是示意不同版本的VisionPro獲取像素?cái)?shù)組的方式略有差異 // 有的版本是PixelData屬性有的是GetPixelData方法按你本地的API來。 byte[] pixels cogImage.PixelData as byte[]; HImage hImage new HImage(); unsafe { fixed (byte* p pixels) { hImage.GenImage1(byte, width, height, (IntPtr)p); } } return hImage; }GenImage1的執(zhí)行效率和內(nèi)存占用比 Bitmap 中轉(zhuǎn)好很多但要注意兩個(gè)前提第一cogImage必須是連續(xù)的 8 位灰度數(shù)據(jù)不是 24 位彩色第二Halcon 的圖像坐標(biāo)原點(diǎn)在左上角VisionPro 的原點(diǎn)也在左上角這塊通常不用額外翻轉(zhuǎn)但如果你做了畸變校正或旋正要自己保證坐標(biāo)映射關(guān)系一致。4.3 把預(yù)處理和 AI 模型封裝成 HDevProcedure 的用法如果模型本身不是模板匹配而是一套完整的 Halcon 流程比如先灰度變換、再閾值分割、再跑深度學(xué)習(xí)分類直接在 C# 里逐行調(diào)用算子里很冗余。這時(shí)候可以把這個(gè)流程保存成 HDevelop 的.hdvp文件用HDevEngine來加載執(zhí)行。這種方式相當(dāng)于把 Halcon 內(nèi)部腳本當(dāng)成黑盒我只負(fù)責(zé)傳入圖像、傳出結(jié)果。private HDevEngine _engine; private HDevProcedure _procedure; private void InitHDevEngine() { _engine new HDevEngine(); _engine.SetProcedurePath(C:\halcon_models); _procedure new HDevProcedure(classify_defect.hdvp); } private void RunWithHDevEngine(HImage halconImage) { HDevProcedureCall call _procedure.CreateCall(); call.SetInputIconicParamObject(InputImage, halconImage); call.SetInputCtrlParamTuple(MinScore, 0.85); call.Execute(); HObject defectRegion call.GetOutputIconicParamObject(DefectRegion); HTuple isOk call.GetOutputCtrlParamTuple(IsOK); // 把結(jié)果轉(zhuǎn)成普通類型寫回QuickBuild輸出 }采用 HDevEngine 的好處是算法同事可以獨(dú)立維護(hù) HDevelop 腳本我們不直接改 C#減少溝通成本。壞處是每次執(zhí)行要經(jīng)過腳本解釋層性能比直接調(diào)用算子略微低一點(diǎn)。對于幀率要求不高的質(zhì)量檢測場景完全夠用。4.4 部署到現(xiàn)場時(shí)的文件整理在開發(fā)機(jī)上跑通還不算完工控機(jī)上部署是另一個(gè)坎。需要帶過去的文件包括Halcon 23.11 運(yùn)行庫至少包含bin\x64-win64下的 DLL 和 LicenseHalconDotNet.dll和運(yùn)行庫版本匹配的模型文件以及 QuickBuild 工程文件。最好把這些放到一個(gè)固定的目錄結(jié)構(gòu)里比如C:\VisionProjects\ConnectorInspect\ ├─ QuickBuild\ConnectorInspect.vpp ├─ Halcon\HALCON-23.11\ ... ├─ Halcon\HalconDotNet.dll └─ Models\connector_model.shm部署后務(wù)必先單獨(dú)運(yùn)行一個(gè) Halcon 自帶的驗(yàn)證工具或小的控制臺(tái)程序確認(rèn) License 生效再打開 QuickBuild。如果先開 QuickBuild 再發(fā)現(xiàn) Halcon 報(bào)錯(cuò)排查時(shí)會(huì)被 QuickBuild 的錯(cuò)誤彈窗干擾。5. 常見問題與排查技巧實(shí)錄5.1DllNotFoundException: halcon.dll這是出現(xiàn)頻率最高的問題原因基本都是 Path 環(huán)境變量里沒有 Halcon 的原生運(yùn)行庫目錄。HalconDotNet.dll 只是托管包裝層它內(nèi)部會(huì)通過 P/Invoke 加載halcon.dll。解決辦法是在系統(tǒng)環(huán)境變量 PATH 中加入C:\Program Files\MVTec\HALCON-23.11\bin\x64-win64同時(shí)確認(rèn)沒有其他 Halcon 版本的目錄排在前面。如果不想改系統(tǒng)環(huán)境變量也可以在 QuickBuild 腳本里動(dòng)態(tài)設(shè)置。在腳本類里加一個(gè)靜態(tài)構(gòu)造函數(shù)或初始化方法執(zhí)行Environment.SetEnvironmentVariable(PATH, halconBinDir ; Environment.GetEnvironmentVariable(PATH))。這個(gè)操作要在第一次調(diào)用 Halcon 算子之前完成否則 DLL 已經(jīng)被加載改了也無效。5.2 License 錯(cuò)誤模型加載階段報(bào) License error模型加載時(shí)報(bào)的 License 錯(cuò)誤代碼上沒有任何問題純粹是授權(quán)環(huán)境不對。Halcon 23.11 在安裝時(shí)會(huì)默認(rèn)申請?jiān)囉?License試用過期后必須重新導(dǎo)入有效 License。需要注意的是如果 QuickBuild 運(yùn)行的 Windows 服務(wù)和登錄用戶不同License 服務(wù)可能對另一個(gè)用戶不可見。這時(shí)可以試試在安裝目錄下執(zhí)行l(wèi)icense_manager或者直接重新運(yùn)行 License 導(dǎo)入向?qū)Т_認(rèn)當(dāng)前運(yùn)行用戶能看到有效授權(quán)。5.3 圖像內(nèi)容正常但匹配結(jié)果異常偏左/偏移這不是調(diào)用問題通常是圖像坐標(biāo)映射不一致。VisionPro 中圖像可能帶有一像素偏移的“原點(diǎn)設(shè)置”或者做過了校準(zhǔn)而 Halcon 默認(rèn)認(rèn)為圖像左上角為 (0,0)。解決方法是統(tǒng)一以像素坐標(biāo)為基準(zhǔn)先只在像素坐標(biāo)系下驗(yàn)證不要一上來就疊加機(jī)器人坐標(biāo)或 Calibration 坐標(biāo)。QuickBuild 里如果開了 Calibration要記得把輸出結(jié)果再經(jīng)過一次坐標(biāo)轉(zhuǎn)換而不是拿 Halcon 的像素結(jié)果直接當(dāng)世界坐標(biāo)用。5.4 圖像轉(zhuǎn) HImage 后顯示全黑或花屏全黑或花屏大概率是圖像通道不匹配。CogImage24彩色圖如果按 8 位灰度方式取數(shù)據(jù)會(huì)錯(cuò)亂。確認(rèn)交給 Halcon 的HImage類型和圖像復(fù)雜度一致灰度圖用byte彩色圖用rgb。如果用的是CogImage8Grey不會(huì)有這個(gè)問題但如果上游源圖像是CogImage24RGB就要先轉(zhuǎn)成灰度或者用HImage(bitmap)讓構(gòu)造函數(shù)自己去判斷通道。5.5 32 位與 64 位不匹配QuickBuild 9.0 默認(rèn)是 64 位進(jìn)程但如果你在 QuickBuild 的啟動(dòng)快捷方式上強(qiáng)制了 32 位兼容或者工控機(jī)上裝了 32 位 VisionPro那 Halcon 也要使用同位的運(yùn)行庫?？焖倥袛喈?dāng)前進(jìn)程位數(shù)可以在腳本里加一句話bool is64 Environment.Is64BitProcess;然后在消息或日志里輸出。如果 Halcon 用的是 x64 DLL 而進(jìn)程是 x86加載時(shí)會(huì)立刻報(bào) BadImageFormatException這個(gè)異常幾乎可以直接用來反向定位。6. 性能與穩(wěn)定性優(yōu)化建議6.1 模型只加載一次不要每次執(zhí)行都 Read這是最容易提升性能的一點(diǎn)。QuickBuild 腳本工具如果每次觸發(fā)都執(zhí)行ReadShapeModel一個(gè) 30W 像素的圖像匹配流程可能從 30ms 被拖到 90ms。把模型對象保存在腳本類成員變量里用標(biāo)志位控制只加載一次后續(xù)每次執(zhí)行只做FindShapeModel收益非?？捎^。對多模型切換的場景可以用Dictionarystring, HShapeModel緩存按配方名稱索引。6.2 圖像轉(zhuǎn)換用指針模式但要處理內(nèi)存生命周期圖像轉(zhuǎn)換方面建議根據(jù)項(xiàng)目需求選擇開發(fā)階段用 Bitmap 轉(zhuǎn)換簡單可靠正式跑節(jié)拍時(shí)換成GenImage1指針模式。指針模式的關(guān)鍵是GenImage1創(chuàng)建的 HImage 不會(huì)自動(dòng)管理原始字節(jié)數(shù)組的內(nèi)存如果原始像素?cái)?shù)據(jù)是局部變量方法返回后內(nèi)存可能已經(jīng)被回收但 Halcon 內(nèi)部還在用。所以要么確保cogImage的存活時(shí)間覆蓋FindShapeModel執(zhí)行完畢要么在GenImage1前把像素?cái)?shù)組拷到獨(dú)立緩沖區(qū)。IntPtr ptr System.Runtime.InteropServices.Marshal.AllocHGlobal(width * height); System.Runtime.InteropServices.Marshal.Copy(pixels, 0, ptr, width * height); HImage hImage new HImage(); hImage.GenImage1(byte, width, height, ptr); // 用完后手動(dòng)釋放 System.Runtime.InteropServices.Marshal.FreeHGlobal(ptr);6.3 多線程并行要注意 Halcon Cloud/HDVL 的限制如果一臺(tái)工控機(jī)要檢測多個(gè)產(chǎn)品同一時(shí)刻可能開多個(gè) QuickBuild Job每個(gè) Job 里都有 Halcon 模型調(diào)用。Halcon 運(yùn)行庫在單進(jìn)程內(nèi)通常能并行處理但如果 License 規(guī)格限制了并行實(shí)例數(shù)多個(gè)線程同時(shí)調(diào)用會(huì)互相等待甚至報(bào)錯(cuò)。遇到這種情況建議把模型推理放到一個(gè)獨(dú)立的串行隊(duì)列里只在拿到結(jié)果后再更新 UI。不要貿(mào)然用多線程去壓榨速度后續(xù)排查許可證并發(fā)問題非常痛苦。6.4 日志與圖像保存的配合項(xiàng)目調(diào)試期我會(huì)在 QuickBuild 腳本里加一個(gè)開關(guān)控制是否保存中間結(jié)果圖。具體做法是在Run()方法里用計(jì)時(shí)器記錄耗時(shí)同時(shí)把 Halcon 匹配分?jǐn)?shù)低于某個(gè)閾值的圖保存到指定目錄。這些圖對后續(xù)分析模型參數(shù)、調(diào)整最小分?jǐn)?shù)非常有幫助。但正式產(chǎn)線版本記得把這個(gè)開關(guān)關(guān)掉否則高頻保存圖片會(huì)嚴(yán)重?fù)p耗硬盤壽命。7. 一些實(shí)際操作后的體會(huì)我實(shí)際踩過幾次坑之后最大的體會(huì)是這個(gè)配置工作真正的難點(diǎn)不在 C# 代碼怎么寫而在環(huán)境一致性。只要 Halcon 的版本、位數(shù)、License、PATH 這四個(gè)環(huán)境變量一樣錯(cuò)位后面寫再多代碼都是白搭。所以我的建議是嚴(yán)格按照順序來先在 Visual Studio 里用控制臺(tái)程序驗(yàn)證 Halcon 調(diào)用再進(jìn) QuickBuild 接腳本最后才部署到工控機(jī)。每一步驗(yàn)證通過再走下一步比一口氣寫完然后反復(fù)猜問題要節(jié)省太多時(shí)間。另外給大家一個(gè)實(shí)用的小技巧在 QuickBuild 腳本里寫結(jié)果輸出時(shí)可以順帶把 Halcon 的執(zhí)行耗時(shí)寫進(jìn) ToolBlock 的另一個(gè)輸出變量比如OutTimeMs。這樣在 QuickBuild 的顯示界面里就能實(shí)時(shí)看到算法耗時(shí)調(diào)起參來非常直觀。別小看這個(gè)細(xì)節(jié)項(xiàng)目驗(yàn)收的時(shí)候一個(gè)醒目的耗時(shí)指標(biāo)能省掉不少給客戶解釋算法的口水。如果你以后遇到類似需求先在 Halcon 里把模型跑通再照著這條鏈路接到 QuickBuild 里整個(gè)過程不會(huì)超過半天。祝各位在項(xiàng)目里少走彎路一次點(diǎn)亮。