# psd_tools.psd.layer_and_mask

Layer and mask data structures.

This module implements the low-level binary structures for PSD layers and masks, corresponding to the “Layer and Mask Information” section of PSD files. This is one of the most complex parts of the PSD format.

Key classes:

- `LayerAndMaskInformation`: Top-level container for all layer data

- `LayerInfo`: Contains layer records and channel image data

- `LayerRecords`: List of individual layer records

- `LayerRecord`: Single layer metadata (name, bounds, blend mode, etc.)

- `ChannelInfo`: Channel metadata within a layer record

- `ChannelImageData`: Compressed pixel data for all channels

- `ChannelData`: Single channel’s compressed pixel data

- `MaskData`: Layer mask parameters

- `GlobalLayerMaskInfo`: Document-wide mask settings

- `TaggedBlocks`: Extended layer metadata (see `psd_tools.psd.tagged_blocks`)

The layer structure in PSD files is stored as a flat list with implicit hierarchy. Group boundaries are marked by special layers with `SectionDivider` tagged blocks:

- `BOUNDING_SECTION_DIVIDER`: Marks the start of a group (the layer that opens the group)

- `OPEN_FOLDER` or `CLOSED_FOLDER`: Marks the end of a group (the closing divider layer) - `OPEN_FOLDER`: Group was open in Photoshop UI - `CLOSED_FOLDER`: Group was closed in Photoshop UI

The high-level API (`psd_tools.api`) reconstructs this into a proper tree structure with parent-child relationships.

Each layer record contains:

1. Metadata: Rectangle bounds, blend mode, opacity, flags

2. Channel info: List of channels (R, G, B, A, masks, etc.) with byte offsets

3. Blend ranges: Advanced blending parameters

4. Layer name: Pascal string (legacy, inaccurate for Unicode names)

5. Tagged blocks: Extended metadata in key-value format

The channel image data section follows all layer records and contains the actual compressed pixel data for each channel, referenced by the channel info structures.

Example of reading layer metadata:

    from psd_tools.psd import PSD

    with open('file.psd', 'rb') as f:
        psd = PSD.read(f)

    layer_info = psd.layer_and_mask_information.layer_info
    for record in layer_info.layer_records:
        print(f"Layer: {record.name}")
        print(f"  Bounds: {record.top}, {record.left}, {record.bottom}, {record.right}")
        print(f"  Blend mode: {record.blend_mode}")
        print(f"  Channels: {len(record.channel_info)}")

For most use cases, prefer the high-level `Layer` API which provides easier access to this data.

## LayerAndMaskInformation

class psd_tools.psd.layer_and_mask.LayerAndMaskInformation(layer_info: LayerInfo | None = None, global_layer_mask_info: GlobalLayerMaskInfo | None = None, tagged_blocks: TaggedBlocks | None = None)

  Layer and mask information section.

  layer_info

    See `LayerInfo`.

  global_layer_mask_info

    See `GlobalLayerMaskInfo`.

  tagged_blocks

    See `TaggedBlocks`.

## LayerInfo

class psd_tools.psd.layer_and_mask.LayerInfo(layer_count: int = 0, layer_records: LayerRecords = NOTHING, channel_image_data: ChannelImageData = NOTHING)

  High-level organization of the layer information.

  layer_count

    Layer count. If it is a negative number, its absolute value is the number of layers and the first alpha channel contains the transparency data for the merged result.

  layer_records

    Information about each layer. See `LayerRecords`.

  channel_image_data

    Channel image data. See `ChannelImageData`.

## GlobalLayerMaskInfo

class psd_tools.psd.layer_and_mask.GlobalLayerMaskInfo(overlay_color: list[int] | None = None, opacity: int = 0, kind=GlobalLayerMaskKind.PER_LAYER)

  Global mask information.

  overlay_color

    Overlay color space (undocumented) and color components.

  opacity

    Opacity. 0 = transparent, 100 = opaque.

  kind

    Kind. 0 = Color selected–i.e. inverted; 1 = Color protected; 128 = use value stored per layer. This value is preferred. The others are for backward compatibility with beta versions.

## LayerRecords

class psd_tools.psd.layer_and_mask.LayerRecords(items=NOTHING)

  List of layer records. See `LayerRecord`.

## LayerRecord

class psd_tools.psd.layer_and_mask.LayerRecord(top: int = 0, left: int = 0, bottom: int = 0, right: int = 0, channel_info: list[ChannelInfo] = NOTHING, signature: bytes = b'8BIM', blend_mode=BlendMode.NORMAL, opacity: int = 255, clipping=Clipping.BASE, flags: LayerFlags = NOTHING, mask_data: object = None, blending_ranges: LayerBlendingRanges = NOTHING, name: str = '', tagged_blocks: TaggedBlocks = NOTHING)

  Layer record.

  top

    Top position.

  left

    Left position.

  bottom

    Bottom position.

  right

    Right position.

  channel_info

    List of `ChannelInfo`.

  signature

    Blend mode signature `b'8BIM'`.

  blend_mode

    Blend mode key. See `BlendMode`.

  opacity

    Opacity, 0 = transparent, 255 = opaque.

  clipping

    Clipping, 0 = base, 1 = non-base. See `Clipping`.

  flags

    See `LayerFlags`.

  mask_data

    `MaskData` or None.

  blending_ranges

    See `LayerBlendingRanges`.

  name

    Layer name.

  tagged_blocks

    See `TaggedBlocks`.

  property channel_sizes: list[tuple[int, int]]

    List of channel sizes: [(width, height)].

  property height: int

    Height of the layer.

  property width: int

    Width of the layer.

## LayerFlags

class psd_tools.psd.layer_and_mask.LayerFlags(transparency_protected: bool = False, visible: bool = True, obsolete: bool = False, photoshop_v5_later: bool = True, pixel_data_irrelevant: bool = False, undocumented_1: bool = False, undocumented_2: bool = False, undocumented_3: bool = False)

  Layer flags.

  Note there are undocumented flags. Maybe photoshop version.

  transparency_protected
  visible
  pixel_data_irrelevant

## LayerBlendingRanges

class psd_tools.psd.layer_and_mask.LayerBlendingRanges(composite_ranges: list[tuple[int, int]] = NOTHING, channel_ranges: list[list[tuple[int, int]]] = NOTHING)

  Layer blending ranges.

  All ranges contain 2 black values followed by 2 white values.

  composite_ranges

    List of composite gray blend source and destination ranges.

  channel_ranges

    List of channel source and destination ranges.

## MaskData

class psd_tools.psd.layer_and_mask.MaskData(top: int = 0, left: int = 0, bottom: int = 0, right: int = 0, background_color: int = 0, flags: MaskFlags = NOTHING, parameters: object = None, real_flags: object = None, real_background_color: int | None = None, real_top: int | None = None, real_left: int | None = None, real_bottom: int | None = None, real_right: int | None = None)

  Mask data.

  Real user mask is a final composite mask of vector and pixel masks.

  top

    Top position.

  left

    Left position.

  bottom

    Bottom position.

  right

    Right position.

  background_color

    Default color. 0 or 255.

  flags

    See `MaskFlags`.

  parameters

    `MaskParameters` or None.

  real_flags

    Real user mask flags. See `MaskFlags`.

  real_background_color

    Real user mask background. 0 or 255.

  real_top

    Top position of real user mask.

  real_left

    Left position of real user mask.

  real_bottom

    Bottom position of real user mask.

  real_right

    Right position of real user mask.

  property height: int

    Height of the mask.

  property real_height: int

    Height of real user mask.

  property real_width: int

    Width of real user mask.

  property width: int

    Width of the mask.

## MaskFlags

class psd_tools.psd.layer_and_mask.MaskFlags(pos_relative_to_layer: bool = False, mask_disabled: bool = False, invert_mask: bool = False, user_mask_from_render: bool = False, parameters_applied: bool = False, undocumented_1: bool = False, undocumented_2: bool = False, undocumented_3: bool = False)

  Mask flags.

  pos_relative_to_layer

    Position relative to layer.

  mask_disabled

    Layer mask disabled.

  invert_mask

    Invert layer mask when blending (Obsolete).

  user_mask_from_render

    The user mask actually came from rendering other data.

  parameters_applied

    The user and/or vector masks have parameters applied to them.

## MaskParameters

class psd_tools.psd.layer_and_mask.MaskParameters(user_mask_density: int | None = None, user_mask_feather: float | None = None, vector_mask_density: int | None = None, vector_mask_feather: float | None = None)

  Mask parameters.

  user_mask_density
  user_mask_feather
  vector_mask_density
  vector_mask_feather

## ChannelInfo

class psd_tools.psd.layer_and_mask.ChannelInfo(id=ChannelID.CHANNEL_0, length: int = 0)

  Channel information.

  id

    Channel ID: 0 = red, 1 = green, etc.; -1 = transparency mask; -2 = user supplied layer mask, -3 real user supplied layer mask (when both a user mask and a vector mask are present). See `ChannelID`.

  length

    Length of the corresponding channel data.

## ChannelImageData

class psd_tools.psd.layer_and_mask.ChannelImageData(items=NOTHING)

  List of channel data list.

  This size of this list corresponds to the size of `LayerRecords`. Each item corresponds to the channels of each layer.

  See `ChannelDataList`.

## ChannelDataList

class psd_tools.psd.layer_and_mask.ChannelDataList(items=NOTHING)

  List of channel image data, corresponding to each color or alpha.

  See `ChannelData`.

## ChannelData

class psd_tools.psd.layer_and_mask.ChannelData(compression=Compression.RAW, data: bytes = b'')

  Channel data.

  compression

    Compression type. See `Compression`.

  data

    Data.

  get_data(width: int, height: int, depth: int, version: int = 1) → bytes

    Get decompressed channel data.

    Parameters:

      - width – width.

      - height – height.

      - depth – bit depth of the pixel.

      - version – psd file version.

    Return type:

      bytes

  set_data(data: bytes, width: int, height: int, depth: int, version: int = 1) → int

    Set raw channel data and compress to store.

    Parameters:

      - data – raw data bytes to write.

      - compression – compression type, see `Compression`.

      - width – width.

      - height – height.

      - depth – bit depth of the pixel.

      - version – psd file version.