3.16.  Layers

Overview

The content of a PDF document can be arranged in multiple layers. Section 8.11.2.1 of the PDF specification PDF 32000-1:2008 says: An optional content group is a dictionary representing a collection of graphics that can be made visible or invisible dynamically by users of conforming readers..

Adobe Reader® uses the term Layer and the specification uses the term OCG. They are equivalent.

PDFUnit provides the following tags to test layers:

<!-- Tags to test layers: -->

<!-- 
  'Layer' means the same as 'OCG, Optional Content Group'. 
  So they have the same type:
-->

<hasNumberOfLayers />, <hasNumberOfOCGs />

<!-- Nested tags: -->
<hasLayer> or <hasOCG>
  <withName>                 (required)
    <matchingComplete />     (one of these nested tags ...
    <containing       />     ...
    <startingWith     />     ... is required)
  </withName>
</hasLayer> or </hasOCG>

<hasLayers> or <hasOCGs>
  <allWithoutDuplicateNames />  (optional)
</hasLayers> or </hasOCGs>

The tag <endingWith /> is not provided because duplicate layer names are expanded internally with a suffix and thus the end of a name is not predictable.

A tag matchingRegex /> is also not provided because layer names are usually short.

Number of Layers

The first tests check the number of existing layers (OCGs):

<testcase name="hasNumberOfOCGs">
  <assertThat testDocument="layer/hang-man-game.pdf">
    <hasNumberOfOCGs>40</hasNumberOfOCGs>     1
    <hasNumberOfLayers>40</hasNumberOfLayers> 2
  </assertThat>
</testcase>

1 2

Layer and Optional Content Group are functionally the same. For ease to use, both terms are available as equivalent tags.

Layer Names

The next example tests the name of a layer:

<testcase name="hasLayerWithName_MatchingComplete">
  <assertThat testDocument="layer/simpleLayerDemo.pdf">
    <hasLayer>
      <withName>
        <matchingComplete>Parent Layer</matchingComplete>
      </withName>
    </hasLayer>
  </assertThat>
</testcase>

The tags endingWith /> and matchingRegex /> are intentionally not provided as explained at the beginning of this chapter.

String comparisons are case-insensitive. Whitespaces remain unchanged.

<!-- Layer names are treated case-insensitive. -->

<testcase name="hasLayerWithName_CaseInSensitive">
  <assertThat testDocument="layer/simpleLayerDemo.pdf">
    <hasLayer>
      <withName>
        <matchingComplete>parent layer</matchingComplete>
      </withName>
    </hasLayer>
    <hasLayer>
      <withName>
        <matchingComplete>Parent Layer</matchingComplete>
      </withName>
    </hasLayer>
  </assertThat>
</testcase>

Duplicate Layer Names

According to the PDF standard, layer names are not necessarily unique. The document of the next example contains duplicate layer names. They can not be seen with Adobe Reader®. Use PDFVole instead. shows them:

Layer Names in Adobe Reader® Layer Objects in PDFVole

You can see clearly that the layer objects with the numbers 32 and 52 have the same name Dash9.

PDFUnit provides a tag to verify that a document has no duplicate layer names:

<testcase name="hasLayers_AllWithoutDuplicateNames">
  <assertThat testDocument="layer/simpleLayerDemo.pdf">
    <hasLayers>
      <allWithoutDuplicateNames />
    </hasLayers>
    <hasOCGs>                   <!-- <hasOCGs /> is equal to <hasLayers /> -->
      <allWithoutDuplicateNames />
    </hasOCGs>
  </assertThat>
</testcase>

In the current release 2015.10 PDFUnit does not provide functions to verify the content of a single layer.