GSoC/2021/StatusReports/Mahmoud Ahmed Khalil

Improve Custom/Image Stamp Annotation Handling in Okular

Okular is a powerful universal document reader that supports different types of document formats, one very important format is the PDF format. PDF files can have what is called an Annotation, an Annotation represents additional object that can be added to the document for clarification purposes, such objects can be text, shapes overlaid on the document, or even sounds/videos and other rich media formats.

A common annotation that is used in a lot of use cases and scenarios is a Stamp Annotation. Stamp Annotation is meant to be like a rubber stamp that gets added to the document. Currently Okular doesn't fully support Stamp Annotation, the reason is that the underlying rendering library we're using (Poppler) doesn't have means to add custom stamps, or in another words Poppler doesn't know yet how to take a stamp annotation and save it in the document in a way that other renderers can parse it and render it as well.

So, the goal of this project was to extend Poppler in order to be able to save new stamp annotations information so that we don't rely on how other renderers generate some of standard stamps and also they would have a way to render the custom ones. Ideally I wanted to make poppler render default standard stamps by itself without depending much on their appearance streams(think of this as a stream that represents instruction for the backend renderer to draw the stamps) but I'll be still working on this after GSoC.

Mentor

Albert Astals Cid

I communicated with my mentor daily by sending daily mails of the work done, we also had a weekly meeting to discuss future plans and to work on the current issues

Status Reports

The project is mainly divided into two parts, the first part where I extend the underlying libraries with the new functionality (Poppler/Qt5). The second part is the part in which we make use of the new functionality in Okular itself.

Poppler Status

Poppler Backend

Implemented a new helper class called `AnnotStampImageHelper`, this class takes in image data (width, height, color space, etc.) and create a new Image XObject (image that can be understood by poppler) and saves it in the document
Modified the `AnnotStamp` implementation to support the new functionality and reference the created object

Qt5 Frontend

Added new APIs to support the new functionality in Poppler
Extended the library to be able to extract the important information from a QImage and pass it to the `AnnotStampImageHelper` to be able to create image objects that will be added to the document
Created a wrapper class to hold in the important information about the appearance stream of the annotation so that users will be able to store it

Okular Status

Disabled Okular's Stamp rendering
Modified the `PopplerAnnotationProxy` class to call the new APIs
Stored stamps appearance streams so that we don't lose it upon deleting the annotation

Links

Here are the links for all the work done so far:

Also, here are the links for my blog posts:

Completed Tasks

Adding support to Poppler to save stamps with custom annotation appearance
Exposed the new APIs through Qt5 Frontend
Disable Okular's stamp rendering
Make use of the new exposed APIs in Okular

Also, here are some images of the completed work in different PDF viewers for the same file:

Partially Completed Tasks

Generating default stamps, in my MR above most of the default stamps works except for three stamps. I'll keep working on those.

Future Plan

I'm planning on continue working on fixing the default stamps issue. Also, there is something that would improve the delete/undo behavior in Okular regarding the stamps annotation, so I'll probably work on it after fixing the standard stamps. Also, I'll port all of my work to Qt6 Frontend so that it would be ready when we switch and port Okular to Qt6 in the future.

Contact Me

IRC Nickname: mkhalil