UTF-8 の YAML を --config で読み込む。# のコメントを記載でき、必要なキーだけ指定できる。入力ファイルを自動で書き戻すことはない。すべての実効値を JSON / HTML の「使った設定」に記録する。全体補正は明示的に有効化する場合だけ実行する。
.\reportdiff.exe compare old.pdf new.pdf --out result --config examples/settings.yaml数値の制限は入力の妥当性を検証するためのもので、速度・メモリの保証ではない。高 DPI・大きい探索距離・出力上限は処理量を増やす。調整時は新しい出力フォルダを指定し、元の結果と比べる。
数値は有限値のみ。整数の上限は、個別の記載がない限り C# の int の上限（2,147,483,647）。長さは mm、位置はページ左上原点。
| キー | 単位・既定値 | 許容範囲 | 適用箇所・変更時の影響 |
|---|---|---|---|
dpi |
dpi、300 | 整数 72〜1200 | PDF の描画と長さの換算。画像寸法・検出・処理量が変わる |
image_dpi |
dpi、省略時は最終 dpi |
整数 72〜1200 | 画像の mm 換算。画像自体は拡縮しない |
diff.max_shift_mm |
mm、0.15 | 0 以上 | TolerantDifference の局所移動吸収。0 は無効。増やすと吸収範囲・探索量が増える |
diff.color_threshold |
Lab チャンネル差、3 | 0 以上 | 差分候補。増やすと色差の検出が減る |
diff.edge_tolerance |
比率、0.3 | 0 以上 1 未満 | 輪郭の許容。0 はぼかしなしの厳密比較 |
cluster.merge_x_mm |
mm、3 | 0 以上 | PageComparer の横方向の結合。増やすと離れた差分も結合しやすい |
cluster.merge_y_mm |
mm、1 | 0 以上 | 同、縦方向 |
cluster.min_pixels |
画素数、4 | 整数 1 以上 | 採用クラスタの最小生差分数。増やすと小さい差分をノイズとして除く |
cluster.max_clusters_per_page |
件、500 | 整数 1 以上 | ページの採用上限。超過時は大きい成分を残して警告 |
cluster.max_diff_ratio |
比率、0.30 | 0 より大きく 1 以下 | 超過時は too_different。大きくするとクラスタ化するページが増える |
move.search_mm |
各軸 mm、5 | 0〜20 | MovementAnnotator の探索。0 は移動注釈を無効化 |
move.min_score |
一致度、0.98 | 0 より大きく 1 以下 | 大きくすると移動注釈の採用を厳しくする |
move.min_score_gap |
一致度差、0.02 | 0 より大きく 1 以下 | 大きくすると曖昧な移動候補を見送りやすい |
align.enabled |
真偽、false | true / false | GlobalAligner を有効化。比較結果・終了コードが変わり得る |
align.max_shift_mm |
各軸 mm、5 | 0〜20 | 全体補正の探索。0 は探索を省略 |
align.min_score |
一致度、0.98 | 0 より大きく 1 以下 | 補正全体と支持区画の一致度の下限 |
align.min_score_gap |
一致度差、0.02 | 0 より大きく 1 以下 | 粗い段階の別ピークと最終段階の次点との差の下限 |
align.min_improvement |
一致度差、0.05 | 0 より大きく 1 以下 | 補正全体と支持区画で要求する改善量 |
exclude[].page |
ページ、必須 | all / 整数 1 以上 | 対象ページ。exclude 自体の既定は空配列 |
exclude[].x / y |
mm、必須 | 0 以上 | 除外矩形の左上。比較・移動・全体補正・PDF 注釈へ反映 |
exclude[].w / h |
mm、必須 | 0 以上 | 除外矩形の幅・高さ。0 は空領域 |
exclude[].note |
文字列、空 | YAML のスカラー文字列 | レポートに表示する除外理由。判定には使わない |
report.crop_margin_mm |
mm、2 | 0 以上 | ReportWriter の切り出し余白。検出結果には影響しない |
report.snippet_margin_mm |
mm、1 | 0〜20 | HTML の除外 YAML に付ける余白。0.5mm 単位で外側へ丸め、ページ端でクリップする。切り出し画像や検出結果には影響しない |
report.raw_overlay |
真偽、false | true / false | 補正前の元画像から赤青の確認用 PNG を作る。判定は変えず、相違なしを含む選択全ページを保存する。--raw-overlay の指定で true を優先 |
report.raw_overlay_common_color |
RGB 色、"#CCCCCC" |
引用符で囲んだ "#RRGGBB"（6 桁、英字大小可） |
確認用 PNG の共通成分の色。既定は薄いグレー。"#000000" で旧版の黒／グレー表示を再現。判定は変えない |
読み込み時に省略値を補い、実効設定に記録する。diff.max_shift_mm と cluster.merge_x_mm / merge_y_mm は、最終 DPI での探索候補数・カーネル寸法が整数で表現できることも検証する。
確認用オーバーレイは共通 YAML → 帳票別 YAML → --raw-overlay の順で決まる。帳票別の false は共通の true を解除し、省略すれば継承する。CLI に指定した場合はすべての比較対象で有効になる。共通色も共通 YAML → 帳票別 YAML の順で決まり、省略時は継承する。# は YAML のコメント開始なので色は必ず引用符で囲む。グレー化の係数・丸めは固定で、色設定は共通成分だけに反映する。プロファイルや各しきい値では表示を変更しない。表示式と出力項目を参照。
v0.1.5のT3-1bで利用できる。最終受け入れは未完了。v0.1.4以前では rows は未知キーとなる。検証状況を参照。設定例は rows.yaml。既定は無効で、PDF同士・元の描画サイズが同じページだけが対象。画像入力、文字層なし、曖昧な対応等では従来の比較へ戻り、理由を報告する。OCR、列ごとの整列は行わない。ページをまたぐ対応は別途 carry_enabled を有効にする。
| キー | 単位・既定値 | 許容範囲 | 意味 |
|---|---|---|---|
rows.enabled |
真偽、false | true / false | PDFテキスト層を手がかりに行整列する |
rows.carry_enabled |
真偽、false | true / false | 隣接ページへの送りと文書集約を検証する。trueには実効 rows.enabled: true が必要 |
rows.max_shift_mm |
mm、20 | 0 より大きく 100 以下 | 全体補正後からの追加縦ずれの絶対値上限。累積量にも適用 |
rows.min_word_match |
比率、0.60 | 0 より大きく 1 以下 | 行の単語一致率の下限 |
rows.refine_mm |
mm、0.3 | 0〜2 | テキスト位置周辺の画像再探索半径。0pxでは中心だけ |
rows.min_improvement |
比率、0.05 | 0 より大きく 1 以下 | 基準の生差分から要求する減少率 |
rows.min_score_gap |
一致度差、0.02 | 0 より大きく 1 以下 | 異なる量の整列仮説との画像一致度の差 |
rows.min_support_bands |
帯数、2 | 整数 2〜100 | 各内容区間に必要な独立した支持帯 |
rows.min_support_ink_mm2 |
黒換算 mm²、1 | 0 より大きく 1000 以下 | 各内容区間の支持帯に必要な面積。A/Bそれぞれで満たす |
rows.max_segments |
区間数、8 | 整数 1〜64 | 同じ追加dyの内容区間数の上限。詰め物・純白余白を除く |
共通YAML → 帳票別YAMLの順で指定スカラーだけを上書きする。プロファイルと --no-regions はrowsの指定を変更しない。専用CLIフラグは設けず、全実効値を config.rows とHTMLの設定欄へ記録する。無効時・後段で上書きする値も型・範囲を検証する。長さ・面積は最終DPIで換算する。
順序は正規化 → 全体補正 → 行整列 → 内容比較。exclude / regions は行整列前のA座標で指定し、表示・内容比較へ写す。PDF注釈では丸めない連続座標の除外を使う。通常のページ内行整列では、HTMLの除外YAMLは各表示断片に余白を付けてから元の設定用A座標へ戻し、外側へ0.5mm単位で丸める。断片間の構造帯をひとつの外接矩形で覆わない。
行整列しても挿入・削除・ブロック移動は相違として残る。CLI/HTMLの総箇所数は内容クラスタと除外されていない構造変化の合計。JSONの clusters は内容クラスタ数を維持し、structural_change_count・structural_change_counts・difference_count・difference_count_complete で総数・内訳・網羅性を示す。構造変化だけでも終了コード1となる。上限による省略・未比較ページでは総数が相違を網羅しない。
行整列後の表示画像と、差分計算に使った内容比較画像を別々に保存する。生差分・ノイズ・上限・抑制量は内容比較画像上の値で、白い詰め物によって相違率を薄めない。確認用オーバーレイは補正前の原画像のままで、行整列・除外・判定の描き込みを適用しない。詳細は SPEC 11.7。
元ページを保持する内容面の限定接続は、既存送り経路を文書全体で採用できない場合だけ使う。全2ページ対応・明示的なページ選択なし・300dpiのnormal相当の実効比較値・全体補正なし・数値対応なし・実効除外／領域なしに限定する。新しい設定キーはない。第1ページの同符号二原因と本文末尾一行の原因、独立した支持・全送り帯の画素一致・各ページの既存改善率を必要とする。strict／looseや他DPIはこの新経路の対象外。同じ内容差分の別ページ表示は content_references に置き、件数に加えない。新経路の除外YAMLは、元Aを表示する断片を物理ページ付きの元座標へ戻した後に余白・丸めを適用する。Bだけの参照位置ではYAMLを作らない。接続検証・実PDFの受け入れ。
v0.1.5の限定機能。設定例は page-flow.yaml。rows.enabled と rows.carry_enabled をともにtrueにする。共通YAMLの enabled: true を帳票別YAMLへ継承して carry_enabled: true だけを指定できる。依存条件は最終的な実効設定で検査する。falseでは送り用の記述収集・再描画・帯画像保存を行わない。
文字層付きPDFの、同じサイズ・一定行間隔の本文と、複数ページで裏付けられる固定ヘッダー／フッターを対象にする。送り元と先の全幅帯は全画素一致を必須とし、許容差や除外で不一致を隠さない。両端ページの実効比較設定・比較領域の条件も検証する。最大移動量、支持帯数・インク面積、区間数、画素再探索の一意性、改善率は既存のrows設定を使う。送り帯の本文対応は全文一致に限定し、単語一致率を下げてもこの条件は緩まない。
align.enabled: true と併用すると、全選択ページが対応し、採用補正がすべて縦方向（dx=0）の場合に送りを検証できる。正負・ページ別のdyと補正量0の混在に対応する。横補正を採用した文書、全体補正を採用して片側ページを含む文書は global_alignment_applied で送りを見送り、補正後の従来比較を維持する。補正後に推定した帯は元画像へ完全に戻して証明し、元画像の帯座標・PNGと補正後の行移動量を区別する。実PDFの接続検証を参照。
文字不足、サイズ差、上限超過、後半ページの写像不成立も文書全体の見送りとなり、JSON／HTMLへ理由を残す。選択していないページを中継しない。全ページが対応する文書では、送り連鎖が別のページ群に分かれ、各群を単一原因で説明できる場合に複数の原因を集約する。一つでも説明できない群や構造があれば、文書全体の集約を見送る。同じ送り連鎖にある同符号の複数原因も、実構造を複製せず累積移動量とページ収支で説明できる場合に集約する。末尾1ページを含む独立原因群と、一連鎖にある同符号の共有原因は、下記の個別条件で扱う。候補の全行が同じページ内に対応済みで、境界を跨ぐ共通行がないことを証明できた候補は same_page_rows_not_flow として理由・対応先をJSON／HTMLへ残す。その帯の画素比較は続ける。複数原因の接続検証を参照。
A側の固定部がページごとに異なる位置にある場合や、除外で必要な支持帯が失われる場合は従来比較へ戻す。 一定行間隔でも、描画端の1px超過や対応する罫線の元画素差によって送りを見送る。A4用紙の固定9条件は現行版の再実行でも未成立で、元の集約期待を保持して保留している（R-02）。疎な対照の成立とは区別する。現行版の再現記録を参照。 同じPDF描画命令・フォントでも位置によって元画素が変わる例があり、その差を除去して送りと認定しない。元描画と比較面の診断を参照。
末尾に1枚だけ片側ページがある場合も、独立した送り原因ごとに全ての行移動と収支を説明できれば集約する。追加対応は、対応ページ2枚以上・明示ページ選択なし・300dpi／normal相当・全体補正無効・数値対応／除外／領域なしに限る。新規ページの送り帯と固定部の外に非白の内容が一画素でもあれば集約しない。独立二原因はページ別内訳11件→2原因、内容変更1件が併存すると12件→3件となる。片側ページは未比較のままで、集約後の網羅性もfalse。既存の単一R11の条件は変更しない。対応範囲と接続仕様を参照。
末尾1枚へ続く同符号の共有原因も、上記の末尾独立原因と同じ文書・設定条件で扱う。全境界が同方向の実際の送りでつながり、各対応ページの局所支持・改善率と末尾の非白残余0が成立する一連鎖に限る。追加6方向では8→2／11→2、本文濃淡変更を残して9→3を確認した。補助帯には元画像・物理ページを表示し、片側ページに構造IDや内容検査済みの扱いを追加しない。元のshared-unpaired両方向は前側支持1行のため10→10であり、この成功の代わりに合格とはしない（R-01）。接続検証・未成立の診断を参照。
result.json の page_flow に候補・採否・元帯画像・ページ別診断・原因と実構造IDの対応を保存する。summary.difference_count と clusters の意味は維持し、aggregated_difference_count と aggregated_difference_count_complete を別に追加する。集約できない場合の集約後件数はページ別内訳と同じ。無効時は追加2項目がnullで、page_flow は省略する。相違の終了コード1と片側ページの未比較状態は変えない。ページ選択を指定した場合、集約後の網羅性はfalseとする。
同じ送り連鎖の複数原因は、任意の page_flow.aggregation.shared_components に原因と各移動への寄与を保存する。たとえば二挿入と付随する移動・送りの内訳7件を2原因へまとめ、数値変更1クラスタがあれば8件→3件として残す。原因と送り端点が同じ実構造に混ざる場合や、共有原因の記述が既存64MiB予算の残りに収まらない場合は部分集約しない。初回の共有原因の接続で未成立だった三ページ共有連鎖・共有原因→独立原因の4方向は、後続の境界再検証で接続済み。同一ページ二原因の元2方向は、冒頭の全2ページ・元ページ保持面の限定条件で接続済み。これらを任意の三ページ連鎖や原因配置への対応へ広げない。
HTMLと compare-dir の一覧には集約後件数とページ別内訳を併記する。元帯は pages/flow_l001_source.png などへ保存し、補正前の座標と対応ページから参照できる。確認用オーバーレイは独立して元A/Bから作る。候補検証後に元画像・入力ファイルが変わった場合や保存失敗時は処理を失敗させ、既存レポートを保護する。
数値変更を含む行も、同じ物理ページ内で一意なラベルと直近二行の完全一致から対応を証明できる場合に扱う。ASCIIの符号付き整数・小数の独立した欄を対象とし、桁区切り・全角数字・英数字ID・反復ラベルへ一般化しない。変更された画素・内容クラスタを残し、変更行を完全一致の支持には数えない。送り帯そのものの数値変更、根拠行不足、根拠に掛かる除外、明示的なページ選択では、この対応を使わず通常比較を維持する。設定の追加や数値の許容誤差はない。JSONの page_flow.numeric_matches とHTMLに、元本文・元座標・根拠行・採用／見送りを記録する。成立範囲と検証を参照。
内部上限は選択128物理ページ、A/B計256記述、32,768行、2,097,152 UTF-16文字、記述化512Mi画素、記述計上64MiB、128候補。記述計上量はプロセスのRSS上限を保証しない。設計と検証範囲・残件を参照。
以下はv0.1.5の設定の違いを確認するための要約。元帯の全画素一致・各ページの支持と採用条件は共通で、詳細はSPEC 11.8による。
| 経路 | 設定・入力の主な制限 |
|---|---|
| 全ページ対応の従来経路 | 採用された全体補正が縦方向だけなら併用可能。同じページ内の数値対応や除外／領域は各証明条件を満たす場合に限る。元帯の証明に除外を使わない |
| 全2ページの元ページ保持面 | 明示ページ選択なし、300dpi／normal相当の実効比較値、全体補正なし、数値対応なし、実効除外／領域なし。第1ページの同符号二原因で、後の原因が本文末尾にある限定配置 |
| 末尾片側1枚を含む追加の独立／共有原因 | 対応ページ2枚以上、明示ページ選択なし、300dpi／normal相当、全体補正の設定が無効、数値対応／除外／領域なし。共有原因は全境界が実際の送りで連結する一連鎖。既存の単一R11を優先し、その条件は変更しない |
300dpi／normal相当が必要な追加経路を、strict／loose・他DPIでの対応済み機能として扱わない。rows.min_support_bands の最小値は2のまま。しきい値を下げたり設定を変えたりすれば、R-01の支持1行やR-02の9条件を解消できるという確認はない。送り採用の見送りでは通常のページ比較を維持し、因果集約だけを見送る場合は採用済みの内容比較と未集約件数を維持する。
薄色1px追加線の元2方向（R-03）は、2026-09-26のメモリ画像診断で通常座標の参照コアでも未検出だった。実PDFや現行版での再実行ではなく、strict／高DPIによる解消も未確認。元カラー／raw overlayは人が元画素を確かめる手段として使い、自動検出の合格には置き換えない。R-01〜R-03は2026-09-27の案A承認により元の期待を保持して保留し、利用者向け制限と残件台帳で管理する。
regions の既定は空配列。領域の指定例は examples/regions.yaml。name・page・x・y・w・h は必須。名前は非空で設定内で一意、page は all（null も同義）または 1 以上の整数。x/y は 0 以上、w/h は 0 より大きい有限 mm 値とする。
| キー | 既定・指定内容 | 意味 |
|---|---|---|
regions[].mode |
compare / exclude、既定 compare | 比較条件の上書き、または除外 |
regions[].profile |
省略で継承、normal / strict / loose | 領域内の max_shift_mm / edge_tolerance を上書き |
regions[].diff.max_shift_mm |
省略で継承、0 以上 | 領域内の位置ずれの許容 |
regions[].diff.color_threshold |
省略で継承、0 以上 | 領域内の色差しきい値 |
regions[].diff.edge_tolerance |
省略で継承、0 以上 1 未満 | 領域内の輪郭許容 |
領域の実効 diff は「CLI を反映したページ設定 → 領域の profile → 領域の明示 diff」の順。内包する親領域からは継承しない。CLI の --profile も領域の明示指定を消さない。mode: exclude と profile/diff の併用はエラー。ink / cluster / move / align / rows / text はページ共通。anchor と float_mm は将来の予約名で、この版では未知キーとして拒否する。
適用座標は A／全体補正後 B の左上原点。左上を切り捨て、右下を切り上げて px 化し、ページ外はクリップする。同じページの領域は非交差か完全内包のみで、内側を優先する。同一矩形と部分交差はエラー。mm で非交差でも最終 DPI の丸めで同じ画素を共有するとエラーになる。内包が丸めで同じ px 矩形になった場合は内側を優先する。除外は常に比較より優先し、従来の exclude との重なりは許可する。
実効 diff ごとにページ全体を比較し、領域の所有画素で生差分を合成した後、一度だけクラスタ化する。境界でクラスタは分割しない。分類は各画素の edge_tolerance を使い、移動候補は移動元・移動先の両方の diff で検証する。異なる設定数が増えると比較時間も増える。同じ設定は一回の実行を共有する。
判定画像には青の破線と名前で領域、薄い橙色で抑制した画素を示す。抑制量は「ページ既定の生差分のうち領域設定で消えた画素」で、箇所数は 8 近傍連結成分数。通常の相違件数とは別で、ノイズ閾値未満の基準画素も含む。除外で消した基準差分は別集計し、重複させない。全差分を抑制したページも判定画像を保存する。元 A/B と確認用オーバーレイには描き込まない。
--no-regions は regions と exclude の両方を比較・全体補正・PDF 注釈・判定画像から外す。実効 config.regions と config.exclude は空配列になり、無視した宣言は config.region_audit と HTML に残る。不正な設定の検証は無効化前に行う。ページの profile、align.enabled、rowsの指定は維持する。
JSON の config.regions は宣言と effective_diff、pages[].regions は適用状態・クリップ後の bounds_px・所有画素・生差分・抑制量・実行参照を記録する。ページ外／内側領域・除外による非適用／対象外ページ／片側ページを区別する。ページと要約の absorbed_groups / max_shift_px はページ既定の基準実行値を維持し、別設定の全ページ実行値は runs に記録する。領域なしではこれらの追加項目を省略する。
各項目は省略できる。旧設定にない項目にも下表の既定値を補う。上限は極端な探索・出力量を誤指定しにくくするための入力制限であり、処理時間・メモリの保証値ではない。
| キー | 単位・既定値 | 許容範囲 | 適用箇所・変更時の影響 |
|---|---|---|---|
ink.background_radius_mm |
mm、1.5 | 0 より大きく 20 以下 | ImageInk の局所背景半径。局所吸収・分類・移動の共通定義を同時に変更する。大きい塗りの内部をインクとして扱う範囲や処理量が変わる |
ink.contrast_threshold |
Lab L 差、25 | 0〜100 | 局所背景との差がこの値より大きい画素をインクとする。上げると薄い文字・線がインクから外れる。100 ではインクがなくなる |
cluster.reading_band_mm |
mm、5 | 0 より大きく 1000 以下 | PageComparer の上から下・左から右の並び順。番号と、同数画素で上限に達した場合の採用順に影響する |
move.template_margin_mm |
mm、1 | 0〜20 | 移動テンプレートの周囲の余白。切り上げ、最低 1px。大きくすると周囲の変更やページ端の影響で移動と推定しにくくなる |
text.max_letters_per_page |
文字要素数、100000 | 整数 1〜1000000 | PdfTextReader の上限。超過時はその側の注釈を省略して警告する |
text.max_words_per_page |
単語数、20000 | 整数 1〜200000 | 同、単語化後の上限。抽出後の整形量を制限する |
text.max_runes_per_cluster |
Unicode スカラー値数、2000 | 整数 1〜100000 | TextAnnotations の片側本文上限。超過時は上限内の最後の 1 文字を「…」にする |
text.min_line_overlap |
短い方の高さに対する比率、0.5 | 0 より大きく 1 以下 | 行の先頭語との縦の重なり。大きくすると同じ行としてまとめにくくなる。通常比較の判定には影響しない。行整列時は行推定にも使う |
align.coarse_max_side_samples |
計算格子の要素数、800 | 整数 64〜4096 | 粗い探索段階の長辺の目安上限。大きくすると縮小が減り細部を残すが、探索量が増える |
align.refine_radius_samples |
各軸の計算格子の要素数、2 | 整数 1〜8 | 各復元段階の候補周囲の探索半径。小さくすると粗い段階の誤差を補えず見送る場合が増える |
align.min_support_cells |
区画数、3 | 整数 1〜9 | 固定 3×3 格子で補正を支持する最小区画数。小さくすると局所移動を全体移動と扱う可能性が高まる |
align.min_support_rows |
行数、2 | 整数 1〜3 | 支持区画がまたがる最小行数。小さくすると縦方向の分散条件が弱まる |
align.min_support_columns |
列数、2 | 整数 1〜3 | 同、横方向の分散条件 |
align.min_ink_area_mm2 |
黒換算 mm²、1 | 0 より大きく 10000 以下 | 各支持区画の A/B にそれぞれ要求する暗さ。上げると少ない情報での補正を見送る |
ink は分類専用にはしない。検出のグループ化も同じ ImageInk を使うため、変更すると差分マスク・件数も変わり得る。既定値での 37 ゴールデンを維持し、非既定値には従来の検出／無視の保証をそのまま適用しない。
align の支持区画数・行数・列数はすべて満たす必要がある。例えば区画数 1・行数 2・列数 2 なら、分散条件によって実際には 2 区画以上が必要になる。これは矛盾ではなく強い方の条件が効くため許可する。件数上限と文字要素上限も独立に判定する。
*_samples は元画像上の物理的な長さではなく、縮小計算の解像度・探索量を指定する計算格子の個数とする。長さ設定の mm とは区別する。mm に置き換えると DPI ごとの現行 800 / 2 の挙動を維持できない。支持量の mm²→画素面積も Units.SquareMmToPixels で換算する。
以下も照合の対象としたうえで、調整キーにはしない。変更する場合は、検出保証・参照実装・回帰ケースを再評価する別の仕様変更とする。
| 対象 | 固定値・条件 | 理由・対応案 |
|---|---|---|
| 色空間・差分式 | float Lab、チャンネル別判定 | 色差検出の定義。既存の color_threshold / edge_tolerance で調整する |
| 輪郭・グループのカーネル | 平均 3×3、コントラスト 5×5、候補膨張 5×5、8 連結 | 参照実装の検出／無視の両立に関わる構造 |
| 分類の輪郭許容 | edge_tolerance > 0 のとき 3×3 膨張 | 輪郭の位置ずれを同一インクに対応させる構造。0 のとき膨張しない |
| 画像・座標 | 8bit BGR、Lab 正規化 1/255、1inch=25.4mm、1pt=1/72inch、整数格子、丸め・端の複製 | 入力表現と単位、再現性の定義 |
| 最適化の ROI 余白 | 探索半径 + 3px、インク半径 + 分類膨張分 | 周辺の参照に必要な派生量。縮めると最適化前後の一致が崩れる |
| 移動の別ピーク | 最良点の各軸 ±1px 以内を同一ピークとして除く | 隣接画素を同じピークとして扱う構造。候補差は既存の min_score_gap で調整 |
| 移動の確認条件 | 双方向一致、色・形・移動元の差分を説明、除外・未採用成分・ページ端をまたがない、競合時は保留 | 「移動」と分類する意味を維持する条件。無効化スイッチは設けない |
| PDF テキストの幾何条件 | 回転 0、UserUnit=1、描画寸法と 1px 以内、正面積の重なり、単語全文、同一文字列・矩形だけ重複除去 | 座標の保証と注釈の定義。1px は描画寸法の丸め許容であり任意の移動許容ではない |
| PDF の描画上限・設定 | 1辺 16000px、注釈・フォーム・アンチエイリアスあり、白背景 | SPEC 4.1 の対応範囲と描画条件。上限超過は dpi を下げて対応し、YAML で対応範囲を拡大しない |
| PDF 単語化・並列度 | PdfPig の NearestNeighbourWordExtractor、逐次処理 | 抽出方式と依存ライブラリの契約。内部の抽出器パラメータは公開しない |
| 全体補正の縮小・スコア | 2 の累乗、面積平均、既存の暗さの一致度、同一評価マスク、同点の安定順 | 探索と比較対象の定義。変更には補正の再評価が必要 |
| 全体補正の別ピーク | 粗い探索で各軸 ±1 セル以内を除く | 移動注釈と同様の隣接ピークの定義。候補差で調整 |
| 全体補正の支持格子 | 3×3 | ページ上の分散を測る構造。採用件数・行列数・情報量を設定で調整する |
| 全体補正の端 | 再補間なし、白 255 で補充、非白を 1 画素でも押し出す場合は見送る | 内容を削除しない保証。閾値による緩和はしない |
| 描画・レポート | 赤／緑／黄色、輪郭列挙方式、文字サイズ、HTML の表示・小数桁・画像形式 | 承認済みの判定調整パラメータではなく表示仕様。確認用オーバーレイの共通色だけは report.raw_overlay_common_color で変更できる。画像エンコードや UI のテーマ設定は本設定の対象外 |
- 既定値 → YAML → 明示
--profile→ CLI の順。プロファイルが上書きするのは diff.max_shift_mm / diff.edge_tolerance だけ。--dpiは dpi を変更し、image_dpi が YAML で未指定の場合だけ追従させる。明示した image_dpi は維持する。 - PDF と画像の混在では、最終 dpi / image_dpi が異なると既存どおりエラーにし、設定をそろえるよう案内する。入力形式が決まる前には不整合としない。
- 未知・重複キー、型、非有限値、範囲違反を日本語で報告し、該当キーを含める。プロファイルで上書きされる値も読み込み時に検証する。既存の上限なし mm 値についても、最終 DPI で換算した派生整数が表現可能か確認し、オーバーフローを処理中の例外にしない。
- 既存の設定ファイルを読み込める。設定省略時の比較結果を維持する。入力 YAML は書き戻さないためコメントを保持できる。設定保存・自動整形・TOML 併用は追加しない。
- 追加項目を含む全実効値を result.json の config と HTML の設定欄に記載する。schema_version は追加項目として 1 を維持。旧 JSON に新項目がない場合は既定値とする。
- 全項目の設定例には目的・単位・範囲・影響のコメントを含む。下記の用途別例も Windows ZIP に含める。
| ファイル | 内容 |
|---|---|
| settings.yaml | 全項目の説明と既定値。image_dpi は追従を維持するためコメント例として掲載 |
| minimal.yaml | 空のマッピング {}。すべて既定値 |
| strict.yaml | 局所ずれと輪郭の許容を 0 にする。同じ出力環境での厳密比較 |
| scan.yaml | JPEG／スキャン向けに色差しきい値を 10 にする |
| align.yaml | 全体補正を有効にする。その他は既定値 |
| rows.yaml | v0.1.5以降用。PDFの行整列と補正前の確認用オーバーレイを有効にする |
| page-flow.yaml | v0.1.5以降用。隣接ページへの送り・文書集約・確認用オーバーレイを有効にする |
上のコマンドの --config に各ファイルを指定する。明示した --profile は YAML の位置ずれ・輪郭の許容を上書きする。たとえば strict.yaml に --profile normal を併記すると、局所ずれ 0.15mm・輪郭許容 0.3 となる。
YAML の dpi: 200 と --dpi 400 を指定すると、dpi と未指定の image_dpi は 400 になる。image_dpi: 150 も明示していれば、それは 150 のまま。この状態で PDF と画像を混在させると、DPI をそろえるようエラーになる。
新規設定を旧バージョンのアプリに渡すと未知キーのエラーになる。旧設定を新バージョンで使うことはできる。JSON は結果出力用で、設定入力には使わない。
compare-dir は共通の --config に加えて、--rules で UTF-8 のコメント付き選択定義を指定できる。選択定義は通常設定とは別のスキーマであり、compare や --config には渡さない。
# config の相対パスは、この選択定義ファイルのフォルダが基準。
schema_version: 1
rules:
- pattern: '\A請求/[^/]+\.pdf\z'
config: settings/invoice.yaml
- pattern: '\Aスキャン/[^/]+\.(png|jpg|jpeg)\z'
config: settings/scan.yamlschema_version: 1 と配列 rules が必須。rules: [] は有効。各要素には空でない pattern / config が必要。未知キー、重複キー、型・版の不正は開始前に拒否する。参照する通常設定は相対パスまたは絶対パスで指定できる。
正規表現は、拡張子を含む相対パスを NFC・/ 区切りにして調べる。既定で大小文字を区別せず、カルチャに依存しない。部分一致を許可し、全体を限定するときは \A / \z を使う。非バックトラック方式のため、先読み・後読み・後方参照等は非対応のエラーになる。A/B どちらかに一致すれば候補となり、同じ規則が両側に一致しても 1 件。
- 0 件一致：共通設定を使う。
- 1 件一致：その設定で指定した項目を上書きする。
- 複数一致：
CONFIG_RULE_AMBIGUOUSとして規則番号・パターンを一覧に残す。同じ設定ファイルを指す複数規則もエラー。
設定順序は 既定値 → 共通 YAML → 選択した YAML → 明示 --profile → CLI。ネストしたマッピングは指定キーだけを上書きし、diff: {} 等の空マッピングは共通値を保持する。exclude / regions は配列全体を置換し、exclude: [] / regions: [] で共通設定の該当配列を解除、省略なら継承する。
image_dpi は両 YAML とも未指定なら最終 dpi に追従する。どちらかで明示した値は保持し、両方で指定した場合は選択した YAML が優先。PDF/画像混在で DPI が異なると、その対をエラーにする。
後で上書きする値も含めて各 YAML を検証する。未使用の参照設定も開始前に読み、合成後の設定も検証する。内容は一度読み込んで保持し、実行中の編集は反映しない。入力 YAML は書き換えない。片側のみのファイルには規則を適用せず、存在差分だけを報告する。
一覧 JSON の configuration に共通・選択定義・全参照設定の絶対パスと SHA-256、CLI 値を記録し、各成功項目に選択規則を記録する。各個別レポートの config は全実効値を保持する。同梱の選択定義は隣の strict / scan 設定を参照する。全項目を含む YAML を選択すると全項目の上書きになるため、継承したい項目は帳票別 YAML から省略する。