跳转至
quickthumb
全部文档

API 参考

使用 Canvas 构建单个场景,使用 Deck 编排多个场景。两者实现了相同的文档级操作;各个图层文档详细说明了它们特有的创作字段。

受支持的公共接口

从 quickthumb 导入文档中记载的创作类型与结果模型,从 quickthumb.audio 模块导入音频分析工具。某名称能够从其他内部模块被导入,并不代表它是受支持的公共入口点。

接口面 受支持的用法
创作构建 Canvas、Deck、文档中记载的图层/效果模型、动效轨道、转场过渡与选项模型
文档操作 针对两类文档均支持 validate()、inspect()、diagnose()、prefetch_assets()、sample() 与 export();为通用消费方提供 inspect_document()
产物结果 强类型报告、ExportResult、CanonicalFrame / FrameSequence 以及 ImageSequence* 结果;可通过 model_dump_json() 进行序列化
JSON 互转 to_json()、Canvas.from_json()、Deck.from_json()、canvas_json_schema() 与 document_json_schema()
音频响应创作 quickthumb.audio.analyze_audio() 与 AudioAnalysis;将源时钟起音(onset)时刻及基于 RMS 的振幅缩放融入数值动效中
专项输出 在其返回类型或控制机制适合当前任务时,使用文档中记载的 render()、render_frame()、to_*() 及 export_image_sequence() 方法

export() 是官方推荐的文件输出边界:它会预检功能策略,并返回已写入的文件路径及排版诊断。专用渲染方法有各自的返回值,且并不都会强制执行该策略;详见输出 API。请在该边界处统一配置格式特定选项,避免直接调用底层导出器。

以 _ 开头的模块、渲染器/上下文内部对象以及时间轴编译辅助类均为内部实现细节。它们可能在没有版本生命周期保证的前提下随时变更或移除。请使用 sample() 采样获取单帧画面,而不要自行拼装编译器与底层渲染器。各参考文档与生成的 Schema 描述了当前安装版本所支持的合法字段;“公开”并不等同于跨版本永久冻结不变。

统一文档工作流

以下示例展示了在 Python、规范 JSON 以及 Deck 幻灯片之间流转相同的图层数据,无需接触底层渲染器对象或安装可选依赖:

from quickthumb import Canvas, Deck, Document, ExportResult

canvas = Canvas(320, 180).background(color="#102030").shape(
    "rectangle", position=(24, 24), width=80, height=40, color="#42CEB7",
    id="badge", motion_key="brand", anchor=(0, 0),
)
restored = Canvas.from_json(canvas.to_json())
document: Document = Deck(slides=[restored])
result: ExportResult = document.export("slides.png")
print(result.written_paths)  # Numbered paths are reported by the result.
print(document.sample().frames[0].sha256)

通用图层术语体系

Canvas 图层无论是放置在 Deck 幻灯片中还是序列化为规范 JSON,均采用相同的字段定义。Deck 仅负责扩充幻灯片顺序、转场、旁白和备注,绝不会重命名底层图层字段。Python 元组在 JSON 中对应为数组,枚举值对应为字符串,每个图层均包含一个 type 判别属性。

字段或概念 含义
id Canvas 场景内唯一的图层标识符(包含分组内的子图层)。每页 Deck 幻灯片拥有独立的 ID 命名空间。
motion_key 用于在 Morph 形状形变转场中跨场景匹配图层的可选键名;独立于场景内部的局部 id。
position, width, height 声明的排版位置与尺寸,在图层支持处可使用像素数值或百分比字符串。百分比相对于画布进行解析;必填字段与尺寸规则请参阅各图层参考。
align 图层边界框在 position 坐标点上的对齐基准点;同时控制文本排版的对齐方式。参阅 Align。
rotation, anchor 旋转角度以度为单位。anchor=(x, y) 是规范动效中归一化在 0–1 范围内的旋转/缩放中心锚点,独立于排版对齐。静态旋转有自身的构图规则;参阅变换锚点。
opacity 在支持的图层中表示 0 到 1 之间的不透明度。
animation 预设动效或包含类型化轨道与时间的 AnimationSpec。位置轨道是相对于设计排版位置的偏移量;缩放轨道变换外部对象,而 ImageZoomTrack 则在画框内缩放图片内容。
Group(分组) 自动布局容器负责为其子元素排版定位。请使用 .group() 构建行与列,避免手动计算各子元素坐标。
parent / null 针对顶层可动画图层的高级场景局部变换层级。子图层的位置相对于父级进行局部定位;百分比坐标依然相对于画布进行解析。这独立于分组布局机制。参阅父级关联。

并非所有图层都支持全部字段。背景、描边、空控制器与常规可视绘制图层各自承担不同的职责。各个 API 参考文档以及 JSON Schema 构成了字段级别的明确契约。插件注册声明了扩展参数,并通过显式的 PluginRegistry 提供自定义渲染回调。仅解析 JSON 数据本身不会自动打包或安装这些外部代码。

文档列表

文档 涵盖内容
Canvas 画布实例化、全量图层方法、排版检查及文件导出方法
Deck 将多个画布组合为单个 PDF、PPTX、HTML 幻灯片放映、视频或图像序列
文档检查 inspect_document() 以及跨 Canvas/Deck 的通用采样分析
背景 .background():纯色、渐变与背景图片
文字 .text() 与 TextPart:纯文本与富文本定制
图像 .image():图片放置、尺寸适配与抠图去背景
形状 .shape():矩形、椭圆、胶囊形、三角形、星形及多边形
路径 .path():带填充与描边的 SVG 路径数据及受限动效
SVG .svg():来自 SVG 文件的图标与徽标矢量绘制
视频 .video():视频剪辑片段、外挂字幕与剪辑音频
分组(自动布局) .group():行与列维度的自适应流式排版
描边 .outline():围绕画布四周的描边边框
数据可视化 .chart() 与 .qr_code() 数据图表与二维码生成
效果 Stroke, Shadow, Glow, Filter, Background, Grain, Duotone, InnerShadow, BackdropBlur
枚举与渐变 Align, BlendMode, FitMode, LinearGradient, RadialGradient, TextFillImage

错误类型

异常类 抛出时机
ValidationError 向图层构建方法传递非法参数时立即抛出。
RenderingError 在 .render()、.to_base64() 或 .to_data_url() 绘图导出期间发生底层故障时抛出。