This week, Mako™ product manager David Stevenson explains vector flattening:
When you print PDF content or save or export it to other formats that do not support transparency, it will need to undergo a process called flattening. Flattening usually involves rasterizing areas of the page that are subject to transparency effects, which could mean replacing sharp-edged vector content with a jagged-edged bitmap. Of course, increasing the resolution of the rasterization can mitigate that problem, but doing so takes longer and adds to file size.
The alternative is to retain vector geometry, including text, as vector objects. This requires dividing the artwork down into smaller parts that no longer overlap, then tracing the edges of the new shapes with a vector path. In the latest release, Global Graphics Software’s Mako Core SDK (v6.2.0) adds this capability to its raster-based transparency flattening API. Using existing APIs that apply De Casteljau’s algorithm to decompose Bézier curves and a new method to trace around shapes, flattened content can retain its device independence and printing quality.
I’ve included a short demo of the vector-based transparency flattening feature using Mako here:
In this week’s post, Global Graphics Software’s principal engineer, Andrew Cardy, explores the structure tagging API in the Mako™ Core SDK. This feature is particularly valuable as it allows developers to create PDFs that can be read by screen readers, such as Jaws®. This helps blind or partially sighted users unlock the content of a PDF. Here, Andy explains how to use the structure tagging API in Mako to tag both text and images:
What can we Structure Tag?
Before I begin, let’s talk about PDF: PDF is a fixed-format document. This means you can create it once, and it should (aside from font embedding or rendering issues) look identical across machines. This is obviously a great thing for ensuring your document looks great on your user’s devices, but the downside is that some PDF generators can create fixed content that is ordered in a way that is hard for screen readers to understand.
Luckily Mako also has an API for page layout analysis. This API will analyze the structure of the PDF, and using various heuristics and techniques, will group the text on the page together in horizontal runs and vertical columns. It’ll then assign a page reading order.
The structure tagging API makes it easy to take the layout analysis of the page and use it to tag and structure the text. So, while we’re tagging the images, we’ll tag the text too!
Mako’s Structure Tagging API
Mako’s structure tagging API is simple to use. Our architect has done a great job of taking the complicated PDF specification and distilling it down to a number of useful APIs.
Let’s take a look at how we use them to structure a document from start to finish:
Setting the Structure Root
Setting the root structure is straight forward. Firstly, we create an instance of IStructure and set it in the document.
Next we create an instance of a Document level IStructureElement and add that to the structure element we’ve just created.
One thing that I learnt the hard way, is that Acrobat will not allow child structures to be read by a screen reader if their parent has alternative (alt) text set.
Add alternate text only to tags that don’t have child tags. Adding alternate text to a parent tag prevents a screen reader from reading any of that tag’s child tags. (Adobe Acrobat help)
Originally, when I started this research project, I had alt text set at the document level, which caused all sorts of confusion when my text and image alt text wasn’t read!
Using the Layout Analysis API
Now that we’ve structured the document, it’s time to structure the text. Firstly, we want to understand the layout of the page. To do this, we use IPageLayout. We give it a reference to the page we want to analyze, then perform the analysis on it.
Now the page has been analyzed, it’s easy to iterate through the columns and nodes in the page layout data.
Tagging the text
Once we’ve found our text runs, we can tag our text with a span IStructureElement. We append this new structure element to the parent paragraph created while we were iterating over the columns.
We also tag the original source Mako DOM node against the new span element.
Tagging the images
Once the text is structured, we can structure the images too.
Earlier, I used Microsoft’s Vision API to take the images in the document and give us a textual description of them. We can now take this textual description and add it to a figure IStructureElement.
Again, we make sure we tag the new figure structure element against the original source Mako DOM image.
Notifying Readers of the Structure Tags
The last thing we need to do is set some metadata in the document’s assembly, this is straight forward enough. Setting this metadata helps viewers to identify that this document is structure tagged.
Putting it all Together
So, after we’ve automated all of that, we now get a nice structure, which, on the whole, flows well and reads well.
We can see this structure in Acrobat DC:
And if we take a look at one of the images, we can see our figure structure now has some alternative text, generated by Microsoft’s Vision API. The alt text will be read by screen readers.
It’s not perfect, but then taking a look at how Adobe handles text selection quite nicely illustrates just how hard it is to get it right. In the image below, I’ve attempted to select the whole of the title text in Acrobat.
In comparison, our page layout analysis seems to have gotten these particular text runs spot on. But how does it fair with the Jaws screen reader? Let’s see it in action!
So, it does a pretty good job. The images have captions automatically generated, there is a sense of flow and most of the content reads in the correct order. Not bad.
Printing accessible PDFs
You may be aware that the Mako SDK comes with a sample virtual printer driver that can print to PDF. I want to take this one step further and add our accessibility structure tagging tool to the printer driver. This way, we could print from any application, and the output will be accessible PDF!
In the video below I’ve found an interesting blog post that I want to save and read offline. If I were partially sighted, it may be somewhat problematic as the PDF printer in Windows 10 doesn’t provide structure tagging, meaning that the PDF I create may not work so well with my combination of PDF reader and screen reader. However, if I throw in my Mako-based structure and image tagger, we’ll see if it can help!
Of course, your mileage will vary and the quality of the tagging will depend on the quality and complexity of the source document. The thing is, structural analysis is a hard problem, made harder sometimes by poorly behaving generators, but that’s another topic in itself. Until all PDF files are created perfectly, we’ll do the best we can!
Want to give it a go?
Please do get in touch if you’re interested in having a play with the technology, or just want to chat about it.
Andy Cardy is a Principal Engineer for Global Graphics Software and a Developer Advocate for the Mako SDK.
Find out more about Mako’s features in Andy’s coding demo:
In this session Andy uses coding in C++ and C# to show you three complex tasks that you can easily achieve with Mako:
• PDF rendering – visualizing PDF for screen and print (15 mins)
• Using Mako in Cloud-ready frameworks (15 mins)
• Analyzing and editing with the Mako Document Object Model (15 mins)
To be the first to receive our blog posts, news updates and product news why not subscribe to our monthly newsletter? Subscribe here
If you’re into code, then you’ll enjoy watching the recording of our recent webinar, Sharpen the saw: a live coding demo using Mako™.
Mako is a versatile SDK for building fast, scalable solutions for your print workflow. Its unique document object model uses Mako’s C++ and C# APIs to control color, fonts, text, images, vector content, metadata and more, combining precision with performance.
In the session, principal engineer Andy Cardy uses coding in C++ and C# to show you three complex tasks that you can easily achieve with Mako:
Using Mako in Cloud-ready frameworks
Analyzing and editing with the Mako Document Object Model
Look out for more sessions like this over the coming months.
We’ve recently released Mako™ 5.0, the latest edition of Global Graphics Software’s digital document SDK. Mako 5.0 earns its major version increment with an upgrade to its internal RIP, new features and a reworked API to simplify implementation. Much requested by Mako customers, Mako 5.0 is the first version to preview C# as a coding alternative to C++ and opens the possibility to support other programming languages in future versions.
Mako 5.0 enables PostScript® (including EPS) files to be read directly, extending the PDL (page description language) support in Mako that already includes PDF, XPS, PCL5 and PCL/XL. Mako can read and write all these PDLs, enabling bi-directional conversion between any of these formats.
With the update of Mako’s internal RIP has come new EDS (error diffusion screens) using algorithms such as Floyd-Steinberg and Stucki. All the screening parameters are exposed via this API, and to help define them, a Windows-based desktop tool can be downloaded from the Mako documentation site. Start with settings that match the popular algorithms and preview the monochrome or color result of your settings tweaks. Then use the settings you have chosen via a button that generates the C++ you need to paste into your code.
Mako 5.0 offers several new APIs that extend its reach into the internals of PDF. For example, it’s now possible to edit property values attached to form and image XObjects. Why is this useful? In PDF, developers can put extra key-value pairs into PDF XObject dictionaries. This is often used to store in application-specific data, as well as for things like variable data tags. This development has led to a more generalized approach to examining and modifying hard-to-reach PDF objects. As ever, well-commented sample code is provided to show exactly how the new APIs work and could be applied in your application.
Finally, we took the opportunity with Mako 5.0 to make changes aimed at making the APIs more consistent in their naming, behavior or return types. Developers new to Mako will be unaware of these changes, but existing code written for Mako 4.x may require minor refactoring to work with Mako 5.0. Our support engineers are ready to assist Mako customers with any questions they have.
Working with a Mako customer recently, I showed him how to code a utility to extract data from a stack of PDF invoices to populate a spreadsheet. I suppose you could describe it as reverse database publishing. This customer had originally licensed Mako to convert XPS to PDF, and later used it to generate CMYK bitmaps of the pages, i.e. using it as a RIP (raster image processor).
With this additional application of Mako, the customer observed that Mako was “like a Swiss Army knife” as it offered so many tools in one – converting, rendering, extracting, combining and processing, of pages and the components that made them up. And doing it not just for PDF but for XPS, PCL and PostScript® too. His description struck a chord with me as it seemed very appropriate. Mako does indeed offer a wide range of capabilities for processing print job formats. It’s not the fastest or feature-richest of the RIPs from Global Graphics Software – that would be Harlequin®. Or the most sophisticated and performant of screening tools – that would be ScreenPro™. But Mako can do both of those things very competently, and much more besides.
For example, we have used Mako to create a Windows desktop app to edit a PDF in ways relevant to production print workflows, such as changing spot colors or converting them to process colors. All the viewing and editing operations are implemented with Mako API calls. That fact alone emphasizes the wide range of applications to which Mako can be put, and I think, fully justifying that “Swiss Army knife” moniker.