dsh-courseware 0.1.0

package/engine/pptxgen/shapes.py

@@ -0,0 +1,417 @@
+"""形状绘制层：文本框、自动缩放、项目符号、图片、图形。"""
+
+from __future__ import annotations
+
+import io
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional, Sequence, Tuple
+
+from pptx.dml.color import RGBColor
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE, PP_ALIGN
+from pptx.oxml.ns import qn
+from pptx.util import Emu, Pt
+
+from .util import (EMU_PER_INCH, EMU_PER_PT, emu_from_inch, parse_color,
+                   pt_from_emu, rgb_tuple, wrap_lines)
+
+ALIGN_MAP = {
+    "left": PP_ALIGN.LEFT, "l": PP_ALIGN.LEFT,
+    "center": PP_ALIGN.CENTER, "c": PP_ALIGN.CENTER, "centre": PP_ALIGN.CENTER,
+    "right": PP_ALIGN.RIGHT, "r": PP_ALIGN.RIGHT,
+    "justify": PP_ALIGN.JUSTIFY,
+}
+
+ANCHOR_MAP = {
+    "top": MSO_ANCHOR.TOP, "t": MSO_ANCHOR.TOP,
+    "middle": MSO_ANCHOR.MIDDLE, "center": MSO_ANCHOR.MIDDLE, "c": MSO_ANCHOR.MIDDLE,
+    "bottom": MSO_ANCHOR.BOTTOM, "b": MSO_ANCHOR.BOTTOM,
+}
+
+
+@dataclass
+class Para:
+    """一段文字（一个段落）。"""
+
+    text: str = ""
+    size: float = 18.0
+    bold: bool = False
+    italic: bool = False
+    color: Optional[str] = None
+    font: Optional[str] = None
+    align: Optional[str] = None   # None = 继承模板/默认左对齐
+    level: int = 0
+    bullet: Optional[str] = None      # None 表示继承；"" 表示无
+    indent_in: float = 0.0
+    space_before: float = 0.0         # 磅
+    space_after: float = 0.0
+    line_spacing: float = 1.18        # 倍数
+    runs: Optional[List[dict]] = None  # 可选：段内多 run（富文本）
+
+
+def measure_block(paras: Sequence[Para], width_pt: float) -> float:
+    """估算一段内容渲染后需要的高度（磅）。"""
+    total = 0.0
+    for p in paras:
+        size = max(p.size, 1.0)
+        text = p.text or ""
+        if p.runs:
+            text = "".join(r.get("text", "") for r in p.runs)
+        n_lines = max(1, wrap_lines(text, size, max(width_pt - p.indent_in * 72.0, 12.0), p.bold))
+        total += p.space_before + p.space_after
+        total += n_lines * size * 1.2 * p.line_spacing
+    return total
+
+
+def fit_paras(paras: List[Para], width_pt: float, height_pt: float,
+              floor: float = 0.55, gap_rhythm: bool = True) -> List[Para]:
+    """等比缩小字号，直到内容能塞进给定高度（有界迭代，不递归）。"""
+    if not paras or height_pt <= 1 or width_pt <= 1:
+        return paras
+    need = measure_block(paras, width_pt)
+    if need <= height_pt:
+        return paras
+
+    def build(k: float) -> List[Para]:
+        out = []
+        for p in paras:
+            q = Para(**{**p.__dict__})
+            q.size = max(9.0, p.size * k)
+            if gap_rhythm:
+                q.space_before = p.space_before * k
+                q.space_after = p.space_after * k
+            out.append(q)
+        return out
+
+    k = max(floor, (height_pt / need) * 0.98)
+    cur = build(k)
+    for _ in range(14):
+        if measure_block(cur, width_pt) <= height_pt or k <= floor:
+            return cur
+        k = max(floor, k * 0.96)
+        cur = build(k)
+    return cur
+
+
+# --------------------------------------------------------------------------
+# 文本框
+# --------------------------------------------------------------------------
+def add_textbox(slide, box: Tuple[int, int, int, int], *, wrap: bool = True,
+                anchor: str = "top", margins=None):
+    x, y, cx, cy = box
+    tb = slide.shapes.add_textbox(Emu(int(x)), Emu(int(y)), Emu(int(max(cx, 1))), Emu(int(max(cy, 1))))
+    tf = tb.text_frame
+    tf.word_wrap = wrap
+    tf.auto_size = MSO_AUTO_SIZE.NONE
+    tf.vertical_anchor = ANCHOR_MAP.get(anchor, MSO_ANCHOR.TOP)
+    m = margins or (0.0, 0.0, 0.0, 0.0)
+    tf.margin_left = emu_from_inch(m[0])
+    tf.margin_right = emu_from_inch(m[1])
+    tf.margin_top = emu_from_inch(m[2])
+    tf.margin_bottom = emu_from_inch(m[3])
+    tb.name = "__pptxgen_text"
+    return tb
+
+
+def set_ea_font(run, font_name: str) -> None:
+    """同时设置 latin / ea / cs 字体，保证中英文都用同一款字。"""
+    if not font_name:
+        return
+    run.font.name = font_name
+    rPr = run._r.get_or_add_rPr()
+    for tag in ("a:latin", "a:ea", "a:cs"):
+        el = rPr.find(qn(tag))
+        if el is None:
+            el = rPr.makeelement(qn(tag), {})
+            rPr.append(el)
+        el.set("typeface", font_name)
+
+
+def write_paras(tf, paras: Sequence[Para], *, default_font: Optional[str] = None) -> None:
+    """把 Para 列表写入 text_frame（会清空原有内容）。"""
+    tf.clear()
+    if not paras:
+        return
+    for i, p in enumerate(paras):
+        para = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
+        _fill_paragraph(para, p, default_font)
+
+
+def _fill_paragraph(para, p: Para, default_font: Optional[str]) -> None:
+    if p.align:
+        para.alignment = ALIGN_MAP.get(str(p.align).lower(), PP_ALIGN.LEFT)
+    p.space_before = max(0.0, p.space_before)
+    pPr = para._p.get_or_add_pPr()
+    if p.space_before:
+        _set_spacing(pPr, "a:spcBef", int(p.space_before * 100))
+    if p.space_after:
+        _set_spacing(pPr, "a:spcAft", int(p.space_after * 100))
+    if p.line_spacing:
+        lnSpc = pPr.makeelement(qn("a:lnSpc"), {})
+        pct = lnSpc.makeelement(qn("a:spcPct"), {"val": str(int(p.line_spacing * 100000))})
+        lnSpc.append(pct)
+        pPr.insert(0, lnSpc)
+
+    if p.level:
+        pPr.set("lvl", str(min(int(p.level), 8)))
+    if p.indent_in:
+        pPr.set("marL", str(int(p.indent_in * EMU_PER_INCH)))
+        pPr.set("indent", str(-int(min(p.indent_in, 0.3) * EMU_PER_INCH)))
+
+    font_name = p.font or default_font
+
+    if p.runs:
+        _apply_bullet(pPr, p)
+        for r in p.runs:
+            run = para.add_run()
+            run.text = r.get("text", "")
+            _style_run(run, size=r.get("size", p.size), bold=r.get("bold", p.bold),
+                       italic=r.get("italic", p.italic), color=r.get("color", p.color),
+                       font=r.get("font", font_name))
+        return
+
+    _apply_bullet(pPr, p)
+    run = para.add_run()
+    run.text = p.text
+    _style_run(run, size=p.size, bold=p.bold, italic=p.italic, color=p.color, font=font_name)
+
+
+def _style_run(run, *, size, bold, italic, color, font) -> None:
+    run.font.size = Pt(max(1.0, float(size)))
+    run.font.bold = bool(bold)
+    run.font.italic = bool(italic)
+    if color:
+        hexv = parse_color(color)
+        if hexv:
+            run.font.color.rgb = RGBColor(*rgb_tuple(hexv))
+    if font:
+        set_ea_font(run, font)
+
+
+def _set_spacing(pPr, tag: str, points_x100: int) -> None:
+    """写入 <a:spcBef>/<a:spcAft> 元素，其子元素必须是 <a:spcPts val="..."/>（OOXML 规范）。"""
+    el = pPr.find(qn(tag))
+    if el is None:
+        el = pPr.makeelement(qn(tag), {})
+        pPr.append(el)
+    for child in list(el):
+        el.remove(child)
+    child = el.makeelement(qn("a:spcPts"), {"val": str(int(points_x100))})
+    el.append(child)
+
+
+def _apply_bullet(pPr, p: Para) -> None:
+    if p.bullet is None:
+        return  # 不干预，继承模板版式里的项目符号设置
+    existing = pPr.findall(qn("a:buNone")) + pPr.findall(qn("a:buChar")) + pPr.findall(qn("a:buAutoNum"))
+    for el in existing:
+        pPr.remove(el)
+    if p.bullet == "":
+        pPr.append(pPr.makeelement(qn("a:buNone"), {}))
+        return
+    if p.bullet == "num":
+        bu = pPr.makeelement(qn("a:buAutoNum"), {"type": "arabicPeriod"})
+        pPr.append(bu)
+        return
+    if p.color:
+        hexv = parse_color(p.color)
+        if hexv:
+            buClr = pPr.makeelement(qn("a:buClr"), {})
+            srgb = buClr.makeelement(qn("a:srgbClr"), {"val": hexv})
+            buClr.append(srgb)
+            pPr.append(buClr)
+    buFont = pPr.makeelement(qn("a:buFont"), {"typeface": "Arial"})
+    pPr.append(buFont)
+    buChar = pPr.makeelement(qn("a:buChar"), {"char": p.bullet})
+    pPr.append(buChar)
+
+
+# --------------------------------------------------------------------------
+# 图形
+# --------------------------------------------------------------------------
+def add_shape(slide, shape_type, box, *, fill=None, line=None, line_width_pt=1.0,
+              shadow: bool = False, fill_alpha: float = 1.0):
+    x, y, cx, cy = box
+    shp = slide.shapes.add_shape(shape_type, Emu(int(x)), Emu(int(y)),
+                                 Emu(int(max(cx, 1))), Emu(int(max(cy, 1))))
+    shp.name = "__pptxgen_shape"
+    if fill:
+        hexv = parse_color(fill)
+        shp.fill.solid()
+        shp.fill.fore_color.rgb = RGBColor(*rgb_tuple(hexv))
+        if fill_alpha < 1.0:
+            _set_fill_alpha(shp, fill_alpha)
+    else:
+        shp.fill.background()
+    if line:
+        hexv = parse_color(line)
+        shp.line.color.rgb = RGBColor(*rgb_tuple(hexv))
+        shp.line.width = Pt(line_width_pt)
+    else:
+        shp.line.fill.background()
+    if not shadow:
+        _no_shadow(shp)
+    shp.text_frame.word_wrap = True
+    return shp
+
+
+def _no_shadow(shp) -> None:
+    spPr = shp._element.spPr
+    existing = spPr.find(qn("a:effectLst"))
+    if existing is not None:
+        spPr.remove(existing)
+    spPr.append(spPr.makeelement(qn("a:effectLst"), {}))
+
+
+def _set_fill_alpha(shp, alpha: float) -> None:
+    solid = shp._element.spPr.find(qn("a:solidFill"))
+    if solid is None:
+        return
+    srgb = solid.find(qn("a:srgbClr"))
+    if srgb is None:
+        return
+    for old in srgb.findall(qn("a:alpha")):
+        srgb.remove(old)
+    srgb.append(srgb.makeelement(qn("a:alpha"), {"val": str(int(max(0.0, min(1.0, alpha)) * 100000))}))
+
+
+def set_shape_transparency(shp, alpha: float) -> None:
+    _set_fill_alpha(shp, alpha)
+
+
+def rounded_box(slide, box, *, fill=None, line=None, radius: float = 0.12, **kw):
+    shp = add_shape(slide, MSO_SHAPE.ROUNDED_RECTANGLE, box, fill=fill, line=line, **kw)
+    try:
+        shp.adjustments[0] = max(0.0, min(0.5, radius))
+    except Exception:
+        pass
+    return shp
+
+
+def add_line(slide, x1, y1, x2, y2, *, color=None, width_pt=1.5, dash=None):
+    from pptx.enum.shapes import MSO_CONNECTOR
+
+    conn = slide.shapes.add_connector(MSO_CONNECTOR.STRAIGHT, Emu(int(x1)), Emu(int(y1)),
+                                      Emu(int(x2)), Emu(int(y2)))
+    conn.name = "__pptxgen_line"
+    if color:
+        conn.line.color.rgb = RGBColor(*rgb_tuple(parse_color(color)))
+    conn.line.width = Pt(width_pt)
+    if dash:
+        conn.line.dash_style = dash
+    return conn
+
+
+# --------------------------------------------------------------------------
+# 图片
+# --------------------------------------------------------------------------
+def image_size(path: str) -> Tuple[int, int]:
+    try:
+        from PIL import Image
+
+        with Image.open(path) as im:
+            return im.size
+    except Exception:
+        return (4, 3)
+
+
+def add_picture_fit(slide, path: str, box, *, mode: str = "contain", align: str = "center",
+                    valign: str = "middle", border=None, radius=None):
+    """把图片按比例放进 box。mode: contain | cover | stretch。"""
+    x, y, cx, cy = box
+    iw, ih = image_size(path)
+    if iw <= 0 or ih <= 0:
+        iw, ih = 4, 3
+    box_ar = cx / float(cy) if cy else 1.0
+    img_ar = iw / float(ih)
+
+    if mode == "stretch":
+        return slide.shapes.add_picture(path, Emu(int(x)), Emu(int(y)), Emu(int(cx)), Emu(int(cy)))
+
+    if mode == "cover":
+        if img_ar > box_ar:
+            h = cy
+            w = int(cy * img_ar)
+        else:
+            w = cx
+            h = int(cx / img_ar)
+        left = int(x + (cx - w) * {"left": 0, "center": 0.5, "right": 1}.get(align, 0.5))
+        top = int(y + (cy - h) * {"top": 0, "middle": 0.5, "bottom": 1}.get(valign, 0.5))
+        pic = slide.shapes.add_picture(path, Emu(left), Emu(top), Emu(int(w)), Emu(int(h)))
+    else:  # contain
+        if img_ar > box_ar:
+            w = cx
+            h = int(cx / img_ar)
+        else:
+            h = cy
+            w = int(cy * img_ar)
+        left = int(x + (cx - w) * {"left": 0, "center": 0.5, "right": 1}.get(align, 0.5))
+        top = int(y + (cy - h) * {"top": 0, "middle": 0.5, "bottom": 1}.get(valign, 0.5))
+        pic = slide.shapes.add_picture(path, Emu(left), Emu(top), Emu(int(w)), Emu(int(h)))
+
+    pic.name = "__pptxgen_pic"
+    if border:
+        pic.line.color.rgb = RGBColor(*rgb_tuple(parse_color(border)))
+        pic.line.width = Pt(1.0)
+    if radius is not None:
+        _round_picture(pic, radius)
+    return pic
+
+
+def _round_picture(pic, radius: float) -> None:
+    """给图片加圆角（通过 prstGeom roundRect + 裁剪）。"""
+    spPr = pic._element.spPr
+    old = spPr.find(qn("a:prstGeom"))
+    if old is not None:
+        spPr.remove(old)
+    geom = spPr.makeelement(qn("a:prstGeom"), {"prst": "roundRect"})
+    avLst = geom.makeelement(qn("a:avLst"), {})
+    gd = avLst.makeelement(qn("a:gd"), {"name": "adj", "fmla": f"val {int(radius * 100000)}"})
+    avLst.append(gd)
+    geom.append(avLst)
+    xfrm = spPr.find(qn("a:xfrm"))
+    if xfrm is not None:
+        xfrm.addnext(geom)
+    else:
+        spPr.append(geom)
+
+
+def add_rect_picture_clip(slide, path: str, box, radius: float = 0.1):
+    """图片填充的圆角矩形（模板里常见的卡片式配图）。"""
+    x, y, cx, cy = box
+    shp = add_shape(slide, MSO_SHAPE.ROUNDED_RECTANGLE, box, fill="FFFFFF", line=None)
+    try:
+        shp.adjustments[0] = radius
+    except Exception:
+        pass
+    fill = shp.fill
+    fill.solid()
+    fill.fore_color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
+    _set_blip_fill(shp, path)
+    return shp
+
+
+def _set_blip_fill(shp, path: str) -> None:
+    from pptx.opc.constants import RELATIONSHIP_TYPE as RT
+
+    part = shp.part
+    with open(path, "rb") as f:
+        blob = f.read()
+    image_part, rId = part.get_or_add_image_part(io.BytesIO(blob))
+    spPr = shp._element.spPr
+    for tag in ("a:solidFill", "a:noFill", "a:gradFill", "a:blipFill"):
+        el = spPr.find(qn(tag))
+        if el is not None:
+            spPr.remove(el)
+    blipFill = spPr.makeelement(qn("a:blipFill"), {})
+    blip = blipFill.makeelement(qn("a:blip"), {qn("r:embed"): rId})
+    blipFill.append(blip)
+    stretch = blipFill.makeelement(qn("a:stretch"), {})
+    stretch.append(stretch.makeelement(qn("a:fillRect"), {}))
+    blipFill.append(stretch)
+    ln = spPr.find(qn("a:ln"))
+    if ln is not None:
+        ln.addprevious(blipFill)
+    else:
+        spPr.append(blipFill)