OpenCV/C++ putText の使い方 〜画像に文字を書き込む〜

cv::putText は画像上に文字列を描画する OpenCV の関数です。デバッグ用ラベルの重ね書きから推論結果の可視化まで、実務でほぼ毎日使います。最小コードはこれだけです。

cv::putText(img, "Hello", cv::Point(10, 50),
            cv::FONT_HERSHEY_SIMPLEX, 1.5, cv::Scalar(0, 255, 0), 2);

動作環境

基本の使い方

#include <opencv2/opencv.hpp>
#include <iostream>

int main()
{
    // 白地の画像を用意（実務では imread した画像を使う）
    cv::Mat img(200, 500, CV_8UC3, cv::Scalar(255, 255, 255));

    // cv::putText で文字を描画
    // 第3引数の cv::Point は文字列の「左下」座標
    cv::putText(
        img,
        "Hello, OpenCV!",
        cv::Point(20, 120),
        cv::FONT_HERSHEY_SIMPLEX,  // フォント種別
        2.0,                        // フォントスケール
        cv::Scalar(0, 0, 200),      // 色（BGR）
        3,                          // 線の太さ
        cv::LINE_AA                 // アンチエイリアス
    );

    cv::imshow("putText sample", img);
    cv::waitKey(0);
    return 0;
}

実行結果

白地の 500x200 ウィンドウに、左下頂点 (20, 120) を起点とした
赤文字「Hello, OpenCV!」が描画されます。

コードの解説

引数と戻り値

void cv::putText(
    InputOutputArray img,
    const String&    text,
    Point            org,
    int              fontFace,
    double           fontScale,
    Scalar           color,
    int              thickness  = 1,
    int              lineType   = LINE_8,
    bool             bottomLeftOrigin = false
);

主なフォント種別

戻り値は void です。

実践例

例1: 画像に検出ラベルを重ねて表示する

物体検出などで検出結果をそのまま画像に書き込む典型パターンです。

#include <opencv2/opencv.hpp>
#include <iostream>
#include <string>

int main()
{
    cv::Mat img = cv::imread("input.jpg");
    if (img.empty()) {
        std::cerr << "画像を読み込めませんでした" << std::endl;
        return 1;
    }

    // バウンディングボックスとラベルを描画
    cv::Rect bbox(50, 80, 200, 150);
    std::string label = "Cat: 92%";

    cv::rectangle(img, bbox, cv::Scalar(0, 200, 0), 2);
    cv::putText(
        img,
        label,
        cv::Point(bbox.x, bbox.y - 8),  // ボックスの少し上に配置
        cv::FONT_HERSHEY_SIMPLEX,
        0.7,
        cv::Scalar(0, 200, 0),
        2,
        cv::LINE_AA
    );

    cv::imshow("detection", img);
    cv::waitKey(0);
    return 0;
}

cv::Point(bbox.x, bbox.y - 8) のように Y 座標をボックス上辺より少し上にずらすと、ラベルがボックス内に被らず視認しやすくなります。

例2: cv::getTextSize でテキストを中央揃えする

putText 単体では中央揃えができないため、cv::getTextSize でテキスト幅を事前に取得し、X 座標を計算します。

#include <opencv2/opencv.hpp>
#include <iostream>
#include <string>

int main()
{
    cv::Mat img(200, 640, CV_8UC3, cv::Scalar(30, 30, 30));

    std::string text = "FONT_HERSHEY_SIMPLEX";
    int fontFace = cv::FONT_HERSHEY_SIMPLEX;
    double fontScale = 1.2;
    int thickness = 2;
    int baseline = 0;

    // テキストの描画サイズを取得
    cv::Size textSize = cv::getTextSize(text, fontFace, fontScale, thickness, &baseline);

    // 画像中央に配置するための左下座標を計算
    cv::Point org(
        (img.cols - textSize.width) / 2,
        (img.rows + textSize.height) / 2
    );

    cv::putText(img, text, org, fontFace, fontScale,
                cv::Scalar(200, 200, 200), thickness, cv::LINE_AA);

    cv::imshow("center align", img);
    cv::waitKey(0);
    return 0;
}

640x200 の黒背景中央に「FONT_HERSHEY_SIMPLEX」がグレー文字で表示されます。

つまずきポイント

⚠️ 座標は「左下」頂点

cv::rectangle の org が左上なのに対し、cv::putText の org は文字列の左下です。cv::Rect に揃えるつもりで bbox.tl() をそのまま渡すと、文字がボックスより上にはみ出します。上の例1のように -8 などのオフセットを意識して調整してください。

⚠️ 日本語・マルチバイト文字は描画できない

cv::putText が扱えるのは ASCII 文字のみです。日本語を描画しようとすると文字化けするか、何も表示されません。日本語を描画するには FreeType を使う cv::freetype::FreeType2 モジュール（opencv_contrib に含まれる）が必要です。計測結果や UI テキストに日本語が必要な場合はあらかじめ設計に組み込んでおきましょう。

⚠️ fontScale はピクセル指定ではない

fontScale はベースフォントサイズへの倍率であり、ピクセル数の直接指定ではありません。「○○px の文字を描きたい」場合は cv::getTextSize で試しながら調整するか、目的のピクセル高から逆算する必要があります。

関連する関数

• cv::getTextSize — 描画前にテキストの幅・高さを取得する。中央揃えや背景矩形の生成に必須
• cv::rectangle — テキスト背景に塗り潰し矩形を描く際にセットで使う
• cv::line / cv::circle — 図形描画と組み合わせてアノテーション画像を作成する

まとめ

• cv::putText の org は文字列の左下座標。cv::Rect の左上と混同しないよう注意する。
• フォントは cv::FONT_HERSHEY_SIMPLEX が最もよく使われる。アンチエイリアスをかけるには cv::LINE_AA を明示する。
• 日本語描画は標準の putText では不可。opencv_contrib の FreeType モジュールが必要になる。