Skip to content

nexu-io/open-design / skills/oil-motion

oil-motion

Verified

处理视频和序列帧,编译滚动、指针、拖动与状态驱动的网页动效;内含本地媒体处理脚本和运行时。新素材生成使用宿主工具。

scripts/motion_budget.py

View on GitHub
#!/usr/bin/env python3
"""根据交互方式、显示尺寸和资源预算自动选择网页动画交付方案。"""

from __future__ import annotations

import argparse
import json
import math
import sys
from dataclasses import asdict, dataclass
from pathlib import Path


def parse_size(value: str) -> tuple[int, int]:
    normalized = value.lower().replace("×", "x").strip()
    try:
        width_text, height_text = normalized.split("x", 1)
        width, height = int(width_text), int(height_text)
    except (ValueError, AttributeError) as exc:
        raise argparse.ArgumentTypeError("尺寸必须写成 WIDTHxHEIGHT") from exc
    if width <= 0 or height <= 0:
        raise argparse.ArgumentTypeError("宽高必须大于 0")
    return width, height


@dataclass(frozen=True)
class SizeCheck:
    width: int
    height: int
    required_width: int
    required_height: int
    width_ratio: float
    height_ratio: float
    passes: bool


def check_size(size: tuple[int, int], required: tuple[int, int]) -> SizeCheck:
    width, height = size
    required_width, required_height = required
    return SizeCheck(
        width=width,
        height=height,
        required_width=required_width,
        required_height=required_height,
        width_ratio=round(width / required_width, 3),
        height_ratio=round(height / required_height, 3),
        passes=width >= required_width and height >= required_height,
    )


def resolve_access(args: argparse.Namespace) -> str:
    if args.access != "auto":
        return args.access
    if args.time_control in {"segment-play", "autonomous"}:
        return "sequential"
    if args.parameter_space == "linear" and args.driver in {
        "scroll",
        "audio",
    }:
        return "sequential"
    return "random"


def select_delivery(
    args: argparse.Namespace,
    capacity: int,
    sheets: int | None,
    decoded_mib: float,
    access: str,
) -> dict[str, object]:
    atlas_within_budget = (
        capacity > 0
        and sheets is not None
        and sheets == 1
        and decoded_mib <= args.atlas_max_memory_mib
    )
    reason_codes: list[str] = []

    if args.background_owner == "video":
        selected = "baked-video"
        reason_codes.append("background-baked-into-video")
        if args.parameter_space in {"2d", "discrete"}:
            reason_codes.append("baked-video-needs-independent-clips")
        if (
            access == "sequential"
            and args.parameter_space == "linear"
            and args.frames >= args.linear_video_min_frames
        ):
            reason_codes.append("long-linear-sequence")
    elif args.parameter_space == "2d":
        selected = "alpha-atlas"
        reason_codes.append("two-dimensional-parameter-needs-discrete-frames")
        if not atlas_within_budget:
            reason_codes.append("atlas-needs-budget-optimization")
    elif args.parameter_space == "discrete":
        selected = "alpha-atlas"
        reason_codes.append("discrete-states-need-independent-assets")
        if not atlas_within_budget:
            reason_codes.append("states-need-separate-budgets")
    elif access == "random" and atlas_within_budget:
        selected = "alpha-atlas"
        reason_codes.append("random-access-fits-atlas-budget")
    elif (
        access == "sequential"
        and args.parameter_space == "linear"
        and args.frames >= args.linear_video_min_frames
    ):
        selected = "chroma-video"
        reason_codes.append("long-linear-sequence")
    elif not atlas_within_budget:
        selected = "chroma-video"
        reason_codes.append("atlas-budget-exceeded")
    else:
        selected = "alpha-atlas"
        reason_codes.append("small-asset-fits-atlas-budget")

    return {
        "selected": selected,
        "reasonCodes": reason_codes,
        "atlasWithinBudget": atlas_within_budget,
        "thresholds": {
            "atlasMaxSheets": 1,
            "atlasMaxDecodedMemoryMiB": args.atlas_max_memory_mib,
            "linearVideoMinFrames": args.linear_video_min_frames,
        },
    }


def build_report(args: argparse.Namespace) -> dict[str, object]:
    display_width, display_height = args.display
    required = (
        math.ceil(display_width * args.dpr),
        math.ceil(display_height * args.dpr),
    )
    required_width, required_height = required
    max_columns = args.max_texture // required_width
    max_rows = args.max_texture // required_height
    capacity = max_columns * max_rows
    sheets = math.ceil(args.frames / capacity) if capacity else None
    decoded_mib = (
        required_width * required_height * args.frames * 4 / 1024 / 1024
    )
    access = resolve_access(args)
    delivery = select_delivery(args, capacity, sheets, decoded_mib, access)
    runtime = {
        "renderer": {
            "alpha-atlas": "css-alpha-atlas",
            "chroma-video": "webgl-chroma-video",
            "baked-video": "baked-video",
        }[str(delivery["selected"])],
        "controller": {
            "scrub": "frame-scrub",
            "segment-play": "segment-playback",
            "autonomous": "autonomous-playback",
        }[args.time_control],
    }

    failures: list[str] = []
    source_check = check_size(args.source, required) if args.source else None
    cell_check = check_size(args.cell, required) if args.cell else None
    if source_check and not source_check.passes:
        failures.append("源素材低于最终显示所需像素")
    if (
        cell_check
        and delivery["selected"] == "alpha-atlas"
        and not cell_check.passes
    ):
        failures.append("图集单帧低于最终显示所需像素")
    if delivery["selected"] == "alpha-atlas" and capacity == 0:
        failures.append("单帧已超过纹理尺寸上限")
    if (
        delivery["selected"] == "baked-video"
        and args.parameter_space in {"2d", "discrete"}
    ):
        failures.append(
            "烘焙视频是一条线性时间轴,二维或离散参数必须拆成多条独立片段分别预算"
        )
    if (
        delivery["selected"] == "alpha-atlas"
        and not delivery["atlasWithinBudget"]
    ):
        if args.parameter_space == "discrete":
            failures.append("离散状态合并后超预算,需要拆成独立状态或转场并分别预算")
        else:
            failures.append(
                "二维 Alpha 图集超出单图集或内存预算,需要降低参数采样密度、"
                "拆分参数轴,或在用户确认的显示范围内重新预算"
            )

    temporal_check = None
    if args.scroll_pages is not None:
        required_frames = math.ceil(args.scroll_pages * args.frames_per_page)
        frames_per_page = args.frames / args.scroll_pages
        temporal_check = {
            "scrollPages": args.scroll_pages,
            "framesPerPage": round(frames_per_page, 2),
            "targetFramesPerPage": args.frames_per_page,
            "requiredFrames": required_frames,
            "passes": args.frames >= required_frames,
        }
        if not temporal_check["passes"]:
            failures.append(
                f"滚动采样密度不足:需要至少 {required_frames} 帧"
            )

    return {
        "display": {
            "width": display_width,
            "height": display_height,
            "dpr": args.dpr,
        },
        "requiredCell": {
            "width": required_width,
            "height": required_height,
        },
        "frames": args.frames,
        "texture": {
            "maxSize": args.max_texture,
            "columnsPerSheet": max_columns,
            "rowsPerSheet": max_rows,
            "framesPerSheet": capacity,
            "sheetCount": sheets,
        },
        "decodedFrameMemoryMiB": round(decoded_mib, 1),
        "sourceCheck": asdict(source_check) if source_check else None,
        "cellCheck": asdict(cell_check) if cell_check else None,
        "temporalCheck": temporal_check,
        "driver": args.driver,
        "parameterSpace": args.parameter_space,
        "timeControl": args.time_control,
        "access": access,
        "backgroundOwner": args.background_owner,
        "delivery": delivery,
        "runtime": runtime,
        "failures": failures,
        "passes": not failures,
    }


def print_human(report: dict[str, object]) -> None:
    display = report["display"]
    required = report["requiredCell"]
    texture = report["texture"]
    print(
        f"显示尺寸:{display['width']}×{display['height']} CSS px,"
        f"DPR {display['dpr']}"
    )
    print(f"最低单帧:{required['width']}×{required['height']} px")
    print(
        f"纹理预算:每片最多 {texture['columnsPerSheet']}×"
        f"{texture['rowsPerSheet']} 帧,共需 {texture['sheetCount']} 片"
    )
    print(f"全部帧解码内存理论值:{report['decodedFrameMemoryMiB']} MiB")
    delivery = report["delivery"]
    runtime = report["runtime"]
    print(
        f"背景归属:{report['backgroundOwner']};"
        f"媒体:{delivery['selected']};"
        f"控制器:{runtime['controller']};渲染器:{runtime['renderer']}"
    )
    print("选择依据:" + "、".join(delivery["reasonCodes"]))

    for label, key in (("源素材", "sourceCheck"), ("当前单帧", "cellCheck")):
        check = report[key]
        if check:
            status = "通过" if check["passes"] else "不通过"
            print(
                f"{label}:{check['width']}×{check['height']} px,{status}"
                f"(宽 {check['width_ratio']}×,高 {check['height_ratio']}×)"
            )

    temporal = report["temporalCheck"]
    if temporal:
        status = "通过" if temporal["passes"] else "不通过"
        print(
            f"滚动采样:{temporal['framesPerPage']} 帧/屏,{status}"
            f"(目标 {temporal['targetFramesPerPage']} 帧/屏,"
            f"至少 {temporal['requiredFrames']} 帧)"
        )

    failures = report["failures"]
    if failures:
        print("阻断项:")
        for failure in failures:
            print(f"- {failure}")
    else:
        print("结果:通过")


def main() -> int:
    parser = argparse.ArgumentParser(
        description=(
            "根据 Concept Contract 的背景归属、交互参数、CSS 尺寸、DPR、帧数和纹理预算"
            "自动选择烘焙场景视频、Alpha 图集或绿幕视频。"
        )
    )
    parser.add_argument("--frames", type=int, required=True, help="总帧数")
    parser.add_argument(
        "--display", type=parse_size, required=True, help="最终 CSS 尺寸,如 268x468"
    )
    parser.add_argument("--dpr", type=float, default=2.0, help="目标设备 DPR")
    parser.add_argument(
        "--max-texture", type=int, default=4096, help="保守纹理边长上限"
    )
    parser.add_argument(
        "--driver",
        choices=(
            "pointer",
            "scroll",
            "drag",
            "touch",
            "orientation",
            "audio",
            "data",
            "state",
            "time",
        ),
        default="scroll",
        help="Motion Brief 中的交互驱动,默认 scroll",
    )
    parser.add_argument(
        "--parameter-space",
        choices=("linear", "circular", "2d", "discrete"),
        default="linear",
        help="Motion Brief 中的参数空间,默认 linear",
    )
    parser.add_argument(
        "--time-control",
        choices=("scrub", "segment-play", "autonomous"),
        required=True,
        help="Concept Contract 中的时间控制方式,必须显式传入",
    )
    parser.add_argument(
        "--access",
        choices=("auto", "random", "sequential"),
        default="auto",
        help="运行时主要访问方式;默认根据 driver 与 parameter-space 自动推断",
    )
    parser.add_argument(
        "--background-owner",
        choices=("page", "video"),
        required=True,
        help=(
            "背景归属,来自 Concept Contract:video 表示背景与主体在同一视频中"
            "烘焙生成(baked-video,默认场景路线);page 表示主体需要透明复用,"
            "由预算在 alpha-atlas 与 chroma-video 之间选择。必须显式传入,"
            "禁止因遗漏参数而静默回退到绿幕路线"
        ),
    )
    parser.add_argument(
        "--atlas-max-memory-mib",
        type=float,
        default=192.0,
        help="自动优先选择 Alpha 图集时允许的理论解码内存,默认 192 MiB",
    )
    parser.add_argument(
        "--linear-video-min-frames",
        type=int,
        default=180,
        help="一维顺序动画自动优先视频的帧数门槛,默认 180",
    )
    parser.add_argument("--source", type=parse_size, help="源视频或母版帧尺寸")
    parser.add_argument("--cell", type=parse_size, help="当前图集单帧尺寸")
    parser.add_argument(
        "--scroll-pages",
        type=float,
        help="滚动驱动覆盖的视口屏数;传入后同时检查时间采样密度",
    )
    parser.add_argument(
        "--frames-per-page",
        type=float,
        default=24.0,
        help="每屏目标帧数,默认 24",
    )
    parser.add_argument("--json", action="store_true", help="输出 JSON")
    parser.add_argument("--report", type=Path, help="同时把完整 JSON 报告写入指定路径")
    parser.add_argument(
        "--strict", action="store_true", help="存在阻断项时返回非零退出码"
    )
    args = parser.parse_args()

    if args.frames <= 0:
        parser.error("--frames 必须大于 0")
    if args.dpr <= 0:
        parser.error("--dpr 必须大于 0")
    if args.max_texture <= 0:
        parser.error("--max-texture 必须大于 0")
    if args.atlas_max_memory_mib <= 0:
        parser.error("--atlas-max-memory-mib 必须大于 0")
    if args.linear_video_min_frames <= 0:
        parser.error("--linear-video-min-frames 必须大于 0")
    if args.scroll_pages is not None and args.scroll_pages <= 0:
        parser.error("--scroll-pages 必须大于 0")
    if args.frames_per_page <= 0:
        parser.error("--frames-per-page 必须大于 0")

    report = build_report(args)
    if args.report:
        report_path = args.report.expanduser().resolve()
        report_path.parent.mkdir(parents=True, exist_ok=True)
        report_path.write_text(
            json.dumps(report, ensure_ascii=False, indent=2),
            encoding="utf-8",
        )
    if args.json:
        print(json.dumps(report, ensure_ascii=False, indent=2))
    else:
        print_human(report)
    return 2 if args.strict and not report["passes"] else 0


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall