Adding Author and Callout on Freetext Annotations

[Kuma-99]

Hi guys,

I am writing to you to request a much needed update on PyPDF2 library. You see, I am a civil engineer, who has to deal with editing and commenting on layout plans from architects. This library comes so close to solving so many inefficiencies for me. I am aware that the pypdf2 library comes with the annotation builder which is exactly what I need to make comments but it does not have the leader line (callouts) that allows me to point out objects from the pdf drawing as well as include the authors name. After going through your code I am a little perplexed on how I can accomplish my idea by supplementing your library with what I think should be a few lines of code.

Please advise, the amount of back date work I have is overwhelming.

Thank you

[MartinThoma]

After going through your code I am a little perplexed on how I can accomplish my idea by supplementing your library with what I think should be a few lines of code.

Did you look up the PDF reference if "leader line" is supported?

If it isn't (what I would guess) then you have to create this with (multiple) line annotations: https://pypdf2.readthedocs.io/en/stable/user/adding-pdf-annotations.html#line

Arrow heads might be directly supported though.

[Kuma-99]

No it is not supported. But I am guessing that it shouldn't be too difficult to add this feature by editing the library. I extrapolate this because the independent objects are available (line and text box)

[MartinThoma]

If it's not that difficult, you can also do it directly in your code 😁

[pubpub-zz]

From your original comments, I understand that you are looking for adding Author, and the callout. Remember that the AnnotationBuilder creates a dictionnary that is in accordance with the PDF reference document. Therefore you can easily complete it:
As @martin said it does not require upgrade in pypdf:

you will just need to have the type conversion adding:
from pypdf.generic import ArrayObject, FloatObject, NameObject, TextStringObject

then you can add author easily:
annotation[NameObject("/T")]=TextStringObject("Author")

and for the callout (page 624-625 in pdf 1.7 reference):
annotation[NameObject("/CL")] = ArrayObject([FloatObject(x1),FloatObject(y1),FloatObject(x2),FloatObject(y2),FloatObject(y2),FloatObject(x3),FloatObject(y3)])

[MartinThoma]

Nice! So you already found a solution 🎉

As /CL is part of the PDF standard, I agree that pypdf should support it.

I suggest adding a new optional parameter callout: Optional[Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]] to the free_text function. Do you want to open a PR for that?

[pubpub-zz]

@MartinThoma
We may propose functions to complete the minimal core annotations as you have produced : in order to be more adaptative and prevent creation call with too many parameters that may be exclusive from each other.

PS : can you rename the title to "add Author and callout on freetext annotations" to ease finding the information

@Kuma-99
Can you confirm that this is good for you

[Kuma-99]

Yes i can confirm this would be great for me, But i cant seem to get it to work. I am very likely doing something wrong. Here is what i did so far to edit the _annotations.py:

from typing import Optional, Tuple, Union

from ._base import (
    BooleanObject,
    FloatObject,
    NameObject,
    NumberObject,
    TextStringObject,
)
from ._data_structures import ArrayObject, DictionaryObject
from ._fit import DEFAULT_FIT, Fit
from ._rectangle import RectangleObject
from ._utils import hex_to_rgb


class AnnotationBuilder:
    """
    The AnnotationBuilder creates dictionaries representing PDF annotations.

    Those dictionaries can be modified before they are added to a PdfWriter
    instance via `writer.add_annotation`.

    See `adding PDF annotations <../user/adding-pdf-annotations.html>`_ for
    it's usage combined with PdfWriter.
    """

    from ..types import FitType, ZoomArgType

    @staticmethod
    def text(
        rect: Union[RectangleObject, Tuple[float, float, float, float]],
        text: str,
        open: bool = False,
        flags: int = 0,
    ) -> DictionaryObject:
        """
        Add text annotation.

        :param Tuple[int, int, int, int] rect:
            or array of four integers specifying the clickable rectangular area
            ``[xLL, yLL, xUR, yUR]``
        :param bool open:
        :param int flags:
        """
        # TABLE 8.23 Additional entries specific to a text annotation
        text_obj = DictionaryObject(
            {
                NameObject("/Type"): NameObject("/Annot"),
                NameObject("/Subtype"): NameObject("/Text"),
                NameObject("/Rect"): RectangleObject(rect),
                NameObject("/Contents"): TextStringObject(text),
                NameObject("/Open"): BooleanObject(open),
                NameObject("/Flags"): NumberObject(flags),
            }
        )
        return text_obj

    @staticmethod
    def free_text(
        author: str,
        text: str,
        rect: Union[RectangleObject, Tuple[float, float, float, float]],
        font: str = "Helvetica",
        bold: bool = False,
        italic: bool = False,
        font_size: str = "14pt",
        font_color: str = "000000",
        border_color: str = "000000",
        background_color: str = "ffffff",
        #: Optional[Tuple[Tuple[float, float], Tuple[float, float]]] = None,
        callout: Optional[Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]],  
    ) -> DictionaryObject:
        """
        Add text in a rectangle to a page.

        :param str text: Text to be added
        :param RectangleObject rect: or array of four integers
            specifying the clickable rectangular area ``[xLL, yLL, xUR, yUR]``
        :param str font: Name of the Font, e.g. 'Helvetica'
        :param bool bold: Print the text in bold
        :param bool italic: Print the text in italic
        :param str font_size: How big the text will be, e.g. '14pt'
        :param str font_color: Hex-string for the color
        :param str border_color: Hex-string for the border color
        :param str background_color: Hex-string for the background of the annotation
        """
        font_str = "font: "
        if bold is True:
            font_str = font_str + "bold "
        if italic is True:
            font_str = font_str + "italic "
        font_str = font_str + font + " " + font_size
        font_str = font_str + ";text-align:left;color:#" + font_color

        bg_color_str = ""
        for st in hex_to_rgb(border_color):
            bg_color_str = bg_color_str + str(st) + " "
        bg_color_str = bg_color_str + "rg"

        free_text = DictionaryObject()
        free_text.update(
            {
                NameObject("/Type"): NameObject("/Annot"),
                NameObject("/Subtype"): NameObject("/FreeText"),
                NameObject("/Rect"): RectangleObject(rect),
                NameObject("/Contents"): TextStringObject(text),
                # font size compile(source, filename, mode)lor
                NameObject("/DS"): TextStringObject(font_str),
                # border color
                NameObject("/DA"): TextStringObject(bg_color_str),
                # background color
                NameObject("/C"): ArrayObject(
                    [FloatObject(n) for n in hex_to_rgb(background_color)]
                ),
                NameObject("/T")=TextStringObject(author)
                NameObject("/CL") = ArrayObject([FloatObject(x1),FloatObject(y1),FloatObject(x2),FloatObject(y2),FloatObject(y2),FloatObject(x3),FloatObject(y3)])
                
                # NameObject("/Rect"): RectangleObject(rect),
                # NameObject("/Contents"): TextStringObject(text),
                # # font size compile(source, filename, mode)lor
                # NameObject("/DS"): TextStringObject(font_str),
                # # border color
                # NameObject("/DA"): TextStringObject(bg_color_str),
                # # background color
                # NameObject("/C"): ArrayObject(
                #     [FloatObject(n) for n in hex_to_rgb(background_color)]
                # ),
                # callout line
                #NameObject("/Line"): RectangleObject(line),
                #NameObject("/LE"): RectangleObject(le),
            }
        )
        if border_color is None:
            # Border Style
            free_text[NameObject("/BS")] = DictionaryObject(
                {
                    # width of 0 means no border
                    NameObject("/W"): NumberObject(0)
                }
            )
        if background_color is not None:
            free_text[NameObject("/C")]
            
        return free_text

    @staticmethod
    def line(
        p1: Tuple[float, float],
        p2: Tuple[float, float],
        rect: Union[RectangleObject, Tuple[float, float, float, float]],
        text: str = "",
        title_bar: str = "",
    ) -> DictionaryObject:
        """
        Draw a line on the PDF.

        :param Tuple[float, float] p1: First point
        :param Tuple[float, float] p2: Second point
        :param RectangleObject rect: or array of four
                integers specifying the clickable rectangular area
                ``[xLL, yLL, xUR, yUR]``
        :param str text: Text to be displayed as the line annotation
        :param str title_bar: Text to be displayed in the title bar of the
            annotation; by convention this is the name of the author
        """
        line_obj = DictionaryObject(
            {
                NameObject("/Type"): NameObject("/Annot"),
                NameObject("/Subtype"): NameObject("/Line"),
                NameObject("/Rect"): RectangleObject(rect),
                NameObject("/T"): TextStringObject(title_bar),
                NameObject("/L"): ArrayObject(
                    [
                        FloatObject(p1[0]),
                        FloatObject(p1[1]),
                        FloatObject(p2[0]),
                        FloatObject(p2[1]),
                    ]
                ),
                NameObject("/LE"): ArrayObject(
                    [
                        NameObject(None),
                        NameObject(None),
                    ]
                ),
                NameObject("/IC"): ArrayObject(
                    [
                        FloatObject(0.5),
                        FloatObject(0.5),
                        FloatObject(0.5),
                    ]
                ),
                NameObject("/Contents"): TextStringObject(text),
            }
        )
        return line_obj

    @staticmethod
    def rectangle(
        rect: Union[RectangleObject, Tuple[float, float, float, float]],
        interiour_color: Optional[str] = None,
    ) -> DictionaryObject:
        """
        Draw a rectangle on the PDF.

        :param RectangleObject rect: or array of four
                integers specifying the clickable rectangular area
                ``[xLL, yLL, xUR, yUR]``
        """
        square_obj = DictionaryObject(
            {
                NameObject("/Type"): NameObject("/Annot"),
                NameObject("/Subtype"): NameObject("/Square"),
                NameObject("/Rect"): RectangleObject(rect),
            }
        )

        if interiour_color:
            square_obj[NameObject("/IC")] = ArrayObject(
                [FloatObject(n) for n in hex_to_rgb(interiour_color)]
            )

        return square_obj

    @staticmethod
    def link(
        rect: Union[RectangleObject, Tuple[float, float, float, float]],
        border: Optional[ArrayObject] = None,
        url: Optional[str] = None,
        target_page_index: Optional[int] = None,
        fit: Fit = DEFAULT_FIT,
    ) -> DictionaryObject:
        """
        Add a link to the document.

        The link can either be an external link or an internal link.

        An external link requires the URL parameter.
        An internal link requires the target_page_index, fit, and fit args.


        :param RectangleObject rect: or array of four
            integers specifying the clickable rectangular area
            ``[xLL, yLL, xUR, yUR]``
        :param border: if provided, an array describing border-drawing
            properties. See the PDF spec for details. No border will be
            drawn if this argument is omitted.
            - horizontal corner radius,
            - vertical corner radius, and
            - border width
            - Optionally: Dash
        :param str url: Link to a website (if you want to make an external link)
        :param int target_page_index: index of the page to which the link should go
                                (if you want to make an internal link)
        :param Fit fit: Page fit or 'zoom' option.
        """
        from ..types import BorderArrayType

        is_external = url is not None
        is_internal = target_page_index is not None
        if not is_external and not is_internal:
            raise ValueError(
                "Either 'url' or 'target_page_index' have to be provided. Both were None."
            )
        if is_external and is_internal:
            raise ValueError(
                f"Either 'url' or 'target_page_index' have to be provided. url={url}, target_page_index={target_page_index}"
            )

        border_arr: BorderArrayType
        if border is not None:
            border_arr = [NameObject(n) for n in border[:3]]
            if len(border) == 4:
                dash_pattern = ArrayObject([NameObject(n) for n in border[3]])
                border_arr.append(dash_pattern)
        else:
            border_arr = [NumberObject(0)] * 3

        link_obj = DictionaryObject(
            {
                NameObject("/Type"): NameObject("/Annot"),
                NameObject("/Subtype"): NameObject("/Link"),
                NameObject("/Rect"): RectangleObject(rect),
                NameObject("/Border"): ArrayObject(border_arr),
            }
        )
        if is_external:
            link_obj[NameObject("/A")] = DictionaryObject(
                {
                    NameObject("/S"): NameObject("/URI"),
                    NameObject("/Type"): NameObject("/Action"),
                    NameObject("/URI"): TextStringObject(url),
                }
            )
        if is_internal:
            # This needs to be updated later!
            dest_deferred = DictionaryObject(
                {
                    "target_page_index": NumberObject(target_page_index),
                    "fit": NameObject(fit.fit_type),
                    "fit_args": fit.fit_args,
                }
            )
            link_obj[NameObject("/Dest")] = dest_deferred
        return link_obj

[pubpub-zz]

@Kuma-99
You don't need to change anything in pypdf : the code I've provided is to be used outside pypdf:
this is an example:

from pypdf import PdfReader, PdfWriter
from pypdf.generic import AnnotationBuilder, ArrayObject, FloatObject, NameObject, TextStringObject

# Fill the writer with the pages you want
pdf_path = 'e:/Downloads/demo.pdf'
reader = PdfReader(pdf_path)
page = reader.pages[0]
writer = PdfWriter()
writer.add_page(page)

# Create the annotation and add it
annotation = AnnotationBuilder.free_text(
    "Hello World\nThis is the 测试!",
    rect=(50, 550, 200, 650),
    font="Arial",
    bold=True,
    italic=True,
    font_size="20pt",
    font_color="00ff00",
    border_color="0000ff",
    background_color="cdcdcd",
)

annotation[NameObject("/T")]=TextStringObject("I'm the Author")
annotation[NameObject("/CL")] = ArrayObject([FloatObject(400),FloatObject(400),
                                             FloatObject(300),FloatObject(500),
                                             FloatObject(200),FloatObject(575)])
annotation[NameObject("/IT")] = NameObject("/FreeTextCallout") # not to be forgotten

writer.add_annotation(page_number=0, annotation=annotation)

# Write the annotated file to disk
writer.write("e:/tt2a.pdf")

[Kuma-99]

Yes this is exactly what i needed. Thank you so much. I have a couple of queries, is there a way to specify the line ending as open arrow ? And one more thing, when I open the pdf file using pdf xchange, the callout textbox appears but the leader line doesnt show, until I manually adjust its position.

[Kuma-99]

I have found the answer to the line ending part, by just adding the following line to @pubpub-zz answer:

annotation[NameObject("/LE")] = NameObject("/OpenArrow")

The latter still remains to be unsolved. Is the a pdf refresh method that should be called to ensure the leader generates with the textbox ?

[pubpub-zz]

I've found the problem
for PDFXchange (and for PDF.js too) the /Rect field should contains the callout function
the CL field define the difference / reduction fom rect to the box that contains the text:

Adobe Reader is more permissive and does not limit the drawing of the callout line.

PS : can you rename the title to "add Author and callout on freetext annotations" to ease finding the information for other users

[Kuma-99]

Ive never been happier to someone reply on this platform. Okay so lets get down to business, i tried to add a new name object “/rect” above the CL line with corresponding four float object to specific the rect[1], rect[2] etc. But i keep getting not a pdf object error. I also tried to sift through the pdf 1.7 documentation you recommended but i had no luck. Im likely doing something coherently wrong, would you explain or give me an example in this context

[Kuma-99]

The before and after image shows the appearance of the leader line after the callout box is moved manually. Any explanation for this ? still cant figure this out @pubpub-zz

[Kuma-99]

My bad, here is the code I used for context. It is marginally edited using the code provided by @pubpub-zz with the added lines of the RD and CL. Is there something im missing.

from pypdf import PdfReader, PdfWriter
from pypdf.generic import AnnotationBuilder, ArrayObject, FloatObject, NameObject, TextStringObject

# Fill the writer with the pages you want
filepath = 'C:/Users/kumaran/Desktop/Piling Progress Layout (Block E).pdf'
reader = PdfReader(filepath)
page = reader.pages[0]
writer = PdfWriter()
writer.add_page(page)

x_top_edge = 200;
y_top_edge = 200;
rect_width = 102;
rect_height = 44;
COL=""

# Create the annotation and add it
annotation = AnnotationBuilder.free_text(
    text="COL="+COL+"mRL",
    rect=(0,0, (rect_width), (rect_height)), #i think this is the internal square defined by the difference between the internal square and external square
    font="Arial",
    bold=False,
    italic=False,               
    font_size="12pt",
    font_color="000000",
    border_color="FF0000",
    background_color="FFFF00",
)
#rect=(0, 0, 102, 44),
annotation[NameObject("/T")]=TextStringObject("Jane Doe")
annotation[NameObject("/IT")] = NameObject("/FreeTextCallout")
annotation[NameObject("/RD")] = ArrayObject([FloatObject(0),FloatObject(0),FloatObject(0),FloatObject(0)]) #this is the external square
annotation[NameObject("/CL")] = ArrayObject([FloatObject(x_top_edge),FloatObject(y_top_edge), #i think the /RD also contains the callout leader line
                                             FloatObject(rect_width+30),FloatObject(rect_height/2),            
                                             FloatObject(rect_width),FloatObject(rect_height/2)])
annotation[NameObject("/LE")] = NameObject("/OpenArrow")
#NameObject('/CL'): ArrayObject([FloatObject(0), FloatObject(0), FlatObject(100), FloatObject(0), FloatObject(100), FloatObject(-50)]), # Callout box corners


writer.add_annotation(page_number=0, annotation=annotation)

# Write the annotated file to disk
writer.write(filepath)

[pubpub-zz]

I'm a little confused about you code.
at first glance(not tested - missing time) and from my memories:
rect should contact the whole annotation including the arrow
/CL should provide absolute coordinates for the arrow
/RD seems not properly calculated : It should define the value to be subtracted to compute the inner box (I used /CL wrongly instead of /RD for the definition of the inner box.
Can you give a feedback with these recommendations

[Kuma-99]

@pubpub-zz it looks like youre telling me that the rect is supposed to contain the /RD and /CL objects. But when i tried this i getting the following error: SyntaxError: expression cannot contain assignment, perhaps you meant "=="?. Could you please show me a demo of the proper code

[pubpub-zz]

Rect shall contain both RD AND CL which are independant from each other.
also,for best compatibility, ensure Rect is LL/UR

I've corrected your code in order to get the following result:

from pypdf import PdfReader, PdfWriter
from pypdf.generic import AnnotationBuilder, ArrayObject, FloatObject, NameObject, TextStringObject

# Fill the writer with the pages you want
filepath = 'resources/crazyones.pdf'
reader = PdfReader(filepath)
page = reader.pages[0]
writer = PdfWriter()
writer.add_page(page)

x_top_edge = 200;
y_top_edge = 600;
rect_width = 102;  # considered only for the textbox only
rect_height = 64;
cl_x = x_top_edge + rect_width;
cl_y = y_top_edge - rect_height/2;
cl_width = 50;
cl_height = rect_height;
full_width = rect_width + cl_width;
full_height = y_top_edge - (cl_y - rect_height);
COL=""

# Create the annotation and add it
annotation = AnnotationBuilder.free_text(
    text="COL="+COL+"mRL",
    rect=(x_top_edge, y_top_edge - full_height, x_top_edge + full_width, y_top_edge), #the whole rect (LL/ UR); other distrib should work but seem to disturb acrobat reader
    font="Arial",
    bold=False,
    italic=False,               
    font_size="12pt",
    font_color="000000",
    border_color="FF0000",
    background_color="FFFF00",
)
#rect=(0, 0, 102, 44),
annotation[NameObject("/T")]=TextStringObject("Jane Doe")
annotation[NameObject("/IT")] = NameObject("/FreeTextCallout")
annotation[NameObject("/RD")] = ArrayObject([FloatObject(0),FloatObject(full_height-rect_height),
                                             FloatObject(full_width-rect_width),FloatObject(0)]) #distance from external to internal text area
annotation[NameObject("/CL")] = ArrayObject([FloatObject(cl_x + cl_width),FloatObject(cl_y - cl_height), 
                                             FloatObject(cl_x + cl_width/2),FloatObject(cl_y),            
                                             FloatObject(cl_x),FloatObject(cl_y)])  # CL is outside RD
annotation[NameObject("/LE")] = NameObject("/OpenArrow")

writer.add_annotation(page_number=0, annotation=annotation)

# Write the annotated file to disk
writer.write("e:/output.pdf")