# pptx-skill

> HTML 슬라이드를 PowerPoint(PPTX) 파일로 변환. PPTX 생성, 편집, 썸네일 생성이 필요할 때 사용.

- Author: Inyoung Cho
- Repository: Mephisto405/seminar-slides-cc-skill
- Version: 20260202101202
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/Mephisto405/seminar-slides-cc-skill
- Web: https://mule.run/skillshub/@@Mephisto405/seminar-slides-cc-skill~pptx-skill:20260202101202

---

---
name: pptx-skill
description: HTML 슬라이드를 PowerPoint(PPTX) 파일로 변환. PPTX 생성, 편집, 썸네일 생성이 필요할 때 사용.
---

# PPTX Skill - PowerPoint 변환 스킬

HTML 슬라이드를 PowerPoint 프레젠테이션 파일로 변환하는 스킬입니다.

## 기능 개요

### 1. 새 프레젠테이션 생성 (HTML → PPTX)
HTML 슬라이드 파일들을 PowerPoint로 변환

### 2. 기존 프레젠테이션 편집
PPTX 파일의 내용 수정

### 3. 썸네일 생성
프레젠테이션의 미리보기 이미지 생성

## 핵심 워크플로우

### HTML → PPTX 변환

1. **HTML 슬라이드 준비**
   - `slides/` 디렉토리에 HTML 파일들 확인
   - 각 파일이 720pt × 405pt (16:9) 규격인지 검증

2. **html2pptx.js 실행**
   ```bash
   node .claude/skills/pptx-skill/scripts/html2pptx.js
   ```

3. **결과 검증**
   - 생성된 PPTX 파일 확인
   - 썸네일로 시각적 검증

## 스크립트 사용법

### html2pptx.js
HTML 파일들을 PPTX로 변환

```javascript
import { html2pptx } from './.claude/skills/pptx-skill/scripts/html2pptx.js';
import PptxGenJS from 'pptxgenjs';

const pres = new PptxGenJS();
pres.layout = 'LAYOUT_WIDE'; // 16:9

// 각 슬라이드 변환
await html2pptx('slides/slide-01.html', pres);
await html2pptx('slides/slide-02.html', pres);

// 저장
await pres.writeFile({ fileName: 'presentation.pptx' });
```

### thumbnail.py
프레젠테이션 썸네일 그리드 생성

```bash
python .claude/skills/pptx-skill/scripts/thumbnail.py presentation.pptx output-thumbnail
```

옵션:
- `--cols N`: 열 수 (기본 5, 범위 3-6)
- `--outline-placeholders`: 플레이스홀더 영역 표시

### pack.py / unpack.py
PPTX 파일 패키징/언패키징

```bash
# 언패킹
python .claude/skills/pptx-skill/ooxml/scripts/unpack.py presentation.pptx output_dir

# 패킹
python .claude/skills/pptx-skill/ooxml/scripts/pack.py input_dir presentation.pptx
```

### validate.py
PPTX 구조 검증

```bash
python .claude/skills/pptx-skill/ooxml/scripts/validate.py unpacked_dir --original presentation.pptx
```

## 상세 문서

- [html2pptx.md](html2pptx.md) - HTML to PPTX 변환 상세 가이드
- [ooxml.md](ooxml.md) - Office Open XML 기술 참조
- [python-pptx-academic.md](python-pptx-academic.md) - **학술 발표용 python-pptx 가이드** (권장)

## 방법 선택 가이드

| 상황 | 권장 방법 |
|------|----------|
| 간단한 텍스트 슬라이드 | HTML → PPTX (html2pptx.js) |
| 표, 차트가 포함된 슬라이드 | **python-pptx** |
| 논문 Figure가 포함된 학술 발표 | **python-pptx** |
| 복잡한 레이아웃 | **python-pptx** |

> **주의**: HTML → PPTX 변환은 표, 이미지, 복잡한 레이아웃에서 문제가 발생할 수 있습니다.
> 학술 발표나 정밀한 레이아웃이 필요한 경우 python-pptx를 직접 사용하세요.

---

## ⚠️ 핵심 교훈: 진정한 시각화란?

> **"텍스트를 도형으로 바꾸는 것은 시각화가 아니다"**

### 잘못된 접근 vs 올바른 접근

| 상황 | ❌ 잘못된 접근 | ✅ 올바른 접근 |
|------|---------------|---------------|
| 아키텍처 설명 | `add_shape()`로 박스+화살표 그리기 | **논문 원본 Figure** 사용 |
| 결과 비교 | 숫자 텍스트 ("FID: 44→34") | **실제 결과 이미지** 비교 |
| 방법 비교 | O/X 텍스트 테이블 | **결과물 이미지** + 😢/😀 |
| 플로우 설명 | 도형 플로우차트 | **논문 Figure** + 주석 |

### 왜 논문 Figure를 써야 하는가?

```
1. 저자가 이미 잘 만들어놓음 - 재발명할 필요 없음
2. 정확한 정보 전달 - 직접 그리면 오류 가능성
3. 시간 절약 - 도형 배치에 시간 낭비 방지
4. 청중 이해도 - 눈으로 보는 것이 가장 효과적
```

### Figure 우선순위

```
1순위: 논문 원본 Figure (arxiv.org/html/[ID]/x[N].png)
2순위: 프로젝트 페이지 이미지
3순위: 논문 PDF에서 추출
4순위: 직접 그리기 (최후의 수단만!)
```

### 권장 레이아웃

```
┌─────────────────┬─────────────────┐
│   텍스트 설명    │   논문 Figure   │
│  (간결한 bullet) │   (원본 이미지)  │
└─────────────────┴─────────────────┘
```

> 📖 자세한 내용: [python-pptx-academic.md](python-pptx-academic.md)

## PptxGenJS 핵심 규칙

### 색상 코드
```javascript
// 올바른 사용 - # 없이
{ color: 'FF0000' }

// 잘못된 사용 - 파일 손상 유발
{ color: '#FF0000' }
```

### 슬라이드 추가
```javascript
const slide = pres.addSlide();

// 텍스트 추가
slide.addText('제목', {
  x: 0.5,
  y: 0.5,
  w: 9,
  h: 1,
  fontSize: 36,
  color: '1a1a2e',
  bold: true
});

// 이미지 추가
slide.addImage({
  path: 'image.png',
  x: 1,
  y: 2,
  w: 4,
  h: 3
});

// 도형 추가
slide.addShape(pres.ShapeType.rect, {
  x: 0.5,
  y: 1,
  w: 3,
  h: 2,
  fill: { color: '1e3a5f' }
});
```

### 차트 추가
```javascript
// 막대 차트
slide.addChart(pres.ChartType.bar, [
  {
    name: '시리즈 1',
    labels: ['A', 'B', 'C'],
    values: [10, 20, 30]
  }
], {
  x: 1,
  y: 2,
  w: 8,
  h: 4
});

// 원형 차트
slide.addChart(pres.ChartType.pie, [...], {...});

// 선형 차트
slide.addChart(pres.ChartType.line, [...], {...});
```

## 전체 변환 프로세스

```
┌─────────────────┐
│   HTML 슬라이드  │
│   slides/*.html │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  html2pptx.js   │
│  (Playwright +  │
│   PptxGenJS)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   PPTX 파일     │
│ presentation.   │
│     pptx        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  thumbnail.py   │
│  (미리보기)     │
└─────────────────┘
```

## 의존성

### Node.js
- pptxgenjs: PowerPoint 생성
- playwright: 브라우저 렌더링
- sharp: 이미지 처리

### Python
- markitdown: 마크다운 변환
- defusedxml: XML 파싱
- pillow: 이미지 처리

### 시스템
- LibreOffice: PDF/이미지 변환 (soffice)
- Poppler: PDF 이미지화 (pdftoppm)

## 주의사항

1. **색상 코드**: PptxGenJS에서 # 접두사 사용 금지
2. **폰트**: 웹 안전 폰트만 사용
3. **텍스트**: p, h1-h6, ul, ol 태그만 변환됨
4. **그라데이션**: CSS 그라데이션은 이미지로 대체
5. **검증**: 변환 후 반드시 썸네일로 확인

---

## 학술 발표 체크리스트

### 생성 전 확인 (필수!)
- [ ] 정확한 저자명 (arXiv/논문에서 복사)
- [ ] 이벤트 유형 확인 (Weekly Paper Review, PhD Seminar 등)
- [ ] **논문 Figure 수집 완료** (가장 중요!)
- [ ] **결과 비교 이미지 수집** (Baseline vs Ours)
- [ ] 청중 수준 파악 (전문가/비전문가)

### 필수 이미지 목록 (학술 발표)
```
images/
├── teaser.png           # 타이틀 슬라이드용
├── architecture.png     # Method 설명용 (논문 Figure 1-2)
├── baseline_result.png  # 비교용 (기존 방법 결과)
├── ours_result.png      # 비교용 (제안 방법 결과)
├── scaling_graph.png    # 정량적 결과 그래프
└── comparison.png       # 정성적 비교 Figure
```

### 이미지 소스
```
https://arxiv.org/html/[PAPER_ID]/x[N].png  # arXiv Figure (고화질)
https://[method].github.io/statics/images/  # 프로젝트 페이지
```

### 슬라이드 검증 체크리스트
- [ ] **모든 Method 슬라이드에 논문 Figure가 있는가?**
- [ ] **결과 슬라이드에 실제 이미지 비교가 있는가?**
- [ ] 도형만으로 구성된 슬라이드가 없는가?
- [ ] 텍스트 위주 슬라이드가 3장 연속으로 없는가?

### 검증 필수
```python
# PowerPoint COM으로 PNG 내보내기
import win32com.client
ppt = win32com.client.Dispatch('PowerPoint.Application')
# slide.Export(output_path, 'PNG', 960, 540)
```

### 흔한 실수
- **도형으로 시각화 시도**: 논문 Figure를 쓰세요!
- **숫자로만 결과 설명**: 실제 이미지를 보여주세요!
- 이미지 크기: `height` 제한으로 겹침 방지
- PowerPoint 인덱싱: 1-based (`Slides(1)`, not `Slides[0]`)
- Windows 인코딩: ✓, ✗ 대신 [OK], [X] 사용