dump_layers

Dump layer info (JSON)

Usage

pdftl <input> dump_layers [output <output>]

Details

The dump_layers operation extracts high-fidelity information about Optional Content Groups (OCGs), commonly known as ‘Layers’.

This operation outputs a structured JSON object containing the layer definitions, their default states, and the UI hierarchy (tree structure) used by PDF viewers.

JSON Schema Details

The output JSON contains several top-level keys:

  • has_layers (boolean): True if the document contains any Layer definitions.

  • layers (list): A flat list of all Layer objects. Each contains:

    • name: The user-visible name of the layer.

    • obj_id: The PDF indirect object ID (used to link to the hierarchy).

    • default_state: “ON” or “OFF” based on the default configuration.

    • intent: Optional list of intents (e.g., “View”, “Design”).

    • usage: Specialized metadata for “Print”, “View”, “Export”, or “Zoom” states.

      • active (boolean): Indicates if this usage category is currently governing the layer’s behavior. A layer might have “Print” settings, but they only take effect if the layer is ‘active’ for the Print event via the document’s Auto-State (/AS) settings.

  • ui_hierarchy (list): A recursive tree structure representing the Layers panel in a PDF viewer.

    • Nested Arrays: A list following a layer ID indicates child layers.

    • Labels: Simple strings or ‘label’ objects representing headers.

  • default_config (object): Details of the default display settings, including the base_state (usually “ON”) and lists of IDs that are explicitly “OFF” or “ON”.

  • alternate_configs (list): Optional secondary profiles (e.g., “Technical View”) defined by the author.

Understanding the Hierarchy

Because PDFs store layers in a flat list but display them in a tree, you must link the ui_hierarchy to the layers list using the obj_id.

Example hierarchy interpretation: [ {"obj_id": 4, "type": "layer"}, [ {"obj_id": 5, "type": "layer"} ] ] This indicates that Layer 5 is a child of Layer 4. For convenience, layer names are added to hierarchy output where possible.

Examples

Print layer information for in.pdf to the console

pdftl in.pdf dump_layers

Save layer information for in.pdf to layers.json

pdftl in.pdf dump_layers output layers.json

Tags: diagnostic, layers

Source: pdftl.operations.dump_layers

Read online: https://pdftl.readthedocs.io/en/stable/operations/dump_layers.html

Type: Operation