Class ResponsiveBuilder

java.lang.Object
cloud.opencode.base.image.responsive.ResponsiveBuilder
public final class ResponsiveBuilder extends Object
Responsive Multi-Size Image Generator 响应式多尺寸图片生成器

Generates multiple image variants at different sizes and formats from a single source image. Useful for creating responsive image sets for web and mobile applications.

从单个源图片生成多种不同尺寸和格式的图片变体。 适用于为 Web 和移动应用程序创建响应式图片集。

TODO Phase 9 — Raster pipeline | Raster 管线（待 Phase 9 处理）: This class orchestrates the high-level Image façade (read → resize → encode → write); it does not directly expose Raster. A Raster- native pipeline depends on the Phase 9 rewrite of Image / OpenImage and a Raster resize primitive — both intentionally out of scope here.

本类编排高层 Image 门面（读取 → 缩放 → 编码 → 写入），并未直接暴露 Raster。Raster 原生管线依赖 Phase 9 对 Image / OpenImage 的重写以及尚不存在的 Raster resize 原语，本阶段刻意不动。

Features | 主要功能:

  • Generate multiple size variants from a single source - 从单个源生成多种尺寸变体
  • Output in multiple formats (JPEG, PNG, etc.) - 输出多种格式（JPEG、PNG 等）
  • Configurable compression quality - 可配置的压缩质量
  • Batch processing with parallel execution - 支持并行执行的批量处理
  • Error handling per source in batch mode - 批量模式下每个源的错误处理

Usage Examples | 使用示例:

ResponsiveBuilder.of(source)
    .variant(64, 64, "icon")
    .variant(200, 200, "thumb")
    .formats(ImageFormat.JPEG, ImageFormat.PNG)
    .quality(0.85f)
    .generate(outputDir);

Security | 安全性:

  • Thread-safe: No (builder pattern) - 线程安全: 否（构建器模式）
Since:
JDK 25, opencode-base-image V2.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • of

      public static ResponsiveBuilder of(Path source) throws ImageIOException
      Create a ResponsiveBuilder from a file path. 从文件路径创建 ResponsiveBuilder。
      Parameters:
      source - the source image path | 源图片路径
      Returns:
      a new builder instance | 新的构建器实例
      Throws:
      ImageIOException - if reading the image fails | 如果读取图片失败

    • of

      public static ResponsiveBuilder of(Image source)
      Create a ResponsiveBuilder from an Image instance. 从 Image 实例创建 ResponsiveBuilder。
      Parameters:
      source - the source image | 源图片
      Returns:
      a new builder instance | 新的构建器实例

    • variant

      public ResponsiveBuilder variant(int width, int height, String name)
      Add a variant configuration. 添加一个变体配置。
      Parameters:
      width - the target width | 目标宽度
      height - the target height | 目标高度
      name - the variant name for output filenames | 用于输出文件名的变体名称
      Returns:
      this builder for chaining | 用于链式调用的构建器

    • formats

      public ResponsiveBuilder formats(ImageFormat... formats)
      Set the output formats. If not called, defaults to JPEG. 设置输出格式。如果未调用，默认为 JPEG。
      Parameters:
      formats - the output formats | 输出格式
      Returns:
      this builder for chaining | 用于链式调用的构建器

    • quality

      public ResponsiveBuilder quality(float quality)
      Set the compression quality. 设置压缩质量。
      Parameters:
      quality - quality from 0.0 to 1.0 (default 0.85) | 质量（0.0 到 1.0，默认 0.85）
      Returns:
      this builder for chaining | 用于链式调用的构建器
      Throws:
      IllegalArgumentException - if quality is out of range | 如果质量超出范围

    • generate

      public List<ResponsiveBuilder.GenerateResult> generate(Path outputDir) throws ImageIOException
      Generate all variant/format combinations and write them to the output directory. 生成所有变体/格式组合并写入输出目录。

      Output filenames follow the pattern: {variantName}.{formatExtension}

      输出文件名遵循以下模式：{变体名称}.{格式扩展名}

      Parameters:
      outputDir - the output directory | 输出目录
      Returns:
      list of generation results | 生成结果列表
      Throws:
      IllegalStateException - if no variants are configured | 如果未配置变体
      ImageIOException - if image processing fails | 如果图片处理失败

    • batch

      public static ResponsiveBuilder.BatchBuilder batch(List<Path> sources)
      Create a batch builder for processing multiple source images. 创建用于处理多个源图片的批量构建器。
      Parameters:
      sources - the list of source image paths | 源图片路径列表
      Returns:
      a new batch builder | 新的批量构建器

    • generateRasters

      public Map<String,Raster> generateRasters(Raster source)
      Generate one resized Raster per configured variant from a source Raster. The returned map preserves declaration order and uses the variant name as key. 从源 Raster 为每个已配置变体生成一份缩放后的 Raster。 返回的 Map 保留声明顺序，以变体名为键。

      Format/encoding/IO are out of scope here — callers control those by encoding the produced Rasters downstream (e.g. OpenImage.write(Raster, Path, ImageFormat)).

      编码与 IO 不在本方法范围内——调用方可对生成的 Raster 在下游做编码 （如 OpenImage.write(Raster, Path, ImageFormat)）。

      Parameters:
      source - the source raster | 源 raster
      Returns:
      ordered map of variant name → resized raster | 按声明顺序的变体名 → 结果 raster
      Throws:
      NullPointerException - if source is null | source 为 null 时抛出
      IllegalStateException - if no variants configured | 未配置变体时抛出
      Since:
      opencode-base-image V1.0.4