Working with PDF layers using Python

PDF layers allow a document to contain multiple sets of content that can be selectively shown or hidden. Each layer may include text, images, or graphics, and users can toggle them on or off as needed. Layers are especially useful in complex documents where content must be organized or separated. The examples below use the Document and Page APIs and manipulate Layer objects via the page’s layers collection.

Lock a PDF layer

With Aspose.PDF for Python via .NET you can open a PDF (see Document), lock a specific Layer on the first Page, and save the document with the changes.

Available methods and property on the Layer object:

• layer.lock() – Locks the layer. (see Layer.lock())
• layer.unlock() – Unlocks the layer. (see Layer.unlock())
• layer.locked – Returns the current lock state. (see Layer.locked)

1. Open the PDF document (see Document).
2. Retrieve the first page using the document’s Pages collection (see Page).
3. Select the Layer to lock from page.layers.
4. Call layer.lock() to prevent users from toggling the layer’s visibility.
5. Save the updated document using Document.save().

import aspose.pdf as ap

def lock_layer(path_infile, path_outfile):
    with ap.Document(path_infile) as document:
        page = document.pages[1]
        layer = page.layers[0]

        # Lock the layer
        layer.lock()

        # Save updated PDF
        document.save(path_outfile)

Extract PDF layer elements

Aspose.PDF allows you to extract each Layer from a Page and save it as a separate PDF file.

To create a new PDF from a layer, the following code snippet can be used (the layers collection is accessed via Page.layers):

import aspose.pdf as ap

def save_layers(path_infile, path_outfile):
    with ap.Document(path_infile) as document:
        layers = document.pages[1].layers

        # Save each layer to a new PDF with a unique filename
        for i, layer in enumerate(layers):
            layer.save(f"{path_outfile}_layer_{i}.pdf")

You can also save layers into a stream:

import aspose.pdf as ap
import io

def save_layers_to_stream(path_infile):
    with ap.Document(path_infile) as document:
        layers = document.pages[1].layers
        streams = []
        for layer in layers:
            layer_stream = io.BytesIO()
            layer.save(layer_stream)
            layer_stream.seek(0)
            streams.append(layer_stream)
        return streams

Flatten a layered PDF

Flattening makes a Layer permanent on the page, removing its toggle functionality.

import aspose.pdf as ap

def flatten_layers(path_infile, path_outfile):
    with ap.Document(path_infile) as document:
        page = document.pages[1]

        # Flatten each layer
        for layer in page.layers:
            layer.flatten(cleanup_content_stream=True)

        document.save(path_outfile)

The cleanup_content_stream parameter controls whether optional content group markers (OCG markers) are removed. Setting it to False speeds up flattening. See the Layer.flatten() method for details.

Merge All Layers inside the PDF into one

You can merge all layers (or specific ones) into a single new Layer (the merge API is on the Page object).

Methods on the Page object:

• page.merge_layers(new_layer_name) — merge all layers into a new layer name (see Page.MergeLayers()).
• page.merge_layers(new_layer_name, new_optional_content_group_id) — merge using a custom optional content group ID (see Page.MergeLayers()).

import aspose.pdf as ap

def merge_layers(path_infile, path_outfile, new_layer_name, optional_group_id=None):
    with ap.Document(path_infile) as document:
        page = document.pages[1]

        if optional_group_id:
            page.merge_layers(new_layer_name, optional_group_id)
        else:
            page.merge_layers(new_layer_name)

        document.save(path_outfile)