Link

Annotations JSON API

This document describes the structure of the annotations.json file. To learn more about how annotations work in BuildVu, please read How do annotations work in BuildVu?

We provide a simple implementation for loading and displaying annotations which is used inside the IDRViewer. You are welcome to use this implementation as-provided, for inspiration, or as the basis of your own custom solution.

Basic structure:

{
    "pages": [{
            "page": 1,
            "annotations": [{
                    "type": "Highlight",
                    "bounds": [0, 0, 100, 100],
                    "objref": "255", (optional)
                    "contents": "contents value", (optional)
                    "appearance": "1/annots/255.png" (optional)
                }
            ]
        }
    ]
}

Annotation types ("type"): Text, Link, FreeText, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret, Ink, FileAttachment, Sound, Movie, Widget, Screen, PrinterMark, TrapNet, Watermark, 3D, Projection, RichMedia, Screen, TextLink

Bounds ("bounds"): Supplied in the format [x, y, width, height] with top-left origin.

Object Reference ("objref"): The object reference for the annotation within the PDF file. Object references are not available in two situations:

  1. In rare cases when the annotations are defined using an inline array.
  2. When TextLink annotations are generated from links detected from the PDF file.

Contents ("contents"): Typically the plaintext content of popup annotations or a description of the annotation (if provided).

Appearance ("appearance"): A rasterised version of the appearance (AP) stream in the ‘normal’ state (if AP dictionary is provided).

Type Specific Values:

{
    "type": "Highlight",
    "bounds": [0, 0, 100, 100],
    "objref": "255", (optional)
    "title": "title value", (optional)
    "contents": "contents value", (optional)
    "appearance": "1/annots/255.png" (optional)
}
{
    "type": "Link",
    "bounds": [0, 0, 100, 100],
    "objref": "255", (optional)
    "title": "title value", (optional)
    "contents": "contents value", (optional)
    "action": { }, (optional)
    "appearance": "1/annots/255.png" (optional)
}

Action types: URI, GoTo, Named, Sound

Action specific values:

URI:

"action": {
    "type": "URI",
    "uri": "https://www.example.com"
}

GoTo:

"action": {
    "type": "GoTo",
    "page": 1
}

Named:

"action": {
    "type": "Named",
    "name": "NextPage"
}

Name types: NextPage, PrevPage, FirstPage, LastPage

Launch:

"action": {
    "type": "Launch",
    "target": "executable/or/file/path.pdf"
}

Sound:

"action": {
    "type": "Sound",
    "sound": "path/to/sound.wav"
}

FileAttachment:

{
    "type": "FileAttachment",
    "bounds": [0, 0, 100, 100],
    "objref": "255", (optional)
    "title": "title value", (optional)
    "contents": "contents value", (optional)
    "attachment": "path/to/attachment.pdf",
    "appearance": "1/annots/255.png" (optional)
}

RichMedia:

{
    "type": "RichMedia",
    "bounds": [0, 0, 100, 100],
    "objref": "255", (optional)
    "contents": "contents value", (optional)
    "richmedia": [{
        "src": "path/to/media.mp4",
        "type": "video/mp4"
    }],
    "appearance": "1/annots/255.png" (optional)
}

Supported video types: m4v, mov, mp4 (video/mp4)

Supported audio types: mp3 (audio/mpeg)

Screen:

{
    "type": "Screen",
    "bounds": [0, 0, 100, 100],
    "objref": "255", (optional)
    "action": {
        "type": "Rendition",
        "media": {
          "src": "path/to/media.mp4",
          "type": "video/mp4"
        }
    },
    "appearance": "1/annots/255.png" (optional)
}

Supported media types: mp4 (video/mp4), mp3 (audio/mpeg)

Still need help? Send us your questions.