Class Image

java.lang.Object
cloud.opencode.base.image.Image
public class Image extends Object
Image 图片处理包装类

Chainable image processing wrapper with fluent API.

支持链式调用的图片处理包装类。

Usage Examples | 使用示例:

// Chain operations
Image.from(path)
    .resize(800, 600)
    .rotate(90)
    .watermark(TextWatermark.of("Copyright"))
    .save(outputPath);

// Get bytes
byte[] bytes = Image.from(inputStream)
    .crop(100, 100, 400, 300)
    .toBytes(ImageFormat.PNG);

Features | 主要功能:

  • Chainable fluent API for image operations - 可链式调用的流式图片操作 API
  • Resize, crop, rotate, watermark operations - 缩放、裁剪、旋转、水印操作
  • Save to file or convert to byte array - 保存到文件或转换为字节数组
  • Multiple format support (JPEG, PNG, GIF, BMP) - 多格式支持（JPEG、PNG、GIF、BMP）

Security | 安全性:

  • Thread-safe: No (mutable internal state) - 线程安全: 否（可变内部状态）
  • Null-safe: No (throws on null image) - 空值安全: 否（null 图片抛异常）
Since:
JDK 25, opencode-base-image V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • Image

      public Image(BufferedImage image)
      Create image wrapper 创建图片包装器
      Parameters:
      image - the buffered image | 缓冲图片

    • Image

      public Image(BufferedImage image, ImageFormat format)
      Create image wrapper with format 创建带格式的图片包装器
      Parameters:
      image - the buffered image | 缓冲图片
      format - the image format | 图片格式

  • Method Details

    • from

      public static Image from(Path path) throws ImageIOException
      Create image from path 从路径创建图片
      Parameters:
      path - the image path | 图片路径
      Returns:
      the image wrapper | 图片包装器
      Throws:
      ImageIOException - if reading fails | 如果读取失败

    • from

      public static Image from(byte[] bytes) throws ImageIOException
      Create image from bytes 从字节数组创建图片
      Parameters:
      bytes - the image bytes | 图片字节数组
      Returns:
      the image wrapper | 图片包装器
      Throws:
      ImageIOException - if reading fails | 如果读取失败

    • from

      public static Image from(BufferedImage image)
      Create image from BufferedImage 从BufferedImage创建图片
      Parameters:
      image - the buffered image | 缓冲图片
      Returns:
      the image wrapper | 图片包装器

    • getBufferedImage

      public BufferedImage getBufferedImage()
      Get the underlying BufferedImage 获取底层BufferedImage

      Warning: Returns the internal mutable reference. Modifications to the returned BufferedImage will affect this Image instance. Use copyBufferedImage() if you need an independent copy.

      警告：返回内部可变引用。对返回的BufferedImage的修改将影响此Image实例。 如果需要独立副本，请使用 copyBufferedImage()。

      Returns:
      the buffered image (mutable reference) | 缓冲图片（可变引用）

    • copyBufferedImage

      public BufferedImage copyBufferedImage()
      Get a copy of the underlying BufferedImage 获取底层BufferedImage的副本

      Returns an independent copy that can be modified without affecting this Image instance.

      返回一个可以修改而不影响此Image实例的独立副本。

      Returns:
      a copy of the buffered image | 缓冲图片的副本

    • getFormat

      public ImageFormat getFormat()
      Get the image format 获取图片格式
      Returns:
      the format | 格式

    • format

      public Image format(ImageFormat format)
      Set the image format 设置图片格式
      Parameters:
      format - the format | 格式
      Returns:
      this image for chaining | 用于链式调用的图片

    • getWidth

      public int getWidth()
      Get image width 获取图片宽度
      Returns:
      the width in pixels | 宽度（像素）

    • getHeight

      public int getHeight()
      Get image height 获取图片高度
      Returns:
      the height in pixels | 高度（像素）

    • getInfo

      public ImageInfo getInfo()
      Get image info 获取图片信息
      Returns:
      the image info | 图片信息

    • resize

      public Image resize(int width, int height)
      Resize to exact dimensions 调整到精确尺寸
      Parameters:
      width - target width | 目标宽度
      height - target height | 目标高度
      Returns:
      this image for chaining | 用于链式调用的图片

    • resizeToFit

      public Image resizeToFit(int maxWidth, int maxHeight)
      Resize maintaining aspect ratio 保持宽高比调整尺寸
      Parameters:
      maxWidth - maximum width | 最大宽度
      maxHeight - maximum height | 最大高度
      Returns:
      this image for chaining | 用于链式调用的图片

    • scale

      public Image scale(double scale)
      Scale by percentage 按百分比缩放
      Parameters:
      scale - scale factor (e.g., 0.5 for 50%) | 缩放因子（如0.5表示50%）
      Returns:
      this image for chaining | 用于链式调用的图片

    • scaleToWidth

      public Image scaleToWidth(int width)
      Scale to fit width 缩放以适应宽度
      Parameters:
      width - target width | 目标宽度
      Returns:
      this image for chaining | 用于链式调用的图片

    • scaleToHeight

      public Image scaleToHeight(int height)
      Scale to fit height 缩放以适应高度
      Parameters:
      height - target height | 目标高度
      Returns:
      this image for chaining | 用于链式调用的图片

    • crop

      public Image crop(int x, int y, int width, int height)
      Crop to specified region 裁剪到指定区域
      Parameters:
      x - the x coordinate | X坐标
      y - the y coordinate | Y坐标
      width - the crop width | 裁剪宽度
      height - the crop height | 裁剪高度
      Returns:
      this image for chaining | 用于链式调用的图片

    • cropCenter

      public Image cropCenter(int width, int height)
      Crop from center 从中心裁剪
      Parameters:
      width - the crop width | 裁剪宽度
      height - the crop height | 裁剪高度
      Returns:
      this image for chaining | 用于链式调用的图片

    • cropSquare

      public Image cropSquare()
      Crop to square from center 从中心裁剪为正方形
      Returns:
      this image for chaining | 用于链式调用的图片

    • rotate

      public Image rotate(double degrees)
      Rotate by degrees 按角度旋转
      Parameters:
      degrees - rotation degrees | 旋转角度
      Returns:
      this image for chaining | 用于链式调用的图片

    • rotate90

      public Image rotate90()
      Rotate 90 degrees clockwise 顺时针旋转90度
      Returns:
      this image for chaining | 用于链式调用的图片

    • rotate180

      public Image rotate180()
      Rotate 180 degrees 旋转180度
      Returns:
      this image for chaining | 用于链式调用的图片

    • rotate270

      public Image rotate270()
      Rotate 270 degrees (90 counter-clockwise) 旋转270度（逆时针90度）
      Returns:
      this image for chaining | 用于链式调用的图片

    • flipHorizontal

      public Image flipHorizontal()
      Flip horizontally 水平翻转
      Returns:
      this image for chaining | 用于链式调用的图片

    • flipVertical

      public Image flipVertical()
      Flip vertically 垂直翻转
      Returns:
      this image for chaining | 用于链式调用的图片

    • watermark

      public Image watermark(TextWatermark watermark)
      Add text watermark 添加文字水印
      Parameters:
      watermark - the text watermark | 文字水印
      Returns:
      this image for chaining | 用于链式调用的图片

    • watermark

      public Image watermark(String text, Position position)
      Add text watermark at position 在指定位置添加文字水印
      Parameters:
      text - the watermark text | 水印文字
      position - the position | 位置
      Returns:
      this image for chaining | 用于链式调用的图片

    • watermark

      public Image watermark(ImageWatermark watermark)
      Add image watermark 添加图片水印
      Parameters:
      watermark - the image watermark | 图片水印
      Returns:
      this image for chaining | 用于链式调用的图片

    • watermark

      public Image watermark(BufferedImage watermarkImage, Position position)
      Add image watermark at position 在指定位置添加图片水印
      Parameters:
      watermarkImage - the watermark image | 水印图片
      position - the position | 位置
      Returns:
      this image for chaining | 用于链式调用的图片

    • compress

      public Image compress(float quality)
      Compress image with quality 按质量压缩图片
      Parameters:
      quality - quality from 0.0 to 1.0 | 质量（0.0到1.0）
      Returns:
      this image for chaining | 用于链式调用的图片

    • convert

      public Image convert(ImageFormat targetFormat)
      Convert to specified format 转换到指定格式
      Parameters:
      targetFormat - the target format | 目标格式
      Returns:
      this image for chaining | 用于链式调用的图片

    • grayscale

      public Image grayscale()
      Convert to grayscale 转换为灰度图
      Returns:
      this image for chaining | 用于链式调用的图片

    • save

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

    • save

      public void save(Path path, ImageFormat format) throws ImageWriteException
      Save to path with format 保存到路径（指定格式）
      Parameters:
      path - the output path | 输出路径
      format - the image format | 图片格式
      Throws:
      ImageWriteException - if writing fails | 如果写入失败

    • writeTo

      public void writeTo(OutputStream out) throws ImageWriteException
      Write to output stream 写入输出流
      Parameters:
      out - the output stream | 输出流
      Throws:
      ImageWriteException - if writing fails | 如果写入失败

    • writeTo

      public void writeTo(OutputStream out, ImageFormat format) throws ImageWriteException
      Write to output stream with format 写入输出流（指定格式）
      Parameters:
      out - the output stream | 输出流
      format - the image format | 图片格式
      Throws:
      ImageWriteException - if writing fails | 如果写入失败

    • toBytes

      public byte[] toBytes() throws ImageOperationException
      Convert to byte array 转换为字节数组
      Returns:
      the byte array | 字节数组
      Throws:
      ImageOperationException - if conversion fails | 如果转换失败

    • toBytes

      public byte[] toBytes(ImageFormat format) throws ImageOperationException
      Convert to byte array with format 转换为字节数组（指定格式）
      Parameters:
      format - the image format | 图片格式
      Returns:
      the byte array | 字节数组
      Throws:
      ImageOperationException - if conversion fails | 如果转换失败

    • toBase64

      public String toBase64() throws ImageOperationException
      Convert to Base64 string 转换为Base64字符串
      Returns:
      the Base64 encoded string | Base64编码字符串
      Throws:
      ImageOperationException - if conversion fails | 如果转换失败

    • toBase64

      public String toBase64(ImageFormat format) throws ImageOperationException
      Convert to Base64 string with format 转换为Base64字符串（指定格式）
      Parameters:
      format - the image format | 图片格式
      Returns:
      the Base64 encoded string | Base64编码字符串
      Throws:
      ImageOperationException - if conversion fails | 如果转换失败

    • copy

      public Image copy()
      Create a copy of this image 创建此图片的副本
      Returns:
      a new Image instance | 新的Image实例