dsh-courseware 0.1.0

package/engine/pptxgen/util.py

@@ -0,0 +1,218 @@
+"""基础工具：单位换算、文本度量、颜色解析。"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional, Tuple
+
+from pptx.util import Emu, Inches, Pt
+
+EMU_PER_INCH = 914400
+EMU_PER_PT = 12700
+
+
+# --------------------------------------------------------------------------
+# 单位
+# --------------------------------------------------------------------------
+def emu_from_pt(pt: float) -> int:
+    return int(round(pt * EMU_PER_PT))
+
+
+def pt_from_emu(emu: Optional[float]) -> float:
+    if emu is None:
+        return 0.0
+    return float(emu) / EMU_PER_PT
+
+
+def inch_from_emu(emu: Optional[float]) -> float:
+    if emu is None:
+        return 0.0
+    return float(emu) / EMU_PER_INCH
+
+
+def emu_from_inch(inch: float) -> int:
+    return int(round(inch * EMU_PER_INCH))
+
+
+def parse_length(value, default: int = 0) -> int:
+    """把 '1.5in' / '3cm' / '24pt' / 1.5 / Emu 解析成 EMU。"""
+    if value is None:
+        return default
+    if isinstance(value, (int, float)):
+        return emu_from_inch(float(value))
+    if isinstance(value, Emu):
+        return int(value)
+    text = str(value).strip().lower()
+    m = re.match(r"^(-?[\d.]+)\s*(in|cm|mm|pt|px|emu)?$", text)
+    if not m:
+        return default
+    num = float(m.group(1))
+    unit = m.group(2) or "in"
+    factor = {
+        "in": EMU_PER_INCH,
+        "cm": EMU_PER_INCH / 2.54,
+        "mm": EMU_PER_INCH / 25.4,
+        "pt": EMU_PER_PT,
+        "px": EMU_PER_INCH / 96.0,
+        "emu": 1,
+    }[unit]
+    return int(round(num * factor))
+
+
+def fmt_len(emu: Optional[int]) -> str:
+    """EMU -> 人类可读字符串（英寸），用于 inspect 输出。"""
+    if emu is None:
+        return "-"
+    v = emu / EMU_PER_INCH
+    return f"{v:.2f}in"
+
+
+# --------------------------------------------------------------------------
+# 颜色
+# --------------------------------------------------------------------------
+_HEX_RE = re.compile(r"^#?([0-9a-fA-F]{6})$")
+
+
+def parse_color(value) -> Optional[str]:
+    """'#RRGGBB' / 'RRGGBB' / (r,g,b) -> 'RRGGBB'（无 #，大写）。"""
+    if value is None:
+        return None
+    if isinstance(value, (tuple, list)) and len(value) == 3:
+        return "".join(f"{int(c) & 0xFF:02X}" for c in value)
+    m = _HEX_RE.match(str(value).strip())
+    if not m:
+        return None
+    return m.group(1).upper()
+
+
+def rgb_tuple(hex_color: str) -> Tuple[int, int, int]:
+    h = parse_color(hex_color) or "000000"
+    return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+
+
+def relative_luminance(hex_color: str) -> float:
+    r, g, b = rgb_tuple(hex_color)
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255.0
+
+
+def readable_on(hex_color: str, dark: str = "1A1A1A", light: str = "FFFFFF") -> str:
+    """在给定底色上选择一个可读的文字色。"""
+    return dark if relative_luminance(hex_color) > 0.55 else light
+
+
+def mix(hex_a: str, hex_b: str, t: float) -> str:
+    """线性混色，t=0 -> a，t=1 -> b。"""
+    ra, ga, ba = rgb_tuple(hex_a)
+    rb, gb, bb = rgb_tuple(hex_b)
+    r = int(round(ra + (rb - ra) * t))
+    g = int(round(ga + (gb - ga) * t))
+    b = int(round(ba + (bb - ba) * t))
+    return f"{r:02X}{g:02X}{b:02X}"
+
+
+# --------------------------------------------------------------------------
+# 文本度量（不依赖字体文件，CJK 场景下足够准）
+# --------------------------------------------------------------------------
+_NARROW = {
+    " ": 0.28, "\u3000": 1.0, "!": 0.30, '"': 0.40, "#": 0.60, "$": 0.60,
+    "%": 0.90, "&": 0.72, "'": 0.25, "(": 0.35, ")": 0.35, "*": 0.50,
+    "+": 0.60, ",": 0.30, "-": 0.35, ".": 0.30, "/": 0.40, ":": 0.30,
+    ";": 0.30, "<": 0.60, "=": 0.60, ">": 0.60, "?": 0.55, "@": 0.95,
+    "[": 0.35, "\\": 0.40, "]": 0.35, "^": 0.55, "_": 0.50, "`": 0.35,
+    "{": 0.40, "|": 0.28, "}": 0.40, "~": 0.60,
+    "f": 0.36, "i": 0.28, "j": 0.28, "l": 0.28, "r": 0.40, "t": 0.38,
+    "I": 0.32, "J": 0.50, "M": 0.88, "W": 0.90,
+    "m": 0.86, "w": 0.76,
+    "A": 0.68, "B": 0.66, "C": 0.70, "D": 0.72, "E": 0.60, "F": 0.58,
+    "G": 0.74, "H": 0.72, "K": 0.68, "L": 0.56, "N": 0.72, "O": 0.76,
+    "P": 0.64, "Q": 0.76, "R": 0.68, "S": 0.64, "T": 0.62, "U": 0.72,
+    "V": 0.68, "X": 0.66, "Y": 0.62, "Z": 0.60,
+}
+_DEFAULT_ASCII = 0.55
+
+
+def char_width_em(ch: str) -> float:
+    """单个字符宽度，单位为 em。"""
+    code = ord(ch)
+    if code < 0x20:
+        return 0.0
+    if _is_wide(ch):
+        return 1.0
+    if ch in _NARROW:
+        return _NARROW[ch]
+    if "0" <= ch <= "9":
+        return 0.55
+    if "a" <= ch <= "z":
+        return 0.55
+    if "A" <= ch <= "Z":
+        return 0.68
+    return _DEFAULT_ASCII
+
+
+def _is_wide(ch: str) -> bool:
+    code = ord(ch)
+    return (
+        0x1100 <= code <= 0x115F
+        or 0x2E80 <= code <= 0xA4CF
+        or 0xA960 <= code <= 0xA97F
+        or 0xAC00 <= code <= 0xD7A3
+        or 0xF900 <= code <= 0xFAFF
+        or 0xFE10 <= code <= 0xFE19
+        or 0xFE30 <= code <= 0xFE6F
+        or 0xFF00 <= code <= 0xFF60
+        or 0xFFE0 <= code <= 0xFFE6
+        or 0x1F300 <= code <= 0x1FAFF
+        or 0x20000 <= code <= 0x3FFFD
+    )
+
+
+def text_width_em(text: str, bold: bool = False) -> float:
+    w = sum(char_width_em(c) for c in text)
+    return w * (1.04 if bold else 1.0)
+
+
+def text_width_pt(text: str, size_pt: float, bold: bool = False) -> float:
+    return text_width_em(text, bold) * size_pt
+
+
+def wrap_lines(text: str, size_pt: float, box_width_pt: float, bold: bool = False) -> int:
+    """粗略估算在给定宽度下会折成几行（按字符贪心，中文逐字断行）。"""
+    if box_width_pt <= 1 or size_pt <= 0:
+        return 1
+    lines = 1
+    cur = 0.0
+    for ch in text:
+        if ch == "\n":
+            lines += 1
+            cur = 0.0
+            continue
+        w = char_width_em(ch) * size_pt * (1.04 if bold else 1.0)
+        if cur + w > box_width_pt and cur > 0:
+            lines += 1
+            cur = w
+        else:
+            cur += w
+    return lines
+
+
+def split_paragraphs(text: str) -> list:
+    if text is None:
+        return []
+    return [p for p in str(text).replace("\r\n", "\n").replace("\r", "\n").split("\n")]
+
+
+def clean_lines(items: Optional[Iterable]) -> list:
+    """把 YAML 里可能是 str 或 list 的字段规整成字符串列表。"""
+    if items is None:
+        return []
+    if isinstance(items, str):
+        return split_paragraphs(items)
+    out = []
+    for it in items:
+        if it is None:
+            continue
+        if isinstance(it, dict):
+            out.append(it)
+        else:
+            out.append(str(it))
+    return out

package/engine/pptxgen/xmlutil.py

@@ -0,0 +1,298 @@
+"""OOXML 底层辅助：命名空间、背景读取、形状克隆、关系重映射。"""
+
+from __future__ import annotations
+
+import copy
+from typing import Iterator, List, Optional
+
+from pptx.oxml.ns import qn
+
+A = "http://schemas.openxmlformats.org/drawingml/2006/main"
+P = "http://schemas.openxmlformats.org/presentationml/2006/main"
+R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+RT_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+
+
+# --------------------------------------------------------------------------
+# 背景读取
+# --------------------------------------------------------------------------
+def cSld_of(element):
+    """从 sld / sldLayout / sldMaster 元素上取 cSld。"""
+    return element.find(qn("p:cSld"))
+
+
+def get_bg(element):
+    """取出 <p:bg>，没有则返回 None。"""
+    cSld = cSld_of(element)
+    if cSld is None:
+        return None
+    return cSld.find(qn("p:bg"))
+
+
+def describe_bg(bg) -> Optional[dict]:
+    """把 <p:bg> 解析成 {kind, rId?, color?, lumMod?, lumOff?, theme_idx?}。"""
+    if bg is None:
+        return None
+    bgPr = bg.find(qn("p:bgPr"))
+    if bgPr is not None:
+        blip = bgPr.find(qn("a:blipFill"))
+        if blip is not None:
+            blipEl = blip.find(qn("a:blip"))
+            rId = blipEl.get(qn("r:embed")) if blipEl is not None else None
+            return {"kind": "picture", "rId": rId}
+        solid = bgPr.find(qn("a:solidFill"))
+        if solid is not None:
+            color = _read_color(solid)
+            if color:
+                return {"kind": "solid", "color": color}
+        grad = bgPr.find(qn("a:gradFill"))
+        if grad is not None:
+            return {"kind": "gradient"}
+        nofill = bgPr.find(qn("a:noFill"))
+        if nofill is not None:
+            return {"kind": "none"}
+    bgRef = bg.find(qn("p:bgRef"))
+    if bgRef is not None:
+        idx = bgRef.get("idx")
+        color = _read_color(bgRef)
+        return {"kind": "ref", "theme_idx": int(idx) if idx else 0, "color": color}
+    return None
+
+
+def _read_color(parent) -> Optional[str]:
+    """从含 srgbClr / sysClr 的节点里读颜色（忽略 lumMod/lumOff 的精确计算）。"""
+    if parent is None:
+        return None
+    srgb = parent.find(qn("a:srgbClr"))
+    if srgb is not None:
+        return (srgb.get("val") or "").upper() or None
+    sysclr = parent.find(qn("a:sysClr"))
+    if sysclr is not None:
+        return (sysclr.get("lastClr") or "").upper() or None
+    return None
+
+
+def resolve_bg(slide=None, layout=None, master=None) -> Optional[dict]:
+    """按 slide -> layout -> master 的顺序解析背景，返回第一个命中的。"""
+    for source, owner in ((slide, "slide"), (layout, "layout"), (master, "master")):
+        if source is None:
+            continue
+        bg = get_bg(source._element)
+        info = describe_bg(bg)
+        if info and info.get("kind") != "none":
+            info["from"] = owner
+            info["element"] = bg
+            info["owner"] = source
+            return info
+    return None
+
+
+# --------------------------------------------------------------------------
+# 形状遍历
+# --------------------------------------------------------------------------
+def iter_shape_elements(spTree) -> Iterator:
+    for el in spTree:
+        tag = el.tag
+        if tag in (qn("p:sp"), qn("p:pic"), qn("p:graphicFrame"), qn("p:grpSp"), qn("p:cxnSp")):
+            yield el
+
+
+def is_placeholder(element) -> bool:
+    nv = element.find(qn("p:nvSpPr"))
+    if nv is None:
+        nv = element.find(qn("p:nvPicPr"))
+    if nv is None:
+        nv = element.find(qn("p:nvGraphicFramePr"))
+    if nv is None:
+        return False
+    nvPr = nv.find(qn("p:nvPr"))
+    if nvPr is None:
+        return False
+    return nvPr.find(qn("p:ph")) is not None
+
+
+def placeholder_idx(element) -> Optional[int]:
+    nv = element.find(qn("p:nvSpPr"))
+    if nv is None:
+        return None
+    nvPr = nv.find(qn("p:nvPr"))
+    if nvPr is None:
+        return None
+    ph = nvPr.find(qn("p:ph"))
+    if ph is None:
+        return None
+    idx = ph.get("idx")
+    return int(idx) if idx is not None else 0
+
+
+def placeholder_type(element) -> Optional[str]:
+    nv = element.find(qn("p:nvSpPr"))
+    if nv is None:
+        return None
+    nvPr = nv.find(qn("p:nvPr"))
+    if nvPr is None:
+        return None
+    ph = nvPr.find(qn("p:ph"))
+    if ph is None:
+        return None
+    return (ph.get("type") or "body").lower()
+
+
+def shape_name(element) -> str:
+    for tag in ("p:nvSpPr", "p:nvPicPr", "p:nvGraphicFramePr", "p:nvGrpSpPr", "p:nvCxnSpPr"):
+        nv = element.find(qn(tag))
+        if nv is not None:
+            cNvPr = nv.find(qn("p:cNvPr"))
+            if cNvPr is not None:
+                return cNvPr.get("name") or ""
+    return ""
+
+
+def shape_off_ext(element):
+    """返回 (x, y, cx, cy)，可能部分为 None。"""
+    xfrm = element.find(f".//{qn('a:xfrm')}")
+    if xfrm is None:
+        return None, None, None, None
+    off = xfrm.find(qn("a:off"))
+    ext = xfrm.find(qn("a:ext"))
+    x = int(off.get("x")) if off is not None and off.get("x") else None
+    y = int(off.get("y")) if off is not None and off.get("y") else None
+    cx = int(ext.get("cx")) if ext is not None and ext.get("cx") else None
+    cy = int(ext.get("cy")) if ext is not None and ext.get("cy") else None
+    return x, y, cx, cy
+
+
+def set_shape_off_ext(element, x, y, cx, cy) -> None:
+    xfrm = element.find(f".//{qn('a:xfrm')}")
+    if xfrm is None:
+        return
+    off = xfrm.find(qn("a:off"))
+    ext = xfrm.find(qn("a:ext"))
+    if off is not None:
+        off.set("x", str(int(x)))
+        off.set("y", str(int(y)))
+    if ext is not None:
+        ext.set("cx", str(int(cx)))
+        ext.set("cy", str(int(cy)))
+
+
+def blip_rid(element) -> Optional[str]:
+    blip = element.find(f".//{qn('a:blip')}")
+    if blip is None:
+        return None
+    return blip.get(qn("r:embed"))
+
+
+def set_blip_rid(element, rId: str) -> None:
+    blip = element.find(f".//{qn('a:blip')}")
+    if blip is not None:
+        blip.set(qn("r:embed"), rId)
+
+
+def next_shape_id(spTree) -> int:
+    ids = [1]
+    for cNvPr in spTree.iter(qn("p:cNvPr")):
+        try:
+            ids.append(int(cNvPr.get("id")))
+        except (TypeError, ValueError):
+            continue
+    return max(ids) + 1
+
+
+def renumber_shape_id(element, new_id: int) -> None:
+    for cNvPr in element.iter(qn("p:cNvPr")):
+        cNvPr.set("id", str(new_id))
+        return
+
+
+def strip_placeholder(element) -> None:
+    """移除 p:ph，使克隆过来的形状不再是占位符（避免版式冲突）。"""
+    for nvPr in element.iter(qn("p:nvPr")):
+        ph = nvPr.find(qn("p:ph"))
+        if ph is not None:
+            nvPr.remove(ph)
+
+
+def remap_rels(src_part, dest_part, element) -> None:
+    """把 element 里所有 r:embed / r:link 重映射到 dest_part 的关系 id。"""
+    for attr in (qn("r:embed"), qn("r:link")):
+        for node in element.iter():
+            rId = node.get(attr)
+            if not rId:
+                continue
+            try:
+                part = src_part.related_part(rId)
+            except KeyError:
+                node.attrib.pop(attr, None)
+                continue
+            new_rId = dest_part.relate_to(part, RT_IMAGE)
+            node.set(attr, new_rId)
+
+
+def clone_shape(src_slide, element, dest_slide):
+    """把源幻灯片上的一个形状深拷贝到目标幻灯片，处理关系与 id。"""
+    new_el = copy.deepcopy(element)
+    strip_placeholder(new_el)
+    remap_rels(src_slide.part, dest_slide.part, new_el)
+    spTree = dest_slide.shapes._spTree
+    renumber_shape_id(new_el, next_shape_id(spTree))
+    spTree.append(new_el)
+    return new_el
+
+
+def clone_bg(src_owner, bg_element, dest_slide):
+    """把 <p:bg> 深拷贝到目标幻灯片并重映射图片关系。"""
+    new_bg = copy.deepcopy(bg_element)
+    remap_rels(src_owner.part, dest_slide.part, new_bg)
+    cSld = cSld_of(dest_slide._element)
+    old = cSld.find(qn("p:bg"))
+    if old is not None:
+        cSld.remove(old)
+    # <p:bg> 必须是 cSld 的第一个子元素
+    cSld.insert(0, new_bg)
+    return new_bg
+
+
+def remove_bg(slide) -> None:
+    cSld = cSld_of(slide._element)
+    if cSld is None:
+        return
+    bg = cSld.find(qn("p:bg"))
+    if bg is not None:
+        cSld.remove(bg)
+
+
+def full_bleed_ratio(element, slide_w: int, slide_h: int) -> float:
+    """形状覆盖画布的比例（按面积），用于识别整页背景图。"""
+    x, y, cx, cy = shape_off_ext(element)
+    if None in (x, y, cx, cy) or slide_w <= 0 or slide_h <= 0:
+        return 0.0
+    area = (cx * cy) / float(slide_w * slide_h)
+    near_origin = abs(x) <= slide_w * 0.06 and abs(y) <= slide_h * 0.06
+    return area if near_origin else min(area, 0.5)
+
+
+def solid_fill_luminance(element, theme_colors=None) -> Optional[float]:
+    """形状纯色填充的相对亮度（0=黑，1=白）；不是纯色填充时返回 None。
+
+    有的模板不用 <p:bg>，而是拿一个整页纯色形状当背景——判断"深色模板"时要认得出。
+    """
+    from .util import relative_luminance
+
+    spPr = element.find(qn("p:spPr"))
+    if spPr is None:
+        return None
+    solid = spPr.find(qn("a:solidFill"))
+    if solid is None:
+        return None
+    srgb = solid.find(qn("a:srgbClr"))
+    color = None
+    if srgb is not None:
+        color = (srgb.get("val") or "").upper() or None
+    else:
+        scheme = solid.find(qn("a:schemeClr"))
+        if scheme is not None:
+            color = (theme_colors or {}).get(scheme.get("val"))
+    if not color:
+        return None
+    return relative_luminance(color)

package/engine/pptxgen.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# courseware 引擎入口 —— 可在任意目录调用。
+#   /path/to/engine/pptxgen.sh build decks/xxx.yaml
+# 引擎目录自动加入 PYTHONPATH，因此不依赖当前工作目录。
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec env PYTHONPATH="$DIR${PYTHONPATH:+:$PYTHONPATH}" "$DIR/.venv/bin/python" -m pptxgen "$@"

package/engine/requirements.txt

@@ -0,0 +1,9 @@
+# pptxgen 引擎 —— Python 3.10+ 依赖
+# 首次使用：python3 -m venv "<引擎目录>/.venv"
+#           "<引擎目录>/.venv/bin/pip" install -r "<引擎目录>/requirements.txt"
+python-pptx>=1.0
+lxml>=5.0
+pymupdf>=1.24
+pillow>=10.0
+pyyaml>=6.0
+certifi>=2024.0