Class Image
java.lang.Object
cloud.opencode.base.image.Image
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 Summary
ConstructorsConstructorDescriptionImage(BufferedImage image) Create image wrapper 创建图片包装器Image(BufferedImage image, ImageFormat format) Create image wrapper with format 创建带格式的图片包装器 -
Method Summary
Modifier and TypeMethodDescriptionadaptiveThreshold(int blockSize, double c) Apply adaptive threshold (MEAN method) 应用自适应阈值(均值方法)autoOrient(int orientation) Auto-orient based on EXIF orientation 根据 EXIF 方向信息自动旋转Apply bilateral filter with default parameters 应用双边滤波,使用默认参数Add a border around the image 在图片外部添加边框boxBlur(int kernelSize) Apply box blur 应用方框模糊brightness(double factor) Adjust brightness 调整亮度cannyEdge(double lowThreshold, double highThreshold) Apply Canny edge detection 应用 Canny 边缘检测clahe(double clipLimit, int tileGridSize) Apply CLAHE (Contrast Limited Adaptive Histogram Equalization) 应用 CLAHE 自适应局部直方图均衡化compress(float quality) Compress image with quality 按质量压缩图片contrast(double factor) Adjust contrast 调整对比度convert(ImageFormat targetFormat) Convert to specified format 转换到指定格式copy()Create a copy of this image 创建此图片的副本Get a copy of the underlying BufferedImage 获取底层BufferedImage的副本crop(int x, int y, int width, int height) Crop to specified region 裁剪到指定区域cropCenter(int width, int height) Crop from center 从中心裁剪Crop to square from center 从中心裁剪为正方形cropToAspectRatio(int aspectWidth, int aspectHeight) Crop to a specific aspect ratio from center 从中心按指定宽高比裁剪Apply histogram equalization 应用直方图均衡化Flip horizontally 水平翻转Flip vertically 垂直翻转format(ImageFormat format) Set the image format 设置图片格式static Imagefrom(byte[] bytes) Create image from bytes 从字节数组创建图片static Imagefrom(BufferedImage image) Create image from BufferedImage 从BufferedImage创建图片static ImageCreate image from path 从路径创建图片gamma(double gamma) Apply gamma correction 应用伽马校正gaussianBlur(double sigma) Apply Gaussian blur 应用高斯模糊Get the underlying BufferedImage 获取底层BufferedImageGet the image format 获取图片格式intGet image height 获取图片高度getInfo()Get image info 获取图片信息intgetWidth()Get image width 获取图片宽度Convert to grayscale 转换为灰度图invert()Apply color inversion filter 应用反色滤镜medianBlur(int kernelSize) Apply median blur 应用中值滤波Apply Otsu automatic thresholding 应用 Otsu 自动阈值overlay(BufferedImage overlay, int x, int y, float opacity) Overlay another image at the specified position and opacity 在指定位置以指定透明度叠加另一张图片Add independent padding for each edge of the image 为图片的每条边添加独立的内边距Add uniform padding around the image 在图片四周添加等距内边距resize(int width, int height) Resize to exact dimensions 调整到精确尺寸resizeProgressive(int width, int height) Resize using progressive multi-step downscaling for better quality on large reductions 使用渐进式多步缩小,在大幅缩小时获得更好的质量resizeToFit(int maxWidth, int maxHeight) Resize maintaining aspect ratio 保持宽高比调整尺寸rotate(double degrees) Rotate by degrees 按角度旋转Rotate 180 degrees 旋转180度Rotate 270 degrees (90 counter-clockwise) 旋转270度(逆时针90度)rotate90()Rotate 90 degrees clockwise 顺时针旋转90度saturation(double factor) Adjust saturation 调整饱和度voidSave to path 保存到路径voidsave(Path path, ImageFormat format) Save to path with format 保存到路径(指定格式)scale(double scale) Scale by percentage 按百分比缩放scaleToHeight(int height) Scale to fit height 缩放以适应高度scaleToWidth(int width) Scale to fit width 缩放以适应宽度sepia()Apply sepia (nostalgic brown tone) filter 应用怀旧棕褐色滤镜sharpen()Apply sharpening (Unsharp Mask) with default parameters 应用锐化(非锐化掩模),使用默认参数sharpen(double amount) Apply sharpening (Unsharp Mask) with custom amount 应用锐化(非锐化掩模),自定义强度Apply Sobel edge detection 应用 Sobel 边缘检测Strip EXIF tags (operates on byte-level, re-encodes image) 清除 EXIF 标签(字节级操作,重新编码图像)threshold(int value) Apply fixed threshold (binary mode) 应用固定阈值(二值模式)tiledWatermark(TextWatermark watermark, int spacingX, int spacingY) Add tiled text watermark across the image 在图片上平铺文字水印toBase64()Convert to Base64 string 转换为Base64字符串toBase64(ImageFormat format) Convert to Base64 string with format 转换为Base64字符串(指定格式)byte[]toBytes()Convert to byte array 转换为字节数组byte[]toBytes(ImageFormat format) Convert to byte array with format 转换为字节数组(指定格式)watermark(ImageWatermark watermark) Add image watermark 添加图片水印watermark(TextWatermark watermark) Add text watermark 添加文字水印watermark(BufferedImage watermarkImage, Position position) Add image watermark at position 在指定位置添加图片水印Add text watermark at position 在指定位置添加文字水印Apply Gray World white balance 应用灰色世界白平衡voidwriteTo(OutputStream out) Write to output stream 写入输出流voidwriteTo(OutputStream out, ImageFormat format) Write to output stream with format 写入输出流(指定格式)
-
Constructor Details
-
Image
Create image wrapper 创建图片包装器- Parameters:
image- the buffered image | 缓冲图片
-
Image
Create image wrapper with format 创建带格式的图片包装器- Parameters:
image- the buffered image | 缓冲图片format- the image format | 图片格式
-
-
Method Details
-
from
Create image from path 从路径创建图片- Parameters:
path- the image path | 图片路径- Returns:
- the image wrapper | 图片包装器
- Throws:
ImageIOException- if reading fails | 如果读取失败
-
from
Create image from bytes 从字节数组创建图片- Parameters:
bytes- the image bytes | 图片字节数组- Returns:
- the image wrapper | 图片包装器
- Throws:
ImageIOException- if reading fails | 如果读取失败
-
from
Create image from BufferedImage 从BufferedImage创建图片- Parameters:
image- the buffered image | 缓冲图片- Returns:
- the image wrapper | 图片包装器
-
getBufferedImage
Get the underlying BufferedImage 获取底层BufferedImageWarning: 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
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
-
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
-
resize
Resize to exact dimensions 调整到精确尺寸- Parameters:
width- target width | 目标宽度height- target height | 目标高度- Returns:
- this image for chaining | 用于链式调用的图片
-
resizeToFit
Resize maintaining aspect ratio 保持宽高比调整尺寸- Parameters:
maxWidth- maximum width | 最大宽度maxHeight- maximum height | 最大高度- Returns:
- this image for chaining | 用于链式调用的图片
-
scale
Scale by percentage 按百分比缩放- Parameters:
scale- scale factor (e.g., 0.5 for 50%) | 缩放因子(如0.5表示50%)- Returns:
- this image for chaining | 用于链式调用的图片
-
scaleToWidth
Scale to fit width 缩放以适应宽度- Parameters:
width- target width | 目标宽度- Returns:
- this image for chaining | 用于链式调用的图片
-
resizeProgressive
Resize using progressive multi-step downscaling for better quality on large reductions 使用渐进式多步缩小,在大幅缩小时获得更好的质量- Parameters:
width- target width | 目标宽度height- target height | 目标高度- Returns:
- this image for chaining | 用于链式调用的图片
-
scaleToHeight
Scale to fit height 缩放以适应高度- Parameters:
height- target height | 目标高度- Returns:
- this image for chaining | 用于链式调用的图片
-
crop
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
Crop from center 从中心裁剪- Parameters:
width- the crop width | 裁剪宽度height- the crop height | 裁剪高度- Returns:
- this image for chaining | 用于链式调用的图片
-
cropSquare
Crop to square from center 从中心裁剪为正方形- Returns:
- this image for chaining | 用于链式调用的图片
-
cropToAspectRatio
Crop to a specific aspect ratio from center 从中心按指定宽高比裁剪- Parameters:
aspectWidth- aspect ratio width component | 宽高比的宽度分量aspectHeight- aspect ratio height component | 宽高比的高度分量- Returns:
- this image for chaining | 用于链式调用的图片
-
rotate
Rotate by degrees 按角度旋转- Parameters:
degrees- rotation degrees | 旋转角度- Returns:
- this image for chaining | 用于链式调用的图片
-
rotate90
Rotate 90 degrees clockwise 顺时针旋转90度- Returns:
- this image for chaining | 用于链式调用的图片
-
rotate180
-
rotate270
Rotate 270 degrees (90 counter-clockwise) 旋转270度(逆时针90度)- Returns:
- this image for chaining | 用于链式调用的图片
-
flipHorizontal
-
flipVertical
-
watermark
Add text watermark 添加文字水印- Parameters:
watermark- the text watermark | 文字水印- Returns:
- this image for chaining | 用于链式调用的图片
-
watermark
-
watermark
Add image watermark 添加图片水印- Parameters:
watermark- the image watermark | 图片水印- Returns:
- this image for chaining | 用于链式调用的图片
-
watermark
Add image watermark at position 在指定位置添加图片水印- Parameters:
watermarkImage- the watermark image | 水印图片position- the position | 位置- Returns:
- this image for chaining | 用于链式调用的图片
-
tiledWatermark
Add tiled text watermark across the image 在图片上平铺文字水印- Parameters:
watermark- the text watermark configuration | 文字水印配置spacingX- horizontal spacing between tiles | 水平方向瓦片间距spacingY- vertical spacing between tiles | 垂直方向瓦片间距- Returns:
- this image for chaining | 用于链式调用的图片
-
pad
-
pad
Add independent padding for each edge of the image 为图片的每条边添加独立的内边距- Parameters:
top- the top padding | 顶部内边距right- the right padding | 右侧内边距bottom- the bottom padding | 底部内边距left- the left padding | 左侧内边距color- the padding color | 内边距颜色- Returns:
- this image for chaining | 用于链式调用的图片
-
border
-
overlay
Overlay another image at the specified position and opacity 在指定位置以指定透明度叠加另一张图片- Parameters:
overlay- the image to overlay | 要叠加的图片x- the x position | X 坐标y- the y position | Y 坐标opacity- the opacity from 0.0 (transparent) to 1.0 (opaque) | 透明度(0.0 全透明,1.0 完全不透明)- Returns:
- this image for chaining | 用于链式调用的图片
-
compress
Compress image with quality 按质量压缩图片- Parameters:
quality- quality from 0.0 to 1.0 | 质量(0.0到1.0)- Returns:
- this image for chaining | 用于链式调用的图片
-
convert
Convert to specified format 转换到指定格式- Parameters:
targetFormat- the target format | 目标格式- Returns:
- this image for chaining | 用于链式调用的图片
-
grayscale
-
gaussianBlur
Apply Gaussian blur 应用高斯模糊- Parameters:
sigma- Gaussian sigma value | 高斯 sigma 值- Returns:
- this image for chaining | 用于链式调用的图片
-
medianBlur
Apply median blur 应用中值滤波- Parameters:
kernelSize- kernel size (must be odd) | 核大小(必须为奇数)- Returns:
- this image for chaining | 用于链式调用的图片
-
boxBlur
Apply box blur 应用方框模糊- Parameters:
kernelSize- kernel size (must be odd) | 核大小(必须为奇数)- Returns:
- this image for chaining | 用于链式调用的图片
-
sharpen
Apply sharpening (Unsharp Mask) with default parameters 应用锐化(非锐化掩模),使用默认参数- Returns:
- this image for chaining | 用于链式调用的图片
-
sharpen
Apply sharpening (Unsharp Mask) with custom amount 应用锐化(非锐化掩模),自定义强度- Parameters:
amount- sharpening amount | 锐化强度- Returns:
- this image for chaining | 用于链式调用的图片
-
bilateralFilter
Apply bilateral filter with default parameters 应用双边滤波,使用默认参数- Returns:
- this image for chaining | 用于链式调用的图片
-
gamma
Apply gamma correction 应用伽马校正- Parameters:
gamma- gamma value (must be positive) | 伽马值(必须为正数)- Returns:
- this image for chaining | 用于链式调用的图片
-
saturation
Adjust saturation 调整饱和度- Parameters:
factor- saturation factor (0.0=grayscale, 1.0=original, 2.0=double) | 饱和度因子- Returns:
- this image for chaining | 用于链式调用的图片
-
whiteBalance
Apply Gray World white balance 应用灰色世界白平衡- Returns:
- this image for chaining | 用于链式调用的图片
-
brightness
Adjust brightness 调整亮度- Parameters:
factor- brightness factor (>1 brighter, invalid input: '<'1 darker, 1 unchanged) | 亮度因子(>1 变亮,invalid input: '<'1 变暗,1 不变)- Returns:
- this image for chaining | 用于链式调用的图片
-
contrast
Adjust contrast 调整对比度- Parameters:
factor- contrast factor (>1 more contrast, invalid input: '<'1 less, 1 unchanged) | 对比度因子(>1 增加,invalid input: '<'1 降低,1 不变)- Returns:
- this image for chaining | 用于链式调用的图片
-
sepia
Apply sepia (nostalgic brown tone) filter 应用怀旧棕褐色滤镜- Returns:
- this image for chaining | 用于链式调用的图片
-
invert
Apply color inversion filter 应用反色滤镜- Returns:
- this image for chaining | 用于链式调用的图片
-
sobelEdge
Apply Sobel edge detection 应用 Sobel 边缘检测- Returns:
- this image for chaining | 用于链式调用的图片
-
cannyEdge
Apply Canny edge detection 应用 Canny 边缘检测- Parameters:
lowThreshold- low threshold | 低阈值highThreshold- high threshold | 高阈值- Returns:
- this image for chaining | 用于链式调用的图片
-
threshold
Apply fixed threshold (binary mode) 应用固定阈值(二值模式)- Parameters:
value- threshold value (0-255) | 阈值(0-255)- Returns:
- this image for chaining | 用于链式调用的图片
-
otsuThreshold
Apply Otsu automatic thresholding 应用 Otsu 自动阈值- Returns:
- this image for chaining | 用于链式调用的图片
-
adaptiveThreshold
Apply adaptive threshold (MEAN method) 应用自适应阈值(均值方法)- Parameters:
blockSize- block size (must be odd, >= 3) | 块大小(必须为奇数,>= 3)c- constant subtracted from mean | 从均值中减去的常数- Returns:
- this image for chaining | 用于链式调用的图片
-
equalizeHistogram
Apply histogram equalization 应用直方图均衡化- Returns:
- this image for chaining | 用于链式调用的图片
-
clahe
Apply CLAHE (Contrast Limited Adaptive Histogram Equalization) 应用 CLAHE 自适应局部直方图均衡化- Parameters:
clipLimit- clip limit | 裁剪限制tileGridSize- tile grid size | 分块网格大小- Returns:
- this image for chaining | 用于链式调用的图片
-
autoOrient
Auto-orient based on EXIF orientation 根据 EXIF 方向信息自动旋转- Parameters:
orientation- EXIF orientation value (1-8) | EXIF 方向值(1-8)- Returns:
- this image for chaining | 用于链式调用的图片
-
stripExif
-
save
Save to path 保存到路径- Parameters:
path- the output path | 输出路径- Throws:
ImageWriteException- if writing fails | 如果写入失败
-
save
Save to path with format 保存到路径(指定格式)- Parameters:
path- the output path | 输出路径format- the image format | 图片格式- Throws:
ImageWriteException- if writing fails | 如果写入失败
-
writeTo
Write to output stream 写入输出流- Parameters:
out- the output stream | 输出流- Throws:
ImageWriteException- if writing fails | 如果写入失败
-
writeTo
Write to output stream with format 写入输出流(指定格式)- Parameters:
out- the output stream | 输出流format- the image format | 图片格式- Throws:
ImageWriteException- if writing fails | 如果写入失败
-
toBytes
Convert to byte array 转换为字节数组- Returns:
- the byte array | 字节数组
- Throws:
ImageOperationException- if conversion fails | 如果转换失败
-
toBytes
Convert to byte array with format 转换为字节数组(指定格式)- Parameters:
format- the image format | 图片格式- Returns:
- the byte array | 字节数组
- Throws:
ImageOperationException- if conversion fails | 如果转换失败
-
toBase64
Convert to Base64 string 转换为Base64字符串- Returns:
- the Base64 encoded string | Base64编码字符串
- Throws:
ImageOperationException- if conversion fails | 如果转换失败
-
toBase64
Convert to Base64 string with format 转换为Base64字符串(指定格式)- Parameters:
format- the image format | 图片格式- Returns:
- the Base64 encoded string | Base64编码字符串
- Throws:
ImageOperationException- if conversion fails | 如果转换失败
-
copy
-