cloud.opencode.base.image.OpenImage

public final class OpenImage extends Object

OpenImage 图片处理工具类

Static utility entry point for image read/write/quick operations on the AWT-free Raster pipeline. All read/write paths go through the opencode-base-image-codec module (PngDecoder/PngEncoder, JpegCodec, WebpCodec, BmpCodec, GifCodec).

基于 AWT-free Raster 管线的图像读写/快速操作静态入口。所有读写路径通过 opencode-base-image-codec（PngDecoder/PngEncoder、JpegCodec、 WebpCodec、BmpCodec、GifCodec）。

Usage Examples | 使用示例:

// Get info
ImageInfo info = OpenImage.getInfo(Path.of("photo.jpg"));

// Read as Image wrapper, chain operations, save
OpenImage.read(path)
    .resize(800, 600)
    .save(outputPath);

// Quick path-to-path
OpenImage.resize(inputPath, outputPath, 800, 600);
OpenImage.convert(inputPath, outputPath, ImageFormat.PNG);

Security | 安全性:

Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
Null-safe: No (throws on null path/stream) - 空值安全: 否（null 路径/流抛异常）
All read entry points are bounded at 209715200 bytes; oversize input raises ImageIOException (or ImageException on the readRaster path). The cap is enforced uniformly on InputStream, Path, byte[] and Base64 entries, so callers cannot bypass the stream guard via a different overload. 所有读取入口统一在 209715200 字节内：超长输入抛 ImageIOException（readRaster 路径抛 ImageException），覆盖 InputStream/Path/byte[]/Base64 全部重载，避免通过其它入口绕过流式守卫。

Migration from V1.0.3 | V1.0.3 迁移说明:

BREAKING: the optional com.twelvemonkeys.imageio:imageio-webp dependency was removed in V1.0.4. WebP read/write now goes through the native libwebp codec in opencode-base-image-codec via FFM, requiring no extra classpath entry. Users who still depend on twelvemonkeys for non-WebP reasons must declare it explicitly in their own POM. 不兼容变更：V1.0.4 移除了可选依赖 com.twelvemonkeys.imageio:imageio-webp。WebP 读写改由 opencode-base-image-codec 通过 FFM 调用原生 libwebp 完成，无需额外 classpath。仍因其它原因需要 twelvemonkeys 的用户须自行声明依赖。
Read paths no longer touch java.desktop (no AWT, no ImageIO); output is byte-identical only when round-tripping through the AWT-free codecs. 读取路径不再依赖 java.desktop（无 AWT/ImageIO）；输出仅在使用 AWT-free 编解码器往返时与 V1.0.3 字节一致。

Since:

JDK 25, opencode-base-image V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static void

compress(Path input, Path output, float quality)

Quick JPEG compress. | 快速 JPEG 压缩。

static void

compressRaster(Path input, Path output, float quality)

Quick path-to-path JPEG compression on the Raster pipeline.

static void

convert(Path input, Path output, ImageFormat format)

Quick format conversion. | 快速格式转换。

static Image

createBlank(int width, int height)

Create a blank image (transparent black RGBA_8).

static Image

createBlank(int width, int height, int color)

Create a blank image filled with the given ARGB color.

static Raster

createBlankRaster(int width, int height)

Create a blank Raster (transparent RGBA_8).

static Raster

createBlankRaster(int width, int height, int argb)

Create a blank Raster filled with the given ARGB color.

static void

crop(Path input, Path output, int x, int y, int width, int height)

Quick crop. | 快速裁剪。

static void

cropRaster(Path input, Path output, int x, int y, int width, int height)

Quick path-to-path crop on the Raster pipeline.

static ImageFormat

detectFormat(Path path)

Detect format from file extension.

static ImageFormat

detectFormatFromMagic(byte[] bytes)

Detect image format from magic bytes (first few bytes of the payload).

static void

flipHorizontal(Path input, Path output)

Quick horizontal flip. | 快速水平翻转。

static void

flipVertical(Path input, Path output)

Quick vertical flip. | 快速垂直翻转。

static Image

fromBase64(String base64)

Read image from Base64 string 从Base64字符串读取图片

static int[]

getDimensions(Path path)

Get image dimensions without fully loading 获取图片尺寸（不完全加载）

static ImageInfo

getInfo(Path path)

Get image info from path.

static void

grayscale(Path input, Path output)

Quick grayscale. | 快速灰度。

static boolean

isSupported(String extension)

Check if format is supported 检查格式是否支持

static boolean

isValidImage(Path path)

Check if file is a valid image 检查文件是否为有效图片

static Image

read(byte[] bytes)

Read image from byte array 从字节数组读取图片

static Image

read(InputStream in)

Read image from input stream 从输入流读取图片

static Image

read(Path path)

Read image from path 从路径读取图片

static Raster

readRaster(byte[] bytes)

Decode a Raster from byte content, auto-detecting the format from magic bytes (PNG / JPEG / WebP / BMP / GIF).

static Raster

readRaster(InputStream in)

Read a Raster from an InputStream.

static Raster

readRaster(Path path)

Read a Raster from a path.

static void

resize(Path input, Path output, int width, int height)

Quick resize. | 快速缩放。

static void

resizeRaster(Path input, Path output, int width, int height)

Quick path-to-path resize on the Raster pipeline. | Raster 路径到路径快速缩放。

static void

rotate(Path input, Path output, double degrees)

Quick rotate. | 快速旋转。

static void

rotateRaster(Path input, Path output, double degrees)

Quick path-to-path arbitrary-angle rotation on the Raster pipeline.

static ThumbnailBuilder

thumbnail()

Create a thumbnail builder 创建缩略图构建器

static void

thumbnail(Path input, Path output, int size)

Quick thumbnail (preserve aspect to maximum dimension). | 快速缩略图（保持比例）。

static byte[]

toBytes(Raster raster, ImageFormat format)

Encode a Raster to a fresh byte array.

static byte[]

toBytes(Path path)

Encode image bytes from path. | 将路径中的图片转为字节。

static void

write(Raster raster, OutputStream out, ImageFormat format)

Encode a Raster to an output stream in the given format.

static void

write(Raster raster, Path path)

Encode a Raster and write it to a path; the target format is inferred from the file extension.

static void

write(Raster raster, Path path, ImageFormat format)

Encode a Raster and write it to a path with the given format.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- read
  
  public static Image read(Path path) throws ImageReadException
  
  Read image from path 从路径读取图片
  
  Parameters:
  
  path - the image path | 图片路径
  
  Returns:
  
  the image wrapper | 图片包装器
  
  Throws:
  
  ImageReadException - if reading fails | 如果读取失败
- read
  
  public static Image read(InputStream in) throws ImageIOException
  
  Read image from input stream 从输入流读取图片
  
  Parameters:
  
  in - the input stream | 输入流
  
  Returns:
  
  the image wrapper | 图片包装器
  
  Throws:
  
  ImageIOException - if reading fails | 如果读取失败
- read
  
  public static Image read(byte[] bytes) throws ImageIOException
  
  Read image from byte array 从字节数组读取图片
  
  Parameters:
  
  bytes - the image bytes | 图片字节数组
  
  Returns:
  
  the image wrapper | 图片包装器
  
  Throws:
  
  ImageIOException - if reading fails | 如果读取失败
- fromBase64
  
  public static Image fromBase64(String base64) throws ImageIOException
  
  Read image from Base64 string 从Base64字符串读取图片
  
  Parameters:
  
  base64 - the Base64 encoded image | Base64编码的图片
  
  Returns:
  
  the image wrapper | 图片包装器
  
  Throws:
  
  ImageIOException - if reading fails | 如果读取失败
- getInfo
  
  public static ImageInfo getInfo(Path path) throws ImageReadException
  
  Get image info from path. Reads only the file size + format header for dimensions; does not decode pixels. 从路径获取图片信息：仅读取文件大小与格式头部尺寸，不解码像素。
  
  Parameters:
  
  path - the image path | 图片路径
  
  Returns:
  
  the image info | 图片信息
  
  Throws:
  
  ImageReadException - if reading fails | 如果读取失败
- getDimensions
  
  public static int[] getDimensions(Path path) throws ImageReadException
  
  Get image dimensions without fully loading 获取图片尺寸（不完全加载）
  
  Parameters:
  
  path - the image path | 图片路径
  
  Returns:
  
  array of [width, height] | [宽度, 高度]数组
  
  Throws:
  
  ImageReadException - if reading fails | 如果读取失败
- resize
  
  public static void resize(Path input, Path output, int width, int height) throws ImageIOException
  
  Quick resize. | 快速缩放。
  
  Throws:
  
  ImageIOException
- crop
  
  public static void crop(Path input, Path output, int x, int y, int width, int height) throws ImageIOException
  
  Quick crop. | 快速裁剪。
  
  Throws:
  
  ImageIOException
- rotate
  
  public static void rotate(Path input, Path output, double degrees) throws ImageIOException
  
  Quick rotate. | 快速旋转。
  
  Throws:
  
  ImageIOException
- convert
  
  public static void convert(Path input, Path output, ImageFormat format) throws ImageIOException
  
  Quick format conversion. | 快速格式转换。
  
  Throws:
  
  ImageIOException
- compress
  
  public static void compress(Path input, Path output, float quality) throws ImageIOException
  
  Quick JPEG compress. | 快速 JPEG 压缩。
  
  Throws:
  
  ImageIOException
- thumbnail
  
  public static void thumbnail(Path input, Path output, int size) throws ImageIOException
  
  Quick thumbnail (preserve aspect to maximum dimension). | 快速缩略图（保持比例）。
  
  Throws:
  
  ImageIOException
- thumbnail
  
  public static ThumbnailBuilder thumbnail()
  
  Create a thumbnail builder 创建缩略图构建器
  
  Returns:
  
  the thumbnail builder | 缩略图构建器
- flipHorizontal
  
  public static void flipHorizontal(Path input, Path output) throws ImageIOException
  
  Quick horizontal flip. | 快速水平翻转。
  
  Throws:
  
  ImageIOException
- flipVertical
  
  public static void flipVertical(Path input, Path output) throws ImageIOException
  
  Quick vertical flip. | 快速垂直翻转。
  
  Throws:
  
  ImageIOException
- grayscale
  
  public static void grayscale(Path input, Path output) throws ImageIOException
  
  Quick grayscale. | 快速灰度。
  
  Throws:
  
  ImageIOException
- toBytes
  
  public static byte[] toBytes(Path path) throws ImageIOException
  
  Encode image bytes from path. | 将路径中的图片转为字节。
  
  Throws:
  
  ImageIOException
- detectFormat
  
  public static ImageFormat detectFormat(Path path)
  
  Detect format from file extension. Falls back to ImageFormat.PNG silently when the extension is missing or unrecognised; callers needing strict detection should use detectFormatFromMagic(byte[]) on the decoded payload instead. 按文件扩展名检测格式。扩展名缺失或不识别时静默回落到 ImageFormat.PNG；需要严格识别的调用方应改用 detectFormatFromMagic(byte[]) 按内容判定。
  
  Parameters:
  
  path - the file path | 文件路径
  
  Returns:
  
  the detected format | 检测到的格式
- isValidImage
  
  public static boolean isValidImage(Path path)
  
  Check if file is a valid image 检查文件是否为有效图片
  
  Parameters:
  
  path - the file path | 文件路径
  
  Returns:
  
  true if valid image | 如果是有效图片返回 true
- isSupported
  
  public static boolean isSupported(String extension)
  
  Check if format is supported 检查格式是否支持
  
  Parameters:
  
  extension - the file extension | 文件扩展名
  
  Returns:
  
  true if supported | 如果支持返回 true
- createBlank
  
  public static Image createBlank(int width, int height)
  
  Create a blank image (transparent black RGBA_8). 创建空白图片（透明黑 RGBA_8）。
  
  Parameters:
  
  width - the width | 宽度
  
  height - the height | 高度
  
  Returns:
  
  the image wrapper | 图片包装器
- createBlank
  
  public static Image createBlank(int width, int height, int color)
  
  Create a blank image filled with the given ARGB color. 创建以 ARGB 颜色填充的空白图片。
  
  Parameters:
  
  width - the width | 宽度
  
  height - the height | 高度
  
  color - the background color (ARGB) | 背景颜色（ARGB）
  
  Returns:
  
  the image wrapper | 图片包装器
- readRaster
  
  public static Raster readRaster(byte[] bytes)
  
  Decode a Raster from byte content, auto-detecting the format from magic bytes (PNG / JPEG / WebP / BMP / GIF). 从字节内容解码 Raster，按 magic bytes 自动识别格式。
  
  Parameters:
  
  bytes - encoded image bytes | 编码后的图片字节
  
  Returns:
  
  decoded Raster | 解码后的 Raster
  
  Throws:
  
  NullPointerException - if bytes is null | bytes 为 null 时抛出
  
  ImageException - if format is unsupported or decode fails | 格式不支持或解码失败时抛出
  
  Since:
  
  opencode-base-image V1.0.4
- readRaster
  
  public static Raster readRaster(Path path)
  
  Read a Raster from a path. Format auto-detected from content. 从路径读取 Raster，按内容自动识别格式。
  
  Parameters:
  
  path - image path | 图片路径
  
  Returns:
  
  decoded Raster | 解码后的 Raster
  
  Throws:
  
  NullPointerException - if path is null | path 为 null 时抛出
  
  ImageException - if reading or decoding fails | 读取或解码失败时抛出
  
  Since:
  
  opencode-base-image V1.0.4
- readRaster
  
  public static Raster readRaster(InputStream in)
  
  Read a Raster from an InputStream. The stream is buffered up to MAX_INPUT_BYTES to avoid memory exhaustion. 从 InputStream 读取 Raster，最大缓冲 MAX_INPUT_BYTES。
  
  Parameters:
  
  in - input stream | 输入流
  
  Returns:
  
  decoded Raster | 解码后的 Raster
  
  Throws:
  
  ImageException - if reading fails | 读取失败时抛出
  
  Since:
  
  opencode-base-image V1.0.4
- write
  
  public static void write(Raster raster, Path path)
  
  Encode a Raster and write it to a path; the target format is inferred from the file extension. 编码 Raster 并写入路径；目标格式由文件扩展名推断。
  
  Parameters:
  
  raster - source raster | 源 raster
  
  path - output path | 输出路径
  
  Throws:
  
  NullPointerException - if any argument is null | 任一参数为 null 时抛出
  
  ImageException - if encoding or writing fails | 编码或写入失败时抛出
  
  Since:
  
  opencode-base-image V1.0.4
- write
  
  public static void write(Raster raster, Path path, ImageFormat format)
  
  Encode a Raster and write it to a path with the given format. 以指定格式编码 Raster 并写入路径。
  
  Parameters:
  
  raster - source raster | 源 raster
  
  path - output path | 输出路径
  
  format - target format | 目标格式
  
  Throws:
  
  NullPointerException - if any argument is null | 任一参数为 null 时抛出
  
  ImageException - if encoding or writing fails | 编码或写入失败时抛出
  
  Since:
  
  opencode-base-image V1.0.4
- write
  
  public static void write(Raster raster, OutputStream out, ImageFormat format)
  
  Encode a Raster to an output stream in the given format. 将 Raster 以指定格式编码到输出流。
  
  Parameters:
  
  raster - source raster | 源 raster
  
  out - output stream | 输出流
  
  format - target format | 目标格式
  
  Throws:
  
  ImageException - if encoding or writing fails | 编码或写入失败时抛出
  
  Since:
  
  opencode-base-image V1.0.4
- toBytes
  
  public static byte[] toBytes(Raster raster, ImageFormat format)
  
  Encode a Raster to a fresh byte array. 将 Raster 编码为新字节数组。
  
  Parameters:
  
  raster - source raster | 源 raster
  
  format - target format | 目标格式
  
  Returns:
  
  encoded bytes | 编码后的字节
  
  Since:
  
  opencode-base-image V1.0.4
- resizeRaster
  
  public static void resizeRaster(Path input, Path output, int width, int height)
  
  Quick path-to-path resize on the Raster pipeline. | Raster 路径到路径快速缩放。
- cropRaster
  
  public static void cropRaster(Path input, Path output, int x, int y, int width, int height)
  
  Quick path-to-path crop on the Raster pipeline.
- rotateRaster
  
  public static void rotateRaster(Path input, Path output, double degrees)
  
  Quick path-to-path arbitrary-angle rotation on the Raster pipeline.
- compressRaster
  
  public static void compressRaster(Path input, Path output, float quality)
  
  Quick path-to-path JPEG compression on the Raster pipeline.
- createBlankRaster
  
  public static Raster createBlankRaster(int width, int height)
  
  Create a blank Raster (transparent RGBA_8).
- createBlankRaster
  
  public static Raster createBlankRaster(int width, int height, int argb)
  
  Create a blank Raster filled with the given ARGB color.
- detectFormatFromMagic
  
  public static ImageFormat detectFormatFromMagic(byte[] bytes)
  
  Detect image format from magic bytes (first few bytes of the payload). 通过 magic bytes（首部字节）识别图片格式。
  
  Parameters:
  
  bytes - encoded image bytes | 编码后的图片字节
  
  Returns:
  
  matched format, or null if no magic matches | 匹配到的格式；无匹配时返回 null
  
  Since:
  
  opencode-base-image V1.0.4

Class OpenImage

Method Summary

Methods inherited from class Object

Method Details

read

read

read

fromBase64

getInfo

getDimensions

resize

crop

rotate

convert

compress

thumbnail

thumbnail

flipHorizontal

flipVertical

grayscale

toBytes

detectFormat

isValidImage

isSupported

createBlank

createBlank

readRaster

readRaster

readRaster

write

write

write

toBytes

resizeRaster

cropRaster

rotateRaster

compressRaster

createBlankRaster

createBlankRaster

detectFormatFromMagic