CLIの使い方¶

YomiToku をコマンドラインインターフェース（CLI）として利用する場合の使い方について説明します。

初めてコマンドを実行する際は、HuggingFace Hubからモデルの重みファイルを自動でダウンロードします。その後、以下のコマンドを実行して文書画像の解析を行います。

yomitoku ${path_data} -v -o results

オプション名	説明
`${path_data}`	解析対象の画像が含まれたディレクトリか画像ファイルのパスを指定します。
`-o`, `--outdir`	出力ディレクトリを指定します（なければ作成）。
`-v`, `--vis`	解析結果の可視化画像を出力します。

補足: ${path_data} について

画像ファイルまたはディレクトリを指定可能です。
ディレクトリの場合はサブディレクトリ内も含めて再帰的に処理します。
対応ファイル形式は pdf、 jpeg、 png、 bmp、 tiff です。

Note

OCRには、文書OCRと情景OCR（看板や標識など、紙以外に印刷された文字のOCR）がありますが、YomiTokuは文書OCR向けに特化しています。
AI-OCRの精度は入力画像の解像度に大きく依存します。精度を高めるために、画像の短辺が1000px以上となるよう推奨します。

ヘルプの表示¶

利用可能なオプションの一覧を表示するには、以下のオプションを使います。

yomitoku --help
# または
yomitoku -h

ライセンスキーによる認証¶

コマンド実行時にライセンスキーとシークレットキーを直接指定することもできます。

yomitoku ${path_data} -k ${your_license_key} -s ${your_secret_key}

-k, --license_key: ライセンスキーを指定
-s, --secret_key: シークレットキーを指定

軽量モード（高速処理）¶

--liteオプションを使うと、軽量モデルを使用して高速に解析を実行できます。ただし、通常モードに比べて文字認識の精度が多少低下する場合があります。

yomitoku ${path_data} --lite -v

可視化画像の保存先指定¶

解析結果を可視化した画像の保存先を指定するには、--vis_dirを使用します。

yomitoku ${path_data} -f md -v --vis_dir ${folder_name}

出力フォーマットの指定¶

-fまたは--formatを使い、解析結果の出力フォーマットを指定できます。サポートされる形式はjson, csv, html, md, pdf (searchable-pdf)です。

yomitoku ${path_data} -f md

pdf を指定した場合、画像内の文字情報を透明なテキストとしてPDF内に埋め込み、検索可能なPDF（サーチャブルPDF）にします。

複数のフォーマットを同時に指定する場合は、コンマで区切って指定します。

yomitoku ${path_data} -f md,html,json,csv

推論デバイスの指定¶

-dまたは--deviceオプションを使い、モデルの実行デバイスを指定できます。指定可能な値はcuda, cpu, mpsです。デフォルトはcudaで、GPUが利用不可の場合は自動的にCPUが使われます。

yomitoku ${path_data} -d cpu

改行を無視した出力¶

通常、画像内の文字情報に従って改行しますが、--ignore_line_breakを指定すると、改行を無視して段落内の文章を繋げて出力します。

yomitoku ${path_data} --ignore_line_break

図やグラフ画像の抽出と保存¶

通常は文書内の図や画像を抽出しませんが、--figureを指定することで、図や画像を個別の画像として切り出し、保存します。さらに、出力ファイル内に個別画像へのリンクが記載されます。

yomitoku ${path_data} --figure

画像の保存フォルダを指定する場合は、--figure_dirを使います。

yomitoku ${path_data} --figure_dir ${folder_name}

--figure_dirに空文字を指定すると、画像は結果出力先フォルダ直下に保存されます。

yomitoku ${path_data} --figure_dir ""

図や画像内の文字を出力する¶

通常は図や画像内の文字情報は抽出されませんが、--figure_letterオプションを使うと、これらの文字情報も出力ファイルに含めることができます。

yomitoku ${path_data} --figure --figure_letter

出力ファイルの文字コード指定¶

出力ファイルの文字コードを--encodingで指定できます（対応コード: utf-8, utf-8-sig, shift-jis, enc-jp, cp932）。対応しない文字コードがある場合、その文字は無視されます。

yomitoku ${path_data} --encoding utf-8-sig

コンフィグファイルのパス指定¶

各モジュールの設定ファイル（yaml形式）のパスを指定できます。

オプション名	対象モデル
`--td_cfg`	Text Detector (文字位置の検知)
`--tr_cfg`	Text Recognizer (文字列認識)
`--lp_cfg`	Layout Parser (レイアウト解析)
`--tsr_cfg`	Table Structure Recognizer (表の構造認識)

例：

yomitoku ${path_data} --td_cfg ${path_yaml}

メタデータの非表示化¶

ヘッダーやフッターなどのメタ情報を出力しないように指定できます。

yomitoku ${path_data} --ignore_meta

PDF複数ページを1ファイルに統合する¶

PDFが複数ページの場合、すべてのページを1つの出力ファイルに統合できます。

yomitoku ${path_data} -f md --combine

書類の向きを自動補正する¶

横向き画像などの向きを検知し、自動的に補正してから処理します。

yomitoku ${path_data} --rotate_detection

認識方向フォールバックの有効化¶

デフォルトでは、認識方向フォールバックは無効化されています。--enable-rec-orientation-fallback オプションを使用することで、文字認識の信頼度が低い場合にROI画像を180度回転して再認識を行い、信頼度が高い方の結果を採用する機能を有効化できます。

yomitoku ${path_data} --enable-rec-orientation-fallback

--rec-orientation-fallback-thresh オプションで、フォールバックを実行する信頼度の閾値を指定できます。（デフォルト: 0.75）

yomitoku ${path_data} --enable-rec-orientation-fallback --rec-orientation-fallback-thresh 0.6

利用枚数（リクエスト数）の確認¶

ライセンスに紐づく利用枚数を確認できます。

query_count --license_key ${YOMITOKU_LICENSE_KEY} --secret_key ${YOMITOKU_SECRET_KEY}

各オプションは省略可能です（省略時は環境変数から取得されます）。

読み取り順序の指定¶

デフォルトでは読み取り順のオプションは auto に設定します。

auto が指定されている場合、システムは文書の向き（横書きか縦書きか）を識別し、読み取り順を自動で推定します。具体的には、横書きの文書は top2left 、縦書きの文書は top2bottom と推定されます。

通常は横書き・縦書きを自動識別しますが、読み取り順序を明示的に指定できます。

設定名	優先される読み取り順	有効なドキュメントのタイプ
`top2bottom`	上から下方向	段組みのワードドキュメントなど
`left2right`	左から右方向	レシートや保険証など、キーと値が段組みになっているレイアウト
`right2left`	右から左方向	縦書きのドキュメント

yomitoku ${path_data} --reading_order left2right

PDF出力の画質設定¶

サーチャブルPDFを出力する際の画質プリセットを --pdf_quality で指定できます。デフォルトは high です。

プリセット	長辺の最大サイズ	JPEG品質	説明
`high`	制限なし	85	高画質（デフォルト）。元画像の解像度を維持します。
`middle`	2000px	80	中画質。ファイルサイズと画質のバランスを取ります。
`low`	1500px	60	低画質。ファイルサイズを最小限に抑えます。

yomitoku ${path_data} -f pdf --pdf_quality middle

PDFの読み取り解像度の設定¶

PDFを読み取る際の解像度の大きさを設定します(標準DPI=200)。PDF内の文字が微細な場合など、細部の文字を読み取りたい場合にDPI値を上げることで読み取り精度が向上する場合があります。

yomitoku ${path_data} --dpi 250

ふりがな（ルビ）の除外¶

文書画像に含まれるふりがな（ルビ）テキストを出力から除外することができます。--ignore_ruby オプションを使用すると、各段落・セル内の文字の行高さの中央値に対して一定の閾値未満かつ、ひらがなのみ・カタカナのみで構成されるテキストをルビとみなし、除外します。

yomitoku ${path_data} --ignore_ruby

--ruby_threshold オプションで、ルビ判定の閾値を調整できます（デフォルト: 2.0）。値を大きくするとルビと判定される範囲が広がります。

yomitoku ${path_data} --ignore_ruby --ruby_threshold 3.0

読み取り対象ページを指定する¶

特定のページのみを対象として処理することが可能です。処理対象のページをコンマ区切りもしくは、ハイフンによって連続するページを指定できます。

yomitoku ${path_data} --pages 1,3-5,10

モデル名を指定し、実行する¶

特定のモデルを指定して、AI-OCRを実行することが可能です。tr_nameはテキストの認識モデル名、td_nameはテキストの検出モデル名を指定します。

yomitoku ${path_data} --tr_name parserqv4-short --td_name dbnet

モデル一覧とそれぞれの特長¶

カテゴリ	モデル名	バージョン	最大文字列長	対応文字種	特長・説明
テキスト認識	`parseqv3`	v1.3.0	100文字	活字 / 手書き	精度に最適化されたモデル。一般的な文書のOCRに高精度対応。
テキスト認識	`parseqv4`	v1.4.0	100文字	活字 / 手書き / 旧字 / 異体字	多様な日本語文字に対応した高精度モデル。旧字・異体字を含む文書に最適。（★ 標準）
テキスト認識	`parseqv4-short`	v1.4.0	75文字	活字 / 手書き / 旧字 / 異体字	処理速度と精度のバランスを重視したモデル。
テキスト認識	`parseqv4-tiny`	v1.4.0	50文字	活字 / 手書き / 旧字 / 異体字	CPU推論向けに最適化された高速モデル。軽量かつ高い汎用性。
テキスト認識	`parseqv4-large`	v1.6	100文字	活字 / 手書き / 旧字 / 異体字	大規模モデルによる高精度認識。言語モデルによる補正が強く、細部の文字・縦書き・記号の読み取り精度が向上。
テキスト検出	`dbnet`	v1.0.0	—	活字	活字文書の検出に最適化されたモデル。
テキスト検出	`dbnetv2`	v1.2.0	—	活字 / 手書き	活字と手書き文字の両方の検出に対応したモデル。
テキスト検出	`dbnetv2_1`	v1.6	—	活字 / 手書き	dbnetv2の改良版。細部の文字・縦書きテキスト・記号の検出精度を向上させたモデル。（★ 標準）