How to use annotation layer in PDF.js?

Question

Some of the PDF.js code mentions an "annotation layer", for example AnnotationLayerBuilder here:

https://github.com/mozilla/pdf.js/blob/95e102c07bc257c2120fd7fd9141762b2c813a1c/web/annotation_layer_builder.js#L118

There is also pdfDocument.annotationStorage and pdfjsLib.AnnotationLayer, which - on all the documents I've tried - are empty, even in documents which do have text annotations.

I couldn't find any examples or documentation on the annotation layer and how it is supposed to be used, but it sure sounds interesting :)

1. What is the annotation layer? Is this talking about standard PDF annotations, as described in https://pspdfkit.com/blog/2018/what-are-annotations/ or https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/pdf_reference_1-7.pdf section 8.4 Annotations? Or, is it something internal to PDF.js?

2. How do I list the existing annotations from javascript code in PDF.js, and how do I add one? (just for display; not expecting to be able to save it in the pdf, of course) Can anyone provide a working code example?

Thanks!

Valentine

Answer 1

Annotations are standard for the PDF file format as described in the links you provided. They are not a new concept to PDF.js.

How you get the annotations will depend on your situation. I'm building a view layer to replace the viewer the PDF.js team built. The basic idea there is you:

1. Get a reference to the PDFDocumentProxy object via const doc = getDocument(url)
2. Get a reference to a PDFPageProxy object via const page = await doc.getPage(num)
3. Get the annotations via await page.getAnnotations()

If you're already using the viewer they built, it doesn't appear to be exposed anywhere.

Wellturned

Also, the annotation data they expose is limited. Square annotations, for example, don't include the fill color. Stamp annotations have no useful information in them but the location on the page. – Wellturned

is this still true? I'm about to start building a tool to extract specific annotations and would rather not learn this the hard way. – Jeramyjerba

@JimB. Curious if you found out more about this - please post an answer if you have more info :) Thanks! – Valentine

The older PDF annotation layers for PDF.js were deprecated in 2018 (see github.com/instructure/pdf-annotate.js). A fairly active fork of it is being maintained here: github.com/Submitty/pdf-annotate.js. Additionally, new annotation capabilities are being added into PDF.js right now (March 2024), as tracked in github.com/mozilla/pdf.js/projects/9 – Prosopopoeia

Answer 2

I tested a lot and found that we can get a serialized map from annotation storage using the code below.

I tested in PDF.js version 4.1 Web Viewer

// pdfPage is PDFPageProxy
var map = pdfPage._transport.annotationStorage.serializable.map);
console.log(map);

or you can use PDFViewerApplication directly using this code:

var map = PDFViewerApplication.pdfDocument.annotationStorage.serializable.map
console.log(map);

The output is something like this for 2 highlight on my document:

new Map([
    [
        "pdfjs_internal_editor_0",
        {
            "annotationType": 9,
            "color": [
                255,
                255,
                152
            ],
            "opacity": 1,
            "thickness": 12,
            "quadPoints": [
                273.8922975645478,
                286.49837430244895,
                307.9118745522762,
                286.49837430244895,
                273.8922975645478,
                298.43025788406993,
                307.9118745522762,
                298.43025788406993
            ],
            "outlines": [
                [
                    293.46318179269997,
                    305.8562940786,
                    293.46318179269997,
                    319.0560937007,
                    328.3637086942,
                    319.0560937007,
                    328.3637086942,
                    305.8562940786
                ]
            ],
            "pageIndex": 1,
            "rect": [
                293.46318179269997,
                305.8562940786,
                328.3637086942,
                319.0560937007
            ],
            "rotation": 0,
            "structTreeParentId": "p1R_mc1"
        }
    ],
    [
        "pdfjs_internal_editor_1",
        {
            "annotationType": 9,
            "color": [
                83,
                255,
                188
            ],
            "opacity": 1,
            "thickness": 12,
            "quadPoints": [
                192.48288494984837,
                274.49724318218466,
                220.0817548219673,
                274.49724318218466,
                192.48288494984837,
                286.42912676380564,
                220.0817548219673,
                286.42912676380564
            ],
            "outlines": [
                [
                    212.05615395499998,
                    293.8510464585,
                    212.05615395499998,
                    307.05084608059997,
                    240.51350665929996,
                    307.05084608059997,
                    240.51350665929996,
                    293.8510464585
                ]
            ],
            "pageIndex": 1,
            "rect": [
                212.05615395499998,
                293.8510464585,
                240.51350665929996,
                307.05084608059997
            ],
            "rotation": 0,
            "structTreeParentId": null
        }
    ]
])

Pryor