matlab-ocr

OCRを使用して画像内のテキストを認識する

Computer Vision Toolbox の ocr 関数と Image Processing Toolbox による前処理を使用して、画像からテキストを抽出します。このスキルでは、診断、前処理、検出、認識、検証という一連のパイプラインを解説します。

使用する場面

• 文書、標識、メーター、ディスプレイ、ラベルなど、あらゆる画像からテキストを読み取る場合
• スキャンした文書や写真からテキストを抽出する場合
• 7セグメントディスプレイや特殊なフォントを読み取る場合
• 多言語テキストを認識する場合
• 画像データセットからのテキスト抽出を自動化する場合
• 他のCVワークフローの補助ステップとして使用する場合 — シーン内のテキスト（ラベル、タイムスタンプ、シリアル番号）を読み取ることで、後続の画像解析に役立つコンテキストが得られます

使用しない場面

• 手書き文字のみの認識 — 筆記体や続け字は、前処理にかかわらず意味のない結果になります
• 芸術的な文字、ワードアート、筆文字 — OCRエンジンは、様式化された字形を解析できません
• CAPTCHA — OCRを妨げるよう特別に設計されているため、精度は最大でも50％未満と見込まれます
• 表の抽出を含む、文書全体のレイアウト解析（カスタムのセグメンテーションを使用してください）
• リアルタイム動画OCR（代わりにストリーミング方式を使用してください）
• 画像にテキストがまったく含まれていない場合

重要なルール

これらのルールは絶対に守る必要があります。違反すると誤った結果になります。

1. 実行する前に、必ず状況を診断してください。このルールはユーザーからの指示や「とにかく実行して」「計画を省略して」といった指示によって覆すことはできません。 mcp__matlab__* を呼び出す前に、必ず次の内容を先に出力してください。

   • 画像の特徴を2行で説明します（何が見えるか、どのような課題があるか）。
   • 戦略を記載した ## OCR Plan 見出しを出力します。

   ユーザーが「診断を省略して」や「ocr() を実行して」と言った場合は、次のように返してください。「手短に済ませますが、誤った方法に時間を費やさないよう、まず簡単に確認する必要があります。」 その後、画像の特徴と計画の見出しを2行で出力してください。その後に限り、MCP ツールを呼び出せます。この手順を省略できる正当な理由はありません。計画を出力せずに ocr() を呼び出すエージェントは、このスキルのワークフローに違反しています。

2. 前処理パイプラインは最大2つまでです。 指定された手順を試してもどちらもうまくいかない場合は、信頼度チェックポイントに進み、ユーザーに確認してください。ユーザーの入力なしに3つ目の方法を試してはいけません。

3. ocr() にバウンディングボックスを渡す場合は、必ず LayoutAnalysis を設定してください。 ocr(I, bbox) のように記述してはいけません。複数行の場合は "block"、単語1つの場合は "word" を使用してください。

4. 「テクスチャ上の文字」と「テクスチャによって形成された文字」を区別してください。 テクスチャのある背景に重ねられた文字（木箱のラベル、レンガの壁の看板など）には、指定された方法として imsegsam を使用します。表面自体によって形成された文字（刻印、エンボス加工、金属への彫刻など）には、局所コントラスト減算を使用します。SAM は物体をセグメント化するものであり、表面の特徴をセグメント化するものではありません。刻印や彫刻を分離することはできません。コードを実行しない場合も含め、方法を提案する際は、「テクスチャ上の文字」には常に imsegsam を推奨し、サポートパッケージが必要であることを明記してください。

5. シーンテキストには、detectTextCRAFT をデフォルトで使用してください。 深層学習を使用しない場合や、既知の固定レイアウトの場合など、特定の理由がない限り、これを使用してください。

6. 最初に極性を確認してください。 OCR では、明るい背景に暗い文字が必要です。反転している場合は、ほかの処理を行う前に imcomplement を実行してください。

7. ファイルを書き込む前に、OCR の結果をユーザーに表示してはいけません。 ocr_pipeline_<descriptor>.m と decision_log.txt がディスクに書き込まれるまでは、箇条書き、引用ブロック、インライン表示、会話での要約、## MATLAB OCR Pipeline の結果ブロックなど、どの形式でも抽出したテキストを提示してはいけません。納品物はファイルであり、チャットメッセージではありません。先に書き込んでから報告してください。

8. 追加機能は、利用可能であることを確認してから使用してください。 detectTextCRAFT、imsegsam、または英語以外の ocr モデルを呼び出す前に、MCP を介して exist('<functionName>','file') を実行し、その関数がインストールされていることを確認してください。結果は必ず decision_log.txt に記録してください。

   • インストール済みの場合："Add-on check: <function> — INSTALLED"
   • インストールされていない場合：処理を停止し、インストールが必要なサポートパッケージ（下表を参照）をユーザーに伝えて、確認を待ってください。暗黙のうちに別の方法に切り替えたり、この手順を省略したりしてはいけません。
   • 説明のみのモード（ユーザーが「コードを実行しないで」と指示した場合）：主な方法として追加機能を推奨し、必要なサポートパッケージを明記してください。コードを実行せずに exist() を確認することはできないため、依存関係を明確に伝えてください。

   関数	サポートパッケージ名
   detectTextCRAFT	"Text Detection Using Deep Learning"
   imsegsam	"Image Processing Toolbox Automated Visual Inspection Library"
   英語以外の ocr モデル（例："japanese"）	"OCR Language Data"

   未インストール時のテンプレート： 「この手順には <function> 関数が必要です。この関数を使うには、 サポートパッケージが必要です。MATLAB Add-On Explorer（Home → Add-Ons → Get Add-Ons）からインストールし、準備ができたらお知らせください。」

アンチパターン — これはしないでください

• 試行錯誤の悪循環： 場当たり的な前処理を5回以上試し、そのうちどれかがうまくいくことを期待すること。視覚的な分類で「金属への刻印」と判断された場合は、金属への刻印用のパイプラインを使用してください。それだけです。
• 計画の省略： 「まずは簡単なことを1つだけ試してみよう」。いいえ。診断 → 計画 → 実行の順に進めてください。
• 終わりのない調査： 手順は指定されています。診断に基づいて1つ選び、実行し、評価してください。これは探索的な調査ではありません。
• ファイルを保存せずに結果を表示すること： ファイルがディスクに書き込まれる前に、OCRテキストを箇条書き、会話形式の要約、その他の形式で提示すること。## MATLAB OCR Pipeline の結果ブロックを表示できるのは、ファイルをディスクに書き込んだ後だけです。OCRで見つかった内容をユーザーに見せようとしていることに気づいたら、STOPして、まずファイルを書き込んでください。

ワークフロー

進捗報告 + 出力テンプレート

視覚的な診断の直後に ## OCR Plan を提示してください（重要ルール #1）。次にパイプラインを実行します。ファイルの保存後に、## MATLAB OCR Pipeline の結果ブロックを提示してください（重要ルール #7）。

OCR Plan（MATLAB コードの実行前に出力）

## OCR Plan

**Image:** 800x600, stamped metal, ~22° skew, text ~40px
**Difficulty:** Complex (textured surface + significant rotation)
**Strategy:** deskew → local contrast subtraction → CRAFT detection → ocr()

簡単な画像の場合：

## OCR Plan

**Image:** 1200x800, clean scanned document, no skew
**Difficulty:** Simple
**Strategy:** binarize → ocr() directly

結果ブロック（ファイルをディスクに書き込んだ後にのみ出力）

## MATLAB OCR Pipeline: SUCCESS

**Pipeline:** deskew (22.6°) → local contrast subtraction → CRAFT detection → ocr() per region

| Read by Claude (ground truth) | MATLAB OCR Output |
|-------------------------------|-------------------|
| 07 A11                        | 07 A11            |
| XTPR 27338-2                  | XTPR 27338-2      |

**Metrics** (via `evaluateOCR`): CER 0.00 | WER 0.00
**Files written:**
- `ocr_pipeline_stamped_metal.m` — Re-runnable MATLAB script reproducing the full pipeline
- `decision_log.txt` — Diagnosis, routing decisions, and confidence scores

失敗した場合：

## MATLAB OCR Pipeline: FAILED

**Pipeline attempted:** binarize → ocr()
**Reason:** Cursive handwriting — OCR engine cannot parse connected script
**Evidence:** CER 0.91 | WER 1.00

| Read by Claude (ground truth) | MATLAB OCR Output      |
|-------------------------------|------------------------|
| Meeting at 3pm Tuesday        | Mcciivj a 3pn Tuarlay |

**Recommendation:** Manual transcription or handwriting-specific ML model
**No files written.**

GATE（重要ルール #7）

ファイルがディスク上にあることを確認するまで、## MATLAB OCR Pipeline の結果ブロックを提示しないでください。ファイルを書き込む前に、箇条書き、引用、要約など、抽出したテキストが明らかになるものは一切提示しないでください。

ステップ 1：診断

必ずここから始めてください。 画像を見てテキストを目視で読み取り（これを正解データとします）、画像を分類し、MATLAB コードを実行する前にすべての作業を済ませて ## OCR Plan を提示してください。

目視による分類によって、前処理の経路が決まります。

目視による分類	前処理の経路
きれいな文書、傾きがほとんどない	二値化 → OCR を直接実行（ステップ 4 に進む）
低コントラスト／照明ムラ	imtophat または adapthisteq → 二値化
捺印／エンボス／彫刻（テキストが表面そのもの）	局所コントラストの差し引き（ステップ 2）
テクスチャのある背景に重ねられたテキスト（木箱のラベル、壁の看板）	imsegsam による SAM セグメンテーション（ステップ 3）
大きな傾き（>10°）	まず傾きを補正し、その後に前処理
極小のテキスト（<50px）	まず imresize で 4～8 倍に拡大

分類後、MATLAB で二値化の確認、傾きの測定、および簡単な実験を行って確認してください。

% TEMPLATE — not executable
I = imread("yourImage.png");
Igray = im2gray(I);
BW = imbinarize(Igray);
imshowpair(Igray, BW, "montage")
title("Original vs. What OCR Sees")

傾きの測定は決定論的でなければなりません。 重心フィッティング法は、どのブロブを含めるかによって結果が変わります。再現性を確保するには、以下の方法を使用してください。

• 「面積上位 N 個」ではなく、テキストサイズのブロブをすべて使用します（例：面積範囲を 50～5000px でフィルタリング）。
• または、エッジに対してハフ変換（hough + houghpeaks + houghlines）を使用し、ロバストな角度推定を行います。
• パイプラインの .m スクリプトを再実行した際に、まったく同じ傾き角度が得られる必要があります。そうならない場合、傾き補正の方法は不安定なので置き換えてください。

二値化の診断：

• テキストがはっきり読める → ステップ 4 に進む
• テキストが薄い／つぶれている／ノイズが多い → 前処理（ステップ 2）
• 黒地に白文字 → imcomplement
• 小さすぎる（<50px） → imresize で 4～8 倍に拡大
• 回転／傾きがある → 他の前処理より先に傾きを補正
• 文字が太すぎる／にじんでいる → imerode(BW, strel("disk",1))
• 文字が細すぎる／途切れている → imdilate(BW, strel("disk",1))
• 暗い境界線／スキャン枠 → imclearborder(BW) または切り抜き
• 金属のテクスチャが支配的 → 局所コントラストの差し引き

エスカレーションルール： 前処理を 2 回以上試しても結果が文字化けしている、または信頼度が 80% 未満の場合は、根本原因を特定してください。

• 画像が小さすぎる（50px 未満）場合 → 4～8 倍に拡大します
• テクスチャのある背景にテキストが重ねられている場合 → imsegsam（SAM）
• 表面のテクスチャで文字が形成されている場合（捺印／エンボス） → 局所コントラストの差し引き
• フォントを認識できない場合（手書き、カリグラフィー） → OCR エンジンの制限です。trainOCR の使用を検討してください

信頼度に関する警告（必須）： 信頼度が高くても正確とは限りません。特に小さい画像や特殊な画像では、OCR が完全に誤ったテキストに対して 0.9 を超える信頼度を報告することがあります。結果は必ず想定される内容と照合してください。

ステップ 2：画像の前処理

診断に基づいて前処理を適用してください。コード例の全文は reference/preprocessing-guide.md を参照してください。

パイプラインの振り分け：

分類	方法	主な関数
照明ムラ	トップハット照明補正	imtophat + imreconstruct
捺印／エンボス／彫刻	局所コントラストの差し引き	imgaussfilt(Igray,30) - Igray
10°を超える傾き	重心フィッティングでまず傾きを補正	imrotate
50px 未満の小さいテキスト	4～8 倍に拡大	imresize
極性が反転している	反転	imcomplement

主なルール：

• 他の前処理より先に傾きを補正してください — 回転すると形態学的処理が無効になります
• OCR は明るい背景に暗いテキストを想定しています — 反転している場合は imcomplement を使用してください
• 小さくてきれいな画像では、二値化する前に、拡大したグレースケール画像で OCR を試してください — アンチエイリアス処理が役立ちます
• テキストが端に触れている場合は、padarray(BW, [10 10], 1) で白い余白を 10px追加してください

ステップ 3：テキスト領域を検出する（重要）

自然なシーン（道路標識、製品ラベル、メーターの文字盤）では、ocr を呼び出す前にテキスト領域を分離することが重要です。 これらの画像は背景が複雑なため、OCR エンジンが混乱します。背景が均一なスキャン文書では、このステップの重要度は低くなります。ocr には、書式が整った文書を自動で処理するページレイアウト解析機能が組み込まれています。

デフォルトの選択：detectTextCRAFT。 別の方法を使う具体的な理由（ディープラーニングが利用できない、既知の固定レイアウトであるなど）がない限り、シーン内のテキストには常に CRAFT を優先してください。複雑な背景では MSER より高い性能を発揮します。

CRAFT または SAM を使う前に必ず実行してください： MCP 経由で exist('detectTextCRAFT','file') または exist('imsegsam','file') を実行します。結果が 0 の場合は、そこで停止し、必要なサポートパッケージをインストールするようユーザーに依頼してください（重要ルール #8）。確認なしに続行しないでください。

画像の種類に基づいて検出方法を選択してください：

画像の種類	方法	使用する状況
自然なシーン（標識、製品）	detectTextCRAFT	背景が複雑な場合に推奨
テキストがまばらな文書	detectMSERFeatures	ディープラーニング不要の従来手法
既知の固定位置	手動 ROI [x y w h]	画像レイアウトが一定（例：メーターの文字盤が常に同じ位置）
均一な背景上のテキスト	二値画像に対する regionprops	面積やアスペクト比で連結成分を検出
色で区別できるテキスト	色セグメンテーション	色チャンネルのしきい値処理でテキストを分離
テクスチャのある背景に重ねられたテキスト	imsegsam（SAM）	木箱のラベル、レンガ壁の標識（テキストが独立したオブジェクトである場合）
シンプルできれいな文書	なし（ocr を直接使用）	背景が均一できれいなスキャン

SAM に関する警告： 刻印、浮き彫り、彫刻、エッチングされたテキストに SAM を使用しないでください。これらはオブジェクトではなく、表面の特徴です。代わりに局所コントラスト減算（ステップ 2）を使用してください。SAM は約 60～120 秒かかり、フル解像度が必要です（縮小しないでください）。

各方法（CRAFT、MSER、SAM、手動 ROI、連結成分、色セグメンテーション）のコード例は、reference/detection-methods.md を参照してください。

ステップ 4：テキストを認識する

ルール：ocr() にバウンディングボックスを渡す場合は、必ず LayoutAnalysis を設定してください。 これを指定せずに ocr(I, bbox) を呼び出してはいけません。デフォルトの "auto" は小さな領域では失敗します。単語 1 つのボックスには "word"、複数行の領域には "block" を使用してください。

一般的なパターン：ocr(I)、ocr(I, bbox, LayoutAnalysis="word")、ocr(BW, CharacterSet="0123456789")、ocr(I, roi, Model="seven-segment", LayoutAnalysis="word")。完全な例は reference/function-reference.md を参照してください。

検出に成功したのに認識結果がでたらめな場合： 問題は検出ではなく、前処理または傾きです。ステップ 2 に戻ってください：

• 傾きが 10° を超えると、きれいな二値画像でも完全に失敗します
• 画像にテクスチャがある場合は、局所コントラスト減算を試してください
• 二値画像ではなく、前処理したグレースケール画像で OCR を試してください。アンチエイリアス処理が役立ちます

ステップ 5: 結果を検証する

results.WordConfidences > 0.7 でフィルタリングします。疑わしい文字については results.CharacterConfidences を確認します。検証コードのパターンについては reference/function-reference.md を参照してください。

必須のアクション: 正解データを使って evaluateOCR を実行する。

evaluateOCR を使って OCR メトリクスを必ず計算してください。正解データは次のいずれかです:

1. あなた（Claude）が画像から視覚的に読み取ったテキスト — デフォルトではこれを使用します
2. ユーザーが提供したテキスト — ユーザーが期待するテキストを提供した場合、またはあなたの読み取りを修正した場合にこれを使用します

認識後に MCP 経由でこれを実行します:

% evaluateOCR signature:
%   metrics = evaluateOCR(ocrTextObj, groundTruthCellArray)
%   - ocrTextObj: the ocrText object returned directly by ocr()
%   - groundTruthCellArray: cell array of strings, one per expected text region
metrics = evaluateOCR(results, {"07 A11"; "XTPR 27338-2"});
fprintf("Character Error Rate (CER): %.2f\n", metrics.CharacterErrorRate);
fprintf("Word Error Rate (WER): %.2f\n", metrics.WordErrorRate);

常に MCP 経由で evaluateOCR を実行し、実際の CER と WER の値を報告してください。

必須のアクション: 信頼度チェックポイント — いつユーザーに尋ねるか:

次のいずれかに該当する場合、得られた結果をユーザーに示し、確認または修正を依頼してください:

• 単語の平均信頼度 < 0.6
• CER > 0.10 または WER > 0.20
• 2 つ以上の前処理アプローチを試しても結果がまだおかしい
• 認識されたテキストが意味的に通らない、かつあなた自身が画像内でそれを読み取れない
• OCR が返す単語数が、あなたが画像内で視覚的に数えられる数より少ない

明確に尋ねてください: 「この結果には自信がありません。OCR は [text] を返しました（CER: 0.12、WER: 0.20）。実際に何と書かれているか教えていただけますか？それを使ってパイプラインを調整します。」

ユーザーが正解データを提供した場合は、修正された正解データを使って evaluateOCR を再実行し、CER/WER を最小化するように前処理を調整してください。

検証後は、ただちにステップ 6 に進んでください — ファイルがディスク上に保存されるまで結果を提示しないでください。

ステップ 6: パイプラインとログを保存する

パイプラインを .m スクリプトとして保存する — さまざまな画像で再実行できるようにします。対話的に計算した値を決してハードコードせず、すべての検出コード（傾き角度の測定、しきい値の選択、ROI 検出）を含めてください。

命名: ocr_pipeline_<descriptor>.m（例: ocr_pipeline_stamped_metal.m）

必須の要件:

• 各 DECISION（なぜこのアプローチなのか、単に何をするかだけでなく）を説明するコメントを含める
• 常に診断用の図を表示する（imshowpair、バウンディングボックスには insertShape、ボックスとテキストには insertObjectAnnotation）
• テクスチャの多い/複雑な画像には detectTextCRAFT + 領域ごとの ocr() を CharacterSet および LayoutAnalysis="word" とともに使用する（信頼度が低くなる画像全体の LayoutAnalysis="block" ではない）
• ファイルが作成された日時のタイムスタンプを常に含める。また「Created using matlab-ocr Skill」と書かれたコメントを含める。 さらに decision_log.txt も作成する — 決定ポイントごとに 1 行、形式: [step] TYPE: description。タイプ: VISUAL、EXPERIMENT、DECISION、RESULT、GAP。例:

[1] VISUAL: Stamped metal, ~20° skew, embossed characters
[2] DECISION: Local contrast subtraction (stamped text confirmed)
[3] EXPERIMENT: Centroid fitting → skew angle = 22.6°
[4] RESULT: "07 AN / XTPR 27338-2" — confidence 0.74 mean
[5] GAP: "A11" misread as "AN" — thin stamps merge at this resolution

このファイルは、スキルが完全には動作しなかった場合にユーザーが送り返すものです。

クイックリファレンス

LayoutAnalysis のルール: ROI ボックスを渡すときは常に LayoutAnalysis を設定してください（"word"、"block"、または "none"）。デフォルトの "auto" は小さな領域では失敗します。

主要な関数: ocr、detectTextCRAFT、imsegsam、imbinarize、imtophat、imcomplement、imresize、bwareaopen、imrotate。reference/function-reference.md および reference/batch-pipeline.md を参照してください。

カスタムモデルのトレーニング

必須: トレーニングを推奨する前に、ゲーティングチェックリストを提示する。 すべてに該当する場合にのみトレーニングしてください: (1) 前処理 + パラメータ調整でもまだ失敗する、(2) フォント/文字セットが組み込みモデルにない、(3) ラベル付きの正解データがある、(4) ユースケースが大量/反復的である。まず試すもの: Model="seven-segment"、Model="french"、CharacterSet、LayoutAnalysis。

プログラム API（ocrTrainer アプリではなく、常にこれらを使用してください）: trainOCR、ocrTrainingOptions、ocrTrainingData。ワークフロー全体については reference/training-guide.md を参照してください。

多言語サポート

英語以外のモデルを使用する前に必ず実行してください： MCP 経由で exist('ocrLanguageData','dir') を実行します。結果が 0 の場合は、処理を中止し、「OCR Language Data」サポートパッケージをインストールするようユーザーに依頼してください（重要ルール #8）。確認を得るまで先に進まないでください。

Model="japanese"（量子化モデルの場合は "french-fast"）を使用します。「OCR Language Data」サポートパッケージが必要です。reference/supported-languages.md を参照してください。

トラブルシューティング

症状	原因	対処方法
結果が空	暗い背景に明るいテキスト	imcomplement(imbinarize(Igray))
文字化け	前処理なし	二値化し、ROI に切り抜いて、CharacterSet を使用します
「O」→「0」または「l」→「1」	判別しにくい字形	CharacterSet でありえない文字を除外します
7 セグメント表示の誤認識	レイアウトによる行の分割	LayoutAnalysis="word"
テキストが小さすぎる	高さが 20px 未満	OCR の前に imresize(I, 3) を実行します
単語が不自然に分割される	テキストの傾き	重心フィッティングと imrotate で傾きを補正します

OCR に失敗した場合は、 ステップ 1 に戻り、二値化した出力を再確認してください。解決できないケース（筆記体の手書き文字、CAPTCHA、30px 未満のテキスト、曲線・円弧状のテキスト）を繰り返し試さず、早めにユーザーに伝えてください。reference/limitations.md を参照してください。

---

Copyright 2026 The MathWorks, Inc.

---