Cv2.PutText の使い方【OpenCV/C#】〜画像に文字を書き込む〜

Cv2.PutText は、Mat 画像の任意の座標にテキスト文字列を描画する関数です。フォント種別・サイズ・色・太さをパラメータで制御でき、検出結果のラベル表示やデバッグ用オーバーレイに幅広く使われます。

最小構成はこの1行です。

Cv2.PutText(img, "Hello OpenCV", new Point(30, 60), HersheyFonts.HersheySimplex, 1.5, Scalar.Red, 2);

動作環境

dotnet add package OpenCvSharp4
dotnet add package OpenCvSharp4.runtime.win

基本の使い方

using OpenCvSharp;

// 黒背景の画像を生成（高さ200・幅500・3チャンネル）
using var img = new Mat(200, 500, MatType.CV_8UC3, Scalar.Black);

// テキストを描画
Cv2.PutText(
    img,                          // 描画先の Mat
    "Hello, OpenCvSharp!",        // 表示する文字列
    new Point(30, 100),           // テキストの左下基点座標
    HersheyFonts.HersheySimplex,  // フォント種別
    1.5,                          // フォントスケール
    Scalar.White,                 // 文字色（BGR）
    2,                            // 線の太さ
    LineTypes.AntiAlias           // アンチエイリアス
);

// 結果を保存
Cv2.ImWrite("output.png", img);
Console.WriteLine("output.png を保存しました");

実行結果:

output.png を保存しました

黒背景に白字で “Hello, OpenCvSharp!” と書かれた 500×200 px の画像が生成されます。

各行の解説

• new Mat(200, 500, MatType.CV_8UC3, Scalar.Black) — 描画先の空画像を作成。using で確実に解放します。
• new Point(30, 100) — テキスト左下の基点座標です（左上ではない点に注意）。
• HersheyFonts.HersheySimplex — OpenCV に組み込まれた Hershey フォントを指定します。
• 1.5 — フォントスケール。1.0 が基準サイズで、比例して拡縮します。
• LineTypes.AntiAlias — アンチエイリアスを有効にすると文字が滑らかになります。

引数と戻り値

戻り値: なし（void）

主な HersheyFonts 一覧

実践例

例1: 文字をバウンディングボックス付きで中央揃えに描画する

検出ラベルを矩形の上に重ねる典型パターンです。Cv2.GetTextSize でテキストサイズを取得してから座標を計算します。

using OpenCvSharp;

using var img = new Mat(300, 500, MatType.CV_8UC3, new Scalar(40, 40, 40));

string label = "Person: 98%";
double fontScale = 0.8;
int thickness = 2;
var fontFace = HersheyFonts.HersheySimplex;

// バウンディングボックス（仮）
var box = new Rect(80, 80, 340, 180);
Cv2.Rectangle(img, box, Scalar.LimeGreen, 2);

// テキストサイズを取得して左上に配置
int baseline;
var textSize = Cv2.GetTextSize(label, fontFace, fontScale, thickness, out baseline);

// ラベル背景の矩形
var labelBg = new Rect(box.X, box.Y - textSize.Height - 8, textSize.Width + 4, textSize.Height + 8);
Cv2.Rectangle(img, labelBg, Scalar.LimeGreen, -1); // 塗りつぶし

// ラベルテキスト（背景の上に黒文字）
Cv2.PutText(
    img, label,
    new Point(box.X + 2, box.Y - 4),
    fontFace, fontScale,
    Scalar.Black, thickness, LineTypes.AntiAlias
);

Cv2.ImWrite("labeled.png", img);
Console.WriteLine("labeled.png を保存しました");

実行結果:

labeled.png を保存しました

緑の矩形の左上に “Person: 98%” のラベルが背景付きで描画されます。

例2: 複数行テキストを等間隔で描画する

Cv2.PutText は改行を扱えないため、行ごとに Y 座標をずらして呼び出します。

using OpenCvSharp;

using var img = new Mat(300, 500, MatType.CV_8UC3, Scalar.Black);

string[] lines = { "OpenCV Version: 4.x", "Lang: C# (OpenCvSharp)", "Module: imgproc" };
double fontScale = 0.7;
int lineHeight = 40; // 行間（ピクセル）

for (int i = 0; i < lines.Length; i++)
{
    Cv2.PutText(
        img, lines[i],
        new Point(20, 60 + i * lineHeight),
        HersheyFonts.HersheySimplex, fontScale,
        Scalar.Cyan, 1, LineTypes.AntiAlias
    );
}

Cv2.ImWrite("multiline.png", img);
Console.WriteLine("multiline.png を保存しました");

実行結果:

multiline.png を保存しました

3行のテキストが 40px 間隔で縦に並んで描画されます。

つまずきポイント

⚠️ テキストの基点は「左下」

org に指定した座標はテキストの左下角です。左上を基準にしたい場合は、Cv2.GetTextSize で高さを取得し org.Y += textSize.Height を加算して調整してください。最初に「文字が上にはみ出る」と感じたらこれが原因です。

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

Hershey フォントは ASCII のみ対応です。日本語を描画したい場合は、一度 System.Drawing や SkiaSharp で文字をビットマップに描いてから Mat に合成するアプローチが必要です。Cv2.PutText に日本語文字列を渡しても文字化けまたは何も表示されません。

⚠️ Mat の Dispose 漏れに注意

Mat は IDisposable を実装しており、Dispose を忘れるとネイティブメモリがリークします。必ず using ブロック（または using var）でスコープ管理してください。本記事のサンプルコードはすべて using var で記述しています。

関連する関数

• Cv2.GetTextSize — テキストの描画サイズ（幅・高さ）を事前に取得する。ラベル背景の矩形計算に必須。
• Cv2.Rectangle — 矩形を描画する。ラベル背景や検出枠との組み合わせで使われる。
• Cv2.Line / Cv2.Circle / Cv2.Ellipse — 同じ imgproc モジュールの描画系関数。テキストと組み合わせてアノテーション画像を構成する。

まとめ

Cv2.PutText は HersheyFonts と fontScale を組み合わせるだけで手軽に文字描画が実現できます。テキストの基点が「左下」である点と、日本語非対応である点を押さえておけば、検出ラベルや診断オーバーレイへの応用がスムーズに進みます。複数行・背景付きレイアウトには Cv2.GetTextSize を併用するのが実務での定番パターンです。