Class PdfImage

java.lang.Object
cloud.opencode.base.pdf.content.PdfImage
All Implemented Interfaces:
PdfElement
public final class PdfImage extends Object implements PdfElement
PDF Image Element - Embedded image content PDF 图像元素 - 嵌入的图像内容

Supports PNG, JPEG, and other common image formats.

支持 PNG、JPEG 和其他常见图像格式。

Features | 主要功能:

  • Load images from file path or byte array - 从文件路径或字节数组加载图像
  • Automatic format detection - 自动格式检测
  • Position, size, rotation, and opacity control - 位置、大小、旋转和不透明度控制
  • Aspect-ratio-preserving scaling - 保持纵横比的缩放

Usage Examples | 使用示例:

PdfImage logo = PdfImage.from(Path.of("logo.png"))
    .position(50, 750)
    .size(100, 50);

PdfImage photo = PdfImage.from(bytes, ImageFormat.JPEG)
    .position(100, 400)
    .scaleToWidth(200)
    .opacity(0.8f);

Security | 安全性:

  • Thread-safe: No — mutable builder pattern - 线程安全: 否 — 可变构建器模式
  • Null-safe: No — callers must ensure non-null values - 空值安全: 否 — 调用方需确保非空值
  • Defensive copies: Byte arrays are cloned on input and output - 防御性拷贝: 字节数组在输入和输出时进行克隆
Since:
JDK 25, opencode-base-pdf V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • from

      public static PdfImage from(Path path)
      Creates image from file path 从文件路径创建图像
      Parameters:
      path - image file path | 图像文件路径
      Returns:
      PdfImage instance | PdfImage 实例

    • from

      public static PdfImage from(byte[] bytes, PdfImage.ImageFormat format)
      Creates image from byte array 从字节数组创建图像
      Parameters:
      bytes - image bytes | 图像字节
      format - image format | 图像格式
      Returns:
      PdfImage instance | PdfImage 实例

    • builder

      public static PdfImage builder()
      Creates an image builder 创建图像构建器
      Returns:
      new PdfImage instance | 新 PdfImage 实例

    • source

      public PdfImage source(Path imagePath)
      Sets image from file 从文件设置图像
      Parameters:
      imagePath - image file path | 图像文件路径
      Returns:
      this image for chaining | 当前图像用于链式调用

    • source

      public PdfImage source(byte[] imageBytes, PdfImage.ImageFormat format)
      Sets image from bytes 从字节设置图像
      Parameters:
      imageBytes - image bytes | 图像字节
      format - image format | 图像格式
      Returns:
      this image for chaining | 当前图像用于链式调用

    • position

      public PdfImage position(float x, float y)
      Sets position 设置位置
      Parameters:
      x - x coordinate | x 坐标
      y - y coordinate | y 坐标
      Returns:
      this image for chaining | 当前图像用于链式调用

    • size

      public PdfImage size(float width, float height)
      Sets size 设置大小
      Parameters:
      width - image width | 图像宽度
      height - image height | 图像高度
      Returns:
      this image for chaining | 当前图像用于链式调用

    • scaleToWidth

      public PdfImage scaleToWidth(float width)
      Scales to fit width (maintains aspect ratio) 缩放以适应宽度（保持纵横比）
      Parameters:
      width - target width | 目标宽度
      Returns:
      this image for chaining | 当前图像用于链式调用

    • scaleToHeight

      public PdfImage scaleToHeight(float height)
      Scales to fit height (maintains aspect ratio) 缩放以适应高度（保持纵横比）
      Parameters:
      height - target height | 目标高度
      Returns:
      this image for chaining | 当前图像用于链式调用

    • rotation

      public PdfImage rotation(float degrees)
      Sets rotation 设置旋转
      Parameters:
      degrees - rotation in degrees | 旋转角度
      Returns:
      this image for chaining | 当前图像用于链式调用

    • opacity

      public PdfImage opacity(float opacity)
      Sets opacity 设置不透明度
      Parameters:
      opacity - opacity (0.0 - 1.0) | 不透明度
      Returns:
      this image for chaining | 当前图像用于链式调用

    • getSourcePath

      public Path getSourcePath()

    • getSourceBytes

      public byte[] getSourceBytes()

    • getFormat

      public PdfImage.ImageFormat getFormat()

    • getX

      public float getX()
      Description copied from interface: PdfElement
      Gets the x coordinate of this element 获取元素的 x 坐标
      Specified by:
      getX in interface PdfElement
      Returns:
      x coordinate | x 坐标

    • getY

      public float getY()
      Description copied from interface: PdfElement
      Gets the y coordinate of this element 获取元素的 y 坐标
      Specified by:
      getY in interface PdfElement
      Returns:
      y coordinate | y 坐标

    • getWidth

      public float getWidth()

    • getHeight

      public float getHeight()

    • getRotation

      public float getRotation()

    • getOpacity

      public float getOpacity()