Community이미지github.com

Personal Handwriting Studio

실제 펜-종이 필기 사진으로 개인 글리프 라이브러리를 구축하고, 대상 초안의 문자 커버리지를 점검하며, 누락된 문자 캡처를 안내하고, AI 이미지 생성 인공물 없이 프로그래매틱 방식으로 사실적인 다중 페이지 필기 문서(PDF)를 생성합니다.

Personal Handwriting Studio란 무엇인가요?

Personal Handwriting Studio는 사용자의 실제 손글씨를 디지털 글리프 라이브러리로 변환하고, 이를 기반으로 완전히 프로그래매틱한 방식으로 사실적인 필기 문서를 렌더링하는 AI 에이전트 스킬입니다. 이 스킬은 Claude Code, Cursor, Codex 등 명령줄 기반 AI 에이전트와 협력하여 작동합니다. 주요 기능으로는 작업 공간 초기화, 대상 초안에 대한 문자 커버리지 사전 점검, DNG/HEIC/JPEG/PNG 사진 전처리(조명 보정 및 그림자 제거), 행 기반 연결 요소 클러스터링을 통한 문자 슬라이싱, 시각적 접촉 시트 감사를 통한 글리프 수집, 그리고 2배 초과 샘플링된 획 두께 정규화와 자연스러운 기준선 물결 효과를 적용한 다중 페이지 PDF 렌더링이 포함됩니다. 사용자가 자신의 필체를 디지털화하거나, 필기 과제, 노트, 실험 보고서 등을 실제와 같은 품질로 렌더링해야 할 때 특히 유용하며, 모든 과정에서 AI 생성 폰트 아티팩트가 발생하지 않습니다.

지원 대상~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에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Personal Handwriting Studio은(는) 무엇을 하나요?

실제 펜-종이 필기 사진을 재사용 가능한 개인 글리프 라이브러리로 변환하고, 프로그래매틱 방식으로 사실적인 다중 페이지 필기 문서 및 PDF를 렌더링합니다 — AI 생성 폰트 아티팩트가 전혀 없습니다.

개요

이 스킬은 완전히 프로그래매틱한 폐쇄 루트 필기 파이프라인을 조정합니다:

  1. 작업 공간 초기화: 로컬 개인 작업 공간을 구성합니다 (.gitignore로 git에서 제외).
  2. 커버리지 사전 점검: 대상 초안(pages.json 또는 일반 텍스트)을 glyphs/manifest.json과 대조하여 정확한 최소 누락 문자 목록(또는 인쇄 가능한 A4 필기 시트)을 생성합니다.
  3. 사진 전처리 및 안내 수집: 조명 정규화(그림자 및 종이 투과 제거)를 통해 .DNG / .HEIC / .JPG / .PNG 사진을 디코딩하고, 플랫폼 간 행 기반 연결 요소 클러스터링으로 문자를 슬라이싱한 후, 글리프 커밋 전에 필수 시각적 접촉 시트 감사를 실행합니다.
  4. 사실적인 레이아웃 및 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단계: 전처리, 행 기반 수집 및 필수 시각적 감사

  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. 항상 ingest를 --dry-run으로 먼저 실행합니다. 파일 읽기/비전 도구를 사용하여 <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에 글리프를 커밋합니다.

3단계: 렌더링 및 페이지별 QA

  1. render를 실행합니다. 이 스크립트는 100% 문자 커버리지 사전 점검(verify_all_chars_covered)을 시행하며, 문자가 누락되면 즉시 실패합니다.
  2. 렌더링된 모든 page_<N>.png를 시각적으로 검사합니다:
    • stdout의 수직 채우기 백분율을 확인합니다. [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-sheetmanifest.json에서 레이블이 지정된 접촉 시트 생성--manifest, --output, --chars
renderpages.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는 .DNG를 순수 Python으로 처리하고 .HEIC는 pillow-heif 또는 ffmpeg로 처리합니다.
  5. 개인 필기를 Git에 커밋: 개인 작업 공간(glyphs/, photos/, output/)을 스킬 저장소 외부나 git 무시 경로 안에 유지하세요.

관련 스킬