图像工具

基于 Pillow 的确定性像素级图像处理工具。适用于缩放、裁剪、合成、格式转换、添加水印及其他标准图像处理任务。

适用场景

• AI 生成图像的后处理：生成后进行缩放、裁剪、网页优化等操作
• 格式转换：PNG ↔ JPEG ↔ WEBP，支持质量控制
• 图像合成：叠加图像、将主体粘贴至背景中
• 批量处理：缩放为多种尺寸、批量添加水印
• 网页优化：压缩并缩放以实现快速交付
• 社交媒体适配：按平台特定宽高比裁剪（如 Instagram、YouTube、Stories）

不适用场景 —— 请改用 bria-ai

本技能仅支持确定性像素级操作。对于任何生成式或 AI 驱动的图像任务，请改用 bria-ai 技能：

• 根据文本提示生成图像 → 使用 bria-ai
• AI 背景移除或替换 → 使用 bria-ai
• AI 图像编辑（内补绘制、对象移除/添加） → 使用 bria-ai
• 风格迁移或 AI 驱动视觉特效 → 使用 bria-ai
• 使用 AI 创建产品生活场景图 → 使用 bria-ai
• AI 超分辨率图像放大 → 使用 bria-ai

经验法则：若任务需创建新的视觉内容或理解图像语义，请使用 bria-ai；若任务仅需变换现有像素（如缩放、裁剪、格式转换、加水印），则使用本技能。

若尚未安装 bria-ai，可通过以下命令安装：

npx skills add bria-ai/bria-skill

快速参考

依赖要求

pip install Pillow requests

基础用法

from image_utils import ImageUtils

# 从 URL 加载
image = ImageUtils.load_from_url("https://example.com/image.jpg")

# 或从多种来源加载
image = ImageUtils.load("/path/to/image.png")         # 文件路径
image = ImageUtils.load(image_bytes)                  # 字节数据
image = ImageUtils.load("data:image/png;base64,...")  # Base64 编码字符串

# 缩放并保存
resized = ImageUtils.resize(image, width=800, height=600)
ImageUtils.save(resized, "output.webp", quality=90)

# 获取图像信息
info = ImageUtils.get_info(image)
print(f"{info['width']}x{info['height']} {info['mode']}")

缩放与缩放控制

# 缩放到精确尺寸
resized = ImageUtils.resize(image, width=800, height=600)

# 保持宽高比缩放（在限定范围内适配）
fitted = ImageUtils.resize(image, width=800, height=600, maintain_aspect=True)

# 仅按宽度缩放（高度自动计算）
resized = ImageUtils.resize(image, width=800)

# 按比例缩放
half = ImageUtils.scale(image, 0.5)    # 50% 尺寸
double = ImageUtils.scale(image, 2.0)  # 200% 尺寸

# 生成缩略图
thumb = ImageUtils.thumbnail(image, (150, 150))

裁剪

# 按指定区域裁剪
cropped = ImageUtils.crop(image, left=100, top=50, right=500, bottom=350)

# 从中心裁剪
center = ImageUtils.crop_center(image, width=400, height=400)

# 按宽高比裁剪（适配社交媒体）
square = ImageUtils.crop_to_aspect(image, "1:1")      # Instagram
wide = ImageUtils.crop_to_aspect(image, "16:9")       # YouTube 缩略图
story = ImageUtils.crop_to_aspect(image, "9:16")      # Stories / Reels

# 控制裁剪锚点
top_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="top")
bottom_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="bottom")

合成

# 将前景图粘贴至背景图
result = ImageUtils.paste(background, foreground, position=(100, 50))

# Alpha 合成（前景图需含透明通道）
result = ImageUtils.composite(background, foreground)

# 将图像适配至指定画布（支持信封式/居中填充）
canvas = ImageUtils.fit_to_canvas(
    image,
    width=1200,
    height=800,
    background_color=(255, 255, 255, 255),  # 白色背景
    position="center"  # 可选 "top"、"bottom"
)

格式转换

# 转换为不同格式
png_bytes = ImageUtils.to_bytes(image, "PNG")
jpeg_bytes = ImageUtils.to_bytes(image, "JPEG", quality=85)
webp_bytes = ImageUtils.to_bytes(image, "WEBP", quality=90)

# 获取 base64 字符串（用于 data URL）
base64_str = ImageUtils.to_base64(image, "PNG")
data_url = ImageUtils.to_base64(image, "PNG", include_data_url=True)
# 返回结果形如："data:image/png;base64,..."

# 根据文件扩展名自动推断格式并保存
ImageUtils.save(image, "output.png")
ImageUtils.save(image, "output.jpg", quality=85)
ImageUtils.save(image, "output.webp", quality=90)

水印

# 文字水印
watermarked = ImageUtils.add_text_watermark(
    image,
    text="© 2024 My Company",
    position="bottom-right",  # 可选：bottom-left、top-right、top-left、center
    font_size=24,
    color=(255, 255, 255, 128),  # 半透明白色
    margin=20
)

# Logo / 图像水印
logo = ImageUtils.load("logo.png")
watermarked = ImageUtils.add_image_watermark(
    image,
    watermark=logo,
    position="bottom-right",
    opacity=0.5,
    scale=0.15,  # 宽度为原图的 15%
    margin=20
)

图像调整

# 亮度（1.0 为原始值，<1 变暗，>1 变亮）
bright = ImageUtils.adjust_brightness(image, 1.3)
dark = ImageUtils.adjust_brightness(image, 0.7)

# 对比度（1.0 为原始值）
high_contrast = ImageUtils.adjust_contrast(image, 1.5)

# 饱和度（0 为灰度，1.0 为原始值，>1 更鲜艳）
vivid = ImageUtils.adjust_saturation(image, 1.3)
grayscale = ImageUtils.adjust_saturation(image, 0)

# 锐化
sharp = ImageUtils.adjust_sharpness(image, 2.0)

# 模糊
blurred = ImageUtils.blur(image, radius=5)

变换

# 旋转（逆时针，单位：度）
rotated = ImageUtils.rotate(image, 45)
rotated = ImageUtils.rotate(image, 90, expand=False)  # 不扩展画布尺寸

# 翻转
mirrored = ImageUtils.flip_horizontal(image)
flipped = ImageUtils.flip_vertical(image)

边框与填充

# 添加实心边框
bordered = ImageUtils.add_border(image, width=5, color=(0, 0, 0))

# 添加填充（空白边距）
padded = ImageUtils.add_padding(image, padding=20)  # 四边统一
padded = ImageUtils.add_padding(image, padding=(10, 20, 10, 20))  # 左、上、右、下

网页优化

# 针对网页交付优化（自动缩放 + 压缩）
optimized_bytes = ImageUtils.optimize_for_web(
    image,
    max_dimension=1920,  # 若任一维度超过该值则缩放
    format="WEBP",       # 最优压缩格式
    quality=85
)

# 保存优化后的图像
with open("optimized.webp", "wb") as f:
    f.write(optimized_bytes)

与 Bria AI 集成

可与 bria-ai 技能协同使用，对 AI 生成图像执行后处理。先通过 Bria API 生成或编辑图像，再使用 image-utils 进行缩放、裁剪、加水印及网页优化。

import requests
from image_utils import ImageUtils

# 使用 Bria AI 生成图像（完整 API 参考见 bria-ai 技能文档）
response = requests.post(
    "https://engine.prod.bria-api.com/v2/image/generate",
    headers={"api_token": BRIA_API_KEY, "Content-Type": "application/json"},
    json={"prompt": "product photo of headphones", "aspect_ratio": "1:1", "sync": True}
)
image_url = response.json()["result"]["image_url"]

# 下载并后处理
image = ImageUtils.load_from_url(image_url)

# 生成响应式多尺寸图像
sizes = {
    "large": ImageUtils.resize(image, width=1200),
    "medium": ImageUtils.resize(image, width=600),
    "thumb": ImageUtils.thumbnail(image, (150, 150))
}

# 全部保存为优化的 WebP 格式
for name, img in sizes.items():
    ImageUtils.save(img, f"product_{name}.webp", quality=85)

批量处理示例

from pathlib import Path
from image_utils import ImageUtils

def process_catalog(input_dir, output_dir):
    """处理目录下所有图像文件。"""
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)

    for image_file in Path(input_dir).glob("*.{jpg,png,webp}"):
        image = ImageUtils.load(image_file)

        # 裁剪为正方形
        square = ImageUtils.crop_to_aspect(image, "1:1")

        # 缩放为标准尺寸
        resized = ImageUtils.resize(square, width=800, height=800)

        # 添加文字水印
        final = ImageUtils.add_text_watermark(resized, "© My Brand")

        # 保存为优化的 WebP
        output_file = output_path / f"{image_file.stem}.webp"
        ImageUtils.save(final, output_file, quality=85)

process_catalog("./raw_images", "./processed")

API 参考

完整实现与详细文档说明请参阅 image_utils.py 中的 docstring。