個人筆跡工作室 是做什麼的?
將真實紙筆手寫照片轉化為可重複使用的個人字形庫,並以程式化方式渲染逼真的多頁手寫文件與 PDF —— 零 AI 生成字型偽影。
概述
此技能協調一個封閉迴圈、100% 程式化手寫管線:
- 工作區初始化:在本地建立個人工作區(透過
.gitignore排除於版本控制之外)。 - 覆蓋率預檢:掃描目標草稿(
pages.json或純文字)與glyphs/manifest.json比對,產出精確的最小缺失字元清單(或可列印的 A4 書寫頁)。 - 照片前處理與引導式擷取:解碼
.DNG/.HEIC/.JPG/.PNG照片並進行照明正規化(去除陰影與紙張透印),透過跨平台列導向連通元件聚類進行字元切片,並在提交字形前執行強制性的視覺接觸片審核。 - 逼真排版與 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 個變體,以使渲染頁面看起來自然),並拍攝一張平整、光線均勻的照片。
階段二:前處理、列導向擷取與強制視覺審核
- 執行
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,以跨平台大小寫安全的檔名(upper_<X>_k.png、lower_<x>_k.png、sym_u<4hex>_k.png、<ch>_k.png)將字形提交至manifest.json。
階段三:渲染與逐頁品質檢查
- 執行
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視覺審核:一個劃掉的污漬或一對相鄰的合併筆劃可能導致整列的標籤偏移。務必在提交前檢查<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以純 Python 處理.DNG,並透過pillow-heif或ffmpeg處理.HEIC。 - 將個人筆跡提交至 Git:將個人工作區(
glyphs/、photos/、output/)保留在技能倉庫之外或位於 gitignore 的路徑中。