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:

Metadata: Rectangle bounds, blend mode, opacity, flags
Channel info: List of channels (R, G, B, A, masks, etc.) with byte offsets
Blend ranges: Advanced blending parameters
Layer name: Pascal string (legacy, inaccurate for Unicode names)
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)[source]

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)[source]

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)[source]

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)[source]: 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)[source]

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]]

[(width, height)].

Type:: List of channel sizes

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)[source]

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)[source]

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: MaskParameters | None = None, real_flags: MaskFlags | None = 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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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'')[source]

Channel data.

compression: Compression type. See Compression.

data: Data.

get_data(width: int, height: int, depth: int, version: int = 1) → bytes[source]

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[source]

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.