image-utils

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Image Utilities

图像处理工具集

Pillow-based utilities for deterministic pixel-level image operations. Use for resize, crop, composite, format conversion, watermarks, and other standard image processing tasks.

基于Pillow的确定性像素级图像处理工具集，可用于调整大小、裁剪、合成、格式转换、添加水印及其他标准图像处理任务。

When to Use This Skill

适用场景

Post-processing AI-generated images: Resize, crop, optimize for web after generation
Format conversion: PNG ↔ JPEG ↔ WEBP with quality control
Compositing: Overlay images, paste subjects onto backgrounds
Batch processing: Resize to multiple sizes, add watermarks
Web optimization: Compress and resize for fast delivery
Social media preparation: Crop to platform-specific aspect ratios

AI生成图像后期处理：生成后调整大小、裁剪、优化以适配Web展示
格式转换：在PNG ↔ JPEG ↔ WEBP之间转换，支持质量控制
图像合成：叠加图像、将主体粘贴至背景
批量处理：批量调整为多种尺寸、添加水印
Web优化：压缩并调整大小以实现快速传输
社交媒体适配：裁剪为平台特定的宽高比

Quick Reference

速查参考

Operation	Method	Description
Loading	`load(source)`	Load from URL, path, bytes, or base64
	`load_from_url(url)`	Download image from URL
Saving	`save(image, path)`	Save with format auto-detection
	`to_bytes(image, format)`	Convert to bytes
	`to_base64(image, format)`	Convert to base64 string
Resizing	`resize(image, width, height)`	Resize to exact dimensions
	`scale(image, factor)`	Scale by factor (0.5 = half)
	`thumbnail(image, size)`	Fit within size, maintain aspect
Cropping	`crop(image, left, top, right, bottom)`	Crop to region
	`crop_center(image, width, height)`	Crop from center
	`crop_to_aspect(image, ratio)`	Crop to aspect ratio
Compositing	`paste(bg, fg, position)`	Overlay at coordinates
	`composite(bg, fg, mask)`	Alpha composite
	`fit_to_canvas(image, w, h)`	Fit onto canvas size
Borders	`add_border(image, width, color)`	Add solid border
	`add_padding(image, padding)`	Add whitespace padding
Transforms	`rotate(image, angle)`	Rotate by degrees
	`flip_horizontal(image)`	Mirror horizontally
	`flip_vertical(image)`	Flip vertically
Watermarks	`add_text_watermark(image, text)`	Add text overlay
	`add_image_watermark(image, logo)`	Add logo watermark
Adjustments	`adjust_brightness(image, factor)`	Lighten/darken
	`adjust_contrast(image, factor)`	Adjust contrast
	`adjust_saturation(image, factor)`	Adjust color saturation
	`blur(image, radius)`	Apply Gaussian blur
Web	`optimize_for_web(image, max_size)`	Optimize for delivery
Info	`get_info(image)`	Get dimensions, format, mode

操作	方法	描述
加载	`load(source)`	从URL、路径、字节或base64加载图像
	`load_from_url(url)`	从URL下载图像
保存	`save(image, path)`	自动检测格式保存图像
	`to_bytes(image, format)`	将图像转换为字节格式
	`to_base64(image, format)`	将图像转换为base64字符串
调整大小	`resize(image, width, height)`	调整至精确尺寸
	`scale(image, factor)`	按比例缩放（0.5为原尺寸的一半）
	`thumbnail(image, size)`	适配指定尺寸，保持宽高比
裁剪	`crop(image, left, top, right, bottom)`	裁剪指定区域
	`crop_center(image, width, height)`	从中心裁剪
	`crop_to_aspect(image, ratio)`	裁剪至指定宽高比
合成	`paste(bg, fg, position)`	在指定坐标叠加前景图
	`composite(bg, fg, mask)`	Alpha通道合成
	`fit_to_canvas(image, w, h)`	将图像适配至画布尺寸
边框	`add_border(image, width, color)`	添加纯色边框
	`add_padding(image, padding)`	添加空白内边距
变换	`rotate(image, angle)`	按角度旋转
	`flip_horizontal(image)`	水平镜像翻转
	`flip_vertical(image)`	垂直翻转
水印	`add_text_watermark(image, text)`	添加文字水印
	`add_image_watermark(image, logo)`	添加Logo水印
色彩调整	`adjust_brightness(image, factor)`	调整亮度（提亮/变暗）
	`adjust_contrast(image, factor)`	调整对比度
	`adjust_saturation(image, factor)`	调整色彩饱和度
	`blur(image, radius)`	应用高斯模糊
Web优化	`optimize_for_web(image, max_size)`	优化以适配Web传输
信息获取	`get_info(image)`	获取图像尺寸、格式、色彩模式

Requirements

依赖安装

bash

pip install Pillow requests

bash

pip install Pillow requests

Basic Usage

基础用法

python

from image_utils import ImageUtils

python

from image_utils import ImageUtils

Load from URL

从URL加载图像

image = ImageUtils.load_from_url("https://example.com/image.jpg")

Or load from various sources

或从多种来源加载

image = ImageUtils.load("/path/to/image.png") # File path image = ImageUtils.load(image_bytes) # Bytes image = ImageUtils.load("data:image/png;base64,...") # Base64

image = ImageUtils.load("/path/to/image.png") # 文件路径 image = ImageUtils.load(image_bytes) # 字节数据 image = ImageUtils.load("data:image/png;base64,...") # Base64字符串

Resize and save

调整大小并保存

resized = ImageUtils.resize(image, width=800, height=600) ImageUtils.save(resized, "output.webp", quality=90)

Get image info

获取图像信息

info = ImageUtils.get_info(image) print(f"{info['width']}x{info['height']} {info['mode']}")

undefined

info = ImageUtils.get_info(image) print(f"{info['width']}x{info['height']} {info['mode']}")

undefined

Resizing & Scaling

调整大小与缩放

python

undefined

python

undefined

Resize to exact dimensions

调整至精确尺寸

resized = ImageUtils.resize(image, width=800, height=600)

Resize maintaining aspect ratio (fit within bounds)

保持宽高比调整大小（适配边界）

fitted = ImageUtils.resize(image, width=800, height=600, maintain_aspect=True)

Resize by width only (height auto-calculated)

仅调整宽度（高度自动计算）

resized = ImageUtils.resize(image, width=800)

Scale by factor

按比例缩放

half = ImageUtils.scale(image, 0.5) # 50% size double = ImageUtils.scale(image, 2.0) # 200% size

half = ImageUtils.scale(image, 0.5) # 原尺寸的50% double = ImageUtils.scale(image, 2.0) # 原尺寸的200%

Create thumbnail

创建缩略图

thumb = ImageUtils.thumbnail(image, (150, 150))

undefined

thumb = ImageUtils.thumbnail(image, (150, 150))

undefined

Cropping

裁剪

python

undefined

python

undefined

Crop to specific region

裁剪指定区域

cropped = ImageUtils.crop(image, left=100, top=50, right=500, bottom=350)

Crop from center

从中心裁剪

center = ImageUtils.crop_center(image, width=400, height=400)

Crop to aspect ratio (for social media)

裁剪至指定宽高比（适配社交媒体）

square = ImageUtils.crop_to_aspect(image, "1:1") # Instagram wide = ImageUtils.crop_to_aspect(image, "16:9") # YouTube thumbnail story = ImageUtils.crop_to_aspect(image, "9:16") # Stories/Reels

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") # 快拍/短视频适配

Control crop anchor

控制裁剪锚点

top_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="top") bottom_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="bottom")

undefined

top_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="top") bottom_crop = ImageUtils.crop_to_aspect(image, "16:9", anchor="bottom")

undefined

Compositing

图像合成

python

undefined

python

undefined

Paste foreground onto background

将前景图粘贴至背景图

result = ImageUtils.paste(background, foreground, position=(100, 50))

Alpha composite (foreground must have transparency)

Alpha通道合成（前景图需带透明通道）

result = ImageUtils.composite(background, foreground)

Fit image onto canvas with letterboxing

将图像适配至画布（添加黑边/白边）

canvas = ImageUtils.fit_to_canvas( image, width=1200, height=800, background_color=(255, 255, 255, 255), # White position="center" # or "top", "bottom" )

undefined

canvas = ImageUtils.fit_to_canvas( image, width=1200, height=800, background_color=(255, 255, 255, 255), # 白色 position="center" # 可选值：top、bottom )

undefined

Format Conversion

格式转换

python

undefined

python

undefined

Convert to different formats

转换为不同格式

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)

Get base64 for data URLs

转换为base64格式用于Data URL

base64_str = ImageUtils.to_base64(image, "PNG") data_url = ImageUtils.to_base64(image, "PNG", include_data_url=True)

Returns: "data:image/png;base64,..."

返回格式："data:image/png;base64,..."

Save with format auto-detected from extension

根据文件扩展名自动检测格式保存

ImageUtils.save(image, "output.png") ImageUtils.save(image, "output.jpg", quality=85) ImageUtils.save(image, "output.webp", quality=90)

undefined

ImageUtils.save(image, "output.png") ImageUtils.save(image, "output.jpg", quality=85) ImageUtils.save(image, "output.webp", quality=90)

undefined

Watermarks

水印添加

python

undefined

python

undefined

Text watermark

添加文字水印

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), # Semi-transparent white margin=20 )

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/image watermark

添加Logo/图像水印

logo = ImageUtils.load("logo.png") watermarked = ImageUtils.add_image_watermark( image, watermark=logo, position="bottom-right", opacity=0.5, scale=0.15, # 15% of image width margin=20 )

undefined

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 )

undefined

Adjustments

色彩调整

python

undefined

python

undefined

Brightness (1.0 = original, <1 darker, >1 lighter)

调整亮度（1.0为原亮度，<1变暗，>1变亮）

bright = ImageUtils.adjust_brightness(image, 1.3) dark = ImageUtils.adjust_brightness(image, 0.7)

Contrast (1.0 = original)

调整对比度（1.0为原对比度）

high_contrast = ImageUtils.adjust_contrast(image, 1.5)

Saturation (0 = grayscale, 1.0 = original, >1 more vivid)

调整饱和度（0为灰度图，1.0为原饱和度，>1色彩更鲜艳）

vivid = ImageUtils.adjust_saturation(image, 1.3) grayscale = ImageUtils.adjust_saturation(image, 0)

Sharpness

调整锐度

sharp = ImageUtils.adjust_sharpness(image, 2.0)

Blur

模糊处理

blurred = ImageUtils.blur(image, radius=5)

undefined

blurred = ImageUtils.blur(image, radius=5)

undefined

Transforms

图像变换

python

undefined

python

undefined

Rotate (counter-clockwise, degrees)

旋转（逆时针，单位为度）

rotated = ImageUtils.rotate(image, 45) rotated = ImageUtils.rotate(image, 90, expand=False) # Don't expand canvas

rotated = ImageUtils.rotate(image, 45) rotated = ImageUtils.rotate(image, 90, expand=False) # 不扩展画布

Flip

翻转

mirrored = ImageUtils.flip_horizontal(image) flipped = ImageUtils.flip_vertical(image)

undefined

mirrored = ImageUtils.flip_horizontal(image) flipped = ImageUtils.flip_vertical(image)

undefined

Borders & Padding

边框与内边距

python

undefined

python

undefined

Add solid border

添加纯色边框

bordered = ImageUtils.add_border(image, width=5, color=(0, 0, 0))

Add padding (whitespace)

添加空白内边距

padded = ImageUtils.add_padding(image, padding=20) # Uniform padded = ImageUtils.add_padding(image, padding=(10, 20, 10, 20)) # left, top, right, bottom

undefined

padded = ImageUtils.add_padding(image, padding=20) # 统一内边距 padded = ImageUtils.add_padding(image, padding=(10, 20, 10, 20)) # 左、上、右、下内边距

undefined

Web Optimization

Web图像优化

python

undefined

python

undefined

Optimize for web delivery

优化以适配Web传输

optimized_bytes = ImageUtils.optimize_for_web( image, max_dimension=1920, # Resize if larger format="WEBP", # Best compression quality=85 )

optimized_bytes = ImageUtils.optimize_for_web( image, max_dimension=1920, # 超过该尺寸则调整 format="WEBP", # 最佳压缩格式 quality=85 )

Save optimized

保存优化后的图像

with open("optimized.webp", "wb") as f: f.write(optimized_bytes)

undefined

with open("optimized.webp", "wb") as f: f.write(optimized_bytes)

undefined

Integration with AI Image Generation

与AI图像生成工具集成

Use with Bria AI or other image generation APIs:

python

from bria_client import BriaClient
from image_utils import ImageUtils

client = BriaClient()

可搭配Bria AI或其他图像生成API使用：

python

from bria_client import BriaClient
from image_utils import ImageUtils

client = BriaClient()

Generate with AI

AI生成图像

result = client.generate("product photo of headphones", aspect_ratio="1:1") image_url = result['result']['image_url']

Download and post-process

下载并进行后期处理

image = ImageUtils.load_from_url(image_url)

Create multiple sizes for responsive images

创建多种尺寸以适配响应式展示

sizes = { "large": ImageUtils.resize(image, width=1200), "medium": ImageUtils.resize(image, width=600), "thumb": ImageUtils.thumbnail(image, (150, 150)) }

Save all as optimized WebP

保存为优化后的WebP格式

for name, img in sizes.items(): ImageUtils.save(img, f"product_{name}.webp", quality=85)

undefined

for name, img in sizes.items(): ImageUtils.save(img, f"product_{name}.webp", quality=85)

undefined

Batch Processing Example

批量处理示例

python

from pathlib import Path
from image_utils import ImageUtils

def process_catalog(input_dir, output_dir):
    """Process all images in a directory."""
    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)

        # Crop to square
        square = ImageUtils.crop_to_aspect(image, "1:1")

        # Resize to standard size
        resized = ImageUtils.resize(square, width=800, height=800)

        # Add watermark
        final = ImageUtils.add_text_watermark(resized, "© My Brand")

        # Save optimized
        output_file = output_path / f"{image_file.stem}.webp"
        ImageUtils.save(final, output_file, quality=85)

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

python

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")

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

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

API Reference

API参考

See image_utils.py for complete implementation with docstrings.

完整实现及文档请查看 image_utils.py。