renderPageAnnotation

Renders a single annotation into an image with a transparent background.

Signature


renderPageAnnotation(
  doc: PdfDocumentObject,
  page: PdfPageObject,
  annotation: PdfAnnotationObject,
  options?: PdfRenderPageAnnotationOptions
): PdfTask<T>;

Description

This powerful method isolates a single annotation and renders its appearance stream into an image buffer. The output image’s dimensions match the annotation’s bounding box, and the background is transparent.

This is extremely useful for creating custom user interfaces where an annotation needs to be re-rendered on the fly (e.g., after a user changes its color or position) without the expense of re-rendering the entire PDF page.

Parameters

Name	Type	Description
`doc`	`PdfDocumentObject`	The handle of the document.
`page`	`PdfPageObject`	The page object that contains the annotation.
`annotation`	`PdfAnnotationObject`	The specific annotation object to render.
`options`	`PdfRenderPageAnnotationOptions`	(Optional) An object to customize the rendering output.

`PdfRenderPageAnnotationOptions` Details

This options object allows you to control how the annotation is rendered.

Option	Type	Description
`scaleFactor`	`number`	The render scaling factor (zoom level). Default: `1.0`.
`rotation`	`Rotation`	The rotation to apply in degrees (`0`, `90`, `180`, `270`). Default: `Rotation.Degree0`.
`dpr`	`number`	The Device Pixel Ratio, used for rendering crisp images on high-resolution screens. Default: `1`.
`imageType`	`'image/webp' \| 'image/png' \| 'image/jpeg'`	The output image format. Default: `'image/webp'`.
`mode`	`AppearanceMode`	The appearance state to render, useful for interactive elements like buttons. Can be `Normal`, `Rollover`, or `Down`. Default: `AppearanceMode.Normal`.

Returns

PdfTask<T>

A Task that resolves with the rendered annotation image (Blob in browsers or Buffer in Node.js). The image has a transparent background.

The Task will be rejected if the annotation cannot be found or if rendering fails.

See Concepts: Tasks for more on how to handle asynchronous operations.

Example


// Assuming 'engine', 'document', and 'page' objects are available
 
async function redrawAnnotation(annotation) {
  try {
    const imageBlob = await engine.renderPageAnnotation(
      document,
      page,
      annotation
    ).toPromise();
 
    // This blob can now be used to update an absolutely positioned
    // <img> element that overlays the PDF page viewer.
    const imageUrl = URL.createObjectURL(imageBlob);
    const annotationElement = document.getElementById(annotation.id);
    if (annotationElement) {
        annotationElement.src = imageUrl;
    }
 
  } catch (error) {
    console.error(`Failed to re-render annotation ${annotation.id}:`, error);
  }
}