Class Image

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

Chainable Raster-based image processing wrapper with fluent API. Backed by an internal mutable Raster; each operation replaces the raster with the result of the corresponding apply(Raster, ...) operator.

基于 Raster 的链式图像处理包装，内部持有可变 Raster；每个操作 都会用相应 apply(Raster, ...) 算子的结果替换它。

Usage Examples | 使用示例:

// Chain operations
Image.from(path)
    .resize(800, 600)
    .rotate(90)
    .save(outputPath);

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

Features | 主要功能:

  • Chainable fluent API for Raster operations - 基于 Raster 的链式 API
  • Resize, crop, rotate, color, blur, edge, threshold, histogram - 多类操作
  • Save to file or convert to byte array - 保存或转字节

Security | 安全性:

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

  • Constructor Summary

    Constructors
    Constructor
    Description
    Image(Raster raster)
    Create image wrapper from a Raster.
    Image(Raster raster, ImageFormat format)
    Create image wrapper with explicit format.

  • Method Summary

    Modifier and Type
    Method
    Description
    Image
    adaptiveThreshold(int blockSize, double c)
    Adaptive threshold. | 自适应阈值。
    Image
    autoOrient(int orientation)
    Auto-orient by EXIF orientation tag. | 按 EXIF orientation 自动正向。
    Image
    bilateralFilter()
    Bilateral filter. | 双边滤波。
    Image
    border(int thickness, int colorArgb)
    Draw a solid border of the given color. | 绘制纯色边框。
    Image
    boxBlur(int kernelSize)
    Box (mean) blur. | 均值模糊。
    Image
    brightness(double factor)
    Brightness. | 亮度。
    Image
    cannyEdge(double lowThreshold, double highThreshold)
    Canny edge detection. | Canny 边缘检测。
    Image
    clahe(double clipLimit, int tileGridSize)
    CLAHE histogram equalization. | CLAHE 直方图均衡化。
    Image
    compress(float quality)
    Compress (JPEG path). | JPEG 压缩。
    Image
    contrast(double factor)
    Contrast. | 对比度。
    Image
    convert(ImageFormat targetFormat)
    Convert pixel layout to suit the target format (e.g. drop alpha for JPEG).
    Image
    copy()
    Make a deep copy. | 深拷贝。
    Image
    crop(int x, int y, int width, int height)
    Crop to rectangle. | 裁剪到矩形。
    Image
    cropCenter(int width, int height)
    Crop centered to (width, height). | 居中裁剪。
    Image
    cropSquare()
    Crop to a centered square. | 裁剪为居中正方形。
    Image
    cropToAspectRatio(int aspectWidth, int aspectHeight)
    Crop to a target aspect ratio centered. | 裁剪为目标宽高比（居中）。
    Image
    equalizeHistogram()
    Histogram equalization. | 直方图均衡化。
    Image
    flipHorizontal()
    Flip horizontally. | 水平翻转。
    Image
    flipVertical()
    Flip vertically. | 垂直翻转。
    Image
    format(ImageFormat format)
    Set image format 设置图片格式
    static Image
    from(byte[] bytes)
    Create image from byte array 从字节数组创建图片
    static Image
    from(Path path)
    Create image from path 从路径创建图片
    static Image
    fromRaster(Raster raster)
    Build an Image that wraps the given Raster.
    static Image
    fromRaster(Raster raster, ImageFormat format)
    Build an Image that wraps the given Raster with format.
    Image
    gamma(double gamma)
    Gamma correction. | 伽马校正。
    Image
    gaussianBlur(double sigma)
    Gaussian blur. | 高斯模糊。
    ImageFormat
    getFormat()
    Get image format 获取图片格式
    int
    getHeight()
    Get image height 获取图片高度
    ImageInfo
    getInfo()
    Get image info 获取图片信息
    int
    getWidth()
    Get image width 获取图片宽度
    Image
    grayscale()
    Convert to grayscale. | 转灰度。
    Image
    invert()
    Invert colors. | 反色。
    Image
    medianBlur(int kernelSize)
    Median blur. | 中值模糊。
    Image
    otsuThreshold()
    Otsu's automatic threshold. | 大津法自动阈值。
    Image
    pad(int padding, int colorArgb)
    Pad uniformly with the given ARGB color. | 用 ARGB 颜色等距填充。
    Image
    pad(int top, int right, int bottom, int left, int colorArgb)
    Pad with explicit insets. | 按指定内边距填充。
    Image
    resize(int width, int height)
    Resize to exact dimensions. | 缩放到指定尺寸。
    Image
    resizeProgressive(int width, int height)
    Progressive resize for higher quality on large downscale. | 大幅缩小时使用渐进缩放保留质量。
    Image
    resizeToFit(int maxWidth, int maxHeight)
    Resize to fit within (maxWidth, maxHeight) preserving aspect ratio. | 等比缩放到 (maxWidth, maxHeight) 内。
    Image
    rotate(double degrees)
    Rotate by arbitrary angle (degrees, around center). | 任意角度旋转（绕中心，单位度）。
    Image
    rotate180()
    Rotate 180 degrees. | 旋转 180°。
    Image
    rotate270()
    Rotate 270 degrees clockwise. | 顺时针旋转 270°。
    Image
    rotate90()
    Rotate 90 degrees clockwise. | 顺时针旋转 90°。
    Image
    saturation(double factor)
    Saturation. | 饱和度。
    void
    save(Path path)
    Save to path inferring format from extension. | 按扩展名保存到路径。
    void
    save(Path path, ImageFormat format)
    Save to path with explicit format. | 以指定格式保存到路径。
    Image
    scale(double scale)
    Scale by uniform factor. | 按统一系数缩放。
    Image
    scaleToHeight(int height)
    Scale to a target height (preserve aspect). | 缩放到目标高度（保持比例）。
    Image
    scaleToWidth(int width)
    Scale to a target width (preserve aspect). | 缩放到目标宽度（保持比例）。
    Image
    sepia()
    Sepia tone. | 棕褐色调。
    Image
    sharpen()
    Sharpen with default amount. | 默认强度锐化。
    Image
    sharpen(double amount)
    Sharpen with the given amount. | 指定强度锐化。
    Image
    sobelEdge()
    Sobel edge detection. | Sobel 边缘检测。
    Image
    stripExif(ExifTag... tags)
    No-op stub for legacy EXIF strip API.
    Image
    threshold(int value)
    Fixed threshold. | 固定阈值。
    String
    toBase64()
    Encode to Base64 using current format. | 以当前格式编码为 Base64。
    String
    toBase64(ImageFormat format)
    Encode to Base64 with explicit format. | 以指定格式编码为 Base64。
    byte[]
    toBytes()
    Encode to bytes using current format. | 以当前格式编码为字节。
    byte[]
    toBytes(ImageFormat format)
    Encode to bytes with explicit format. | 以指定格式编码为字节。
    Raster
    toRaster()
    Get the underlying Raster.
    Image
    whiteBalance()
    Auto white balance (gray world). | 灰度世界白平衡。
    void
    writeTo(OutputStream out)
    Write to output stream using current format. | 用当前格式写入输出流。
    void
    writeTo(OutputStream out, ImageFormat format)
    Write to output stream with explicit format. | 以指定格式写入输出流。

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Image

      public Image(Raster raster)
      Create image wrapper from a Raster. 由 Raster 创建图像包装。
      Parameters:
      raster - the raster | raster

    • Image

      public Image(Raster raster, ImageFormat format)
      Create image wrapper with explicit format. 创建带显式格式的图像包装。
      Parameters:
      raster - the raster | raster
      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 byte array 从字节数组创建图片
      Parameters:
      bytes - the image bytes | 图片字节数组
      Returns:
      the image wrapper | 图片包装器
      Throws:
      ImageIOException - if reading fails | 如果读取失败

    • fromRaster

      public static Image fromRaster(Raster raster)
      Build an Image that wraps the given Raster. 构造包装给定 Raster 的 Image。
      Parameters:
      raster - source raster | 源 raster
      Returns:
      the wrapper | 包装器
      Since:
      opencode-base-image V1.0.4

    • fromRaster

      public static Image fromRaster(Raster raster, ImageFormat format)
      Build an Image that wraps the given Raster with format. 构造包装给定 Raster 与格式的 Image。
      Parameters:
      raster - source raster | 源 raster
      format - target format | 目标格式
      Returns:
      the wrapper | 包装器
      Since:
      opencode-base-image V1.0.4

    • toRaster

      public Raster toRaster()
      Get the underlying Raster. 返回底层 Raster。
      Returns:
      the raster | raster
      Since:
      opencode-base-image V1.0.4

    • getFormat

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

    • format

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

    • getWidth

      public int getWidth()
      Get image width 获取图片宽度
      Returns:
      the width | 宽度

    • getHeight

      public int getHeight()
      Get image height 获取图片高度
      Returns:
      the height | 高度

    • getInfo

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

    • resize

      public Image resize(int width, int height)
      Resize to exact dimensions. | 缩放到指定尺寸。

    • resizeToFit

      public Image resizeToFit(int maxWidth, int maxHeight)
      Resize to fit within (maxWidth, maxHeight) preserving aspect ratio. | 等比缩放到 (maxWidth, maxHeight) 内。

    • scale

      public Image scale(double scale)
      Scale by uniform factor. | 按统一系数缩放。

    • scaleToWidth

      public Image scaleToWidth(int width)
      Scale to a target width (preserve aspect). | 缩放到目标宽度（保持比例）。

    • resizeProgressive

      public Image resizeProgressive(int width, int height)
      Progressive resize for higher quality on large downscale. | 大幅缩小时使用渐进缩放保留质量。

    • scaleToHeight

      public Image scaleToHeight(int height)
      Scale to a target height (preserve aspect). | 缩放到目标高度（保持比例）。

    • crop

      public Image crop(int x, int y, int width, int height)
      Crop to rectangle. | 裁剪到矩形。

    • cropCenter

      public Image cropCenter(int width, int height)
      Crop centered to (width, height). | 居中裁剪。

    • cropSquare

      public Image cropSquare()
      Crop to a centered square. | 裁剪为居中正方形。

    • cropToAspectRatio

      public Image cropToAspectRatio(int aspectWidth, int aspectHeight)
      Crop to a target aspect ratio centered. | 裁剪为目标宽高比（居中）。

    • rotate

      public Image rotate(double degrees)
      Rotate by arbitrary angle (degrees, around center). | 任意角度旋转（绕中心，单位度）。

    • rotate90

      public Image rotate90()
      Rotate 90 degrees clockwise. | 顺时针旋转 90°。

    • rotate180

      public Image rotate180()
      Rotate 180 degrees. | 旋转 180°。

    • rotate270

      public Image rotate270()
      Rotate 270 degrees clockwise. | 顺时针旋转 270°。

    • flipHorizontal

      public Image flipHorizontal()
      Flip horizontally. | 水平翻转。

    • flipVertical

      public Image flipVertical()
      Flip vertically. | 垂直翻转。

    • pad

      public Image pad(int padding, int colorArgb)
      Pad uniformly with the given ARGB color. | 用 ARGB 颜色等距填充。

    • pad

      public Image pad(int top, int right, int bottom, int left, int colorArgb)
      Pad with explicit insets. | 按指定内边距填充。

    • border

      public Image border(int thickness, int colorArgb)
      Draw a solid border of the given color. | 绘制纯色边框。

    • compress

      public Image compress(float quality)
      Compress (JPEG path). | JPEG 压缩。

    • convert

      public Image convert(ImageFormat targetFormat)
      Convert pixel layout to suit the target format (e.g. drop alpha for JPEG).

    • grayscale

      public Image grayscale()
      Convert to grayscale. | 转灰度。

    • gaussianBlur

      public Image gaussianBlur(double sigma)
      Gaussian blur. | 高斯模糊。

    • medianBlur

      public Image medianBlur(int kernelSize)
      Median blur. | 中值模糊。

    • boxBlur

      public Image boxBlur(int kernelSize)
      Box (mean) blur. | 均值模糊。

    • sharpen

      public Image sharpen()
      Sharpen with default amount. | 默认强度锐化。

    • sharpen

      public Image sharpen(double amount)
      Sharpen with the given amount. | 指定强度锐化。

    • bilateralFilter

      public Image bilateralFilter()
      Bilateral filter. | 双边滤波。

    • gamma

      public Image gamma(double gamma)
      Gamma correction. | 伽马校正。

    • saturation

      public Image saturation(double factor)
      Saturation. | 饱和度。

    • whiteBalance

      public Image whiteBalance()
      Auto white balance (gray world). | 灰度世界白平衡。

    • brightness

      public Image brightness(double factor)
      Brightness. | 亮度。

    • contrast

      public Image contrast(double factor)
      Contrast. | 对比度。

    • sepia

      public Image sepia()
      Sepia tone. | 棕褐色调。

    • invert

      public Image invert()
      Invert colors. | 反色。

    • sobelEdge

      public Image sobelEdge()
      Sobel edge detection. | Sobel 边缘检测。

    • cannyEdge

      public Image cannyEdge(double lowThreshold, double highThreshold)
      Canny edge detection. | Canny 边缘检测。

    • threshold

      public Image threshold(int value)
      Fixed threshold. | 固定阈值。

    • otsuThreshold

      public Image otsuThreshold()
      Otsu's automatic threshold. | 大津法自动阈值。

    • adaptiveThreshold

      public Image adaptiveThreshold(int blockSize, double c)
      Adaptive threshold. | 自适应阈值。

    • equalizeHistogram

      public Image equalizeHistogram()
      Histogram equalization. | 直方图均衡化。

    • clahe

      public Image clahe(double clipLimit, int tileGridSize)
      CLAHE histogram equalization. | CLAHE 直方图均衡化。

    • autoOrient

      public Image autoOrient(int orientation)
      Auto-orient by EXIF orientation tag. | 按 EXIF orientation 自动正向。

    • stripExif

      public Image stripExif(ExifTag... tags)
      No-op stub for legacy EXIF strip API. 旧版 stripExif 兼容空实现。

      EXIF metadata is not embedded in the Raster pipeline — encoded outputs from OpenImage.write(Raster, Path) carry no EXIF, so stripping is implicit. This method exists only for fluent compatibility.

      Raster 管线不携带 EXIF 元数据 —— OpenImage.write(Raster, Path) 输出本身就不含 EXIF，无需剥离。本方法仅为流式 API 兼容保留。

      Parameters:
      tags - ignored | 忽略
      Returns:
      this image | 当前图片

    • save

      public void save(Path path) throws ImageWriteException
      Save to path inferring format from extension. | 按扩展名保存到路径。
      Throws:
      ImageWriteException

    • save

      public void save(Path path, ImageFormat format) throws ImageWriteException
      Save to path with explicit format. | 以指定格式保存到路径。
      Throws:
      ImageWriteException

    • writeTo

      public void writeTo(OutputStream out) throws ImageWriteException
      Write to output stream using current format. | 用当前格式写入输出流。
      Throws:
      ImageWriteException

    • writeTo

      public void writeTo(OutputStream out, ImageFormat format) throws ImageWriteException
      Write to output stream with explicit format. | 以指定格式写入输出流。
      Throws:
      ImageWriteException

    • toBytes

      public byte[] toBytes() throws ImageOperationException
      Encode to bytes using current format. | 以当前格式编码为字节。
      Throws:
      ImageOperationException

    • toBytes

      public byte[] toBytes(ImageFormat format) throws ImageOperationException
      Encode to bytes with explicit format. | 以指定格式编码为字节。
      Throws:
      ImageOperationException

    • toBase64

      public String toBase64() throws ImageOperationException
      Encode to Base64 using current format. | 以当前格式编码为 Base64。
      Throws:
      ImageOperationException

    • toBase64

      public String toBase64(ImageFormat format) throws ImageOperationException
      Encode to Base64 with explicit format. | 以指定格式编码为 Base64。
      Throws:
      ImageOperationException

    • copy

      public Image copy()
      Make a deep copy. | 深拷贝。