Define background color and transparency of link annotation in PDF

Question

The following code corresponds to a minimal PDF page with a link annotation defined by a rectangle and a text inside it:

%PDF-1.4
1 0 obj
<>
endobj
3 0 obj
<>
endobj
4 0 obj
<>>>>>/Contents 2 0 R/Annots [<>>>]>>
endobj
2 0 obj
<>
stream
BT /F1 24 Tf 1 0 0 1 115 415 Tm (Go to StackOverflow)Tj
ET
endstream
xref
0 5
0000000060 65535 f
0000000009 00000 n
0000000441 00000 n
0000000055 00000 n
0000000106 00000 n
trailer
<>
startxref
540
%%EOF

How can I set the background color and transparency of the annotation? For example, I want to make the background (of the link box, not of the whole page) cyan but still be able to read the text "Go to Stackoverflow".

I've checked the ISO standard but it's a horrible text. It seems it could be through "Appearance Streams" (Annotation Properties a.k.a. /AP) but can't quite figure out how to do it. I was hoping though there is a more straightforward way (à la /C [ 0 1 1] ) that I might be missing.

I´m trying to learn to write PDF files from scratch as a first step write my own code for manipulating PDFs. Also, learning some things I want may help in hacking some already available library w/o wasting time in deciphering code I don´t need.

Thanks.

Note: If you copy&paste the code to test it, make sure the last character of each line is a newline, i.e., no space nor tabs after the last visible character. The byte counts seen depend on this.

EDIT: The annotation appearance of mine which I have problems getting it to work with. The annotation entry

<>

and the corresponding form XObject

10 0 obj
<>
stream
4 w q /GS0 gs 105.0 405.0 240.0 040.0 re 1.0 0.0 0.0 rg 0.0 0.0 1.0 RG B Q
endstream
endobj

I get no link highlighting nor border on screen as per this form.

mkl · Accepted Answer

Link annotation transparent background

The PDF specification for Link annotations only defines settings to customize the border (Border, C, BS) and the highlighting mode, i.e. the visual effect that shall be used when the mouse button is pressed or held down inside its active area (H). So, nothing to set the normal background.

In such a situation you always can resort to providing a customized appearance stream (AP) which indeed may provide transparency:

Starting with PDF 1.4, an annotation appearance may include transparency. If the appearance’s stream dictionary does not contain a Group entry, it shall be treated as a non-isolated, non-knockout transparency group. Otherwise, the isolated and knockout values specified in the group dictionary (see 11.6.6, “Transparency Group XObjects”) shall be used.

(Section 12.5.5 - Appearance Streams - in ISO 32000-1)

So you might try this approach.

Unfortunately, though, the specification specifies AP as follows:

AP dictionary (Optional; PDF 1.2) An appearance dictionary specifying how the annotation shall be presented visually on the page (see 12.5.5, “Appearance Streams”). Individual annotation handlers may ignore this entry and provide their own appearances.

Thus, any PDF viewer may ignore your custom appearance and provide its own link visualization.

Your only sure way to add some colored background to the content below the link annotation, therefore, is to already add that background to the page content. You can do this e.g. by adding a colored rectangle under the existing content. If the content is not text but some image, you can alternatively draw a colored rectangle over the existing content using transparency or (even better) a blend mode Darken or Multiply.

A validity issue

One remark: The way you add the annotation to the page is not valid: In your Page object you have

<>>>]>>

In particular you define the annotation using a direct dictionary object in the Annots array. But the specification requires:

Annots array (Optional) An array of annotation dictionaries that shall contain indirect references to all annotations associated with the page (see 12.5, "Annotations").

(Table 30 – Entries in a page object - in ISO 32000-1)

So the array is required to contain indirect references to the annotation dictionaries.

PDF viewers, in particular Adobe Reader, will not complain because they usually are quite lax concerning validity of the viewed PDFs, but other PDF processing software might run into issues.

An example appearance

You commented

I'm struggling with adding a minimal /AP resources to that example of mine. Can you provide one?

Here the objects building a page with content text with a link over it and an appearance stream with a special blend mode:

4 0 obj
<>>>
endobj
5 0 obj
<>stream
/F1 15 Tf
BT
100 500 Td
(Test)Tj
ET
endstream
endobj
7 0 obj
<>>>/Annots[4 0 R]/Contents 5 0 R/Parent 6 0 R>>
endobj
1 0 obj
<>
endobj
2 0 obj
<>>>/BBox[0 0 39.18 21]/FormType 1/Matrix [1 0 0 1 0 0]/Length 34>>stream
/GS1 gs
0 1 0 rg
0 0 39.18 21 re
f
endstream
endobj
3 0 obj
<>
endobj

Unfortunately it turns out that Adobe Reader decides to ignore this appearance stream when displaying the PDF

In other viewers, though, in particular in previewers which tend to simply take the given appearances, you see this

Interestingly enough Adobe Acrobat 9.5 export-as-image does use the appearance stream... It's a weird world after all...

Define background color and transparency of link annotation in PDF

Answers (1)

Link annotation transparent background

A validity issue

An example appearance

Related Questions