Add support for text markup annotation

[konbraphat51]

What?

This add supports reading and writing text markup annotation objects.

This adds:

• basic infrastructure of reading/editing/adding annotation object
• actual function PDFPage.addTextMarkupAnnotation() to add text markup annotation object

Reading

• User can fetch the annotation objects from PDFPage.annotations()
  • This returns PDFAnnotation class instances

Editing

• Able to change values of annotation objects using set methods of PDFAnnotation class

Adding

• Able to add annotation object to the specified page by PDFPage.addTextMarkupAnnotation()

Why?

• There was no interface for controling annotation object in this library
• I guess many people wanted this feature

How?

• implement conversion of annotation dictionary objects to PDFAnnotation class instance.
• add a lot of get/set methods in PDFAnnotation

Testing?

• Added new test code for this annotation feature.
  • test passed

New Dependencies?

N/A

Screenshots

This is created by this code:

//yarn node annotationsample-fixed.js
const fs = require('fs');

async function createAnnotatedPDF() {
  try {
    console.log('Creating PDF with annotation...');

    // Import pdf-lib
    const { PDFDocument, StandardFonts, rgb } = require('./cjs/index');
    const {
      AnnotationTypes,
    } = require('./cjs/core/annotation/AnnotationTypes');

    console.log('PDF-lib loaded successfully');

    // Create a new PDF document
    const pdfDoc = await PDFDocument.create();
    const page = pdfDoc.addPage([600, 400]);
    console.log('Page created');

    // Add some text first
    const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica);
    page.drawText('This text will be highlighted', {
      x: 50,
      y: 300,
      size: 12,
      font: helveticaFont,
      color: rgb(0, 0, 0),
    });
    console.log('Text added');

    // Try to add a highlight annotation
    try {
      page.addTextMarkupAnnotation({
        subtype: AnnotationTypes.Highlight,
        color: [1, 1, 0], // Yellow
        rect: {
          x: 50,
          y: 300,
          width: 150,
          height: 20,
        },
        contents: 'This is a highlight annotation',
        quadPoints: {
          leftbottomX: 50,
          leftbottomY: 300,
          lefttopX: 50,
          lefttopY: 320,
          righttopX: 200,
          righttopY: 320,
          rightbottomX: 200,
          rightbottomY: 300,
        },
      });
      console.log('Annotation added successfully');
    } catch (annotationError) {
      console.log('Could not add annotation:', annotationError.message);
      console.log('Proceeding without annotation...');
    }

    // Save the PDF
    const pdfBytes = await pdfDoc.save();
    fs.writeFileSync('annotationsample.pdf', pdfBytes);
    console.log('PDF created successfully: annotationsample.pdf');
  } catch (error) {
    console.error('Error creating PDF:', error);
  }
}

// Run the function
createAnnotatedPDF();

Suggested Reading?

Anything Else?

N/A

Checklist

• I read CONTRIBUTING.md.
• I read MAINTAINERSHIP.md#pull-requests.
• I added/updated unit tests for my changes.
• I added/updated integration tests for my changes.
• I ran the integration tests.
• I tested my changes in Node, Deno, and the browser.
• I viewed documents produced with my changes in Adobe Acrobat, Foxit Reader, Firefox, and Chrome.
• I added/updated doc comments for any new/modified public APIs.
• My changes work for both new and existing PDF files.
• I ran the linter on my changes.

[Sharcoux]

Changing eslint and the yarn.lock doesn't seem related to that PR. Can you split it into 2 PRs please?

[konbraphat51]

Okey, this PR is ready for review!

[Sharcoux]

According to the PDF Spec, the order should be: leftBottom, rightBottom, rightTop, leftTop, meaning that you probably inverted the top part.

[konbraphat51]

Oh, sorry for that. I fixed it

[konbraphat51]

Wait, I remembered now why I did this.

https://stackoverflow.com/questions/9855814/pdf-spec-vs-acrobat-creation-quadpoints

It seems that Adobe implemented the last two corners horizontally inverted.

I tried the order in the spec and became like this hourglass shape:

/QuadPoints [69.9398 58.8418 96.5932 58.8418 96.5932 47.3526 69.9398 47.3526 ] 

[konbraphat51]

↑forgot to mention: The image is rendered by Adobe Acrobat

[Sharcoux]

We need to test in multiple readers, then. If Adobe Acrobat failed to respect the spec and other reader respected it, we need to give priority to the spec because Adobe will probably have to comply at some point.

[Sharcoux]

That's a very annoying data format. Please use Rect instead. Way easier to manipulate!

[konbraphat51]

Do you mean Rect as src\utils\elements\Rectangle.ts?

Actually, qualPoints also covers trapezoids and hourglass shapes, not only rectangles. So I think that is not a good idea

my experiments (sorry it's in Japanese): https://qiita.com/konbraphat51/items/a7ddb30e5277d5e10a5a#%E8%9D%B6%E3%81%A4%E3%81%8C%E3%81%84

[Sharcoux]

Border

[Sharcoux]

Should we use lookupMaybe instead?

[Sharcoux]

Add a test to edit an existing annotation