How to annotate PDF with image in Java using GroupDocs

If you need to annotate PDF with image—for example, inserting a logo, a diagram, or a photo directly onto a contract or a training manual—GroupDocs.Annotation for Java makes it painless. In this tutorial you’ll see how to add an image annotation, control its opacity and rotation, and handle common pitfalls such as password‑protected PDFs or large files. By the end you’ll be able to embed images into PDFs programmatically and confidently ship the solution in production.

Quick answers

  • Can I add an image to a PDF with Java? Yes – use GroupDocs.Annotation’s ImageAnnotation class.
  • Which method controls image opacity? Call setOpacity(float) on the annotation object.
  • Do I need a license for production? A trial works for testing; a full license is required for commercial use.
  • Can I annotate a password‑protected PDF? Yes – provide the password when creating the Annotator.
  • What Java version is required? Java 8+, though Java 11+ is recommended for best performance.

What is add image to pdf?

Loading an image onto a PDF page creates an image annotation that becomes part of the document’s content stream. ImageAnnotation is the object that stores the image data, its position, size, rotation, and visual style, allowing you to treat the picture like any other annotation type.

Why use GroupDocs Annotation for Java?

Load your PDF, attach an ImageAnnotation, and save—no external viewers needed. GroupDocs Annotation supports 50+ input and output formats, can process PDFs up to 500 MB without loading the whole file into memory, and runs on Windows, Linux, and macOS. Its API gives you fine‑grained control over placement, opacity (0‑1 range), and rotation (0‑360°), making it ideal for enterprise‑grade document workflows.

Prerequisites

  • Java 8 or higher (Java 11+ recommended).
  • IDE – IntelliJ IDEA, Eclipse, or any Java‑compatible editor.
  • Build tool – Maven or Gradle (examples use Maven).

Setting up GroupDocs.Annotation

Add the Maven repository and dependency to your pom.xml:

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/annotation/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-annotation</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>

Pro tip: Always verify the latest version on the GroupDocs releases page. Version 25.2 was current in early 2025, but newer releases may add features.

Licensing (don’t skip this!)

You have three options:

  1. Free trial – perfect for testing – grab it from the GroupDocs trial page.
  2. Temporary license – need more evaluation time? Get one from the temporary license page.
  3. Full license – production use – available on the purchase page.

Getting started – your first image annotation

Step 1: initialize the annotator

Annotator is the entry point that opens a PDF and prepares it for modifications. Annotator is the core class that loads a PDF document, exposes annotation collections, and writes changes back to disk.

try (final Annotator annotator = new Annotator("YOUR_DOCUMENT_DIRECTORY/input.pdf")) {
    // Your annotation magic happens here
}

Why try‑with‑resources? It guarantees the annotator closes and releases file handles, preventing memory leaks.

Step 2: create and configure your image annotation

Below is a minimal ImageAnnotation setup; ImageAnnotation represents an image‑based annotation that can be placed on a PDF page. You’ll define the rectangle, opacity, page number, image source, and rotation angle.

Rectangle defines the position and size of the annotation on the page. Rectangle(100, 100, 100, 100) means “start at (100, 100) from the top‑left corner and make the box 100 × 100 px”. Adjust these numbers to fit your layout.

// Initialize the image annotation
class ImageAnnotation {
    public void setBox(Rectangle rectangle) { /* Implementation */ }
    public void setOpacity(double opacity) { /* Implementation */ }
    public void setPageNumber(int pageNumber) { /* Implementation */ }
    public void setImagePath(String imagePath) { /* Implementation */ }
    public void setAngle(double angle) { /* Implementation */ }
}

// Create your image annotation
ImageAnnotation imageAnnotation = new ImageAnnotation();

// Position and size (x, y, width, height in pixels)
imageAnnotation.setBox(new Rectangle(100, 100, 100, 100));

// Make it 70% opaque (0.0 = transparent, 1.0 = fully opaque)
imageAnnotation.setOpacity(0.7);

// Place it on the first page (0‑indexed)
imageAnnotation.setPageNumber(0);

// Your image source (can be local file or URL)
imageAnnotation.setImagePath("www.google.com.ua/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png");

// Rotate it 100 degrees (because why not?)
imageAnnotation.setAngle(100.);

Understanding setOpacity – the setOpacity(float) method sets the annotation’s transparency on a scale from 0 (fully transparent) to 1 (fully opaque).

Step 3: apply the annotation and save

Now attach the annotation to the document and write the result to disk.

// Add the annotation to your document
annotator.add(imageAnnotation);

// Save the annotated PDF
annotator.save("YOUR_OUTPUT_DIRECTORY/result_image_annotation.pdf");

That’s it – you’ve just annotate PDF with image successfully.

Common issues and solutions

File path problems

  • Symptom: FileNotFoundException or blank images.
  • Fix: Use absolute paths or verify that URLs are reachable.
// Bad: relative path that may fail
imageAnnotation.setImagePath("images/logo.png");

// Good: absolute path
imageAnnotation.setImagePath("/full/path/to/your/images/logo.png");

Image size and quality

  • Symptom: Pixelated or oversized images.
  • Fix: Match image dimensions to the annotation rectangle.
// Rectangle is 200 × 200, so use an image at least that size
imageAnnotation.setBox(new Rectangle(50, 50, 200, 200));

Memory issues with large PDFs

  • Symptom: OutOfMemoryError.
  • Fix: Process documents in batches and keep images lightweight.

When to annotate PDF with image

You should annotate PDF with image when visual context adds value that plain text cannot convey—such as attaching a site‑photo to an inspection report, embedding a diagram in a training worksheet, or stamping a logo onto a contract. Using an image annotation preserves the original PDF layout while delivering the extra visual information instantly to the reader.

Performance best practices

Optimize image sources

// Avoid huge files
imageAnnotation.setImagePath("massive_10mb_image.png");

// Resize to match annotation box (e.g., 100 × 100)

Batch processing strategy

List<String> pdfFiles = Arrays.asList("doc1.pdf", "doc2.pdf", "doc3.pdf");

for (String pdfFile : pdfFiles) {
    try (final Annotator annotator = new Annotator(pdfFile)) {
        ImageAnnotation annotation = createImageAnnotation();
        annotator.add(annotation);
        annotator.save("annotated_" + pdfFile);
    }
}

Resource management

// Good – automatically closes resources
try (final Annotator annotator = new Annotator("input.pdf")) {
    // Your code here
}

// Bad – might cause memory leaks
Annotator annotator = new Annotator("input.pdf");
// ... do stuff ...
// Forgot to close!

Advanced configuration tips

Dynamic positioning

// Bottom‑right corner placement (assuming standard Letter size)
int pageWidth = 612;   // points
int pageHeight = 792;  // points
int imageSize = 50;

Rectangle dynamicPosition = new Rectangle(
    pageWidth - imageSize - 10,   // 10 px margin from right
    pageHeight - imageSize - 10,  // 10 px margin from bottom
    imageSize,
    imageSize
);

imageAnnotation.setBox(dynamicPosition);

Multiple images on one page

// Add a logo
ImageAnnotation logo = new ImageAnnotation();
logo.setBox(new Rectangle(50, 50, 100, 50));
logo.setImagePath("company_logo.png");
logo.setPageNumber(0);

// Add an approval stamp
ImageAnnotation stamp = new ImageAnnotation();
stamp.setBox(new Rectangle(400, 700, 100, 50));
stamp.setImagePath("approved_stamp.png");
stamp.setPageNumber(0);

annotator.add(logo);
annotator.add(stamp);

Frequently asked questions

Q: What’s the maximum image size I can use?
A: No hard limit, but keep images under 2 MB for optimal performance.

Q: Can I use animated GIFs?
A: GroupDocs renders only the first frame of an animated GIF.

Q: How do I position images precisely?
A: GroupDocs uses a top‑left origin; the Rectangle coordinates are measured in pixels from that point.

Q: Can I annotate password‑protected PDFs?
A: Yes – provide the password when constructing the Annotator.

Q: Does this work with all PDF versions?
A: Supported PDF versions range from 1.4 to 2.0, covering virtually every PDF you’ll encounter.

Wrapping up

You now have a solid foundation to annotate PDF with image using GroupDocs.Annotation for Java. Remember to:

  • Use try‑with‑resources for clean disposal.
  • Optimize image dimensions to keep PDFs lightweight.
  • Test with absolute paths to avoid path‑related errors.
  • Choose opacity and rotation that suit your visual design.

Next steps: Explore other annotation types (text, shapes, highlights) or integrate this logic into a Spring Boot service for on‑the‑fly PDF processing.

The documentation at docs.groupdocs.com has more advanced examples and API references when you’re ready to dive deeper.

Last Updated: 2026-09-15
Tested with: GroupDocs.Annotation 25.2 (Java)
Author: GroupDocs

Resources and support