一、Halcon 图像对象模型

Halcon 作为工业级机器视觉库，其图像处理架构遵循数据与句柄分离的设计哲学。在 C# 集成开发中，理解 HImage 对象的内部构造是掌握显示机制的基础：

这种分层架构使得 Halcon 能够在保持 C++ 核心性能的同时，通过 .NET 封装提供类型安全的开发体验。

二、代码实现

public HTuple hv_ExpDefaultWinHandle;

  //输入图像宽高
  Int64 Input_Image_Width = 0, Input_Image_Height = 0;

  /// <summary>
  /// 加载图像
  /// </summary>
  ///  <param name="type">类型,0:内存地址; 1:文件路径；2:图像; 3:空白图像</param>
  /// <param name="ptr">内存地址</param>
  /// <param name="filePath">文件路径</param>
  /// <exception cref="Exception"></exception>
  private void action(int type, IntPtr ptr, String filePath = "")
  {
      try
      {
          HObject ho_Image;
          HOperatorSet.GenEmptyObj(out ho_Image);
          HTuple win_Width, win_Height, win_Col, win_Row;
          HOperatorSet.GetWindowExtents(hv_ExpDefaultWinHandle, out win_Row, out win_Col, out win_Width, out win_Height);//获取窗体大小规格

          //设置画图颜色
          HOperatorSet.SetDraw(hv_ExpDefaultWinHandle, "margin");
          HOperatorSet.SetColor(hv_ExpDefaultWinHandle, "red");
          //设置窗体显示对象个数
          HOperatorSet.SetWindowParam(hv_ExpDefaultWinHandle, "graphics_stack_max_element_num", 500000);

          if (type == 0 || type == 1)
          {
              if (!string.IsNullOrEmpty(filePath))
              {
                  //文件路径加载图像
                  HOperatorSet.ReadImage(out ho_Image, filePath);
              }
              else if (ptr != IntPtr.Zero)
              {
                  //内存加载图像
                  HOperatorSet.GenImage1(out ho_Image, "byte", Input_Image_Width, Input_Image_Height, ptr);
              }
          }
          else if (type == 3)
          {
              //创建黑色空白图像
              HOperatorSet.GenImageConst(out ho_Image, "byte", Input_Image_Width, Input_Image_Height);
          }

          //LogHelperUtility.Info("结束畸变：" + DateTime.Now.ToLongTimeString());
          HTuple Width, Height;
          HOperatorSet.GetImageSize(ho_Image, out Width, out Height);  // 获取图像宽高

          HTuple ScaleWidth = Width / (win_Width * 1.0);
          HTuple ScaleHeight = Height / (win_Height * 1.0);

          HTuple row1, column1, row2, column2;
          row1 = 0;
          column1 = -(1.0) * ((win_Width * ScaleHeight) - Width) / 2;
          row2 = row1 + win_Height * ScaleHeight;
          column2 = column1 + win_Width * ScaleHeight;
          HOperatorSet.SetPart(hv_ExpDefaultWinHandle, row1, column1, row2, column2);
          // 关键
          HOperatorSet.ClearWindow(hv_ExpDefaultWinHandle);
          HOperatorSet.DispObj(ho_Image, hv_ExpDefaultWinHandle);
      }
      catch (Exception ex)
      {
          throw new Exception("[action]图像加载失败,ex:" + ex.Message);
      }
  }

三、空白图像创建的语义与用途

Halcon 提供多种空白图像创建方式，对应不同应用场景：

四、显示系统的架构集成

4.1 Halcon 窗口与 .NET 控件交互

Halcon 提供多层次的显示抽象：
HWindow 控件

• WinForms 平台的 ActiveX 封装
• 直接嵌入窗体，支持交互式 ROI 绘制
• 消息循环集成，响应鼠标/键盘事件

HSmartWindowControl

• WPF 友好的智能控件，支持 MVVM 绑定
• 自动缩放、平移、自适应布局
• 渲染层优化，高 DPI 显示支持

自定义渲染

• 获取 HImage 的像素指针，转换为 BitmapSource（WPF）或 Bitmap（WinForms）
• 适用于 Halcon 窗口与 WPF/WinUI 深度集成场景
• 需处理色彩空间转换（RGB ↔ BGR）与内存对齐

五、生命周期管理与资源释放

5.1 非托管资源释放策略

HImage 对象封装非托管 Halcon 对象，需关注：
确定性释放

• using 语句或显式 Dispose() 调用
• 确保图像句柄及时归还至 Halcon 对象数据库

终结器兜底

• 封装类实现析构函数作为安全网
• 但不应依赖，避免非托管内存峰值

批量清理

• HOperatorSet.ClearObj() 按句柄列表批量释放
• 程序退出时的全局清理策略

六、异常处理与诊断

七、总结

C# 中 Halcon 的图像显示机制涵盖从文件系统到屏幕像素的完整链路。核心要点在于：

• 路径处理：关注编码、权限与格式自动识别
• 缓存分层：磁盘-内存-显存多级缓存优化 IO 瓶颈
• 空白图像：明确创建语义，匹配处理算法的类型需求
• 显示集成：根据 UI 框架选择合适的窗口控件或自定义渲染
• 资源管理：非托管对象的确定性释放与生命周期追踪