Class ImageStitch

java.lang.Object
cloud.opencode.base.image.ImageStitch
public final class ImageStitch extends Object
Image Stitching Utility 图片拼接工具类

Provides static methods for stitching multiple images together horizontally, vertically, or in a grid layout.

提供静态方法用于将多张图片水平拼接、垂直拼接或按网格排列。

Features | 主要功能:

  • Horizontal stitching with auto vertical centering - 水平拼接，自动垂直居中
  • Vertical stitching with auto horizontal centering - 垂直拼接，自动水平居中
  • Grid layout stitching by column count - 按列数网格拼接
  • Gap and background color support - 支持间距和背景色

Usage Examples | 使用示例:

// Horizontal stitch
BufferedImage result = ImageStitch.horizontal(img1, img2, img3);

// Vertical stitch with gap
BufferedImage result = ImageStitch.vertical(10, Color.WHITE, img1, img2);

// Grid layout
BufferedImage result = ImageStitch.grid(List.of(img1, img2, img3, img4), 2);

Security | 安全性:

  • Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具）
  • Null-safe: No (throws on null input) - 空值安全: 否（null 输入抛异常）
Since:
JDK 25, opencode-base-image V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • horizontal

      public static BufferedImage horizontal(BufferedImage... images)
      Stitch images horizontally; height is the maximum, smaller images are vertically centered 水平拼接图片；高度取最大值，较小的图片垂直居中
      Parameters:
      images - the images to stitch | 要拼接的图片
      Returns:
      the stitched image | 拼接后的图片
      Throws:
      IllegalArgumentException - if images is null or empty | 如果图片数组为 null 或空

    • horizontal

      public static BufferedImage horizontal(int gap, Color bgColor, BufferedImage... images)
      Stitch images horizontally with gap and background color 水平拼接图片，带间距和背景色
      Parameters:
      gap - the gap between images in pixels | 图片之间的间距（像素）
      bgColor - the background color for gaps and padding (null for transparent) | 间距和边距的背景色（null 表示透明）
      images - the images to stitch | 要拼接的图片
      Returns:
      the stitched image | 拼接后的图片
      Throws:
      IllegalArgumentException - if images is null or empty, or gap is negative | 如果图片为 null/空或间距为负

    • vertical

      public static BufferedImage vertical(BufferedImage... images)
      Stitch images vertically; width is the maximum, smaller images are horizontally centered 垂直拼接图片；宽度取最大值，较小的图片水平居中
      Parameters:
      images - the images to stitch | 要拼接的图片
      Returns:
      the stitched image | 拼接后的图片
      Throws:
      IllegalArgumentException - if images is null or empty | 如果图片数组为 null 或空

    • vertical

      public static BufferedImage vertical(int gap, Color bgColor, BufferedImage... images)
      Stitch images vertically with gap and background color 垂直拼接图片，带间距和背景色
      Parameters:
      gap - the gap between images in pixels | 图片之间的间距（像素）
      bgColor - the background color for gaps and padding (null for transparent) | 间距和边距的背景色（null 表示透明）
      images - the images to stitch | 要拼接的图片
      Returns:
      the stitched image | 拼接后的图片
      Throws:
      IllegalArgumentException - if images is null or empty, or gap is negative | 如果图片为 null/空或间距为负

    • grid

      public static BufferedImage grid(List<BufferedImage> images, int columns)
      Stitch images in a grid layout with the specified number of columns 按指定列数网格拼接图片，自动计算行数

      Cell size is determined by the maximum width and height across all images. Each image is centered within its cell.

      单元格尺寸由所有图片中的最大宽度和最大高度决定。每张图片在其单元格内居中。

      Parameters:
      images - the images to stitch | 要拼接的图片
      columns - the number of columns | 列数
      Returns:
      the stitched image | 拼接后的图片
      Throws:
      IllegalArgumentException - if images is null or empty, or columns < 1 | 如果图片为 null/空或列数小于 1