Personal Handwriting Studio은(는) 무엇을 하나요?
실제 펜-종이 필기 사진을 재사용 가능한 개인 글리프 라이브러리로 변환하고, 프로그래매틱 방식으로 사실적인 다중 페이지 필기 문서 및 PDF를 렌더링합니다 — AI 생성 폰트 아티팩트가 전혀 없습니다.
개요
이 스킬은 완전히 프로그래매틱한 폐쇄 루트 필기 파이프라인을 조정합니다:
- 작업 공간 초기화: 로컬 개인 작업 공간을 구성합니다 (
.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(참조/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(참조/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참조). - 항상
ingest를--dry-run으로 먼저 실행합니다. 파일 읽기/비전 도구를 사용하여<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에 글리프를 커밋합니다.
3단계: 렌더링 및 페이지별 QA
render를 실행합니다. 이 스크립트는 100% 문자 커버리지 사전 점검(verify_all_chars_covered)을 시행하며, 문자가 누락되면 즉시 실패합니다.- 렌더링된 모든
page_<N>.png를 시각적으로 검사합니다:- stdout의 수직 채우기 백분율을 확인합니다.
[WARNING] ... overflowed bottom margin이 나타나면--font-size(일반 범위28–34)를 줄이거나line_h_ratio(1.38–1.50)를 조정하거나 내용을 추가 페이지로 분할합니다. - 표지 필드가 밑줄에 깔끔하게 정렬되는지, 표의 셀 텍스트가 잘리지 않는지, 획 두께가 균일한지 확인합니다.
- stdout의 수직 채우기 백분율을 확인합니다.
유틸리티 스크립트 참조
| 하위 명령어 | 설명 | 주요 플래그 |
|---|---|---|
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는.DNG를 순수 Python으로 처리하고.HEIC는pillow-heif또는ffmpeg로 처리합니다. - 개인 필기를 Git에 커밋: 개인 작업 공간(
glyphs/,photos/,output/)을 스킬 저장소 외부나 git 무시 경로 안에 유지하세요.