图像
.image() 用于在指定位置添加叠加图像。支持本地文件与远程 URL,并提供背景去除、适配模式、混合模式以及各类效果。
方法签名
canvas.image(
path,
position,
width=None,
height=None,
fit=None,
opacity=1.0,
rotation=0.0,
align=Align.TOP_LEFT,
remove_background=False,
border_radius=0,
blend_mode=None,
effects=None,
)
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
path |
str |
必填 | 本地文件路径或远程 http(s):// URL。 |
position |
tuple |
必填 | (x, y) 坐标。取值可为整数(像素)或百分比字符串("50%")。 |
width |
int \| None |
None |
目标宽度(像素)。若仅指定单侧尺寸,将保持原始宽高比。 |
height |
int \| None |
None |
目标高度(像素)。若仅指定单侧尺寸,将保持原始宽高比。 |
fit |
str \| FitMode \| None |
None |
同时指定 width 和 height 时的缩放模式。参见 FitMode。 |
opacity |
float |
1.0 |
图层不透明度,范围为 0.0 至 1.0。 |
rotation |
float |
0.0 |
旋转角度(度数)。 |
align |
str \| Align \| tuple |
Align.TOP_LEFT |
position 对应的图像对齐参考点。参见 Align。 |
remove_background |
bool |
False |
使用 AI 去除图像背景。需要安装 quickthumb[rembg]。 |
border_radius |
int |
0 |
圆角半径(像素)。非负整数。 |
blend_mode |
str \| BlendMode \| None |
None |
图像合成混合模式。参见 BlendMode。 |
effects |
list \| None |
[] |
效果列表:Stroke、Shadow、Glow、Filter、Grain。 |
示例
基础叠加图层
canvas.image(
path="portrait.png",
position=("74%", "54%"),
width=420,
height=520,
fit="cover",
align=("center", "middle"),
)
配合效果使用
from quickthumb import Filter, Shadow
canvas.image(
path="portrait.png",
position=("74%", "54%"),
width=420,
height=520,
fit="cover",
align=("center", "middle"),
border_radius=28,
effects=[
Filter(contrast=1.1, saturation=1.05),
Shadow(offset_x=0, offset_y=12, color="#000000", blur_radius=24),
],
)
去除背景
canvas.image(
path="portrait.jpg",
position=("75%", "55%"),
width=430,
height=540,
align=("center", "middle"),
remove_background=True,
)
说明
remove_background=True 需要 Python 3.11 或更高版本,并执行 uv pip install "quickthumb[rembg]"。首次使用时会自动下载并缓存 ONNX 模型(约 170 MB)。
远程图片
canvas.image(
path="https://example.com/avatar.png",
position=("50%", "50%"),
width=300,
height=300,
align=("center", "middle"),
border_radius=150, # circle
)
保持宽高比
# Only width: height keeps the image's proportions
canvas.image(path="logo.png", position=(40, 40), width=200)
# Only height: width keeps the image's proportions
canvas.image(path="logo.png", position=(40, 40), height=80)
适配模式
当同时指定 width 和 height 时生效:
| 取值 | 行为 |
|---|---|
"cover" |
填满容器,必要时裁剪超出部分 |
"contain" |
完整容纳于容器内,边缘可能留白 |
"fill" |
忽略原始比例,拉伸填满整个容器 |
校验规则
path和position为必填项。position必须为包含 2 个元素的元组。百分比字符串必须符合-?N%格式。border_radius不能为负数。opacity必须介于0.0至1.0之间。path无效或远程下载失败时,将在渲染阶段抛出RenderingError。