#  `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](https://pdftl.readthedocs.io/en/stable/operations/dump_layers.html)*

*Type: Operation*