dsh-courseware 0.1.0

package/engine/pptxgen/layoutmap.py

@@ -0,0 +1,211 @@
+"""页型 -> 模板版式 的自动映射。"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .template import LayoutInfo, TemplateInfo
+
+# 版式名关键词（中英双语，覆盖 Office 默认主题命名）
+KEYWORDS: Dict[str, List[str]] = {
+    "cover": ["封面", "标题幻灯片", "标题页", "首页", "title slide", "title & subtitle", "cover"],
+    "toc": ["目录", "內容", "内容页", "agenda", "contents", "table of contents", "toc"],
+    "section": ["节标题", "章节", "过渡", "分隔", "部分", "section header", "section", "divider"],
+    "objectives": ["目标", "objective", "学习目标", "goals"],
+    "content": [
+        "标题和内容", "标题与内容", "内容与标题", "两栏内容", "正文", "图文",
+        "title and content", "content with caption", "two content", "picture with caption",
+    ],
+    "example": ["例题", "示例", "范例", "example", "sample"],
+    "practice": ["练习", "习题", "测验", "检测", "practice", "quiz", "exercise"],
+    "summary": ["小结", "总结", "summary", "思维导图", "mindmap", "回顾"],
+    "homework": ["作业", "homework", "assignment", "课后"],
+    "end": ["结束", "谢谢", "谢谢观看", "end", "thanks", "thank you", "空白", "blank"],
+}
+
+# 这些页型只需要一个标题占位符
+TITLE_ONLY_TYPES = {"cover", "section", "end"}
+
+
+def build_map(tpl: TemplateInfo, overrides: Optional[dict] = None) -> Dict[str, int]:
+    """为每个页型挑选最合适的版式索引。
+
+    优先顺序：用户显式覆盖 > 样张学到的角色版式 > 主母版内的关键词/结构打分。
+    多母版模板里这一步很关键——套错母版会让整套配色和背景都不对。
+    """
+    overrides = overrides or {}
+    result: Dict[str, int] = {}
+
+    # 1) 用户显式覆盖优先
+    for stype, value in overrides.items():
+        idx = resolve_layout_ref(tpl, value)
+        if idx is not None:
+            result[stype] = idx
+
+    # 2) 样张给出的角色先验：封面/结束页常常和内容页不是同一套母版
+    role = getattr(tpl, "role_layout", None) or {}
+    for stype in ("cover", "end"):
+        if stype not in result and stype in role:
+            result[stype] = role[stype]
+
+    # 3) 其余页型：限定在"样张内容页所属母版"内打分
+    preferred_master = None
+    if "content" in role:
+        lay = tpl.layout_by_index(role["content"])
+        if lay is not None:
+            preferred_master = lay.master_index
+    pool = [l for l in tpl.layouts
+            if preferred_master is None or l.master_index == preferred_master] or list(tpl.layouts)
+
+    for stype, kws in KEYWORDS.items():
+        if stype in result:
+            continue
+        best_idx, best_score = None, -10 ** 9
+        for lay in pool:
+            sc = _score(tpl, lay, stype, kws)
+            if sc > best_score:
+                best_idx, best_score = lay.index, sc
+        if best_idx is not None and best_score > 0:
+            result[stype] = best_idx
+
+    # 3.5) 样张内容页版式先验：关键词挑的版式若在样张里从没被用过，
+    #      而样张内容页明显集中在另一个版式（如"标题幻灯片"上画装饰）
+    #      —— 套用样张实际用的版式，否则会丢掉模板的装饰层（背景渐变等）。
+    content_role = role.get("content")
+    if content_role is not None:
+        role_lay = tpl.layout_by_index(content_role)
+        if role_lay is not None and role_lay.find_title() is not None:
+            usage = _sample_layout_usage(tpl)
+            for stype in ("content", "example", "practice", "summary",
+                          "homework", "toc", "objectives", "section"):
+                cur = result.get(stype)
+                if cur is None or cur == content_role:
+                    continue
+                if usage.get(cur, 0) == 0 and usage.get(content_role, 0) > 0:
+                    result[stype] = content_role
+
+    # 4) 兜底
+    fallback = _generic_layout(tpl, pool)
+    for stype in KEYWORDS:
+        result.setdefault(stype, fallback)
+    return result
+
+
+def _score(tpl: TemplateInfo, lay: LayoutInfo, stype: str, keywords: List[str]) -> int:
+    name = (lay.name or "").lower()
+    s = 0
+    for kw in keywords:
+        if kw.lower() in name:
+            s += 20
+            break
+
+    title = lay.find_title()
+    body = lay.find_body()
+    total_area = float((tpl.width or 1) * (tpl.height or 1))
+
+    if stype in TITLE_ONLY_TYPES:
+        if title:
+            s += 4
+        else:
+            s -= 25          # 章节/封面/结束页没有标题占位符基本不可用
+        if body:
+            s -= 3
+        if len(lay.placeholders) <= 2:
+            s += 2
+    else:
+        if title:
+            s += 4
+        else:
+            s -= 8
+        if body:
+            s += 6
+            # 正文区域越大越适合做通用内容页
+            area = float((body.width or 0) * (body.height or 0)) / total_area
+            s += int(round(max(0.0, min(area, 0.75)) * 12))
+        else:
+            s -= 14
+        # 除标题/正文/页眉页脚之外的大占位符，说明这是专用版式
+        extras = [
+            ph for ph in lay.placeholders
+            if not ph.is_title and not ph.is_body and not ph.is_decoration
+            and ph.width and ph.height and ph.width * ph.height > 0.05 * total_area
+        ]
+        s -= 4 * len(extras)
+        if len(lay.placeholders) > 6:
+            s -= 3
+
+    # 名字里带"竖排"的一般不用
+    if "竖排" in (lay.name or "") or "vertical" in name:
+        s -= 12
+    return s
+
+
+def _sample_layout_usage(tpl: TemplateInfo) -> Dict[int, int]:
+    """统计样张里每张幻灯片实际挂在哪个版式上（跨多母版全局下标）。"""
+    usage: Dict[int, int] = {}
+    try:
+        prs = tpl._prs
+        for slide in prs.slides:
+            partname = str(slide.slide_layout.part.partname)
+            for i, lo in enumerate(tpl.layout_objects):
+                try:
+                    if str(lo.part.partname) == partname:
+                        usage[i] = usage.get(i, 0) + 1
+                        break
+                except Exception:
+                    continue
+    except Exception:
+        pass
+    return usage
+
+
+def _generic_layout(tpl: TemplateInfo, pool=None) -> int:
+    """挑一个最保险的通用版式：有标题+最大正文占位符。"""
+    best, best_score = 0, -10 ** 9
+    for lay in (pool or tpl.layouts):
+        title = lay.find_title()
+        body = lay.find_body()
+        s = 0
+        if body:
+            s += (body.width or 0) * (body.height or 0) / 1e12
+        if title:
+            s += 2
+        if len(lay.placeholders) == 0:
+            s -= 1
+        if s > best_score:
+            best, best_score = lay.index, s
+    return best
+
+
+def resolve_layout_ref(tpl: TemplateInfo, value) -> Optional[int]:
+    return _resolve_layout_ref(tpl, value)
+
+
+def _resolve_layout_ref(tpl: TemplateInfo, value) -> Optional[int]:
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return value if tpl.layout_by_index(value) else None
+    text = str(value).strip()
+    if text.isdigit():
+        idx = int(text)
+        return idx if tpl.layout_by_index(idx) else None
+    low = text.lower()
+    for lay in tpl.layouts:
+        if (lay.name or "").lower() == low:
+            return lay.index
+    for lay in tpl.layouts:
+        if low in (lay.name or "").lower():
+            return lay.index
+    return None
+
+
+def describe_map(tpl: TemplateInfo, mapping: Dict[str, int]) -> str:
+    from .spec import TYPE_LABELS
+
+    lines = ["页型 -> 模板版式 映射"]
+    for stype, idx in mapping.items():
+        lay = tpl.layout_by_index(idx)
+        label = TYPE_LABELS.get(stype, stype)
+        lines.append(f"  {label:<8} ({stype:<10}) -> [{idx}] {lay.name if lay else '?'}")
+    return "\n".join(lines)

package/engine/pptxgen/patterns.py

@@ -0,0 +1,106 @@
+"""版面骨架（pattern）的判定与清单。
+
+渲染器和设计审查共用同一套判定，避免"审查说的"和"渲染做的"不一致。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Sequence
+
+# 步骤型文字特征：第1步 / 步骤一 / ① / 1.
+STEP_RE = re.compile(
+    r"^\s*(第\s*[一二三四五六七八九十\d]+\s*步|步骤\s*[一二三四五六七八九十\d]+|"
+    r"[①②③④⑤⑥⑦⑧⑨]|\d+\s*[.、．)）])"
+)
+
+# 全部可用骨架
+PATTERNS = ("bullets", "steps", "flow", "compare", "cards", "levels", "timeline",
+            "callout", "image_left", "image_right")
+
+# 单页最适合的骨架（内容形态 -> 骨架）
+CONTENT_MATCH = {
+    "流程/步骤/环节": "flow",
+    "有序步骤": "steps",
+    "并列要点": "cards",
+    "分级/强弱梯度": "levels",
+    "两者对照": "compare",
+    "先后/因果": "timeline",
+    "核心问题/结论": "callout",
+    "一般叙述": "bullets",
+}
+
+
+def guess_pattern(spec: dict, bullets: Optional[Sequence[dict]] = None) -> str:
+    """显式 pattern 优先；没有就按内容形态自动挑一个（确定性）。"""
+    explicit = str(spec.get("pattern") or "").strip().lower()
+    if explicit and explicit != "auto":
+        return explicit
+    if [t for t in (spec.get("timeline") or []) if t.get("text")]:
+        return "timeline"
+    if spec.get("compare"):
+        return "compare"
+    if [s for s in (spec.get("steps") or []) if s.get("text")]:
+        return "steps"
+    if spec.get("cards"):
+        return "cards"
+    items = bullets if bullets is not None else (spec.get("bullets") or [])
+    lvl0 = [b.get("text", "") for b in items if int(b.get("level", 0) or 0) == 0]
+    if len(lvl0) >= 3 and sum(1 for t in lvl0 if STEP_RE.match(t)) >= 2:
+        return "steps"
+    return "bullets"
+
+
+def collect_texts(spec: dict) -> List[str]:
+    """把一页里所有会显示出来的文字收集起来（用于密度/润色检查）。"""
+    out: List[str] = []
+
+    def add(v):
+        if isinstance(v, str) and v.strip():
+            out.append(v.strip())
+
+    add(spec.get("title"))
+    add(spec.get("subtitle"))
+    add(spec.get("key"))
+    add(spec.get("image_caption"))
+    for key in ("bullets", "steps", "points", "items", "goals", "key_points", "hard_points"):
+        for b in spec.get(key) or []:
+            if isinstance(b, dict):
+                add(b.get("text"))
+            else:
+                add(b)
+    for c in spec.get("cards") or []:
+        add(c.get("title"))
+        for it in c.get("items") or []:
+            add(it)
+    cmp = spec.get("compare") or {}
+    for side in ("left", "right"):
+        d = cmp.get(side) or {}
+        add(d.get("title"))
+        for it in d.get("items") or []:
+            add(it)
+    for t in spec.get("timeline") or []:
+        add(t.get("time"))
+        add(t.get("text"))
+    for q in spec.get("questions") or []:
+        add(q.get("q"))
+        for o in q.get("options") or []:
+            add(o)
+        add(q.get("answer"))
+        add(q.get("analysis"))
+    return out
+
+
+def text_len(texts: Sequence[str]) -> int:
+    """中文字符按 1 计，连续西文按 1 个词计。"""
+    n = 0
+    for t in texts:
+        t = re.sub(r"\*\*", "", str(t))
+        cn = len(re.findall(r"[\u4e00-\u9fff]", t))
+        en = len(re.findall(r"[A-Za-z0-9]+", t))
+        n += cn + en
+    return n
+
+
+def highlight_count(spec: dict) -> int:
+    return sum(len(re.findall(r"\*\*.+?\*\*", t)) for t in collect_texts(spec))

package/engine/pptxgen/preview.py

@@ -0,0 +1,126 @@
+"""渲染预览：用 LibreOffice 把 pptx 转成 PDF，再用 PyMuPDF 出 PNG。
+
+没有 LibreOffice 时会给出清晰提示，不影响生成 pptx 本身。
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import shutil
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+SOFFICE_CANDIDATES = [
+    os.environ.get("PPTXGEN_SOFFICE", ""),
+    os.path.join(ROOT, ".tools", "LibreOffice.app", "Contents", "MacOS", "soffice"),
+    "/Applications/LibreOffice.app/Contents/MacOS/soffice",
+    "/opt/homebrew/bin/soffice",
+    "/usr/local/bin/soffice",
+    "/usr/bin/soffice",
+    "/usr/bin/libreoffice",
+]
+
+
+def find_soffice() -> Optional[str]:
+    for cand in SOFFICE_CANDIDATES:
+        if cand and os.path.exists(cand):
+            return cand
+    for name in ("soffice", "libreoffice"):
+        found = shutil.which(name)
+        if found:
+            return found
+    return None
+
+
+def to_pdf(pptx_path: str, out_dir: str, timeout: int = 300) -> str:
+    """用 LibreOffice 转 PDF，返回 PDF 路径。"""
+    soffice = find_soffice()
+    if not soffice:
+        raise RuntimeError(
+            "未找到 LibreOffice，无法渲染预览。\n"
+            "  安装方式一：brew install --cask libreoffice\n"
+            "  安装方式二：把 LibreOffice.app 放到 /Applications 下\n"
+            "  或设置环境变量 PPTXGEN_SOFFICE=/path/to/soffice"
+        )
+    os.makedirs(out_dir, exist_ok=True)
+    out_dir = os.path.abspath(out_dir)
+    # profile 放在 .tools 下复用（加速第二次转换），不污染输出目录
+    profile_root = os.path.join(ROOT, ".tools")
+    os.makedirs(profile_root, exist_ok=True)
+    profile = os.path.join(profile_root, "lo_profile")
+    cmd = [
+        soffice, "--headless", "--norestore", "--invisible", "--nolockcheck",
+        f"-env:UserInstallation=file://{profile}",
+        "--convert-to", "pdf",
+        "--outdir", out_dir, os.path.abspath(pptx_path),
+    ]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(f"LibreOffice 转换超时（>{timeout}s）。可尝试手动运行：\n  {' '.join(cmd)}")
+    pdf = os.path.join(out_dir, os.path.splitext(os.path.basename(pptx_path))[0] + ".pdf")
+    if not os.path.exists(pdf):
+        raise RuntimeError(
+            f"LibreOffice 转换失败（returncode={proc.returncode}）\n"
+            f"stdout: {proc.stdout[-800:]}\nstderr: {proc.stderr[-800:]}"
+        )
+    return pdf
+
+
+def pdf_to_pngs(pdf_path: str, out_dir: str, dpi: int = 110) -> List[str]:
+    import pymupdf as fitz
+
+    os.makedirs(out_dir, exist_ok=True)
+    base = os.path.splitext(os.path.basename(pdf_path))[0]
+    paths: List[str] = []
+    with fitz.open(pdf_path) as doc:
+        for i, page in enumerate(doc, 1):
+            pix = page.get_pixmap(dpi=dpi)
+            out = os.path.join(out_dir, f"{base}_{i:02d}.png")
+            pix.save(out)
+            paths.append(out)
+    return paths
+
+
+def contact_sheet(png_paths: List[str], out_path: str, cols: int = 3,
+                  cell_w: int = 560, pad: int = 12) -> str:
+    """把多页预览拼成一张总览图。"""
+    from PIL import Image, ImageDraw
+
+    if not png_paths:
+        raise ValueError("没有可拼接的预览图")
+    imgs = []
+    for p in png_paths:
+        with Image.open(p) as im:
+            im = im.convert("RGB")
+            ratio = cell_w / float(im.width)
+            imgs.append(im.resize((cell_w, max(int(im.height * ratio), 1)), Image.LANCZOS))
+    cell_h = max(i.height for i in imgs)
+    rows = (len(imgs) + cols - 1) // cols
+    W = cols * cell_w + (cols + 1) * pad
+    H = rows * cell_h + (rows + 1) * pad
+    sheet = Image.new("RGB", (W, H), (238, 241, 246))
+    draw = ImageDraw.Draw(sheet)
+    for idx, im in enumerate(imgs):
+        r, c = divmod(idx, cols)
+        x = pad + c * (cell_w + pad)
+        y = pad + r * (cell_h + pad)
+        sheet.paste(im, (x, y))
+        draw.rectangle([x - 1, y - 1, x + im.width, y + im.height], outline=(180, 190, 205))
+    sheet.save(out_path)
+    return out_path
+
+
+def render(pptx_path: str, out_dir: str, *, dpi: int = 110,
+           sheet_name: Optional[str] = None) -> Tuple[List[str], Optional[str], str]:
+    """完整流程：pptx -> pdf -> 每页 png (+ 总览图)。"""
+    pdf = to_pdf(pptx_path, out_dir)
+    pngs = pdf_to_pngs(pdf, out_dir, dpi=dpi)
+    sheet = None
+    if sheet_name and pngs:
+        sheet = contact_sheet(pngs, os.path.join(out_dir, sheet_name))
+    return pngs, sheet, pdf