Reference XObjects


PDF 1.4 introduced Reference XObjects, but it has not been implemented in Acrobat in the intervening years. With the growing popularity of PDF/X-5 documents and interest in variable data printing (VDP) Acrobat decided to add support for Reference XObjects in 9.0. This is likely to benefit Original Equipment Manufacturers (OEMs) and print providers to provide customized workflows for their customers by executing VDP.
So far, there were no consumers for documents containing Reference XObjects (including absence of it in Acrobat) because there were no producers for the same. Acrobat finally breaks this chicken and egg situation that has been prevalent for a while. With Acrobat’s support of such documents, more applications will be encouraged to produce them.

What the PDF Reference says (Section 4.9.3):

Reference XObjects (PDF 1.4) enable one PDF document to import content from another. The document in which the reference occurs is called the containing document; the one whose content is being imported is the target document. The reference XObject in the containing document is a form XObject containing the optional Ref entry in its form dictionary. This form XObject serves as a proxy that can be displayed or printed in place of the imported content. The proxy might consist of a low-resolution image of the imported content, a piece of descriptive text referring to it, a gray box to be displayed in its place, or any other similar placeholder. The presence of the Ref entry distinguishes reference XObjects from other types of form XObjects.

When the imported content replaces the proxy, it is transformed according to the proxy object’s transformation matrix and clipped to the boundaries of its bounding box, as specified by the Matrix and BBox entries in the proxy’s form dictionary The combination of the proxy object’s matrix and bounding box thus implicitly defines the bounding box of the imported page.

For a detailed description see: PDF Reference Manual

Using Reference XObjects in Acrobat 9

In Acrobat 9, reference XObjects are enabled by default for PDF/X-5 documents only. To enable it for all documents, select Always as the View Mode for Reference XObjects in Preferences –> Page Display. The location of the target documents can be specified in the box below that.

Since reference XObjects access external content, security becomes a concern and to ensure that the documents are trust-worthy, the location of the containing documents must be specified in the Enhanced Security locations. This can be found in Preferences –> Security (Enhanced). All documents accessing external streams must be added as trusted locations irrespective of whether the checkbox, Enable Enhanced Security is checked or not.

With these settings in place, Acrobat will look for target documents in the specified locations and use the imported content. If it does not find a target document, or if there is an error in the pdf, or if the containing document is not trusted, the proxy will be displayed.

Special Notes:
The Ref dictionary contains:

F – File specification dictionary. This is according to the file specification given in PDF Reference 1.7. For non-english characters to be supported across all platforms, the file name must be contained in UF, the text string entry.
Page – Integer or text string. A page index or page label identifying the page of the target document containing the content to be imported.
ID – array. An optional entry specifying a file identifier for the file containing the target document.

10 Responses to Reference XObjects

  1. Do you have a sample document? I’ve tried to create such a document manually (I know my way around COS objects), but so far failed miserably…Thanks,Karl Heinz

  2. Shradha Budhiraja says:

    I have uploaded some files on Below are the urls:These are the containing files: refxob A to A.pdf – File referring to itself. refxob base.pdf refxob groups.pdf – Target file contains transparency. refxob main3.pdf – File containing references from different files on each page. refxob N to 1.pdf – Multiple references of the same file on a single page. refxob x5.pdf – A PDF/X-5 compliant document.These are the target file that are needed to display the above files: target labels.pdf target tai.pdf target.pdf target group.pdf targetX5.pdfShradha

  3. I don’t think your links are working. I looked at the page source with Firefox, and the actual link seems to be missing.Karl Heinz

  4. Thank you for the samples.

  5. Wow, impressive. I had to rename the files however: They downloaded with all spaces replaced by plus signs. Thanks to the “Browse Internal PDF Structure” function on the Preflight dialog, it was pretty straight forward to figure out why things did not work correctly. I’m doing this on a Mac, so I don’t know if the filename problem is specific to my architecture, or if Windows machines are having the same problem.Thanks again,Karl HeinzPS: My own samples did not work because of the security settings.

  6. Shradha Budhiraja says:

    I tried downloading the files on my Windows machine and the names were just fine. I am not sure, if this is an architectural or Mac only issue.

  7. Anonymous says:

    I could not download the samples.

  8. Anonymous says:

    I mentioned that I had a problem downloading.The Problem was on my side and I have lready downloaded the files.Thanks

  9. John says:

    How can I create new proxy and/or edit existing proxy in containing document from Acrobat 9? Please show me the steps. Thanks in advance.

  10. Shradha Budhiraja says:

    You cannot create/edit the proxies from within Acrobat 9. Acrobat is the consumer of files containing referenceX objects, i.e. it will view such files. To edit the proxies, you have to change the dictionary within the pdf using one of the producers of pdfs, like distiller. The Ref entry in the PDF Structure describes the proxy. It points to a file and its page number. This gets replaced for the proxy (or anything else that your pdf is designed to show if it does not find the specified file). You can refer to PDF Reference v.1.6 Section- 4.9.3 to understand more about the structure.