Community影像github.com

個人筆跡工作室

影像技能。從真實紙筆照片建立個人手寫字形庫,檢查目標草稿的字元覆蓋率,引導最小缺失字元擷取,並以程式化方式渲染逼真的多頁手寫文件與PDF(含表格、方程式與自訂模板),無 AI 生成影像偽影。當使用者想要數位化自己的筆跡、建立或擴充個人字形庫,或渲染手寫作業、筆記或實驗報告時使用。

個人筆跡工作室 是什麼?

「個人筆跡工作室」是一套完整的管線,能將真實紙筆手寫照片轉化為可重複使用的個人字形庫,並以程式化方式渲染逼真的多頁手寫文件與 PDF,完全避免 AI 字型生成的偽影。它支援 macOS、Linux 與 Windows,依賴 `uv` 或 Python 3.10+ 搭配 Pillow 與 NumPy,並可選用 ffmpeg 處理 HEIC 照片。運作流程包含:工作區初始化、目標草稿字元覆蓋率預檢(針對 `pages.json` 或純文字)、照片前處理(消除陰影與紙張透印)、基於連通元件的字元切片(需強制進行視覺接觸片審核),以及最終渲染——採用 2× 超取樣筆劃寬度正規化、滑動視窗多變體去重、自然基線波浪與手繪風格表格/方程式。此技能特別適合需要大量真實手寫樣本(如作業、實驗報告)的使用者,確保每個字元均由實際手寫照片產生,無任何合成字型介入。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Elizhng/personal-handwriting/tree/HEAD

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

個人筆跡工作室 是做什麼的?

將真實紙筆手寫照片轉化為可重複使用的個人字形庫,並以程式化方式渲染逼真的多頁手寫文件與 PDF —— 零 AI 生成字型偽影。

概述

此技能協調一個封閉迴圈、100% 程式化手寫管線:

  1. 工作區初始化:在本地建立個人工作區(透過 .gitignore 排除於版本控制之外)。
  2. 覆蓋率預檢:掃描目標草稿(pages.json 或純文字)與 glyphs/manifest.json 比對,產出精確的最小缺失字元清單(或可列印的 A4 書寫頁)。
  3. 照片前處理與引導式擷取:解碼 .DNG / .HEIC / .JPG / .PNG 照片並進行照明正規化(去除陰影與紙張透印),透過跨平台列導向連通元件聚類進行字元切片,並在提交字形前執行強制性的視覺接觸片審核。
  4. 逼真排版與 PDF 渲染:在空白紙張或自訂模板上組成頁面,採用 2× 超取樣筆劃寬度正規化(約 0.6 mm 中性筆一致性)、滑動視窗多變體去重、自然基線波浪、搖晃手繪表格/方程式,以及 100% 字元覆蓋率驗證。

依賴項目

  • 執行環境:uv(建議)或 Python 3.10+,搭配 pillow 與 numpy。scripts/handwrite.py 包含 PEP 723 內嵌中繼資料,因此 uv run scripts/handwrite.py ... 可在 macOS、Linux 與 Windows 上自動配置依賴。
  • 選用:
    • ffmpeg(或 pillow-heif)用於解碼 .HEIC 照片。
    • macOS swift 僅在選用 Apple Vision OCR 自由格式擷取器時需要(參見 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

標準代理工作流程

階段一:在要求使用者書寫前進行覆蓋率預檢

  • 將使用者的草稿轉換為結構化的 pages.json(參見 references/page_schema.md)或直接將純文字 .txt 草稿傳遞給 check。
  • 執行 uv run scripts/handwrite.py check ... 計算依頻率排序的精確缺失字元。
  • 要求使用者僅在空白白紙上以黑色中性筆書寫缺失字元(建議高頻字元、數字 0–9 與標點符號書寫 2–4 個變體,以使渲染頁面看起來自然),並拍攝一張平整、光線均勻的照片。

階段二:前處理、列導向擷取與強制視覺審核

  1. 執行 preprocess 將 .DNG / .HEIC / .JPG / .PNG 解碼為 <base>_clean.png 與 <base>_ink.png(透明 RGBA)。若照片包含桌面邊緣或陰影,可使用 --crop x0,y0,x1,y1(歸一化 0.0–1.0)。
  2. 建立 rows_spec.json,列出每列書寫的字元(使用 "□" 或 "SKIP" 忽略劃掉的錯誤或雜散斑點;參見 examples/usst_lab_report/sample_rows_spec.json)。
  3. 務必先以 --dry-run 執行 ingest。 使用你的檔案讀取/視覺工具檢查 <base>_debug.png(墨水上的邊界框)與 <base>_sheet.png(有標籤的單字元接觸片)。
  4. 確認無錯位、墨斑或裁切筆劃。然後在無 --dry-run 的情況下重新執行 ingest,以跨平台大小寫安全的檔名(upper_<X>_k.png、lower_<x>_k.png、sym_u<4hex>_k.png、<ch>_k.png)將字形提交至 manifest.json。

階段三:渲染與逐頁品質檢查

  1. 執行 render。腳本會強制執行 100% 字元覆蓋率的起飛前檢查(verify_all_chars_covered),若缺少任何字元則快速失敗。
  2. 以視覺方式檢查每個渲染的 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

常見錯誤

  1. 在 ingest 時跳過 --dry-run 視覺審核:一個劃掉的污漬或一對相鄰的合併筆劃可能導致整列的標籤偏移。務必在提交前檢查 <base>_debug.png 與 <base>_sheet.png。
  2. 使用 AI 影像生成或系統字型替代:切勿使用擴散模型生成手寫頁面或使用系統字型替代缺失字元。務必透過 check → ingest 擷取真實缺失字形。
  3. 大小寫不敏感的檔案系統衝突:在 macOS (APFS) 與 Windows (NTFS) 上,A_0.png 與 a_0.png 會互相覆蓋。務必使用 handwrite.py(其強制使用 upper_A_0.png / lower_a_0.png / sym_uXXXX_0.png)。
  4. 在沙箱環境中呼叫 macOS sips:sips 可能在沙箱環境中靜默輸出全黑影像。handwrite.py preprocess 以純 Python 處理 .DNG,並透過 pillow-heif 或 ffmpeg 處理 .HEIC。
  5. 將個人筆跡提交至 Git:將個人工作區(glyphs/、photos/、output/)保留在技能倉庫之外或位於 gitignore 的路徑中。

相關技能