在 OpenCV 4.5 中使用 CvxText 绘制中文的适配指南

最近又有在图像上实时绘制汉字的需求。通常情况下，如果绘制汉字的需求不可避免，直接在图片上绘制是最为简便的实现方式，否则可能需要引入复杂的 GUI 组件。大家通常会选择 freetype + CvxText 这一经典方案。然而，在升级到 OpenCV 4.5 后，直接使用旧版 CvxText 代码会出现编译错误，需要进行一些必要的适配。

准备工作

项目依赖项如下：

• C/C++ 编译环境
• OpenCV 库
• FreeType 库：需提前编译，官网地址为 https://freetype.org/（本文使用版本为 2.9.1）
• 字体文件：如 simhei.ttf（可从系统字体目录中获取）

修改 CvxText 代码

我手头有一份在 OpenCV 3.x 下运行良好的 CvxText 代码。迁移至 OpenCV 4.5 时，主要存在以下几个兼容性问题。

1. OpenCV 头文件包含方式

OpenCV 4.x 对头文件目录结构进行了调整，移除了 opencv 子目录，统一规范为 opencv2。相关的头文件引用需修改如下：

#include "opencv2/core/core.hpp"
#include "opencv2/core/core_c.h"
#include "opencv2/highgui/highgui.hpp"
#include "opencv2/imgproc/imgproc.hpp"

特别注意，引入 core_c.h 非常关键，因为它提供了对旧式 C 类型（如 CvScalar 等）的兼容支持。

2. CvScalar 类型兼容问题

在 OpenCV 4.x 中，CvScalar 无法直接隐式转换为 C++ 的 cv::Scalar。在 putText 函数中，我们需要手动进行显式转换，代码如下：

int CvxText::putText(cv::Mat &frame, const char *text, CvPoint pos)
{
    CvScalar s = {255, 255, 255};
    return putText(frame, text, pos, s);
}

int CvxText::putText(cv::Mat &frame, const wchar_t *text, CvPoint pos)
{
    CvScalar s = {255, 255, 255};
    return putText(frame, text, pos, s);
}

3. cv::Mat 转 IplImage

旧版代码中直接使用 C 风格强制转换 &(IplImage)frame 在 OpenCV 4.x 中已失效。现在应使用 core_c.h 提供的 cvIplImage 函数进行转换：

IplImage* img = NULL;
img = &(cvIplImage(frame));

至此，代码即可正常运行。

调用方法

初始化：

CvxText text("path/to/your/font.ttf");

调用接口：

int putText(cv::Mat &frame, const char *text, CvPoint pos);

完整代码

以下是适配 OpenCV 4.5 的完整代码实现，理论上适用于所有 4.x 版本。

CvxText.h

#ifndef CVX_TEXT_H
#define CVX_TEXT_H

#include <ft2build.h>  
#include FT_FREETYPE_H  
#include "opencv2/core/core.hpp"
#include "opencv2/core/core_c.h"
#include "opencv2/highgui/highgui.hpp"
#include "opencv2/imgproc/imgproc.hpp"

class CvxText
{
    CvxText& operator=(const CvxText&);
public:
    CvxText(const char *freeType);
    virtual ~CvxText();

    void getFont(int *type, CvScalar *size = NULL, bool *underline = NULL, float *diaphaneity = NULL);
    void setFont(int *type, CvScalar *size = NULL, bool *underline = NULL, float *diaphaneity = NULL);
    void restoreFont();

    int putText(cv::Mat &frame, const char *text, CvPoint pos);
    int putText(cv::Mat &frame, const wchar_t *text, CvPoint pos);
    int putText(cv::Mat &frame, const char *text, CvPoint pos, CvScalar color);
    int putText(cv::Mat &frame, const wchar_t *text, CvPoint pos, CvScalar color);

private:
    void putWChar(cv::Mat &frame, wchar_t wc, CvPoint &pos, CvScalar color);

private:
    FT_Library   m_library;
    FT_Face      m_face;
    int          m_fontType;
    CvScalar     m_fontSize;
    bool         m_fontUnderline;
    float        m_fontDiaphaneity;
};

#endif

CvxText.cpp

#include "CvxText.h"
#include <wchar.h>  
#include <assert.h>  
#include <locale.h>  
#include <ctype.h> 

using namespace cv;

CvxText::CvxText(const char *freeType)
{
    assert(freeType != NULL);
    if (FT_Init_FreeType(&m_library)) throw;
    if (FT_New_Face(m_library, freeType, 0, &m_face)) throw;
    restoreFont();
    setlocale(LC_ALL, "");
}

CvxText::~CvxText()
{
    FT_Done_Face(m_face);
    FT_Done_FreeType(m_library);
}

void CvxText::getFont(int *type, CvScalar *size, bool *underline, float *diaphaneity)
{
    if (type) *type = m_fontType;
    if (size) *size = m_fontSize;
    if (underline) *underline = m_fontUnderline;
    if (diaphaneity) *diaphaneity = m_fontDiaphaneity;
}

void CvxText::setFont(int *type, CvScalar *size, bool *underline, float *diaphaneity)
{
    if (type && *type >= 0) m_fontType = *type;
    if (size) {
        m_fontSize.val[0] = fabs(size->val[0]);
        m_fontSize.val[1] = fabs(size->val[1]);
        m_fontSize.val[2] = fabs(size->val[2]);
        m_fontSize.val[3] = fabs(size->val[3]);
    }
    if (underline) m_fontUnderline = *underline;
    if (diaphaneity) m_fontDiaphaneity = *diaphaneity;
}

void CvxText::restoreFont()
{
    m_fontType = 0;
    m_fontSize.val[0] = 40;
    m_fontSize.val[1] = 0.5;
    m_fontSize.val[2] = 0.1;
    m_fontSize.val[3] = 0;
    m_fontUnderline = false;
    m_fontDiaphaneity = 1.0;
    FT_Set_Pixel_Sizes(m_face, (int)m_fontSize.val[0], 0);
}

int CvxText::putText(cv::Mat &frame, const char *text, CvPoint pos)
{
    CvScalar s = {255, 255, 255};
    return putText(frame, text, pos, s);
}

int CvxText::putText(cv::Mat &frame, const wchar_t *text, CvPoint pos)
{
    CvScalar s = {255, 255, 255};
    return putText(frame, text, pos, s);
}

int CvxText::putText(cv::Mat &frame, const char *text, CvPoint pos, CvScalar color)
{
    if (frame.empty() || text == NULL) return -1;
    int i;
    for (i = 0; text[i] != '\0'; ++i) {
        wchar_t wc = text[i];
        if (!isascii(wc)) mbtowc(&wc, &text[i++], 2);
        putWChar(frame, wc, pos, color);
    }
    return i;
}

int CvxText::putText(cv::Mat &frame, const wchar_t *text, CvPoint pos, CvScalar color)
{
    if (frame.empty() || text == NULL) return -1;
    int i;
    for (i = 0; text[i] != '\0'; ++i) {
        putWChar(frame, text[i], pos, color);
    }
    return i;
}

void CvxText::putWChar(cv::Mat &frame, wchar_t wc, CvPoint &pos, CvScalar color)
{
    IplImage* img = &(cvIplImage(frame));
    FT_UInt glyph_index = FT_Get_Char_Index(m_face, wc);
    FT_Load_Glyph(m_face, glyph_index, FT_LOAD_DEFAULT);
    FT_Render_Glyph(m_face->glyph, FT_RENDER_MODE_MONO);

    FT_GlyphSlot slot = m_face->glyph;
    int rows = slot->bitmap.rows;
    int cols = slot->bitmap.width;

    for (int i = 0; i < rows; ++i) {
        for (int j = 0; j < cols; ++j) {
            int off = ((img->origin == 0) ? i : (rows - 1 - i)) * slot->bitmap.pitch + j / 8;
            if (slot->bitmap.buffer[off] & (0xC0 >> (j % 8))) {
                int r = (img->origin == 0) ? pos.y - (rows - 1 - i) : pos.y + i;
                int c = pos.x + j;
                if (r >= 0 && r < img->height && c >= 0 && c < img->width) {
                    CvScalar scalar = cvGet2D(img, r, c);
                    float p = m_fontDiaphaneity;
                    for (int k = 0; k < 4; ++k)
                        scalar.val[k] = scalar.val[k] * (1 - p) + color.val[k] * p;
                    cvSet2D(img, r, c, scalar);
                }
            }
        }
    }
    double space = m_fontSize.val[0] * m_fontSize.val[1];
    double sep = m_fontSize.val[0] * m_fontSize.val[2];
    pos.x += (int)((cols ? cols : space) + sep);
}