Refactor PPTX generation logic to separate module

Moved all PowerPoint generation functions from app.py to a new module dots_ocr/utils/pptx_generator.py for better modularity and maintainability. Added PPT_DATA_SCHEMA.md to document the required input data structure. Included local_test.py and test.json for local testing of PPTX generation.

PPT_DATA_SCHEMA.md

@@ -0,0 +1,65 @@
+# PPT Conversion Data Schema
+
+This document outlines the data schema required by the `build_pptx_from_results` function in `app.py` to generate a PowerPoint presentation.
+
+## Overview
+
+The input data (`parse_results`) is a list of dictionaries, where each dictionary represents a **single page**.
+
+## Data Structure
+
+```json
+[
+  {
+    "layout_result": [
+      {
+        "bbox": [109, 235, 450, 280],
+        "category": "Title",
+        "text": "Document Title"
+      },
+      {
+        "bbox": [109, 300, 800, 500],
+        "category": "Text",
+        "text": "Content goes here..."
+      }
+    ]
+  },
+  {
+    "layout_result": [ ... next page data ... ]
+  }
+]
+```
+
+## Field Definitions
+
+Each item in the `layout_result` list must be a dictionary with the following fields:
+
+| Field | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **bbox** | `List[int]` | **Yes** | `[x1, y1, x2, y2]` coordinates (Top-Left, Bottom-Right). Absolute pixel coordinates relative to the image size. |
+| **category** | `str` | **Yes** | The layout element category (see Allowed Categories below). |
+| **text** | `str` | Conditional | The text content to display. Required for text-based categories. |
+
+## Allowed Categories
+
+The `category` field determines styling (font size, bolding) and whether the element is included in the PPT.
+
+### Text Elements (Rendered)
+These categories are rendered as text boxes in the PowerPoint slide.
+
+*   `Title`: Rendered in **Bold**. Minimum font size 24pt.
+*   `Section-header`: Rendered in **Bold**. Minimum font size 18pt.
+*   `Caption`: Maximum font size 12pt.
+*   `Footnote`: Maximum font size 12pt.
+*   `Text`: Standard text body.
+*   `List-item`: Standard text body.
+*   `Page-header`
+*   `Page-footer`
+*   `Formula`
+
+### Non-Text Elements (Skipped)
+These categories are **excluded** from text box generation in the current implementation (they are assumed to be part of the background image or handled separately).
+
+*   `Picture`
+*   `Table`
+

app.py

@@ -38,15 +38,13 @@ from qwen_vl_utils import process_vision_info
 # pptx imports
 try:
     from pptx import Presentation
-    from pptx.util import Inches, Pt
-    from pptx.dml.color import RGBColor
-    from pptx.enum.text import MSO_AUTO_SIZE, MSO_ANCHOR, PP_ALIGN
 except ImportError as exc:
     raise ImportError("python-pptx is required.") from exc
 
 # dots_ocr utils (PDF 로드용)
 from dots_ocr.utils.doc_utils import load_images_from_pdf
 from dots_ocr.utils.consts import MIN_PIXELS, MAX_PIXELS, IMAGE_FACTOR
+from dots_ocr.utils.pptx_generator import build_pptx_from_results
 
 
 # ============================================================
@@ -107,144 +105,7 @@ CATEGORY_COLORS = {
 # 폰트 크기 관련 상수 및 유틸리티
 # ============================================================
 
-# PPT 표준 폰트 크기 프리셋
-FONT_PRESETS = [
-    8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 
-    28, 32, 36, 40, 44, 48, 54, 60, 66, 72, 
-    80, 88, 96
-]
-
-def _calculate_font_size(
-    width: int, 
-    height: int, 
-    text: str, 
-    category: str = "",
-    is_bold: bool = False
-) -> Pt:
-    """
-    박스 크기와 텍스트 구성 성분을 분석하여 최적의 폰트 크기 계산
-    
-    Args:
-        width: 박스 너비 (EMU 단위)
-        height: 박스 높이 (EMU 단위)
-        text: 텍스트 내용
-        category: 레이아웃 카테고리
-        is_bold: 볼드체 여부
-    
-    Returns:
-        Pt 객체 (계산된 폰트 크기)
-    """
-    if not text:
-        return Pt(12)
-
-    # EMU to Pt conversion
-    w_pt = width / 12700
-    h_pt = height / 12700
-    
-    # 1. 텍스트 구성 성분 분석 (Character Composition Analysis)
-    total_weight = 0.0
-    max_word_weight = 0.0
-    current_word_weight = 0.0
-    
-    # 가중치 설정
-    # 볼드체일 경우 가중치 상향
-    w_hangul = 1.0
-    w_upper = 0.8 if is_bold else 0.7
-    w_lower = 0.6 if is_bold else 0.55
-    w_other = 0.4 if is_bold else 0.3
-    
-    for char in text:
-        if '가' <= char <= '힣':
-            weight = w_hangul
-        elif 'A' <= char <= 'Z':
-            weight = w_upper
-        elif 'a' <= char <= 'z' or '0' <= char <= '9':
-            weight = w_lower
-        else:
-            weight = w_other
-            
-        # 공백이면 단어 구분
-        if char.isspace():
-            max_word_weight = max(max_word_weight, current_word_weight)
-            current_word_weight = 0.0
-            # 공백 자체는 total_weight에 포함 (줄바꿈 계산용)
-            total_weight += weight
-        else:
-            current_word_weight += weight
-            total_weight += weight
-            
-    # 마지막 단어 처리
-    max_word_weight = max(max_word_weight, current_word_weight)
-    
-    # 안전 장치: 가중치가 0이면 기본값
-    if total_weight <= 0:
-        total_weight = len(text) * 0.5
-    if max_word_weight <= 0:
-        max_word_weight = total_weight
-
-    # 2. Case A: 너비 제약 (단어 단위)
-    # 가장 긴 단어가 박스 너비를 넘지 않도록 함
-    # Font Size * Max Word Weight <= Width
-    # Font Size <= Width / Max Word Weight
-    # 안전 마진 90% 적용
-    width_limit_size = (w_pt / max_word_weight) * 0.9
-    
-    # 3. Case B: 높이 제약 (줄바꿈 시뮬레이션)
-    # 큰 프리셋부터 내려오면서 높이 조건 만족하는지 확인
-    height_limit_size = FONT_PRESETS[0] # 기본값
-    
-    for preset in reversed(FONT_PRESETS):
-        # 예상 줄 수 = 올림(총 텍스트 너비 / 박스 너비)
-        # 총 텍스트 너비 = total_weight * preset
-        # 여유 있게 계산하기 위해 줄바꿈 시 낭비되는 공간 고려 (1.0 -> 1.1 등 조정 가능)
-        text_virtual_width = total_weight * preset
-        expected_lines = math.ceil(text_virtual_width / w_pt)
-        
-        # 최소 1줄
-        if expected_lines < 1:
-            expected_lines = 1
-            
-        # 필요 높이 = 줄 수 * 폰트크기 * 줄간격(1.2)
-        required_height = expected_lines * preset * 1.2
-        
-        # 박스 높이의 95% 이내에 들어오면 채택
-        if required_height <= h_pt * 0.95:
-            height_limit_size = preset
-            break
-            
-        # 가장 작은 프리셋까지 왔는데도 안되면 가장 작은거 선택
-        if preset == FONT_PRESETS[0]:
-            height_limit_size = preset
-
-    # 4. 최종 크기 결정 및 보정
-    target_size = min(width_limit_size, height_limit_size)
-    
-    # 카테고리별 최소/최대 보정
-    min_size = 9
-    max_size = 80
-
-    if category == 'Title':
-        min_size = 24
-        # 제목은 한 줄에 꽉 차게 보이는게 좋으므로 width_limit 비중을 높게 봄
-        target_size = max(target_size, 24)
-    elif category == 'Section-header':
-        min_size = 18
-        target_size = max(target_size, 18)
-    elif category in ('Caption', 'Footnote'):
-        max_size = 12
-        
-    # 범위 제한
-    target_size = max(min_size, min(target_size, max_size))
-    
-    # 프리셋 매핑 (계산된 값보다 작거나 같은 가장 큰 프리셋)
-    final_size = FONT_PRESETS[0]
-    for preset in FONT_PRESETS:
-        if preset <= target_size:
-            final_size = preset
-        else:
-            break
-            
-    return Pt(final_size)
+# (pptx_generator로 이동됨)
 
 
 # ============================================================
@@ -712,193 +573,8 @@ def process_single_image(
 # ============================================================
 # PPTX 생성 함수들
 # ============================================================
-def _get_page_size(
-    page_image: Optional[Image.Image], layout_data: Optional[List[Dict]]
-) -> Tuple[int, int]:
-    if page_image:
-        return page_image.width, page_image.height
-    return 1200, 1600
-
-
-def _add_background(slide, slide_width, slide_height, page_image: Optional[Image.Image]) -> None:
-    if not page_image:
-        return
-    try:
-        buf = io.BytesIO()
-        page_image.save(buf, format="PNG")
-        buf.seek(0)
-        slide.shapes.add_picture(buf, 0, 0, width=slide_width, height=slide_height)
-    except Exception as e:
-        print(f"Background add failed: {e}")
-
-
-def _clean_text_for_pptx(text: str) -> str:
-    """
-    PPTX용 텍스트 정리 - 마크다운 기호 제거
-    
-    제거 대상: #, **, *, `, ^, ~~ 등
-    """
-    import re
-    
-    if not text:
-        return ""
-    
-    # 마크다운 기호 제거
-    cleaned = text
-    
-    # 헤딩 기호 제거: # ## ### 등
-    cleaned = re.sub(r'^#{1,6}\s*', '', cleaned, flags=re.MULTILINE)
-    
-    # 볼드/이탤릭 제거: **text** → text, *text* → text, __text__ → text, _text_ → text
-    cleaned = re.sub(r'\*\*(.+?)\*\*', r'\1', cleaned)
-    cleaned = re.sub(r'__(.+?)__', r'\1', cleaned)
-    cleaned = re.sub(r'\*(.+?)\*', r'\1', cleaned)
-    cleaned = re.sub(r'_(.+?)_', r'\1', cleaned)
-    
-    # 인라인 코드 제거: `code` → code
-    cleaned = re.sub(r'`(.+?)`', r'\1', cleaned)
-    
-    # 취소선 제거: ~~text~~ → text
-    cleaned = re.sub(r'~~(.+?)~~', r'\1', cleaned)
-    
-    # 각주 기호 제거: ^text^ → text
-    cleaned = re.sub(r'\^(.+?)\^', r'\1', cleaned)
-    
-    # 링크 제거: [text](url) → text
-    cleaned = re.sub(r'\[(.+?)\]\(.+?\)', r'\1', cleaned)
-    
-    # 남은 특수 마크다운 기호 제거
-    cleaned = cleaned.replace('**', '').replace('__', '')
-    
-    return cleaned.strip()
-
-
-def _add_textbox(
-    slide, 
-    bbox, 
-    text, 
-    scale_x, 
-    scale_y, 
-    category: str = "",
-    page_height: int = 0,
-    use_dark_bg: bool = False
-) -> None:
-    """
-    텍스트 박스 추가 (AutoSize 강제 적용 - 순서 수정 최종 버전)
-    """
-    try:
-        left = int(bbox[0] * scale_x)
-        top = int(bbox[1] * scale_y)
-        width = int((bbox[2] - bbox[0]) * scale_x)
-        height = int((bbox[3] - bbox[1]) * scale_y)
-        
-        if width <= 0 or height <= 0:
-            return
-
-        textbox = slide.shapes.add_textbox(left, top, width, height)
-        
-        # 1. 텍스트 프레임 설정
-        text_frame = textbox.text_frame
-        text_frame.clear()
-        text_frame.word_wrap = True
-        
-        # 정렬 및 여백: 박스 중앙에 오도록, 여백은 제거
-        text_frame.vertical_anchor = MSO_ANCHOR.MIDDLE
-        text_frame.margin_left = 0
-        text_frame.margin_right = 0
-        text_frame.margin_top = 0
-        text_frame.margin_bottom = 0
-        
-        # 2. 텍스트 입력 (가장 먼저!)
-        if len(text_frame.paragraphs) == 0:
-            p = text_frame.paragraphs.add_paragraph()
-        else:
-            p = text_frame.paragraphs[0]
-            
-        run = p.add_run()
-        cleaned_text = _clean_text_for_pptx(text)
-        run.text = cleaned_text
-        
-        # 3. 폰트 설정
-        is_bold = category in ('Title', 'Section-header')
-        if is_bold:
-            run.font.bold = True
-            
-        # 폰트 크기 전략: 박스 크기와 텍스트 구성 성분 기반 정교한 계산
-        run.font.size = _calculate_font_size(width, height, cleaned_text, category, is_bold=is_bold)
-
-        # 4. 색상 및 배경
-        if use_dark_bg:
-            run.font.color.rgb = RGBColor(255, 255, 255)
-            textbox.fill.solid()
-            textbox.fill.fore_color.rgb = RGBColor(0, 0, 0)
-        else:
-            run.font.color.rgb = RGBColor(0, 0, 0)
-            textbox.fill.solid()
-            textbox.fill.fore_color.rgb = RGBColor(255, 255, 255)
-            
-        # 5. AutoSize 설정 (마지막에!)
-        # MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE: 텍스트가 넘치면 폰트를 줄여서 맞춤
-        text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
-
-    except Exception as e:
-        print(f"Textbox add failed: {e}")
-
-
-def build_pptx_from_results(
-    parse_results: List[Dict],
-    background_images: List[Image.Image],
-    output_path: Path,
-) -> Tuple[int, int]:
-    """파싱 결과로부터 PPTX 생성"""
-    prs = Presentation()
-    
-    first_image = background_images[0] if background_images else None
-    sample_width, sample_height = 1200, 1600
-    if first_image:
-        sample_width, sample_height = first_image.width, first_image.height
-
-    slide_width = Inches(10)
-    slide_height = Inches(10 * sample_height / sample_width)
-    prs.slide_width = slide_width
-    prs.slide_height = slide_height
-
-    total_boxes = 0
-
-    for idx, result in enumerate(parse_results):
-        slide = prs.slides.add_slide(prs.slide_layouts[6])
-        bg_image = background_images[idx] if idx < len(background_images) else None
-        
-        page_width, page_height = _get_page_size(bg_image, result.get('layout_result'))
-        if page_width == 0: page_width = sample_width
-        if page_height == 0: page_height = sample_height
-
-        _add_background(slide, slide_width, slide_height, bg_image)
-
-        scale_x = slide_width / float(page_width)
-        scale_y = slide_height / float(page_height)
-
-        layout_data = result.get('layout_result') or []  # None 및 빈 값 방어
-        if layout_data and isinstance(layout_data, list):  # 타입 체크 추가
-            for cell in layout_data:
-                bbox = cell.get("bbox")
-                if not bbox or len(bbox) != 4:
-                    continue
-                category = cell.get("category", "")
-                text = cell.get("text", "") or ""
-                if category in ("Picture", "Table"):
-                    continue
-                if not text.strip():
-                    continue
-                _add_textbox(
-                    slide, bbox, text, scale_x, scale_y,
-                    category=category,
-                    page_height=page_height
-                )
-                total_boxes += 1
 
-    prs.save(output_path)
-    return len(parse_results), total_boxes
+# (pptx_generator로 이동됨)
 
 
 # ============================================================

dots_ocr/utils/pptx_generator.py

@@ -0,0 +1,354 @@
+import io
+import math
+from typing import List, Optional, Tuple, Dict
+from pathlib import Path
+from PIL import Image
+
+try:
+    from pptx import Presentation
+    from pptx.util import Inches, Pt
+    from pptx.dml.color import RGBColor
+    from pptx.enum.text import MSO_AUTO_SIZE, MSO_ANCHOR
+except ImportError as exc:
+    raise ImportError("python-pptx is required.") from exc
+
+# ============================================================
+# 폰트 크기 관련 상수 및 유틸리티
+# ============================================================
+
+# PPT 표준 폰트 크기 프리셋
+FONT_PRESETS = [
+    8, 9, 10, 11, 12, 14, 16, 18, 20, 24, 
+    28, 32, 36, 40, 44, 48, 54, 60, 66, 72, 
+    80, 88, 96
+]
+
+def _calculate_font_size(
+    width: int, 
+    height: int, 
+    text: str, 
+    category: str = "",
+    is_bold: bool = False
+) -> Pt:
+    """
+    박스 크기와 텍스트 구성 성분을 분석하여 최적의 폰트 크기 계산
+    
+    Args:
+        width: 박스 너비 (EMU 단위)
+        height: 박스 높이 (EMU 단위)
+        text: 텍스트 내용
+        category: 레이아웃 카테고리
+        is_bold: 볼드체 여부
+    
+    Returns:
+        Pt 객체 (계산된 폰트 크기)
+    """
+    if not text:
+        return Pt(12)
+
+    # EMU to Pt conversion
+    w_pt = width / 12700
+    h_pt = height / 12700
+    
+    # 1. 텍스트 구성 성분 분석 (Character Composition Analysis)
+    total_weight = 0.0
+    max_word_weight = 0.0
+    current_word_weight = 0.0
+    
+    # 가중치 설정
+    # 볼드체일 경우 가중치 상향
+    w_hangul = 1.0
+    w_upper = 0.8 if is_bold else 0.7
+    w_lower = 0.6 if is_bold else 0.55
+    w_other = 0.4 if is_bold else 0.3
+    
+    for char in text:
+        if '가' <= char <= '힣':
+            weight = w_hangul
+        elif 'A' <= char <= 'Z':
+            weight = w_upper
+        elif 'a' <= char <= 'z' or '0' <= char <= '9':
+            weight = w_lower
+        else:
+            weight = w_other
+            
+        # 공백이면 단어 구분
+        if char.isspace():
+            max_word_weight = max(max_word_weight, current_word_weight)
+            current_word_weight = 0.0
+            # 공백 자체는 total_weight에 포함 (줄바꿈 계산용)
+            total_weight += weight
+        else:
+            current_word_weight += weight
+            total_weight += weight
+            
+    # 마지막 단어 처리
+    max_word_weight = max(max_word_weight, current_word_weight)
+    
+    # 안전 장치: 가중치가 0이면 기본값
+    if total_weight <= 0:
+        total_weight = len(text) * 0.5
+    if max_word_weight <= 0:
+        max_word_weight = total_weight
+
+    # 2. Case A: 너비 제약 (단어 단위)
+    # 가장 긴 단어가 박스 너비를 넘지 않도록 함
+    # Font Size * Max Word Weight <= Width
+    # Font Size <= Width / Max Word Weight
+    # 안전 마진 90% 적용
+    width_limit_size = (w_pt / max_word_weight) * 0.9
+    
+    # 3. Case B: 높이 제약 (줄바꿈 시뮬레이션)
+    # 큰 프리셋부터 내려오면서 높이 조건 만족하는지 확인
+    height_limit_size = FONT_PRESETS[0] # 기본값
+    
+    for preset in reversed(FONT_PRESETS):
+        # 예상 줄 수 = 올림(총 텍스트 너비 / 박스 너비)
+        # 총 텍스트 너비 = total_weight * preset
+        # 여유 있게 계산하기 위해 줄바꿈 시 낭비되는 공간 고려 (1.0 -> 1.1 등 조정 가능)
+        text_virtual_width = total_weight * preset
+        expected_lines = math.ceil(text_virtual_width / w_pt)
+        
+        # 최소 1줄
+        if expected_lines < 1:
+            expected_lines = 1
+            
+        # 필요 높이 = 줄 수 * 폰트크기 * 줄간격(1.2)
+        required_height = expected_lines * preset * 1.2
+        
+        # 박스 높이의 95% 이내에 들어오면 채택
+        if required_height <= h_pt * 0.95:
+            height_limit_size = preset
+            break
+            
+        # 가장 작은 프리셋까지 왔는데도 안되면 가장 작은거 선택
+        if preset == FONT_PRESETS[0]:
+            height_limit_size = preset
+
+    # 4. 최종 크기 결정 및 보정
+    target_size = min(width_limit_size, height_limit_size)
+    
+    # 카테고리별 최소/최대 보정
+    min_size = 9
+    max_size = 80
+
+    if category == 'Title':
+        min_size = 24
+        # 제목은 한 줄에 꽉 차게 보이는게 좋으므로 width_limit 비중을 높게 봄
+        target_size = max(target_size, 24)
+    elif category == 'Section-header':
+        min_size = 18
+        target_size = max(target_size, 18)
+    elif category in ('Caption', 'Footnote'):
+        max_size = 12
+        
+    # 범위 제한
+    target_size = max(min_size, min(target_size, max_size))
+    
+    # 프리셋 매핑 (계산된 값보다 작거나 같은 가장 큰 프리셋)
+    final_size = FONT_PRESETS[0]
+    for preset in FONT_PRESETS:
+        if preset <= target_size:
+            final_size = preset
+        else:
+            break
+            
+    return Pt(final_size)
+
+
+# ============================================================
+# PPTX 생성 함수들
+# ============================================================
+def _get_page_size(
+    page_image: Optional[Image.Image], layout_data: Optional[List[Dict]]
+) -> Tuple[int, int]:
+    if page_image:
+        return page_image.width, page_image.height
+    return 1200, 1600
+
+
+def _add_background(slide, slide_width, slide_height, page_image: Optional[Image.Image]) -> None:
+    if not page_image:
+        return
+    try:
+        buf = io.BytesIO()
+        page_image.save(buf, format="PNG")
+        buf.seek(0)
+        slide.shapes.add_picture(buf, 0, 0, width=slide_width, height=slide_height)
+    except Exception as e:
+        print(f"Background add failed: {e}")
+
+
+def _clean_text_for_pptx(text: str) -> str:
+    """
+    PPTX용 텍스트 정리 - 마크다운 기호 제거
+    
+    제거 대상: #, **, *, `, ^, ~~ 등
+    """
+    import re
+    
+    if not text:
+        return ""
+    
+    # 마크다운 기호 제거
+    cleaned = text
+    
+    # 헤딩 기호 제거: # ## ### 등
+    cleaned = re.sub(r'^#{1,6}\s*', '', cleaned, flags=re.MULTILINE)
+    
+    # 볼드/이탤릭 제거: **text** → text, *text* → text, __text__ → text, _text_ → text
+    cleaned = re.sub(r'\*\*(.+?)\*\*', r'\1', cleaned)
+    cleaned = re.sub(r'__(.+?)__', r'\1', cleaned)
+    cleaned = re.sub(r'\*(.+?)\*', r'\1', cleaned)
+    cleaned = re.sub(r'_(.+?)_', r'\1', cleaned)
+    
+    # 인라인 코드 제거: `code` → code
+    cleaned = re.sub(r'`(.+?)`', r'\1', cleaned)
+    
+    # 취소선 제거: ~~text~~ → text
+    cleaned = re.sub(r'~~(.+?)~~', r'\1', cleaned)
+    
+    # 각주 기호 제거: ^text^ → text
+    cleaned = re.sub(r'\^(.+?)\^', r'\1', cleaned)
+    
+    # 링크 제거: [text](url) → text
+    cleaned = re.sub(r'\[(.+?)\]\(.+?\)', r'\1', cleaned)
+    
+    # 남은 특수 마크다운 기호 제거
+    cleaned = cleaned.replace('**', '').replace('__', '')
+    
+    return cleaned.strip()
+
+
+def _add_textbox(
+    slide, 
+    bbox, 
+    text, 
+    scale_x, 
+    scale_y, 
+    category: str = "",
+    page_height: int = 0,
+    use_dark_bg: bool = False
+) -> None:
+    """
+    텍스트 박스 추가 (AutoSize 강제 적용 - 순서 수정 최종 버전)
+    """
+    try:
+        left = int(bbox[0] * scale_x)
+        top = int(bbox[1] * scale_y)
+        width = int((bbox[2] - bbox[0]) * scale_x)
+        height = int((bbox[3] - bbox[1]) * scale_y)
+        
+        if width <= 0 or height <= 0:
+            return
+
+        textbox = slide.shapes.add_textbox(left, top, width, height)
+        
+        # 1. 텍스트 프레임 설정
+        text_frame = textbox.text_frame
+        text_frame.clear()
+        text_frame.word_wrap = True
+        
+        # 정렬 및 여백: 박스 중앙에 오도록, 여백은 제거
+        text_frame.vertical_anchor = MSO_ANCHOR.MIDDLE
+        text_frame.margin_left = 0
+        text_frame.margin_right = 0
+        text_frame.margin_top = 0
+        text_frame.margin_bottom = 0
+        
+        # 2. 텍스트 입력 (가장 먼저!)
+        if len(text_frame.paragraphs) == 0:
+            p = text_frame.paragraphs.add_paragraph()
+        else:
+            p = text_frame.paragraphs[0]
+            
+        run = p.add_run()
+        cleaned_text = _clean_text_for_pptx(text)
+        run.text = cleaned_text
+        
+        # 3. 폰트 설정
+        is_bold = category in ('Title', 'Section-header')
+        if is_bold:
+            run.font.bold = True
+            
+        # 폰트 크기 전략: 박스 크기와 텍스트 구성 성분 기반 정교한 계산
+        run.font.size = _calculate_font_size(width, height, cleaned_text, category, is_bold=is_bold)
+
+        # 4. 색상 및 배경
+        if use_dark_bg:
+            run.font.color.rgb = RGBColor(255, 255, 255)
+            textbox.fill.solid()
+            textbox.fill.fore_color.rgb = RGBColor(0, 0, 0)
+        else:
+            run.font.color.rgb = RGBColor(0, 0, 0)
+            textbox.fill.solid()
+            textbox.fill.fore_color.rgb = RGBColor(255, 255, 255)
+            
+        # 5. AutoSize 설정 (마지막에!)
+        # MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE: 텍스트가 넘치면 폰트를 줄여서 맞춤
+        text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
+
+    except Exception as e:
+        print(f"Textbox add failed: {e}")
+
+
+def build_pptx_from_results(
+    parse_results: List[Dict],
+    background_images: List[Image.Image],
+    output_path: Path,
+) -> Tuple[int, int]:
+    """파싱 결과로부터 PPTX 생성"""
+    prs = Presentation()
+    
+    first_image = background_images[0] if background_images else None
+    sample_width, sample_height = 1200, 1600
+    if first_image:
+        sample_width, sample_height = first_image.width, first_image.height
+
+    slide_width = Inches(10)
+    slide_height = Inches(10 * sample_height / sample_width)
+    prs.slide_width = slide_width
+    prs.slide_height = slide_height
+
+    total_boxes = 0
+
+    for idx, result in enumerate(parse_results):
+        slide = prs.slides.add_slide(prs.slide_layouts[6])
+        bg_image = background_images[idx] if idx < len(background_images) else None
+        
+        page_width, page_height = _get_page_size(bg_image, result.get('layout_result'))
+        if page_width == 0: page_width = sample_width
+        if page_height == 0: page_height = sample_height
+
+        _add_background(slide, slide_width, slide_height, bg_image)
+
+        scale_x = slide_width / float(page_width)
+        scale_y = slide_height / float(page_height)
+
+        layout_data = result.get('layout_result') or []  # None 및 빈 값 방어
+        if layout_data and isinstance(layout_data, list):  # 타입 체크 추가
+            for cell in layout_data:
+                bbox = cell.get("bbox")
+                if not bbox or len(bbox) != 4:
+                    continue
+                category = cell.get("category", "")
+                text = cell.get("text", "") or ""
+                if category in ("Picture", "Table"):
+                    continue
+                if not text.strip():
+                    continue
+                _add_textbox(
+                    slide, bbox, text, scale_x, scale_y,
+                    category=category,
+                    page_height=page_height
+                )
+                total_boxes += 1
+
+    prs.save(output_path)
+    return len(parse_results), total_boxes
+
+if __name__ == "__main__":
+    # 간단한 테스트 코드
+    print("PPTX Generator Test")
+    # 더미 데이터 생성 및 테스트 가능
+

local_test.py

@@ -0,0 +1,48 @@
+import json
+import os
+from pathlib import Path
+from dots_ocr.utils.pptx_generator import build_pptx_from_results
+
+def main():
+    # 경로 설정
+    base_dir = Path(__file__).parent
+    input_json_path = base_dir / "test.json"
+    output_dir = base_dir / "output"
+    output_pptx_path = output_dir / "test_result.pptx"
+
+    # 1. Output 디렉토리 생성
+    output_dir.mkdir(exist_ok=True)
+
+    # 2. JSON 데이터 로드
+    if not input_json_path.exists():
+        print(f"Error: {input_json_path} not found.")
+        return
+
+    print(f"Reading data from {input_json_path}...")
+    with open(input_json_path, "r", encoding="utf-8") as f:
+        parse_results = json.load(f)
+
+    # 3. PPT 생성
+    # 배경 이미지가 없으므로 빈 리스트 전달 (흰 배경 생성됨)
+    # build_pptx_from_results는 background_images 리스트 길이를 체크하여 처리함
+    background_images = [] 
+
+    print("Generating PPTX...")
+    try:
+        page_count, box_count = build_pptx_from_results(
+            parse_results=parse_results,
+            background_images=background_images,
+            output_path=output_pptx_path
+        )
+        print(f"✅ Success! Generated {output_pptx_path}")
+        print(f"   Pages: {page_count}")
+        print(f"   Text Boxes: {box_count}")
+        
+    except Exception as e:
+        print(f"❌ Failed to generate PPTX: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()
+

test.json

@@ -0,0 +1,51 @@
+[
+  {
+    "layout_result": [
+      {
+        "bbox": [100, 100, 800, 200],
+        "category": "Title",
+        "text": "PPT 생성 테스트: 제목"
+      },
+      {
+        "bbox": [100, 250, 400, 300],
+        "category": "Section-header",
+        "text": "섹션 1: 개요"
+      },
+      {
+        "bbox": [100, 320, 500, 600],
+        "category": "Text",
+        "text": "이것은 로컬 테스트를 위한 더미 데이터입니다.\nJSON 파일에서 읽어온 좌표와 텍스트를 기반으로 PPT가 생성됩니다."
+      },
+      {
+        "bbox": [600, 320, 1000, 600],
+        "category": "List-item",
+        "text": "- 첫 번째 항목\n- 두 번째 항목\n- 세 번째 항목"
+      },
+      {
+        "bbox": [100, 800, 500, 850],
+        "category": "Caption",
+        "text": "그림 1: 테스트 데이터 구조"
+      },
+      {
+         "bbox": [100, 1400, 500, 1450],
+         "category": "Page-footer",
+         "text": "Page 1"
+      }
+    ]
+  },
+  {
+      "layout_result": [
+        {
+          "bbox": [100, 100, 800, 200],
+          "category": "Title",
+          "text": "두 번째 페이지"
+        },
+        {
+          "bbox": [100, 300, 800, 500],
+          "category": "Text",
+          "text": "페이지 넘김이 잘 동작하는지 확인합니다."
+        }
+      ]
+  }
+]
+