Discussion about bubble filling

This document grows out of the ongoing email thread about cross-platform PDF functionality and ballot-marking. I mean it to be both informative and discussion-prompting; please comment, edit, etc.

It is important to remember what PDF actually is. Wikipedia has a rather complete article on the format, but I point you to the section on technical foundations:

A PDF file is often a combination of vector graphics, text, and bitmap graphics. The basic types of content in a PDF are:

• Text stored as content streams (i.e., not encoded in plain text);
• Vector graphics for illustrations and designs that consist of shapes and lines;
• Raster graphics for photographs and other types of images
• Multimedia objects in the document.

In later PDF revisions, a PDF document can also support links (inside document or web page), forms, JavaScript (initially available as a plugin for Acrobat 3.0), or any other types of embedded contents that can be handled using plug-ins.

In other words, PDF could stand for Portmanteau Document Format: it is a structured document containing metadata and datastreams of various sorts that make it possible for programs to render vector graphics, text, and bitmaps to devices like printers and displays, and for various sorts of device-independent interactivity to be effected. You don’t care about that.

Let me repeat: you do not care about that.

Why not? Because you are not using any of those features of PDF in your application, save one: the raster graphic stream. For your application, PDF is simply a wrapper around a bitmap. BallotMaker does use the open-source version of ReportLab, which creates PDFs, but a quick look over the draw.py file seems to suggest it is simply drawing to a raster canvas. I could be entirely mistaken; ReportLab is a big library, and I’ve never used it; you should without question consult with your developer to confirm.

And I’ll have some suggestions about how better to use PDF in a minute.

If I am correct, though, the fact that BallotMaker generates a PDF is only an encumbrance for your mobile apps; what they really want is the bitmap contained in that PDF, which they must draw on and then re-serialize as a brand-new PDF so that the bitmap may be printed on a printer in a device-independent way.

Why is this important?

Because your developers do not have to worry about ios or android PDF libraries or SDKs; your mobile apps do not need them. They can use native drawing libraries to paint on the bitmap. All they need is some position information and some dimension information in order to draw black bubbles. The only use they might have for a PDF library at this point is to embed the bitmap in a PDF file, so that it can be printed using standard printing software.

But PDF might be useful in solving your other problems: how to tell the apps where to draw the black bubbles (and write-in text), and how to know the dimensions of those black bubbles. Because PDF is a a portmanteau format, you can include any number of streams in it, in addition to the bitmap. So, for example, BallotMaker might embed a properly proportioned black-bubble image as a separate stream, which the mobile apps could use as a kind of stamp. Or BallotMaker might include the bubble image ins an XMP by converting it to Base64.

Either of these techniques (separate stream, XMP) could also be used to bundle the position data, and even the entire CRV, rather than passing them around as separate files.