Prev  Next

3.19.  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 methods to test layers: 

// Simple methods:

.hasNumberOfLayers(..)  // 'Layer' and ...
.hasNumberOfOCGs(..)    // ...'OCG' are always used the same way

.hasLayer()
.hasOCG()
.hasOCGs()
.hasLayers()

// Methods for layer names:
.hasLayer().withName().containing(..) 
.hasLayer().withName().equalsTo(..) 
.hasLayer().withName().startingWith(..)
.hasOCG().withName().containing(..) 
.hasOCG().withName().equalsTo(..) 
.hasOCG().withName().startingWith(..) 

// see the plural form:
.hasLayers().allWithoutDuplicateNames()
.hasOCG().allWithoutDuplicateNames()

A test method matchingRegex() is not provided because layer names are usually short and well known.

Number of Layers

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

@Test
public void hasNumberOfOCGs() throws Exception {
  String filename = "documentUnderTest.pdf";

  AssertThat.document(filename)
            .hasNumberOfOCGs(40)     1
            .hasNumberOfLayers(40)   2
  ;
}

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: 

@Test
public void hasLayer_WithName() throws Exception {
  String filename = "documentUnderTest.pdf";

  AssertThat.document(filename)
            .hasLayer()
            .withName().equalsTo("Parent Layer")
  ;
}

A layer name can be compared using the following methods: 

.hasLayer().withName().equalsTo(layerName1)
.hasLayer().withName().startingWith(layerName2)
.hasLayer().withName().containing(layerName3)

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 method to verify that a document has no duplicate layer names: 

@Test
public void hasLayers_AllWithoutDuplicateNames() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  AssertThat.document(filename)
            .hasLayers().allWithoutDuplicateNames()
            .hasOCGs().allWithoutDuplicateNames()    // hasOCGs() is equal to hasLayers() 
  ;
}

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

Prev Up Next
3.18.  Language  Home 3.20.  Layout - Entire PDF Pages