Thumbnail Generator

缩略图生成器

Create optimized thumbnails with smart cropping, multiple output sizes, and batch processing.

支持智能裁剪、多输出尺寸和批量处理，可生成优化后的缩略图。

Features

功能特性

Smart Cropping: Center, face-aware, or edge-detection based
Multiple Sizes: Generate multiple thumbnail sizes at once
Presets: Web, social media, app icon presets
Batch Processing: Process entire folders
Quality Control: Optimize file size vs quality
Formats: JPEG, PNG, WebP output

智能裁剪：支持居中、人脸感知或基于边缘检测的裁剪模式
多尺寸输出：可一次性生成多种尺寸的缩略图
预设模板：内置网页、社交媒体、应用图标预设
批量处理：可处理整个文件夹内的所有图片
质量控制：可平衡文件大小与输出质量
格式支持：JPEG、PNG、WebP 格式输出

Quick Start

快速开始

python

from thumbnail_gen import ThumbnailGenerator

gen = ThumbnailGenerator()
gen.load("photo.jpg")

python

from thumbnail_gen import ThumbnailGenerator

gen = ThumbnailGenerator()
gen.load("photo.jpg")

Create single thumbnail

gen.resize(200, 200).save("thumb.jpg")

Create multiple sizes

gen.generate_sizes([ (100, 100), (200, 200), (400, 400) ], output_dir="./thumbs/")

undefined

gen.generate_sizes([ (100, 100), (200, 200), (400, 400) ], output_dir="./thumbs/")

undefined

CLI Usage

CLI 使用方法

bash

undefined

bash

undefined

Single thumbnail

python thumbnail_gen.py --input photo.jpg --size 200x200 --output thumb.jpg

Multiple sizes

python thumbnail_gen.py --input photo.jpg --sizes 100x100,200x200,400x400 --output ./thumbs/

Batch process folder

python thumbnail_gen.py --input ./photos/ --size 200x200 --output ./thumbs/

Use preset

python thumbnail_gen.py --input photo.jpg --preset social --output ./thumbs/

Smart crop

python thumbnail_gen.py --input photo.jpg --size 200x200 --crop smart --output thumb.jpg

WebP output

python thumbnail_gen.py --input photo.jpg --size 200x200 --format webp --output thumb.webp

undefined

python thumbnail_gen.py --input photo.jpg --size 200x200 --format webp --output thumb.webp

undefined

API Reference

API 参考

ThumbnailGenerator Class

ThumbnailGenerator 类

python

class ThumbnailGenerator:
    def __init__(self)

    # Loading
    def load(self, filepath: str) -> 'ThumbnailGenerator'

    # Resizing
    def resize(self, width: int, height: int,
              crop: str = "fit") -> 'ThumbnailGenerator'
    def resize_width(self, width: int) -> 'ThumbnailGenerator'
    def resize_height(self, height: int) -> 'ThumbnailGenerator'

    # Cropping
    def crop_center(self, width: int, height: int) -> 'ThumbnailGenerator'
    def crop_smart(self, width: int, height: int) -> 'ThumbnailGenerator'
    def crop_position(self, width: int, height: int,
                     position: str = "center") -> 'ThumbnailGenerator'

    # Output
    def save(self, output: str, quality: int = 85,
            format: str = None) -> str
    def to_bytes(self, format: str = "JPEG", quality: int = 85) -> bytes

    # Batch operations
    def generate_sizes(self, sizes: list, output_dir: str,
                      prefix: str = None) -> list
    def process_folder(self, input_dir: str, output_dir: str,
                      width: int, height: int, recursive: bool = False) -> list

    # Presets
    def apply_preset(self, preset: str, output_dir: str) -> list

python

class ThumbnailGenerator:
    def __init__(self)

    # Loading
    def load(self, filepath: str) -> 'ThumbnailGenerator'

    # Resizing
    def resize(self, width: int, height: int,
              crop: str = "fit") -> 'ThumbnailGenerator'
    def resize_width(self, width: int) -> 'ThumbnailGenerator'
    def resize_height(self, height: int) -> 'ThumbnailGenerator'

    # Cropping
    def crop_center(self, width: int, height: int) -> 'ThumbnailGenerator'
    def crop_smart(self, width: int, height: int) -> 'ThumbnailGenerator'
    def crop_position(self, width: int, height: int,
                     position: str = "center") -> 'ThumbnailGenerator'

    # Output
    def save(self, output: str, quality: int = 85,
            format: str = None) -> str
    def to_bytes(self, format: str = "JPEG", quality: int = 85) -> bytes

    # Batch operations
    def generate_sizes(self, sizes: list, output_dir: str,
                      prefix: str = None) -> list
    def process_folder(self, input_dir: str, output_dir: str,
                      width: int, height: int, recursive: bool = False) -> list

    # Presets
    def apply_preset(self, preset: str, output_dir: str) -> list

Resize Modes

调整大小模式

Fit (Default)

Fit（默认）

Resize to fit within bounds, maintaining aspect ratio:

python

gen.resize(200, 200, crop="fit")

调整大小以适配边界，保持宽高比：

python

gen.resize(200, 200, crop="fit")

Result: Image fits within 200x200, may have letterboxing

undefined

undefined

Fill

Resize to fill bounds, cropping excess:

python

gen.resize(200, 200, crop="fill")

调整大小以填充边界，裁剪超出部分：

python

gen.resize(200, 200, crop="fill")

Result: Exactly 200x200, some content may be cropped

undefined

undefined

Stretch

Resize to exact dimensions (distorts aspect ratio):

python

gen.resize(200, 200, crop="stretch")

调整为指定精确尺寸（会改变宽高比导致变形）：

python

gen.resize(200, 200, crop="stretch")

Result: Exactly 200x200, may be distorted

undefined

undefined

Smart Cropping

智能裁剪

Automatically detect the most interesting part of the image:

python

gen.load("photo.jpg")
gen.crop_smart(200, 200)
gen.save("thumb.jpg")

Uses edge detection to find areas of interest.

自动检测图片中最具吸引力的区域：

python

gen.load("photo.jpg")
gen.crop_smart(200, 200)
gen.save("thumb.jpg")

使用边缘检测技术识别感兴趣的区域。

Crop Positions

裁剪位置

python

undefined

python

undefined

Predefined positions

gen.crop_position(200, 200, position="center") gen.crop_position(200, 200, position="top") gen.crop_position(200, 200, position="bottom") gen.crop_position(200, 200, position="left") gen.crop_position(200, 200, position="right") gen.crop_position(200, 200, position="top-left") gen.crop_position(200, 200, position="top-right") gen.crop_position(200, 200, position="bottom-left") gen.crop_position(200, 200, position="bottom-right")

undefined

gen.crop_position(200, 200, position="center") gen.crop_position(200, 200, position="top") gen.crop_position(200, 200, position="bottom") gen.crop_position(200, 200, position="left") gen.crop_position(200, 200, position="right") gen.crop_position(200, 200, position="top-left") gen.crop_position(200, 200, position="top-right") gen.crop_position(200, 200, position="bottom-left") gen.crop_position(200, 200, position="bottom-right")

undefined

Presets

预设模板

Web Preset

网页预设

python

gen.apply_preset("web", "./output/")

python

gen.apply_preset("web", "./output/")

Generates:

- thumb_small.jpg (150x150)

- thumb_medium.jpg (300x300)

- thumb_large.jpg (600x600)

undefined

undefined

Social Media Preset

社交媒体预设

python

gen.apply_preset("social", "./output/")

python

gen.apply_preset("social", "./output/")

Generates:

- instagram_square.jpg (1080x1080)

- instagram_portrait.jpg (1080x1350)

- instagram_landscape.jpg (1080x566)

- twitter.jpg (1200x675)

- facebook.jpg (1200x630)

- linkedin.jpg (1200x627)

undefined

undefined

App Icons Preset

应用图标预设

python

gen.apply_preset("icons", "./output/")

python

gen.apply_preset("icons", "./output/")

Generates:

- icon_16.png (16x16)

- icon_32.png (32x32)

- icon_48.png (48x48)

- icon_64.png (64x64)

- icon_128.png (128x128)

- icon_256.png (256x256)

- icon_512.png (512x512)

undefined

undefined

Favicon Preset

站点图标预设

python

gen.apply_preset("favicon", "./output/")

python

gen.apply_preset("favicon", "./output/")

Generates:

- favicon_16.png (16x16)

- favicon_32.png (32x32)

- apple_touch.png (180x180)

- android_192.png (192x192)

- android_512.png (512x512)

undefined

undefined

Multiple Sizes

多尺寸生成

Generate multiple thumbnail sizes at once:

python

gen.load("photo.jpg")
files = gen.generate_sizes(
    sizes=[(100, 100), (200, 200), (400, 400), (800, 800)],
    output_dir="./thumbs/",
    prefix="product"
)

一次性生成多种尺寸的缩略图：

python

gen.load("photo.jpg")
files = gen.generate_sizes(
    sizes=[(100, 100), (200, 200), (400, 400), (800, 800)],
    output_dir="./thumbs/",
    prefix="product"
)

Creates:

- product_100x100.jpg

- product_200x200.jpg

- product_400x400.jpg

- product_800x800.jpg

undefined

undefined

Batch Processing

批量处理

Process entire folders:

python

gen = ThumbnailGenerator()
results = gen.process_folder(
    input_dir="./photos/",
    output_dir="./thumbnails/",
    width=200,
    height=200,
    recursive=True
)

print(f"Processed {len(results)} images")

处理整个文件夹内的所有图片：

python

gen = ThumbnailGenerator()
results = gen.process_folder(
    input_dir="./photos/",
    output_dir="./thumbnails/",
    width=200,
    height=200,
    recursive=True
)

print(f"Processed {len(results)} images")

Quality and Format

质量与格式

Quality Settings

质量设置

python

undefined

python

undefined

High quality (larger file)

gen.save("thumb.jpg", quality=95)

Balanced (default)

gen.save("thumb.jpg", quality=85)

Web optimized (smaller file)

gen.save("thumb.jpg", quality=70)

undefined

gen.save("thumb.jpg", quality=70)

undefined

Output Formats

输出格式

python

undefined

python

undefined

JPEG (best for photos)

gen.save("thumb.jpg", format="JPEG")

PNG (best for graphics/transparency)

gen.save("thumb.png", format="PNG")

WebP (modern, smaller files)

gen.save("thumb.webp", format="WEBP", quality=80)

undefined

gen.save("thumb.webp", format="WEBP", quality=80)

undefined

Output Structure

输出结构

python

result = gen.generate_sizes(
    sizes=[(100, 100), (200, 200)],
    output_dir="./thumbs/"
)

python

result = gen.generate_sizes(
    sizes=[(100, 100), (200, 200)],
    output_dir="./thumbs/"
)

Returns:

[ { "size": "100x100", "path": "./thumbs/image_100x100.jpg", "file_size": 5432 }, { "size": "200x200", "path": "./thumbs/image_200x200.jpg", "file_size": 15234 } ]

undefined

[ { "size": "100x100", "path": "./thumbs/image_100x100.jpg", "file_size": 5432 }, { "size": "200x200", "path": "./thumbs/image_200x200.jpg", "file_size": 15234 } ]

undefined

Example Workflows

示例工作流

E-commerce Product Images

电商商品图片

python

gen = ThumbnailGenerator()
gen.load("product.jpg")

python

gen = ThumbnailGenerator()
gen.load("product.jpg")

Generate product thumbnails

gen.generate_sizes( sizes=[ (80, 80), # Cart thumbnail (200, 200), # Category listing (400, 400), # Product page (800, 800) # Zoom view ], output_dir="./product_images/", prefix="sku_12345" )

undefined

gen.generate_sizes( sizes=[ (80, 80), # Cart thumbnail (200, 200), # Category listing (400, 400), # Product page (800, 800) # Zoom view ], output_dir="./product_images/", prefix="sku_12345" )

undefined

Gallery Thumbnails

图库缩略图

python

gen = ThumbnailGenerator()
results = gen.process_folder(
    input_dir="./gallery/",
    output_dir="./gallery/thumbs/",
    width=300,
    height=200
)

python

gen = ThumbnailGenerator()
results = gen.process_folder(
    input_dir="./gallery/",
    output_dir="./gallery/thumbs/",
    width=300,
    height=200
)

Social Media Batch

社交媒体批量处理

python

gen = ThumbnailGenerator()

for image in Path("./photos/").glob("*.jpg"):
    gen.load(str(image))
    gen.apply_preset("social", f"./social/{image.stem}/")

python

gen = ThumbnailGenerator()

for image in Path("./photos/").glob("*.jpg"):
    gen.load(str(image))
    gen.apply_preset("social", f"./social/{image.stem}/")

Dependencies

依赖

pillow>=10.0.0
numpy>=1.24.0

pillow>=10.0.0
numpy>=1.24.0

thumbnail-generator

Original

Translation

Thumbnail Generator

缩略图生成器

Features

功能特性

Quick Start

快速开始

Create single thumbnail

Create single thumbnail

Create multiple sizes

Create multiple sizes

CLI Usage

CLI 使用方法

Single thumbnail

Single thumbnail

Multiple sizes

Multiple sizes

Batch process folder

Batch process folder

Use preset

Use preset

Smart crop

Smart crop

WebP output

WebP output

API Reference

API 参考

ThumbnailGenerator Class

ThumbnailGenerator 类

Resize Modes

调整大小模式

Fit (Default)

Fit（默认）

Result: Image fits within 200x200, may have letterboxing

Result: Image fits within 200x200, may have letterboxing

Fill

Fill

Result: Exactly 200x200, some content may be cropped

Result: Exactly 200x200, some content may be cropped

Stretch

Stretch

Result: Exactly 200x200, may be distorted

Result: Exactly 200x200, may be distorted

Smart Cropping

智能裁剪

Crop Positions

裁剪位置

Predefined positions

Predefined positions

Presets

预设模板

Web Preset

网页预设

Generates:

Generates:

- thumb_small.jpg (150x150)

- thumb_small.jpg (150x150)

- thumb_medium.jpg (300x300)

- thumb_medium.jpg (300x300)

- thumb_large.jpg (600x600)

- thumb_large.jpg (600x600)

Social Media Preset

社交媒体预设

Generates:

Generates:

- instagram_square.jpg (1080x1080)

- instagram_square.jpg (1080x1080)

- instagram_portrait.jpg (1080x1350)

- instagram_portrait.jpg (1080x1350)

- instagram_landscape.jpg (1080x566)

- instagram_landscape.jpg (1080x566)

- twitter.jpg (1200x675)

- twitter.jpg (1200x675)

- facebook.jpg (1200x630)

- facebook.jpg (1200x630)

- linkedin.jpg (1200x627)

- linkedin.jpg (1200x627)

App Icons Preset