# Text Preserve

> 비라틴 문자(한글, 일본어, 중국어 등)를 AI 이미지에 정확히 렌더링하는 스킬. Canvas 프리렌더링과 Gemini를 활용하여 텍스트 깨짐 없이 이미지를 생성합니다.

- Skill: `kbarbel640-del/text-preserve` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kbarbel640-del/text-preserve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kbarbel640-del/text-preserve/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kbarbel640-del (https://skillmd.com/u/kbarbel640-del)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/kbarbel640-del/text-preserve

---


# 다국어 텍스트 프리렌더링 스킬

AI 이미지 모델은 한글·한자·일본어 등 비라틴 문자를 직접 그리면 글자가 깨지거나 오타가 생깁니다.
이 스킬은 **웹앱과 완전히 동일한 파이프라인**을 제공합니다:

1. **detect** — 프롬프트에 비라틴 문자가 있는지 감지
2. **analyze** — Gemini LLM으로 프롬프트에서 텍스트와 스타일 추출
3. **render** — Canvas로 정확한 폰트를 사용해 텍스트를 PNG 프리렌더링
4. **generate** — 프리렌더링 PNG를 Gemini 이미지 생성에 인풋으로 넣어 최종 이미지 생성

## 최초 설정 (한 번만)

```bash
cd {baseDir} && node setup.mjs
```

- `canvas` + `@google/generative-ai` npm 패키지 설치
- Noto Sans 폰트 파일을 `{baseDir}/fonts/`에 준비

## 환경 변수

| 변수 | 필수 | 설명 |
|---|---|---|
| `GEMINI_API_KEY` | ⭐ 필수 | Gemini Flash(분석) + Gemini Image(생성) 모두에 사용 |
| `GEMINI_IMAGE_MODEL` | 선택 | 이미지 생성 모델 (기본: gemini-3-pro-image-preview) |

---

## 사용 흐름 (Step-by-Step)

### 한 번에 실행: `pipeline`

전체 파이프라인을 한 명령어로 실행합니다:

```bash
node {baseDir}/render.mjs pipeline "욎홎 뙤앾뼡이라는 지역 축제 포스터 만들어줘" \
  --output /tmp/final-image.png --no-base64
```

결과:
```json
{
  "detect": { "needsRendering": true, "primaryScript": "hangul", ... },
  "analyze": { "texts": [...], "style": {...}, "reasoning": "..." },
  "render": { "success": true, "outputPath": "/tmp/text-render-xxx.png", ... },
  "generate": { "success": true, "outputPath": "/tmp/final-image.png", ... }
}
```

### 단계별 실행

#### Step 1: 비라틴 문자 감지 (`detect`)

```bash
node {baseDir}/render.mjs detect "사용자 프롬프트 전체"
```

- `needsRendering: false` → 프리렌더링 없이 일반 이미지 생성 진행
- `needsRendering: true` → Step 2로 진행

#### Step 2: Gemini LLM 프롬프트 분석 (`analyze`)

```bash
node {baseDir}/render.mjs analyze "욎홎 뙤앾뼡이라는 지역 축제 포스터 만들어줘"
```

Gemini Flash가 프롬프트를 분석하여:
- 이미지에 들어갈 **텍스트** 추출 (따옴표, 레이블, 맥락 기반)
- 디자인 맥락에 맞는 **스타일** 결정 (폰트, 크기, 색상)
- 각 텍스트의 **역할**(headline/subheadline/body/caption) 지정
- 각 텍스트의 **스크립트·언어** 자동 감지

> **GEMINI_API_KEY가 없으면** 규칙 기반 fallback이 동작합니다.

#### Step 3: Canvas 프리렌더링 (`render`)

analyze 결과를 그대로 render에 전달합니다:

```bash
node {baseDir}/render.mjs render \
  --json '{"texts":[...],"style":{...}}' \
  --output /tmp/rendered-text.png
```

또는 JSON 파일로:
```bash
node {baseDir}/render.mjs render --input /tmp/analysis.json --output /tmp/rendered-text.png
```

#### Step 4: Gemini 이미지 생성 (`generate`)

**프리렌더링된 텍스트 PNG를 Gemini에 인풋 이미지로 넣어서 최종 이미지를 생성합니다.**

```bash
node {baseDir}/render.mjs generate \
  --prompt "욎홎 뙤앾뼡이라는 지역 축제 포스터 만들어줘" \
  --rendered /tmp/rendered-text.png \
  --analysis '{"texts":[...],"style":{...}}' \
  --output /tmp/final-image.png \
  --no-base64
```

이 명령어는 내부적으로:
1. 프리렌더링 PNG를 **첫 번째 참조 이미지**로 Gemini에 전달
2. `buildTextRenderFinalPrompt`로 프롬프트를 구성 (텍스트 목록 + 스타일 + "텍스트를 다시 그리지 말고 그대로 사용하라" 지침)
3. Gemini가 텍스트를 자연스럽게 통합한 최종 이미지를 생성

추가 참조 이미지가 있으면 `--ref`로 전달:
```bash
node {baseDir}/render.mjs generate \
  --prompt "포스터 만들어줘" \
  --rendered /tmp/rendered-text.png \
  --ref /tmp/user-reference.jpg \
  --output /tmp/final-image.png
```

---

## 지원 폰트

| 언어 | sans-serif | serif | display | handwriting |
|---|---|---|---|---|
| 한국어 | Noto Sans KR | Noto Serif KR | Black Han Sans | Nanum Pen Script |
| 일본어 | Noto Sans JP | Noto Serif JP | Noto Sans JP | Noto Sans JP |
| 중국어 | Noto Sans SC | Noto Serif SC | Noto Sans SC | Noto Sans SC |
| 태국어 | Noto Sans Thai | — | — | — |
| 영어 | Inter | Georgia | Impact | Comic Sans MS |

## 텍스트 역할별 크기

| role | 용도 | 크기 비율 |
|---|---|---|
| headline | 메인 제목 | 1.0x |
| subheadline | 부제목 | 0.7x |
| body | 본문 | 0.5x |
| caption | 캡션/설명 | 0.4x |

## 폰트 크기 매핑

| fontSize | 픽셀 |
|---|---|
| small | 24px |
| medium | 36px |
| large | 48px |
| xlarge | 72px |

---

## 트리거 키워드

이 스킬은 사용자 프롬프트에 다음 키워드가 포함되어 있을 때 자동 활성화됩니다:

`텍스트`, `글자`, `문구`, `로고`, `워터마크`, `브랜드`, `글씨`, `제목`, `헤드라인`,
`text`, `logo`, `title`, `headline`,
또는 프롬프트에 한글/한자/일본어/태국어/아랍어 등 비라틴 문자가 포함된 경우.

## 규칙 (Do)

- 비라틴 문자가 감지되면 반드시 전체 파이프라인 (detect→analyze→render→generate)을 실행한다
- `analyze`로 LLM이 텍스트와 스타일을 추출하도록 한다
- `render`로 Canvas 프리렌더링 PNG를 생성한다
- `generate`로 프리렌더링 PNG를 Gemini에 인풋으로 넣어 최종 이미지를 생성한다

## 금지사항 (Don't)

- AI 모델에게 비라틴 문자를 직접 그리라고 요청하지 않는다
- 프리렌더링 없이 한글/한자/일본어 텍스트를 이미지 프롬프트에 포함하지 않는다
- `render` 단계를 건너뛰고 바로 `generate`하지 않는다
- `analyze` 결과에서 텍스트를 임의로 수정하지 않는다