Class ThumbnailBuilder

java.lang.Object
cloud.opencode.base.image.thumbnail.ThumbnailBuilder
public class ThumbnailBuilder extends Object
Thumbnail Builder 缩略图构建器

Builder for creating thumbnails with various options.

用于创建各种选项缩略图的构建器。

Usage Examples | 使用示例:

// Simple thumbnail
ThumbnailBuilder.of(imagePath)
    .size(200, 200)
    .save(thumbnailPath);

// With crop
ThumbnailBuilder.of(image)
    .size(150, 150)
    .crop(true)
    .quality(0.85f)
    .format(ImageFormat.JPEG)
    .save(outputPath);

// Get as bytes
byte[] bytes = ThumbnailBuilder.of(inputPath)
    .size(100, 100)
    .toBytes();

Features | 主要功能:

  • Fluent builder API for thumbnail generation - 用于缩略图生成的流式构建器 API
  • Configurable size, crop mode, quality, and format - 可配置的大小、裁剪模式、质量和格式
  • Save to file or convert to byte array - 保存到文件或转换为字节数组

Security | 安全性:

  • Thread-safe: No (mutable builder) - 线程安全: 否（可变构建器）
  • Null-safe: No (throws on null source) - 空值安全: 否（null 源抛异常）

Performance | 性能特性:

  • Time complexity: O(W*H) for build() where W*H is the source pixel count - pixel resampling visits every source pixel - 时间复杂度: O(W*H)，W*H 为源图片像素数 - 像素重采样需访问每个源像素
  • Space complexity: O(w*h) where w*h is the target thumbnail dimensions - output image buffer proportional to target size - 空间复杂度: O(w*h)，w*h 为目标缩略图尺寸 - 输出图像缓冲区与目标大小成正比
Since:
JDK 25, opencode-base-image V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • ThumbnailBuilder

      public ThumbnailBuilder()
      Create empty thumbnail builder 创建空的缩略图构建器

      Use source(Path) or source(Image) to set the source image.

      使用 source(Path) 或 source(Image) 设置源图片。

    • ThumbnailBuilder

      public ThumbnailBuilder(BufferedImage source)
      Create thumbnail builder from BufferedImage 从BufferedImage创建缩略图构建器
      Parameters:
      source - the source image | 源图片

  • Method Details

    • of

      public static ThumbnailBuilder of(Path path) throws ImageIOException
      Create thumbnail builder from path 从路径创建缩略图构建器
      Parameters:
      path - the image path | 图片路径
      Returns:
      the builder | 构建器
      Throws:
      ImageIOException - if reading fails | 如果读取失败

    • of

      public static ThumbnailBuilder of(Image image)
      Create thumbnail builder from Image 从Image创建缩略图构建器
      Parameters:
      image - the image | 图片
      Returns:
      the builder | 构建器

    • of

      public static ThumbnailBuilder of(BufferedImage image)
      Create thumbnail builder from BufferedImage 从BufferedImage创建缩略图构建器
      Parameters:
      image - the buffered image | 缓冲图片
      Returns:
      the builder | 构建器

    • of

      public static ThumbnailBuilder of(byte[] bytes) throws ImageIOException
      Create thumbnail builder from bytes 从字节数组创建缩略图构建器
      Parameters:
      bytes - the image bytes | 图片字节数组
      Returns:
      the builder | 构建器
      Throws:
      ImageIOException - if reading fails | 如果读取失败

    • size

      public ThumbnailBuilder size(int width, int height)
      Set thumbnail size 设置缩略图尺寸
      Parameters:
      width - the width | 宽度
      height - the height | 高度
      Returns:
      this builder | 构建器

    • width

      public ThumbnailBuilder width(int width)
      Set thumbnail width (height auto-calculated) 设置缩略图宽度（高度自动计算）
      Parameters:
      width - the width | 宽度
      Returns:
      this builder | 构建器

    • height

      public ThumbnailBuilder height(int height)
      Set thumbnail height (width auto-calculated) 设置缩略图高度（宽度自动计算）
      Parameters:
      height - the height | 高度
      Returns:
      this builder | 构建器

    • crop

      public ThumbnailBuilder crop(boolean crop)
      Enable/disable cropping to fit exact size 启用/禁用裁剪以适应精确尺寸
      Parameters:
      crop - true to crop | 是否裁剪
      Returns:
      this builder | 构建器

    • quality

      public ThumbnailBuilder quality(float quality)
      Set output quality (for JPEG) 设置输出质量（用于JPEG）
      Parameters:
      quality - quality from 0.0 to 1.0 | 质量（0.0到1.0）
      Returns:
      this builder | 构建器

    • format

      public ThumbnailBuilder format(ImageFormat format)
      Set output format 设置输出格式
      Parameters:
      format - the format | 格式
      Returns:
      this builder | 构建器

    • source

      public ThumbnailBuilder source(Path path) throws ImageIOException
      Set source image from path 从路径设置源图片
      Parameters:
      path - the source image path | 源图片路径
      Returns:
      this builder | 构建器
      Throws:
      ImageIOException - if reading fails | 如果读取失败

    • source

      public ThumbnailBuilder source(Image image)
      Set source image from Image 从Image设置源图片
      Parameters:
      image - the source image | 源图片
      Returns:
      this builder | 构建器

    • output

      public ThumbnailBuilder output(Path path)
      Set output path 设置输出路径
      Parameters:
      path - the output path | 输出路径
      Returns:
      this builder | 构建器

    • create

      public void create() throws ImageWriteException
      Create the thumbnail and save to output path 创建缩略图并保存到输出路径

      This method combines build() and save(Path).

      此方法组合了 build() 和 save(Path)。

      Throws:
      ImageWriteException - if writing fails | 如果写入失败
      IllegalStateException - if source or output is not set | 如果源或输出未设置

    • build

      public BufferedImage build()
      Build thumbnail 构建缩略图
      Returns:
      the thumbnail image | 缩略图
      Throws:
      IllegalStateException - if source is not set | 如果源未设置

    • toImage

      public Image toImage()
      Build and return as Image wrapper 构建并返回Image包装器
      Returns:
      the Image wrapper | 图片包装器

    • save

      public void save(Path path) throws ImageWriteException
      Build and save to path 构建并保存到路径
      Parameters:
      path - the output path | 输出路径
      Throws:
      ImageWriteException - if writing fails | 如果写入失败

    • toBytes

      public byte[] toBytes() throws ImageOperationException
      Build and return as bytes 构建并返回字节数组
      Returns:
      the thumbnail bytes | 缩略图字节数组
      Throws:
      ImageOperationException - if conversion fails | 如果转换失败