📚 课程目录第4章图像读取与显示

图像读取与显示：支持图像格式、HALCON图像读取算子（read_image）、在MFC/Qt中显示HALCON图像

在机器视觉项目中，图像读取与显示是连接硬件采集与算法处理的第一道桥梁。HALCON作为工业级机器视觉算法库，其图像读取算子read_image不仅支持多种标准图像格式，还具备处理多通道、多帧图像的能力。然而，在实际VC++集成开发中，工程师面临的核心挑战往往不在于算子本身，而在于如何将HALCON的图像数据（HObject）高效地转换为MFC或Qt框架中可显示的位图（Bitmap/QImage），并确保内存管理与显示性能的平衡。本章将系统讲解HALCON图像格式的内部机制、read_image的完整用法，以及两种主流UI框架下的显示集成方案。

4.1 HALCON图像格式与内存模型

HALCON的图像对象（HObject）并非简单的像素数组，而是一个包含图像数据、通道信息、感兴趣区域（ROI）以及元数据的复杂数据结构。理解其内部模型是正确读取和显示的前提。

4.1.1 核心原理：HObject与通道管理

HALCON图像支持多通道（Channel）概念，每个通道可以看作一个独立的二维矩阵。常见的图像类型包括：

byte：8位无符号整数，灰度范围0-255，是最常用的灰度图像格式。
uint2：16位无符号整数，常用于深度图或高动态范围图像。
int1/int2/int4：有符号整数类型，用于某些科学计算场景。
real：32位浮点型，用于图像处理中间结果。
rgb：三通道彩色图像，每个通道独立存储。

在内存布局上，HALCON默认采用逐通道存储（Planar）方式，即所有像素的R通道连续存储，然后是G通道，最后是B通道。这与Windows位图（DIB）的交错存储（Interleaved）方式（BGRBGRBGR...）存在本质差异。因此，在显示时必须进行通道重排。

关键理解：HALCON的get_image_pointer1算子返回的是指向第一个通道像素数据的指针，以及该通道的宽度、高度和步长（LineBytes）。步长可能大于宽度，因为HALCON为了内存对齐会填充额外的字节。在转换时，必须使用步长而非宽度来计算行偏移。

4.1.2 判断方法：如何识别图像格式

在集成过程中，可以通过以下算子获取图像的关键属性：

// 获取图像尺寸和类型
Hlong width, height;
HString type;
GetImageSize(hoImage, &width, &height);
GetImageType(hoImage, &type);

// 获取通道数
Hlong channels;
CountChannels(hoImage, &channels);

// 获取像素指针和步长
Hlong pointer;
Hlong lineBytes;
GetImagePointer1(hoImage, &pointer, &type, &width, &height, &lineBytes);

通过判断type和channels，可以决定后续的显示转换策略。例如，若type == "byte"且channels == 1，则直接映射为8位灰度图；若channels == 3，则需要转换为24位BGR格式。

4.2 read_image算子深度解析

read_image是HALCON中最基础也最常用的图像读取算子，其函数原型为：

read_image( : Image : FileName : )

该算子支持读取多种格式，包括PNG、JPEG、BMP、TIFF、GIF以及HALCON专有的HOBJ格式。在VC++中调用时，需要注意文件名编码问题——HALCON的HString默认使用系统编码，在中文路径下建议使用HString的宽字符构造函数。

4.2.1 操作流程：从文件到HObject

构造文件路径：使用HTuple或HString封装路径，支持相对路径和路径。
调用read_image：传入输出HObject变量和文件路径。
错误处理：使用try-catch捕获HALCON异常，或检查HException。
验证图像：读取后立即检查图像是否为空，尺寸是否合理。

// 标准读取示例
HObject hoImage;
HString filePath = "C:/Images/defect_sample.png";
try {
    ReadImage(&hoImage, filePath);
    // 成功读取
} catch (HException &ex) {
    // 处理错误，如文件不存在、格式不支持等
    printf("读取失败: %s\n", ex.msg.Text());
}

常见陷阱：HALCON的read_image在读取多页TIFF或包含多个图像的文件时，默认只读取第一帧。若需读取所有帧，应使用read_sequence或循环调用read_image并指定帧索引。此外，对于16位PNG图像，HALCON会自动将其转换为uint2类型，此时若直接按byte处理会导致显示异常。

4.2.2 案例拆解：批量读取与格式兼容

假设我们需要开发一个缺陷检测工具，需要批量读取一个文件夹下的所有PNG图像，并统计其格式分布。以下代码展示了如何结合list_files和read_image实现：

HTuple files;
ListFiles("C:/Dataset", "files", &files);
Hlong count = files.Length();
for (Hlong i = 0; i < count; i++) {
    HString path = files[i].S();
    // 过滤非PNG文件
    if (path.SubString(path.Length()-3, 3) != "png") continue;
    
    HObject img;
    try {
        ReadImage(&img, path);
        Hlong w, h;
        GetImageSize(img, &w, &h);
        printf("图像 %s: %ld x %ld\n", path.Text(), w, h);
    } catch (...) {
        printf("跳过无法读取的文件: %s\n", path.Text());
    }
}

该案例展示了实际工程中常见的批量处理模式。值得注意的是，ListFiles返回的路径可能包含子目录，需要根据需求过滤。同时，对于大量小文件的读取，建议使用read_image的批量版本read_image配合元组（Tuple）参数，以减少函数调用开销。

4.3 在MFC中显示HALCON图像

MFC（Microsoft Foundation Classes）是Windows平台传统的C++ GUI框架。在MFC中显示HALCON图像，核心任务是将HObject转换为CImage或直接操作DIB（设备无关位图）。

4.3.1 核心原理：从HObject到CImage

推荐使用CImage类，它封装了DIB操作，支持直接绘制到DC。转换步骤如下：

获取HObject的像素指针、宽度、高度和步长。
创建CImage对象并分配内存。
将HALCON像素数据按目标格式拷贝到CImage的缓冲区。
调用Draw或BitBlt显示。

// 灰度图转换示例
void ShowGrayImage(HDC hdc, HObject &hoImg, int x, int y) {
    Hlong w, h, lineBytes, ptr;
    HString type;
    GetImagePointer1(hoImg, &ptr, &type, &w, &h, &lineBytes);
    
    CImage cimg;
    cimg.Create((int)w, (int)h, 8);  // 8位灰度
    // 设置灰度调色板
    RGBQUAD* palette = new RGBQUAD[256];
    for (int i = 0; i < 256; i++) {
        palette[i].rgbRed = palette[i].rgbGreen = palette[i].rgbBlue = i;
        palette[i].rgbReserved = 0;
    }
    cimg.SetColorTable(0, 256, palette);
    delete[] palette;
    
    // 逐行拷贝
    BYTE* src = (BYTE*)ptr;
    BYTE* dst = (BYTE*)cimg.GetBits();
    int dstPitch = cimg.GetPitch();
    for (Hlong row = 0; row < h; row++) {
        memcpy(dst + row * dstPitch, src + row * lineBytes, w);
    }
    
    // 绘制到指定位置
    cimg.Draw(hdc, x, y);
    cimg.Destroy();
}

4.3.2 实战场景：MFC Picture Control显示

在MFC对话框应用中，通常使用Picture Control作为图像显示区域。在OnPaint或按钮事件中调用上述转换函数即可。但需要注意以下几点：

双缓冲：避免直接绘制到屏幕导致闪烁，应先在内存DC中绘制，再一次性BitBlt到屏幕。
缩放显示：使用StretchBlt实现图像缩放，但会损失性能，建议在非实时场景使用。
内存释放：CImage对象使用后必须调用Destroy，否则会造成GDI对象泄漏。

性能优化：对于实时相机采集场景，建议避免每次显示都重新创建CImage。可以预先创建好CImage对象，仅更新像素数据。同时，使用GetImagePointer1获取的指针是HALCON内部内存，直接读取即可，无需额外拷贝到临时缓冲区。

4.4 在Qt中显示HALCON图像

Qt以其跨平台特性和现代C++接口，在工业软件中越来越流行。在Qt中显示HALCON图像，核心是将HObject转换为QImage，再通过QPixmap显示在QLabel或自定义控件上。

4.4.1 核心原理：HObject到QImage

QImage支持多种像素格式，最常用的是Format_Grayscale8（8位灰度）和Format_RGB888（24位彩色）。转换时需要注意QImage默认使用4字节对齐，而HALCON的步长可能不同。

// 灰度图转换
QImage HalconToQImage(HObject &hoImg) {
    Hlong w, h, lineBytes, ptr;
    HString type;
    GetImagePointer1(hoImg, &ptr, &type, &w, &h, &lineBytes);
    
    QImage img((uchar*)ptr, (int)w, (int)h, (int)lineBytes, QImage::Format_Grayscale8);
    // 注意：这里直接共享内存，不拷贝数据。若HObject生命周期结束，img将失效。
    return img.copy();  // 深拷贝，确保安全
}

// RGB图转换（HALCON planar → QImage interleaved）
QImage HalconRGBToQImage(HObject &hoImg) {
    Hlong w, h;
    GetImageSize(hoImg, &w, &h);
    
    // 获取三个通道的指针
    Hlong rPtr, , bPtr;
    GetImagePointer3(hoImg, &rPtr, &, &bPtr, &type, &w, &h);
    
    QImage img((int)w, (int)h, QImage::Format_RGB888);
    const uchar* rSrc = (const uchar*)rPtr;
    const uchar* gSrc = (const uchar*);
    const uchar* bSrc = (const uchar*)bPtr;
    
    for (int y = 0; y < h; y++) {
        uchar* line = img.scanLine(y);
        for (int x = 0; x < w; x++) {
            line[x*3] = rSrc[y*w + x];   // R
            line[x*3+1] = gSrc[y*w + x]; // G
            line[x*3+2] = bSrc[y*w + x]; // B
        }
    }
    return img;
}

4.4.2 操作流程：在QLabel中显示

将QImage转换为QPixmap：QPixmap::fromImage(img)。
设置到QLabel：ui->label->setPixmap(pixmap)。
若需缩放，使用pixmap.scaled(label->size(), Qt::KeepAspectRatio)。

内存安全警告：上述灰度转换示例中，QImage直接使用了HALCON的内存指针。如果HObject在显示前被销毁或重新赋值，QImage将变成野指针。因此，在非性能敏感场景，务必使用.copy()进行深拷贝。对于实时显示，可以设计一个环形缓冲区，交替使用多个QImage对象。

4.5 常见误区与总结复盘

误区	后果	正确做法
忽略步长（LineBytes）	图像显示错位、倾斜	始终使用`GetImagePointer1`返回的步长进行行寻址
RGB通道顺序混淆	红蓝通道互换，颜色异常	HALCON为RGB顺序，Windows/Qt显示为BGR顺序，需转换
直接使用HObject内存构造QImage	悬垂指针，程序崩溃	使用深拷贝或确保HObject生命周期覆盖显示周期
未处理16位图像	显示为全黑或全白	判断`type`，对uint2图像进行缩放或映射到8位
在UI线程中执行大图像读取	界面卡顿，无响应	使用工作线程读取，通过信号/消息通知UI更新

总结复盘：图像读取与显示是HALCON集成的第一道关卡，其核心在于理解HALCON的内存模型与UI框架显示格式之间的差异。通过本章的学习，应掌握以下关键能力：

能够根据图像类型和通道数选择合适的转换策略。
熟练使用read_image及其变体处理批量读取需求。
在MFC和Qt中分别实现高效的图像显示，并注意内存管理和性能优化。
具备排查显示异常（如颜色错乱、图像倾斜、内存泄漏）的能力。

在下一阶段的开发中，建议将图像读取与显示封装为独立的模块，提供统一的接口，以便上层算法模块直接调用，降低耦合度。同时，对于高分辨率图像（如500万像素以上），应优先考虑使用GPU加速显示或降采样预览，以保证交互流畅性。