Personal Handwriting Studio は何をしますか?
実際の紙とペンによる手書き写真を再利用可能な個人用グリフライブラリに変換し、AI生成フォントのアーティファクトなしでリアルな多ページ手書き文書やPDFをプログラム的にレンダリングします。
概要
このスキルは、完全にプログラムによるクローズドループの手書きパイプラインを実現します:
- ワークスペース初期化:ローカルに個人用ワークスペースをセットアップします(
.gitignoreによりgit管理外に保持)。 - カバレッジ事前チェック:対象文書(
pages.jsonまたはプレーンテキスト)をglyphs/manifest.jsonと照合し、不足文字の最小リスト(または印刷可能なA4用紙)を生成します。 - 写真前処理とガイド付き取り込み:
.DNG/.HEIC/.JPG/.PNG写真を照明補正(影や紙の裏抜け除去)し、クロスプラットフォーム対応の行ガイド付き連結成分クラスタリングで文字をスライスし、グリフを登録する前に 必須のビジュアルコンタクトシート監査 を実行します。 - リアルなレイアウトとPDFレンダリング:白紙またはカスタムテンプレート上に、2倍スーパーサンプリングによる線幅均一化(約0.6mmのゲルペン一貫性)、スライディングウィンドウによるマルチバリアント重複除去、自然なベースラインの波、手書き風のテーブル/数式、そして100%の文字カバレッジ検証を行ってページを構成します。
依存関係
- ランタイム:
uv(推奨)または Python 3.10+、pillow、numpy。scripts/handwrite.pyには PEP 723 インラインメタデータが含まれているため、uv run scripts/handwrite.py ...で macOS、Linux、Windows 上で自動的に依存関係がプロビジョニングされます。 - オプション:
.HEIC写真のデコードにffmpeg(またはpillow-heif)。- オプションの Apple Vision OCR 抽出機能を使用する場合のみ macOS の
swift(詳細は references/macos_vision_ocr.md 参照)。
クイックスタート
# 1. 個人用ワークスペースを初期化(オプションでUSSTラボレポートテンプレート例付き)
uv run scripts/handwrite.py init --workspace ./my_handwriting --with-example
# 2. 文書の中でグリフライブラリに不足している文字をチェック
uv run scripts/handwrite.py check \
--content ./my_handwriting/content/sample_pages.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--output ./my_handwriting/coverage_report.json \
--grid-dir ./my_handwriting/missing_grid
# 3. 手書きシートの写真を前処理(DNG / HEIC / JPG / PNG)
uv run scripts/handwrite.py preprocess \
--input ./my_handwriting/photos/sheet1.jpg \
--output-dir ./my_handwriting/preprocessed
# 4. ドライランでスライスし、manifest.json に登録前にビジュアル監査
uv run scripts/handwrite.py ingest \
--input ./my_handwriting/preprocessed/sheet1_ink.png \
--rows-spec ./my_handwriting/content/rows_spec.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--contact-dir ./my_handwriting/contact_sheets \
--dry-run
# 5. デバッグオーバーレイとコンタクトシートを視認確認した後、グリフを登録(--dry-run を外す)
uv run scripts/handwrite.py ingest \
--input ./my_handwriting/preprocessed/sheet1_ink.png \
--rows-spec ./my_handwriting/content/rows_spec.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--contact-dir ./my_handwriting/contact_sheets
# 6. リアルな多ページ手書きPNGと結合PDFをレンダリング
uv run scripts/handwrite.py render \
--content ./my_handwriting/content/sample_pages.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--assets-dir ./my_handwriting \
--output-dir ./my_handwriting/output \
--pdf-name report.pdf
標準エージェントワークフロー
ステージ 1: ユーザーに書いてもらう前のカバレッジ事前チェック
- ユーザーのドラフトを構造化された
pages.json(references/page_schema.md 参照)に変換するか、プレーン.txtドラフトをそのままcheckに渡します。 uv run scripts/handwrite.py check ...を実行し、不足文字を頻度順に正確に計算します。- ユーザーに、白い紙に黒いゲルペンで 不足文字のみ を手書きしてもらうよう依頼します(高頻度文字、数字
0-9、句読点は2~4バリエーション書くことを推奨。レンダリングページが自然に見えるため)。フラットで均一な照明の写真を撮影してもらいます。
ステージ 2: 前処理、行ガイド付き取り込み、必須のビジュアル監査
preprocessを実行し、.DNG/.HEIC/.JPG/.PNGを<base>_clean.pngと<base>_ink.png(透明RGBA)にデコードします。写真に机の端や影が写っている場合は--crop x0,y0,x1,y1(正規化0.0–1.0)を使用します。- 各行に書かれている文字をリストした
rows_spec.jsonを作成します(取り消し線ミスや不要なブロブを無視するには"□"または"SKIP"を使用。例:examples/usst_lab_report/sample_rows_spec.json)。 - 常に最初は
--dry-run付きでingestを実行します。<base>_debug.png(インク上のバウンディングボックス)と<base>_sheet.png(ラベル付き単一文字コンタクトシート)の両方を、ファイル読み取り/ビジョンツールを使用して検査します。 - 位置ずれ、インクブロブ、クリッピングされたストロークがゼロであることを確認します。その後、
--dry-runなしでingestを再実行し、グリフをmanifest.jsonに登録します。ファイル名はクロスプラットフォームでケースセーフな形式を使用します(upper_<X>_k.png、lower_<x>_k.png、sym_u<4hex>_k.png、<ch>_k.png)。
ステージ 3: レンダリングとページごとのQA
renderを実行します。スクリプトは100%の文字カバレッジ事前チェック(verify_all_chars_covered)を実施し、不足文字がある場合は即座に失敗します。- レンダリングされたすべての
page_<N>.pngを目視で検査します:- 標準出力の縦方向充填率を確認。
[WARNING] ... overflowed bottom marginが表示された場合は、--font-sizeを小さくする(標準範囲28–34)、line_h_ratioを調整する(1.38–1.50)、またはコンテンツを追加の継続ページに分割します。 - 表紙のフィールドが下線にきちんと配置されているか、表のセルテキストがクリップされていないか、ストロークの太さが均一かを確認します。
- 標準出力の縦方向充填率を確認。
ユーティリティスクリプトリファレンス
| サブコマンド | 説明 | 主要フラグ |
|---|---|---|
init | クリーンな個人用ワークスペースを作成 | --workspace, --with-example |
check | グリフカバレッジとオプションのA4不足文字グリッドを計算 | --content, --manifest, --output, --grid-dir |
preprocess | 写真をデコードし、影のないRGBAインクを抽出 | --input, --output-dir, --crop, --hi, --lo |
ingest | 行ガイド付きスライスでRGBAグリフと監査シートを生成 | --input, --rows-spec, --manifest, --contact-dir, --dry-run, --source-id |
contact-sheet | manifest.json からラベル付きコンタクトシートを生成 | --manifest, --output, --chars |
render | pages.json をテンプレートにレンダリングしPDFを出力 | --content, --manifest, --output-dir, --assets-dir, --pdf-name, --font-size, --messiness, --seed |
よくある間違い
ingestの--dry-runによるビジュアル監査をスキップする:1つの取り消し線ブロブや隣接ストロークの結合が行全体のラベルをずらす可能性があります。登録前には必ず<base>_debug.pngと<base>_sheet.pngを検査してください。- AI画像生成やシステムフォントのフォールバックを使用する:不足文字に対して拡散モデルで手書きページを生成したり、システムフォントを代用したりしないでください。必ず
check→ingestで実際の不足グリフを取得してください。 - 大文字小文字を区別しないファイルシステムでの衝突:macOS(APFS)やWindows(NTFS)では、
A_0.pngとa_0.pngが上書きされます。必ずhandwrite.py(upper_A_0.png/lower_a_0.png/sym_uXXXX_0.pngを強制)を使用してください。 - サンドボックス内でmacOS
sipsを呼び出す:sipsはサンドボックス環境内で真っ黒な画像を出力することがあります。handwrite.py preprocessは.DNGを純粋Pythonで、.HEICをpillow-heifまたはffmpegで処理します。 - 個人の手書きをGitにコミットする:個人用ワークスペース(
glyphs/、photos/、output/)はスキルリポジトリの外か、gitignoredパス内に保持してください。