"""画中画（PiP）配置领域模型 — 纯逻辑，无外部依赖. 抽离自 pip_engine.py 的数据类和纯逻辑函数， 方便单测覆盖，同时保持向后兼容。 """ from __future__ import annotations import logging from dataclasses import dataclass, field from typing import Any logger = logging.getLogger(__name__) # ── 位置常量 ────────────────────────────────────────────────────────────────── POSITION_TOP_LEFT = "top_left" POSITION_TOP_CENTER = "top_center" POSITION_TOP_RIGHT = "top_right" POSITION_CENTER_LEFT = "center_left" POSITION_CENTER = "center" POSITION_CENTER_RIGHT = "center_right" POSITION_BOTTOM_LEFT = "bottom_left" POSITION_BOTTOM_CENTER = "bottom_center" POSITION_BOTTOM_RIGHT = "bottom_right" _VALID_POSITIONS = { POSITION_TOP_LEFT, POSITION_TOP_CENTER, POSITION_TOP_RIGHT, POSITION_CENTER_LEFT, POSITION_CENTER, POSITION_CENTER_RIGHT, POSITION_BOTTOM_LEFT, POSITION_BOTTOM_CENTER, POSITION_BOTTOM_RIGHT, } # 动画类型 ANIMATION_FADE = "fade" ANIMATION_SLIDE_LEFT = "slide_left" ANIMATION_SLIDE_RIGHT = "slide_right" ANIMATION_SLIDE_TOP = "slide_top" ANIMATION_SLIDE_BOTTOM = "slide_bottom" ANIMATION_SCALE = "scale" _VALID_ANIMATIONS = { ANIMATION_FADE, ANIMATION_SLIDE_LEFT, ANIMATION_SLIDE_RIGHT, ANIMATION_SLIDE_TOP, ANIMATION_SLIDE_BOTTOM, ANIMATION_SCALE, } # ── 数据模型 ────────────────────────────────────────────────────────────────── @dataclass class PiPLayerConfig: """单个画中画图层配置.""" # 素材来源 source: str = "" source_type: str = "asset_id" # "asset_id" | "url" | "local_path" # 位置配置 position: str = POSITION_BOTTOM_RIGHT x: int | str = 0 y: int | str = 0 margin: int = 20 # 大小配置 width: int | str = "25%" height: int | str = "" # 空则按比例自适应 # 样式 opacity: float = 1.0 corner_radius: int = 0 border_width: int = 0 border_color: str = "white" # 时间控制 start_time: float = 0.0 duration: float = 0.0 # 0表示全程显示 # 动画 animation_in: str = "" animation_out: str = "" animation_duration: float = 0.5 # 层级 z_index: int = 1 def validate(self) -> tuple[bool, str]: """校验配置合法性，返回 (是否合法, 错误信息).""" if not self.source: return False, "source不能为空" if self.position != "custom" and self.position not in _VALID_POSITIONS: return False, f"无效的position: {self.position}" if self.opacity < 0 or self.opacity > 1: return False, "opacity必须在0-1之间" if self.corner_radius < 0: return False, "corner_radius不能为负数" if self.start_time < 0: return False, "start_time不能为负数" if self.duration < 0: return False, "duration不能为负数" if self.animation_in and self.animation_in not in _VALID_ANIMATIONS: return False, f"无效的入场动画: {self.animation_in}" if self.animation_out and self.animation_out not in _VALID_ANIMATIONS: return False, f"无效的出场动画: {self.animation_out}" if self.animation_duration < 0: return False, "animation_duration不能为负数" return True, "" @dataclass class PiPConfig: """画中画整体配置.""" enabled: bool = False layers: list[PiPLayerConfig] = field(default_factory=list) @classmethod def from_dict(cls, data: dict[str, Any] | None) -> "PiPConfig": """从字典解析配置.""" if not data or not data.get("enabled", False): return cls(enabled=False) layers_data = data.get("layers", []) layers: list[PiPLayerConfig] = [] for layer_data in layers_data: try: layer = PiPLayerConfig( source=layer_data.get("source", ""), source_type=layer_data.get("source_type", "asset_id"), position=layer_data.get("position", POSITION_BOTTOM_RIGHT), x=layer_data.get("x", 0), y=layer_data.get("y", 0), margin=int(layer_data.get("margin", 20)), width=layer_data.get("width", "25%"), height=layer_data.get("height", ""), opacity=float(layer_data.get("opacity", 1.0)), corner_radius=int(layer_data.get("corner_radius", 0)), border_width=int(layer_data.get("border_width", 0)), border_color=layer_data.get("border_color", "white"), start_time=float(layer_data.get("start_time", 0.0)), duration=float(layer_data.get("duration", 0.0)), animation_in=layer_data.get("animation_in", ""), animation_out=layer_data.get("animation_out", ""), animation_duration=float(layer_data.get("animation_duration", 0.5)), z_index=int(layer_data.get("z_index", 1)), ) valid, err = layer.validate() if valid: layers.append(layer) else: logger.warning("PiP图层配置无效，跳过: %s", err) except (ValueError, TypeError) as e: logger.warning("PiP图层解析失败，跳过: %s", e) # 按 z_index 排序 layers.sort(key=lambda layer: layer.z_index) return cls(enabled=bool(layers), layers=layers) @property def layer_count(self) -> int: """有效图层数量.""" return len(self.layers) @property def max_z_index(self) -> int: """最大 z_index.""" if not self.layers: return 0 return max(layer.z_index for layer in self.layers) # ── 纯逻辑工具函数 ─────────────────────────────────────────────────────────── def parse_size_value(value: int | str, base: int, default_pct: float = 0.25) -> int: """解析尺寸值（像素或百分比）. Args: value: 尺寸值，int（像素）或 str（如 "30%"） base: 基准尺寸（用于百分比计算） default_pct: 解析失败时的默认百分比 Returns: 像素尺寸，>= 1 """ if isinstance(value, int): return max(1, value) if isinstance(value, str) and value.endswith("%"): try: pct = float(value.rstrip("%")) / 100.0 return max(1, int(base * pct)) except (ValueError, TypeError): return max(1, int(base * default_pct)) try: return max(1, int(value)) except (ValueError, TypeError): return max(1, int(base * default_pct)) def calculate_pip_position( position: str, output_width: int, output_height: int, pip_width: int, pip_height: int, margin: int = 20, custom_x: int | str = 0, custom_y: int | str = 0, ) -> tuple[int, int]: """计算画中画的实际像素位置 (x, y). Args: position: 9宫格位置或 "custom" output_width: 画布宽度 output_height: 画布高度 pip_width: 画中画宽度 pip_height: 画中画高度 margin: 9宫格边距 custom_x: 自定义x（position=custom时有效） custom_y: 自定义y（position=custom时有效） Returns: (x, y) 像素坐标 """ W = output_width H = output_height m = margin if position == "custom": x = parse_size_value(custom_x, W) y = parse_size_value(custom_y, H) return (x, y) pos_map = { POSITION_TOP_LEFT: (m, m), POSITION_TOP_CENTER: ((W - pip_width) // 2, m), POSITION_TOP_RIGHT: (W - pip_width - m, m), POSITION_CENTER_LEFT: (m, (H - pip_height) // 2), POSITION_CENTER: ((W - pip_width) // 2, (H - pip_height) // 2), POSITION_CENTER_RIGHT: (W - pip_width - m, (H - pip_height) // 2), POSITION_BOTTOM_LEFT: (m, H - pip_height - m), POSITION_BOTTOM_CENTER: ((W - pip_width) // 2, H - pip_height - m), POSITION_BOTTOM_RIGHT: (W - pip_width - m, H - pip_height - m), } return pos_map.get(position, pos_map[POSITION_BOTTOM_RIGHT])