Halcon HObject转Bitmap24位：内存重排原理与完整实现

做机器视觉的上位机开发，最绕不开的一件事就是把 Halcon 里算完的图送到界面显示，或者转成标准位图保存。Halcon 的 HObject 在内部是平面分离存储的，而 Windows 的 Bitmap24 位格式是 BGR 三通道交错排列，两者直接对接根本行不通，网上讨论大都是零散代码，没讲清楚为什么这么做。我最早做这块时，也是东拼西凑才跑通，中间还踩过颜色颠倒、图像上下翻转、花屏、内存泄漏各种坑。这篇就专门聊 HObject 转 Bitmap24 位的完整思路和直接能用的实现，看懂之后你也能顺手封装一套自己的转换工具。

1. 为什么 Halcon 图像不能直接当 Bitmap 用

1.1 Halcon 图像内部的真面目

Halcon 里的图像对象，包括从相机采集回来的图和经过算子处理后的结果，本质上是按“平面”存储的。所谓平面存储，就是如果有 R、G、B 三个通道，内存里先把所有红色像素放一块，再把所有绿色像素放一块，最后放蓝色像素。每个通道的数据是独立的一块矩形缓冲区，互不夹杂。

举个例子，一张 4x4 的三通道彩色图，Halcon 内存布局大概是：

• Red 通道：16 个 byte 连续排列
• Green 通道：16 个 byte 连续排列
• Blue 通道：16 个 byte 连续排列

这和我们在 Windows 下常见的 DIB/Bitmap 格式正好相反。Bitmap24 位要求内存里从第一个像素开始，依次存 B、G、R，然后再下一个像素，也就是所谓的“交错存储”。两个像素在内存里就是 B1 G1 R1 B2 G2 R2 这样排。

所以就算你把 Halcon 的指针直接交给 Bitmap 的 LockBits，结果必然是花屏、颜色错乱、显示成三个灰度图叠在一起。转换的核心工作就是把平面数据“打散重排”成交错数据。

1.2 24 位 BMP/DIB 到底想要什么

Windows 的 24 位位图，最常打交道的两个内存场景是 BitmapData 和 BMP 文件。

用 C# 的 System.Drawing.Bitmap 时，LockBits拿到的Scan0指向一块内存，里面存的是一行一行的像素。24 位格式下每个像素占用 3 个字节，顺序固定是 B、G、R。这里有个特别容易忽略的细节：行与行之间不是紧贴着的，每行字节数必须按 4 字节对齐。

计算公式是：

stride = ((width * 24 + 31) / 32) * 4

等价写法是：

stride = ((width * 3 + 3) / 4) * 4

比如宽度 100 像素，width * 3 = 300，300 除以 4 恰好整除，stride 是 300。宽度 101 像素，101 * 3 = 303，303 不能被 4 整除，stride 向上取整到 304。这一行的最后多出来的 1 个字节是 padding，不存任何有效像素。如果忽略这个对齐，转换出的图会从某一列开始出现倾斜和彩色条纹，而且越靠下偏移越明显。

还有一个行序问题。Halcon 图像默认是从上到下排列的，第一行是图像顶部。而标准 BMP 文件或者使用正高度的 Bitmap 对象，像素数据却是从最后一行开始放的。也就是说，如果你想把 Halcon 图像完整存成 BMP，需要在写入时把行序反过来。要么在内存复制时用h - 1 - y翻转，要么在构造位图头时把biHeight设为负数，表示 top-down 扫描顺序。多数上位机场景我习惯在复制时直接翻转，这样兼容性最好。

1.3 转换前要确认的三件事

拿到一个 HObject 后，先别急着取指针，先想清楚三件事。

第一，这个 HObject 到底是不是图像对象。Halcon 的 HObject 是个大杂烩容器，图像、Region、XLD 都叫 HObject。万一传进来一个 Region，get_image_pointer3会直接报异常。稳健的封装应该先检查类型，或者用一个 try-catch 兜底。

第二，图像的像素类型是什么。get_image_pointer3会返回 Type，可能是"byte"、"uint2"、"int2"、"real"等。Bitmap24 位里每个通道只接受 0 到 255 的 byte 值。如果类型不是 byte，必须先转换成 byte，否则数据范围对不上，显示出来要么全黑，要么高光一片。

第三，通道数是多少。三通道图像用get_image_pointer3，灰度图用get_image_pointer1。不要指望灰度图也能拿到三个指针，Halcon 不会给单通道图返回三个通道指针。灰度转 24 位时，需要把同一个灰度值复制三份，分别填到 B、G、R 位置。

2. 转换方案的整体设计与取舍

2.1 直接内存复制还是用 Halcon 算子

有人会问，Halcon 自带的write_image不是可以直接写 BMP 吗？确实可以，如果目标只是存文件，write_image(Image, "bmp", 0, "output.bmp")一行搞定，根本不用自己转换。但实际开发中，很多需求是转成内存 Bitmap 去刷新 WinForms 或 WPF 界面，或者把 HObject 转成 OpenCV 的 Mat 继续处理。这种场景下不能落盘，只能在内存里手动重排。

Halcon 有没有现成的算子把平面图像转成交错图像？有个gen_image_interleaved可以从交错数据创建图像，方向是反的，不能用来把 HObject 直接转成交错格式。另一些算子像access_channel、compose3虽然能操作通道，但内部数据布局依然是平面分离的。所以最终还是要靠最底层的指针操作，自己写循环重排。

我个人测试下来，直接内存复制是性能最优、逻辑最可控的方案。每层只是简单的颜色分量搬移，没有算子调用的额外开销，也不依赖 Halcon 的运行时状态。

2.2 输出目标决定实现细节

转换函数写成一个还是多个？我建议看输出目标拆成两层。

第一层是“HObject 转内存像素缓冲”，输出一个标准的 24 位交错 BGR 数据块，按 Bitmap 要求完成行对齐。这一层只关心像素本身，不依赖 GDI+。

第二层才是“像素缓冲转 Bitmap 对象”或者“像素缓冲写 BMP 文件”。这一层可以由上层逻辑自由选择。如果要把图给 WinForms，就包成Bitmap；如果要做网络传输或存档，可以直接写文件。

这么做的好处是，核心交换代码只维护一份，其他场景都复用同一份缓冲。比如 C++ 项目里经常需要把 Halcon 图转给图像采集卡或者 OpenCV，直接对接第一层的std::vector<uint8_t>就行。

2.3 封装思路：统一入口，避免到处 CopyPixels

很多项目里，同一份 Halcon 图像会被好几个模块同时转换。一开始我图省事，直接在窗体事件里写转换逻辑，后来发现代码重复不说，改一个通道顺序要全局搜索，特别痛苦。

后来我固定一个静态工具类，提供两个入口：

public static Bitmap ToBitmap(HObject image) public static byte[] ToBgrBuffer(HObject image)

内部统一处理单通道、三通道、类型检查和行序翻转。外部使用者完全不知道 Halcon 内部的存储细节，只要传 HObject 进去，拿到的就是能直接显示的 Bitmap。这个封装习惯强烈推荐，尤其项目里有多个窗体或者还要对接二次开发时，能省掉大量重复劳动。

3. 核心代码实现：HObject 转 24 位 Bitmap

3.1 C# 实现：从 GetImagePointer3 到 Bitmap

下面这段是 C# + HalconDotNet 的完整实现。核心是先取三通道指针，再通过unsafe把平面数据填充到 Bitmap 的Scan0指向的目标缓冲。

using System; using System.Drawing; using System.Drawing.Imaging; using HalconDotNet; public static class HalconBitmapConverter { public static Bitmap ToBitmap(HObject image) { HTuple channels = new HTuple(); HOperatorSet.CountChannels(image, out channels); int numChannels = channels[0].I; if (numChannels == 1) { return ConvertGrayToBitmap24(image); } else if (numChannels == 3) { return ConvertColorToBitmap24(image); } else { throw new NotSupportedException("仅支持单通道或三通道图像"); } } private static Bitmap ConvertColorToBitmap24(HObject image) { HTuple pointerR, pointerG, pointerB; HTuple type, width, height; HOperatorSet.GetImagePointer3(image, out pointerR, out pointerG, out pointerB, out type, out width, out height); string typeStr = type[0].S; if (typeStr != "byte") { throw new NotSupportedException("三通道转换要求图像类型为 byte，当前类型：" + typeStr); } int w = width[0].I; int h = height[0].I; int stride = ((w * 3 + 3) / 4) * 4; Bitmap bmp = new Bitmap(w, h, PixelFormat.Format24bppRgb); BitmapData bmpData = bmp.LockBits(new Rectangle(0, 0, w, h), ImageLockMode.WriteOnly, PixelFormat.Format24bppRgb); unsafe { byte* pR = (byte*)pointerR[0].L; byte* pG = (byte*)pointerG[0].L; byte* pB = (byte*)pointerB[0].L; byte* dst = (byte*)bmpData.Scan0; // Bitmap 默认 bottom-up，需要把图像最后一行放到目标第一行 for (int y = 0; y < h; y++) { byte* srcR = pR + (long)y * w; byte* srcG = pG + (long)y * w; byte* srcB = pB + (long)y * w; byte* dstRow = dst + (long)(h - 1 - y) * bmpData.Stride; for (int x = 0; x < w; x++) { dstRow[x * 3] = srcB[x]; dstRow[x * 3 + 1] = srcG[x]; dstRow[x * 3 + 2] = srcR[x]; } } } bmp.UnlockBits(bmpData); return bmp; } private static Bitmap ConvertGrayToBitmap24(HObject image) { HTuple pointer; HTuple type, width, height; HOperatorSet.GetImagePointer1(image, out pointer, out type, out width, out height); string typeStr = type[0].S; if (typeStr != "byte") { throw new NotSupportedException("灰度转换要求图像类型为 byte，当前类型：" + typeStr); } int w = width[0].I; int h = height[0].I; Bitmap bmp = new Bitmap(w, h, PixelFormat.Format24bppRgb); BitmapData bmpData = bmp.LockBits(new Rectangle(0, 0, w, h), ImageLockMode.WriteOnly, PixelFormat.Format24bppRgb); unsafe { byte* pGray = (byte*)pointer[0].L; byte* dst = (byte*)bmpData.Scan0; for (int y = 0; y < h; y++) { byte* src = pGray + (long)y * w; byte* dstRow = dst + (long)(h - 1 - y) * bmpData.Stride; for (int x = 0; x < w; x++) { byte g = src[x]; dstRow[x * 3] = g; // B dstRow[x * 3 + 1] = g; // G dstRow[x * 3 + 2] = g; // R } } } bmp.UnlockBits(bmpData); return bmp; } }

这段代码有几个地方要特别说。

GetImagePointer3返回的三个指针顺序是 Red、Green、Blue，而不是 BGR。所以填充目标时，我把pB放到dstRow[x*3]，把pR放到dstRow[x*3+2]。很多新手第一次写反，结果图像偏蓝或者偏红，原理就在这里。

pointerR[0].L在 HalconDotNet 里表示取 HTuple 中的 64 位整数指针地址，转成byte*后就可以直接按字节访问。要注意的是，这里必须在unsafe上下文中，并且项目要允许不安全代码。

行序上，我用的是(h - 1 - y)做翻转，原因是new Bitmap(w, h, PixelFormat.Format24bppRgb)默认高度为正，对应的 DIB 是 bottom-up，Scan0指向的是图像最后一行。如果你在复制时没有翻转，最终显示或保存的图会是上下颠倒的。

3.2 C++ 实现：不依赖托管环境

C++ 环境下使用 HalconCpp，思路完全一致，区别只是指针类型换成了H5_IntPtr。下面这个函数把 HObject 转换并直接写出一个 24 位 BMP 文件，不依赖 Windows GDI，纯标准库写位图头，适合任何平台。

#include <vector> #include <fstream> #include <cstdint> #include <cstring> #include "HalconCpp.h" using namespace HalconCpp; void Put16(std::vector<unsigned char>& data, size_t offset, uint16_t value) { data[offset] = static_cast<unsigned char>(value & 0xFF); data[offset + 1] = static_cast<unsigned char>((value >> 8) & 0xFF); } void Put32(std::vector<unsigned char>& data, size_t offset, uint32_t value) { data[offset] = static_cast<unsigned char>(value & 0xFF); data[offset + 1] = static_cast<unsigned char>((value >> 8) & 0xFF); data[offset + 2] = static_cast<unsigned char>((value >> 16) & 0xFF); data[offset + 3] = static_cast<unsigned char>((value >> 24) & 0xFF); } void SaveHObjectAsBmp24(const HObject& image, const std::string& filename) { HTuple type, width, height; HTuple pR, pG, pB; HOperatorSet::GetImagePointer3(image, &pR, &pG, &pB, &type, &width, &height); int w = width[0].I(); int h = height[0].I(); int rowSize = ((w * 3 + 3) / 4) * 4; size_t headerSize = 54; size_t pixelSize = static_cast<size_t>(rowSize) * h; std::vector<unsigned char> fileData(headerSize + pixelSize, 0); // BITMAPFILEHEADER fileData[0] = 'B'; fileData[1] = 'M'; Put32(fileData, 2, static_cast<uint32_t>(fileData.size())); Put32(fileData, 10, static_cast<uint32_t>(headerSize)); // BITMAPINFOHEADER Put32(fileData, 14, 40); Put32(fileData, 18, static_cast<uint32_t>(w)); Put32(fileData, 22, static_cast<uint32_t>(h)); Put16(fileData, 26, 1); Put16(fileData, 28, 24); Put32(fileData, 30, 0); // BI_RGB Put32(fileData, 34, static_cast<uint32_t>(pixelSize)); H5_IntPtr ptrR = pR[0].L(); H5_IntPtr ptrG = pG[0].L(); H5_IntPtr ptrB = pB[0].L(); size_t outPos = headerSize; for (int y = 0; y < h; ++y) { int srcY = h - 1 - y; const unsigned char* srcR = reinterpret_cast<const unsigned char*>(ptrR) + static_cast<size_t>(srcY) * w; const unsigned char* srcG = reinterpret_cast<const unsigned char*>(ptrG) + static_cast<size_t>(srcY) * w; const unsigned char* srcB = reinterpret_cast<const unsigned char*>(ptrB) + static_cast<size_t>(srcY) * w; unsigned char* dst = fileData.data() + outPos; for (int x = 0; x < w; ++x) { dst[x * 3] = srcB[x]; dst[x * 3 + 1] = srcG[x]; dst[x * 3 + 2] = srcR[x]; } outPos += rowSize; } std::ofstream outFile(filename, std::ios::binary); outFile.write(reinterpret_cast<const char*>(fileData.data()), fileData.size()); }

这个实现把位图头写死成 54 字节，适用于 24 位非压缩 BMP。rowSize按 4 字节对齐，写入像素时已经处理了底部的 padding。由于fileData初始化为 0，每行末尾的空余字节天然是 0，不需要额外清零。

如果只是要内存中的像素缓冲而不是写文件，可以仿照 C# 版本，把dst换成外部传入的std::vector<unsigned char>，外面的代码再决定怎么用。

注意：这段代码假设输入已经是 byte 类型的三通道图。如果拿到的是灰度图，需要先转成三通道，否则GetImagePointer3本身会抛出异常。

3.3 顺手把 BMP 文件写出来

直接用上面 C++ 代码写 BMP 文件，好处是不依赖 GDI+，生成的.bmp文件能被所有看图软件识别。C# 里其实更省事，因为我们已经在内存里构建好了Bitmap对象，直接调用bmp.Save("output.bmp", ImageFormat.Bmp)就行。

但有一点要注意：C# 的Bitmap保存时，可能会附带一些额外信息，不过最终像素布局仍然是标准的 24 位 BMP，不用太担心。如果你的项目要求在 Linux 或嵌入式环境导出一个纯 BMP 文件，建议用 C++ 那种手动构造头文件的方式，完全可控。

4. 避坑指南：颜色错乱、花屏、类型不对

4.1 图像类型不是 byte 怎么办

工业相机经常输出 10 位、12 位、14 位的图像数据，Halcon 读进来后类型通常是uint2，数值范围可能到 0 到 65535。如果直接把uint2当成 byte 处理，要么强制截断，低位信息丢失，要么数据溢出变成噪点，显示出来就是一团黑或者一片花。

正确做法是先拉伸再转换。Halcon 里我最常用的组合是：

scale_image_max(Image, ImageScaled) convert_image_type(ImageScaled, ImageByte, "byte")

scale_image_max会根据图像实际最大值和最小值做线性拉伸，把动态范围映射到 0 到 255，显示效果比直接convert_image_type截断好得多。也有场景需要按固定比例拉伸，那就用scale_image，传入自己的参数。

在 C# 封装里，如果检测到类型不是 byte，不要直接抛异常，至少先尝试ScaleImageMax再ConvertImageType。这样外部调用者不会因为相机参数不同而经常改代码。

4.2 指针不连续、Region 影响与错位

Halcon 图像经过reduce_domain、crop_domain等操作后，图像本身可能带一个非全图的 Region。这里有个容易搞混的概念：get_image_pointer3返回的指针永远指向原始完整图像缓冲的左上角，宽度和高度也是完整图像的宽高，而不是 Region 的外接矩形。

如果直接拿指针按照 Region 的尺寸去复制，结果就是错位、花屏、内容偏移。处理办法是，转换前先判断是否需要对 Region 处理。大多数显示场景我们关心的是整幅图像，所以拿到指针后按完整宽高复制是正常的。如果确实只需要 ROI，先用crop_domain裁剪出一个新的 HObject，再对这个新对象做转换，这时候返回的宽高就是裁剪后的尺寸。

另外，Halcon 内部图像行与行之间通常是紧凑排列的，但不能绝对保证每行之间不存在额外行间距。常规read_image、grab_image出来的图像没问题，但某些算子处理后的中间图像可能带 internal padding。如果转换出现了只偏几列的问题，可以考虑用get_image_pointer1_rect获取更精确的步长信息。日常开发中我用基础版get_image_pointer1偏多，因为绝大多数采集和标准读图场景都是紧凑的。

4.3 颜色通道顺序：为什么偏绿、偏红

最经典的坑：Halcon 的get_image_pointer3返回顺序是 R、G、B，而 Bitmap24 位需要 B、G、R。如果你在代码里把pR放到目标第 0 字节，图像会明显偏蓝；如果把pB放到第 2 字节，图像偏红。这里不是背顺序的问题，而是要建立“源通道名 → 目标通道名”的映射思维。

正确映射表如下：

如果图像还是偏绿，常见原因是灰度图转换时误用了GetImagePointer3的某个通道，把灰度值只填进了 G 通道。灰度转彩色必须把同一个灰度值复制成三个分量，不能只填一个。

4.4 stride 对齐：歪斜和锯齿的根源

Bitmap 的 stride 和图像宽度不一定是同一个数字。当width * 3不能被 4 整除时，每行末尾会多出 1 到 3 个 padding 字节。如果你复制的时候整行拷贝用的是width * 3，而目标行距用bmpData.Stride，最终结果是对的；如果目标行距也用了width * 3，从第二行开始就会慢慢向左偏，形成明显的锯齿。

我在 C# 版本里故意让代码一直使用bmpData.Stride定位目标行，就是因为这个坑太隐蔽。C++ 版本则统一用rowSize = ((w * 3 + 3) / 4) * 4，确保自己的像素缓冲本身就满足对齐要求，后续写文件不会出问题。

常见问题速查：

5. 性能优化与实测经验

5.1 unsafe 指针与逐行复制的微优化

C# 不开启 unsafe，直接操作像素只能通过Marshal.Copy配合字节数组，每一次都要拷贝整行，效率还可以，但灵活度差。而unsafe指针写法在LockBits后直接读写内存，避免多一次托管数组拷贝，实测性能能提升一半以上。

对于三通道彩色图，最直观的写法是三层for循环：

for (int y = 0; y < h; y++) for (int x = 0; x < w; x++) dstRow[x * 3] = srcB[x];

这个写法缓存命中率尚可，因为三个源指针分别指向三块连续的通道缓冲，目标指针按行交错写入。编译器在 Release 模式下通常会做循环优化，不需要人为拆成按 16 字节块处理。如果对性能有极致要求，可以增加一个临时交错行缓冲，先把三个通道组合成一行 BGR 数据，再用memcpy整行搬到目标，减少对目标缓冲的随机写。但多数项目里，1920x1080 的图三通道转换在普通桌面机上也就 10 到 15 毫秒，完全够用。

5.2 并行化与缓存复用

如果图像分辨率到了 4000x3000 以上，逐像素循环的时间会明显增加。这时可以用Parallel.For对行做并行，因为每一行的源指针和目标行地址都是独立计算出来的，互不干扰。需要注意线程安全，不能在所有线程里共享同一个可变的y变量。

还有一点经验，频繁转换大图时，Bitmap对象不要每次new完就丢给 GC。尤其在大分辨率下，反复分配非托管内存容易造成内存碎片和句柄泄漏。更好的做法是预分配一个Bitmap，每次进来新图时，只重新LockBits更新像素，用完立即UnlockBits。界面刷新时直接把同一个Bitmap对象赋值给 PictureBox，能明显降低 GC 压力。

5.3 大图像实测数据与项目建议

我曾经在一个项目里测试过不同规格图像的转换耗时，环境是普通 i5 台式机，Release 模式，C# unsafe 实现：

以上数据是连续转换多次后的平均值，包含 LockBits 和创建 Bitmap 的开销。如果你的视觉处理周期是 40 毫秒一帧，这种转换开销基本可以接受。但如果要做 100 帧以上的实时预览，建议把转换次数降到最低，最好在采集线程直接转换到目标缓冲，界面线程只负责 Blit，不要再做二次转换。

如果最终目的只是保存图像文件，强烈建议直接用write_image算子，不要转 Bitmap 再存文件，节省的时间和内存完全不是一个量级。转换应该发生在“需要给显示/其他库用”的时候，而不是每次处理完都例行公事转一遍。

6. 一点个人体会

这套 HObject 转 Bitmap24 的方法，我前后在不同的项目里用过很多次，踩过的坑基本都写在上面了。个人体会是，格式转换从来不是把代码拷贝过去就完事，最重要的是搞懂内存布局，然后再动手写。尤其是 Halcon 内部的平面存储和 Windows 位图的交错存储，这两个概念一旦理解了，遇到 OpenCV、Python 图像库或者其他需要互转的场景，思路其实是完全一样的。

最后再分享一个小技巧。如果你的工程里到处都是 HObject 转 Bitmap 的散装代码，建议统一收敛到一个静态类里，对外暴露一个方法。以后哪怕 Halcon 版本升级，或者换成新的图像接口，只需要改这一处，不用满工程翻代码。这个习惯帮我节省的排障时间，远比写转换函数本身多得多。