Callout annotation

Author: bobsingor

packages/engines/src/lib/pdfium/engine.ts

@@ -3349,7 +3349,13 @@ export class PdfiumNative implements IPdfiumExecutor {
     annotation: PdfFreeTextAnnoObject,
   ) {
     // Type-specific properties
-    if (!this.setBorderStyle(annotationPtr, PdfAnnotationBorderStyle.SOLID, 0)) {
+    if (
+      !this.setBorderStyle(
+        annotationPtr,
+        PdfAnnotationBorderStyle.SOLID,
+        annotation.strokeWidth ?? 0,
+      )
+    ) {
       return false;
     }
     if (!this.setAnnotationOpacity(annotationPtr, annotation.opacity ?? 1)) {
@@ -3361,21 +3367,42 @@ export class PdfiumNative implements IPdfiumExecutor {
     if (!this.setAnnotationVerticalAlignment(annotationPtr, annotation.verticalAlign)) {
       return false;
     }
+    const daColor = annotation.strokeColor ?? annotation.fontColor;
     if (
       !this.setAnnotationDefaultAppearance(
         annotationPtr,
         annotation.fontFamily === PdfStandardFont.Unknown
           ? PdfStandardFont.Helvetica
           : annotation.fontFamily,
         annotation.fontSize,
-        annotation.fontColor,
+        daColor,
       )
     ) {
       return false;
     }
+    if (annotation.strokeColor && annotation.strokeColor !== annotation.fontColor) {
+      this.setAnnotationColor(
+        annotationPtr,
+        annotation.fontColor,
+        PdfAnnotationColorType.TextColor,
+      );
+    }
     if (annotation.intent && !this.setAnnotIntent(annotationPtr, annotation.intent)) {
       return false;
     }
+    if (
+      annotation.calloutLine &&
+      annotation.calloutLine.length >= 2 &&
+      !this.setCalloutLine(doc, page, annotationPtr, annotation.calloutLine)
+    ) {
+      return false;
+    }
+    if (
+      annotation.lineEnding !== undefined &&
+      !this.setLineEndings(annotationPtr, PdfAnnotationLineEnding.None, annotation.lineEnding)
+    ) {
+      return false;
+    }
     // Prefer color, fall back to deprecated backgroundColor
     const bgColor = annotation.color ?? annotation.backgroundColor;
     if (!bgColor || bgColor === 'transparent') {
@@ -6463,6 +6490,9 @@ export class PdfiumNative implements IPdfiumExecutor {
    * @returns `{ ok, left, top, right, bottom }`
    *          • `ok`     – `true` when the annotation *has* an /RD entry
    *          • the four floats are 0 when `ok` is false
+   *
+   * Native PDFium exposes /RD as [left, bottom, right, top]. We remap it here
+   * to the model's stable { left, top, right, bottom } shape.
    */
   private getRectangleDifferences(annotationPtr: number): {
     ok: boolean;
@@ -6473,29 +6503,29 @@ export class PdfiumNative implements IPdfiumExecutor {
   } {
     /* tmp storage ─────────────────────────────────────────── */
     const lPtr = this.memoryManager.malloc(4);
-    const tPtr = this.memoryManager.malloc(4);
-    const rPtr = this.memoryManager.malloc(4);
     const bPtr = this.memoryManager.malloc(4);
+    const rPtr = this.memoryManager.malloc(4);
+    const tPtr = this.memoryManager.malloc(4);
 
     const ok = !!this.pdfiumModule.EPDFAnnot_GetRectangleDifferences(
       annotationPtr,
       lPtr,
-      tPtr,
-      rPtr,
       bPtr,
+      rPtr,
+      tPtr,
     );
 
     const pdf = this.pdfiumModule.pdfium;
     const left = pdf.getValue(lPtr, 'float');
-    const top = pdf.getValue(tPtr, 'float');
-    const right = pdf.getValue(rPtr, 'float');
     const bottom = pdf.getValue(bPtr, 'float');
+    const right = pdf.getValue(rPtr, 'float');
+    const top = pdf.getValue(tPtr, 'float');
 
     /* cleanup ─────────────────────────────────────────────── */
     this.memoryManager.free(lPtr);
-    this.memoryManager.free(tPtr);
-    this.memoryManager.free(rPtr);
     this.memoryManager.free(bPtr);
+    this.memoryManager.free(rPtr);
+    this.memoryManager.free(tPtr);
 
     return { ok, left, top, right, bottom };
   }
@@ -6517,9 +6547,9 @@ export class PdfiumNative implements IPdfiumExecutor {
     return this.pdfiumModule.EPDFAnnot_SetRectangleDifferences(
       annotationPtr,
       rd.left,
-      rd.top,
-      rd.right,
       rd.bottom,
+      rd.right,
+      rd.top,
     );
   }
 
@@ -7503,11 +7533,16 @@ export class PdfiumNative implements IPdfiumExecutor {
     const defaultStyle = this.getAnnotString(annotationPtr, 'DS');
     const da = this.getAnnotationDefaultAppearance(annotationPtr);
     const bgColor = this.getAnnotationColor(annotationPtr);
+    const textColor = this.getAnnotationColor(annotationPtr, PdfAnnotationColorType.TextColor);
+    const borderStyle = this.getBorderStyle(annotationPtr);
     const textAlign = this.getAnnotationTextAlignment(annotationPtr);
     const verticalAlign = this.getAnnotationVerticalAlignment(annotationPtr);
     const opacity = this.getAnnotationOpacity(annotationPtr);
     const richContent = this.getAnnotRichContent(annotationPtr);
     const rd = this.getRectangleDifferences(annotationPtr);
+    const intent = this.getAnnotIntent(annotationPtr);
+    const calloutLine = this.getCalloutLine(doc, page, annotationPtr);
+    const lineEndings = this.getLineEndings(annotationPtr);
 
     return {
       pageIndex: page.index,
@@ -7516,10 +7551,10 @@ export class PdfiumNative implements IPdfiumExecutor {
       rect,
       fontFamily: da?.fontFamily ?? PdfStandardFont.Unknown,
       fontSize: da?.fontSize ?? 12,
-      fontColor: da?.fontColor ?? '#000000',
+      fontColor: textColor ?? da?.fontColor ?? '#000000',
       verticalAlign,
-      color: bgColor, // fill color (matches shape convention)
-      backgroundColor: bgColor, // deprecated alias
+      color: bgColor,
+      backgroundColor: bgColor,
       opacity,
       textAlign,
       defaultStyle,
@@ -7532,6 +7567,14 @@ export class PdfiumNative implements IPdfiumExecutor {
           bottom: rd.bottom,
         },
       }),
+      ...(intent && { intent }),
+      ...(calloutLine && { calloutLine }),
+      ...(lineEndings && { lineEnding: lineEndings.end }),
+      ...(borderStyle.width > 0
+        ? { strokeWidth: borderStyle.width, strokeColor: da?.fontColor ?? '#000000' }
+        : intent === 'FreeTextCallout'
+          ? { strokeWidth: 1, strokeColor: da?.fontColor ?? '#000000' }
+          : {}),
       ...this.readBaseAnnotationProperties(doc, page, annotationPtr),
     };
   }
@@ -9178,6 +9221,67 @@ export class PdfiumNative implements IPdfiumExecutor {
     return ok;
   }
 
+  /**
+   * Read the callout line points (/CL) from a FreeText annotation.
+   * Returns an array of 2 or 3 Position points in device coords, or undefined.
+   *
+   * @private
+   */
+  private getCalloutLine(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    annotationPtr: number,
+  ): Position[] | undefined {
+    const count = this.pdfiumModule.EPDFAnnot_GetCalloutLineCount(annotationPtr);
+    if (count === 0) {
+      return undefined;
+    }
+
+    const FS_POINTF_SIZE = 8;
+    const pointsPtr = this.memoryManager.malloc(count * FS_POINTF_SIZE);
+    const result = this.pdfiumModule.EPDFAnnot_GetCalloutLine(annotationPtr, pointsPtr, count);
+    if (result === 0) {
+      this.memoryManager.free(pointsPtr);
+      return undefined;
+    }
+
+    const points: Position[] = [];
+    for (let i = 0; i < count; i++) {
+      const px = this.pdfiumModule.pdfium.getValue(pointsPtr + i * FS_POINTF_SIZE, 'float');
+      const py = this.pdfiumModule.pdfium.getValue(pointsPtr + i * FS_POINTF_SIZE + 4, 'float');
+      points.push(this.convertPagePointToDevicePoint(doc, page, { x: px, y: py }));
+    }
+    this.memoryManager.free(pointsPtr);
+    return points;
+  }
+
+  /**
+   * Set the callout line points (/CL) on a FreeText annotation.
+   * Converts from device coords to page coords before writing.
+   *
+   * @private
+   */
+  private setCalloutLine(
+    doc: PdfDocumentObject,
+    page: PdfPageObject,
+    annotPtr: number,
+    points: Position[],
+  ): boolean {
+    const pdf = this.pdfiumModule.pdfium;
+    const FS_POINTF_SIZE = 8;
+
+    const buf = this.memoryManager.malloc(FS_POINTF_SIZE * points.length);
+    points.forEach((v, i) => {
+      const pagePt = this.convertDevicePointToPagePoint(doc, page, v);
+      pdf.setValue(buf + i * FS_POINTF_SIZE + 0, pagePt.x, 'float');
+      pdf.setValue(buf + i * FS_POINTF_SIZE + 4, pagePt.y, 'float');
+    });
+
+    const ok = this.pdfiumModule.EPDFAnnot_SetCalloutLine(annotPtr, buf, points.length);
+    this.memoryManager.free(buf);
+    return ok;
+  }
+
   /**
    * Read the target of pdf bookmark
    * @param docPtr - pointer to pdf document object

packages/models/src/pdf.ts

@@ -1243,6 +1243,7 @@ export enum PdfAnnotationColorType {
   Color = 0,
   InteriorColor = 1,
   OverlayColor = 2,
+  TextColor = 3,
 }
 
 /**
@@ -2314,6 +2315,26 @@ export interface PdfFreeTextAnnoObject extends PdfAnnotationObjectBase {
    * Rectangle Differences (/RD) - inset padding from Rect to the drawn area.
    */
   rectangleDifferences?: PdfRectDifferences;
+  /**
+   * Callout line points (PDF /CL array).
+   * 2 points for a simple leader line, 3 points for a knee-jointed leader line.
+   * Points are in device coordinates (same as rect/vertices).
+   * Present only when intent is 'FreeTextCallout'.
+   */
+  calloutLine?: Position[];
+  /**
+   * Line ending style for the callout leader line (PDF /LE).
+   * Only meaningful when calloutLine is present.
+   */
+  lineEnding?: PdfAnnotationLineEnding;
+  /**
+   * Border / callout line stroke width (from /BS -> W).
+   */
+  strokeWidth?: number;
+  /**
+   * Border / callout line stroke color (from /DA rg color).
+   */
+  strokeColor?: string;
 }
 
 /**

packages/pdfium/src/vendor/functions.ts

@@ -54,6 +54,8 @@ export const functions = {
   EPDFAnnot_GetBorderEffect: [['number', 'number'] as const, 'boolean'] as const,
   EPDFAnnot_GetBorderStyle: [['number', 'number'] as const, 'number'] as const,
   EPDFAnnot_GetButtonExportValue: [['number', 'number', 'number'] as const, 'number'] as const,
+  EPDFAnnot_GetCalloutLine: [['number', 'number', 'number'] as const, 'number'] as const,
+  EPDFAnnot_GetCalloutLineCount: [['number'] as const, 'number'] as const,
   EPDFAnnot_GetColor: [
     ['number', 'number', 'number', 'number', 'number'] as const,
     'boolean',
@@ -96,6 +98,7 @@ export const functions = {
   EPDFAnnot_SetBorderDashPattern: [['number', 'number', 'number'] as const, 'boolean'] as const,
   EPDFAnnot_SetBorderEffect: [['number', 'number'] as const, 'boolean'] as const,
   EPDFAnnot_SetBorderStyle: [['number', 'number', 'number'] as const, 'boolean'] as const,
+  EPDFAnnot_SetCalloutLine: [['number', 'number', 'number'] as const, 'boolean'] as const,
   EPDFAnnot_SetColor: [
     ['number', 'number', 'number', 'number', 'number'] as const,
     'boolean',

packages/pdfium/src/vendor/pdfium.cjs

@@ -69,6 +69,8 @@ var createPdfium = (() => {
       '_EPDFAnnot_GetBorderEffect',
       '_EPDFAnnot_GetBorderStyle',
       '_EPDFAnnot_GetButtonExportValue',
+      '_EPDFAnnot_GetCalloutLine',
+      '_EPDFAnnot_GetCalloutLineCount',
       '_EPDFAnnot_GetColor',
       '_EPDFAnnot_GetDefaultAppearance',
       '_EPDFAnnot_GetExtendedRotation',
@@ -96,6 +98,7 @@ var createPdfium = (() => {
       '_EPDFAnnot_SetBorderDashPattern',
       '_EPDFAnnot_SetBorderEffect',
       '_EPDFAnnot_SetBorderStyle',
+      '_EPDFAnnot_SetCalloutLine',
       '_EPDFAnnot_SetColor',
       '_EPDFAnnot_SetDefaultAppearance',
       '_EPDFAnnot_SetExtendedRotation',
@@ -6399,6 +6402,16 @@ var createPdfium = (() => {
       'EPDFAnnot_ShareFormField',
       3,
     ));
+    var _EPDFAnnot_GetCalloutLineCount = (Module['_EPDFAnnot_GetCalloutLineCount'] =
+      createExportWrapper('EPDFAnnot_GetCalloutLineCount', 1));
+    var _EPDFAnnot_GetCalloutLine = (Module['_EPDFAnnot_GetCalloutLine'] = createExportWrapper(
+      'EPDFAnnot_GetCalloutLine',
+      3,
+    ));
+    var _EPDFAnnot_SetCalloutLine = (Module['_EPDFAnnot_SetCalloutLine'] = createExportWrapper(
+      'EPDFAnnot_SetCalloutLine',
+      3,
+    ));
     var _EPDFAnnot_SetFormFieldOptions = (Module['_EPDFAnnot_SetFormFieldOptions'] =
       createExportWrapper('EPDFAnnot_SetFormFieldOptions', 4));
     var _FPDFDoc_GetAttachmentCount = (Module['_FPDFDoc_GetAttachmentCount'] = createExportWrapper(