psd_tools.api.layers

Layer module.

Artboard

class psd_tools.api.layers.Artboard(psd: Any, record: LayerRecord, channels: ChannelDataList, parent: TGroupMixin | None)

Artboard is a special kind of group that has a pre-defined viewbox.

append(layer: Layer) → None

Add a layer to the end (top) of the group

Parameters:

layer – The layer to add

property bbox: tuple[int, int, int, int]

(left, top, right, bottom) tuple.

property blend_mode: BlendMode

Blend mode of this layer. Writable.

Example:

from psd_tools.constants import BlendMode
if layer.blend_mode == BlendMode.NORMAL:
    layer.blend_mode = BlendMode.SCREEN

Returns:

BlendMode.

property bottom: int

Bottom coordinate.

Returns:

int

clear() → None

Clears the group.

property clip_layers: list[Self]

Clip layers associated with this layer.

Returns:

list of layers

property clipping_layer: bool

Clipping flag for this layer. Writable.

Returns:

bool

composite(viewport: tuple[int, int, int, int] | None = None, force: bool = False, color: float | tuple[float, ...] | ndarray = 1.0, alpha: float | ndarray = 0.0, layer_filter: Callable | None = None, apply_icc: bool = True)

Composite layer and masks (mask, vector mask, and clipping layers).

Parameters:

• viewport – Viewport bounding box specified by (x1, y1, x2, y2) tuple. Default is the layer’s bbox.

• force – Boolean flag to force vector drawing.

• color – Backdrop color specified by scalar or tuple of scalar. The color value should be in [0.0, 1.0]. For example, (1., 0., 0.) specifies red in RGB color mode.

• alpha – Backdrop alpha in [0.0, 1.0].

• layer_filter – Callable that takes a layer as argument and returns whether if the layer is composited. Default is is_visible().

Returns:

PIL.Image.

count(layer: Layer) → int

Counts the number of occurences of a layer in the group.

Parameters:

layer

delete_layer() → Self

Deletes the layer and all its child layers if the layer is a group from its parent (group or psdimage).

descendants(include_clip: bool = True) → Iterator[Layer]

Return a generator to iterate over all descendant layers.

Example:

# Iterate over all layers
for layer in psd.descendants():
    print(layer)

# Iterate over all layers in reverse order
for layer in reversed(list(psd.descendants())):
    print(layer)

Parameters:

include_clip – include clipping layers.

property effects: Effects

Layer effects.

Returns:

Effects

extend(layers: Iterable[Layer]) → None

Add a list of layers to the end (top) of the group

Parameters:

layers – The layers to add

static extract_bbox(layers, include_invisible: bool = False) → tuple[int, int, int, int]

Returns a bounding box for layers or (0, 0, 0, 0) if the layers have no bounding box.

Parameters:

include_invisible – include invisible layers in calculation.

Returns:

tuple of four int

find(name: str) → Layer | None

Returns the first layer found for the given layer name

Parameters:

name

findall(name: str) → Iterator[Layer]

Return a generator to iterate over all layers with the given name.

Parameters:

name

classmethod group_layers(layers: list[Layer], name: str = 'Group', parent: GroupMixin | None = None, open_folder: bool = True)

Create a new Group object containing the given layers and moved into the parent folder.

If no parent is provided, the group will be put in place of the first layer in the given list. Example below:

Parameters:

• layers – The layers to group. Can by any subclass of Layer

• name – The display name of the group. Default to “Group”.

• parent – The parent group to add the newly created Group object into.

• open_folder – Boolean defining whether the folder will be open or closed in photoshop. Default to True.

Returns:

A Group

has_clip_layers() → bool

Returns True if the layer has associated clipping.

Returns:

bool

has_effects() → bool

Returns True if the layer has effects.

Returns:

bool

has_mask() → bool

Returns True if the layer has a mask.

Returns:

bool

has_origination() → bool

Returns True if the layer has live shape properties.

Returns:

bool

has_pixels() → bool

Returns True if the layer has associated pixels. When this is True, topil method returns PIL.Image.

Returns:

bool

has_stroke() → bool

Returns True if the shape has a stroke.

has_vector_mask() → bool

Returns True if the layer has a vector mask.

Returns:

bool

property height: int

Height of the layer.

Returns:

int

index(layer: Layer) → int

Returns the index of the specified layer in the group.

Parameters:

layer

insert(index: int, layer: Layer) → None

Insert the given layer at the specified index.

Parameters:

• index

• layer

is_group() → bool

Return True if the layer is a group.

Returns:

bool

is_visible() → bool

Layer visibility. Takes group visibility in account.

Returns:

bool

property kind: str

Kind of this layer, such as group, pixel, shape, type, smartobject, or psdimage. Class name without layer suffix.

Returns:

str

property layer_id: int

Layer ID.

Returns:

int layer id. if the layer is not assigned an id, -1.

property left: int

Left coordinate. Writable.

Returns:

int

lock(lock_flags: int = ProtectedFlags.COMPLETE) → None

Locks a layer accordind to the combination of flags.

Parameters:

lockflags – An integer representing the locking state

Example using the constants of ProtectedFlags and bitwise or operation to lock both pixels and positions:

layer.lock(ProtectedFlags.COMPOSITE | ProtectedFlags.POSITION)

property mask: Mask | None

Returns mask associated with this layer.

Returns:

Mask or None

move_down(offset: int = 1) → Self

Moves the layer down a certain offset within the group the layer is in.

Parameters:

offset

move_to_group(group: GroupMixin) → Self

Moves the layer to the given group, updates the tree metadata as needed.

Parameters:

group – The group the current layer will be moved into.

move_up(offset: int = 1) → Self

Moves the layer up a certain offset within the group the layer is in.

Parameters:

offset

property name: str

Layer name. Writable.

Returns:

str

classmethod new(name: str = 'Group', open_folder: bool = True, parent: GroupMixin | None = None) → Self

Create a new Group object with minimal records and data channels and metadata to properly include the group in the PSD file.

Parameters:

• name – The display name of the group. Default to “Group”.

• open_folder – Boolean defining whether the folder will be open or closed in photoshop. Default to True.

• parent – Optional parent folder to move the newly created group into.

Returns:

A Group object

numpy(channel: str | None = None, real_mask: bool = True) → ndarray | None

Get NumPy array of the layer.

Parameters:

channel – Which channel to return, can be ‘color’, ‘shape’, ‘alpha’, or ‘mask’. Default is ‘color+alpha’.

Returns:

numpy.ndarray or None if there is no pixel.

property offset: tuple[int, int]

(left, top) tuple. Writable.

Returns:

tuple

property opacity: int

Opacity of this layer in [0, 255] range. Writable.

Returns:

int

property origination: list[Origination]

Property for a list of live shapes or a line.

Some of the vector masks have associated live shape properties, that are Photoshop feature to handle primitive shapes such as a rectangle, an ellipse, or a line. Vector masks without live shape properties are plain path objects.

See psd_tools.api.shape.

Returns:

List of Invalidated, Rectangle, RoundedRectangle, Ellipse, or Line.

property parent: TGroupMixin | None

Parent of this layer.

pop(index: int = -1) → Layer

Removes the specified layer from the list and returns it.

Parameters:

index

remove(layer: Layer) → Self

Removes the specified layer from the group

Parameters:

layer

property right: int

Right coordinate.

Returns:

int

property size: tuple[int, int]

(width, height) tuple.

Returns:

tuple

property stroke: Stroke | None

Property for strokes.

property tagged_blocks: TaggedBlocks

Layer tagged blocks that is a dict-like container of settings.

See psd_tools.constants.Tag for available keys.

Returns:

TaggedBlocks.

Example:

from psd_tools.constants import Tag
metadata = layer.tagged_blocks.get_data(Tag.METADATA_SETTING)

property top: int

Top coordinate. Writable.

Returns:

int

topil(channel: int | None = None, apply_icc: bool = True) → Image | None

Get PIL Image of the layer.

Parameters:

• channel – Which channel to return; e.g., 0 for ‘R’ channel in RGB image. See ChannelID. When None, the method returns all the channels supported by PIL modes.

• apply_icc – Whether to apply ICC profile conversion to sRGB.

Returns:

PIL.Image, or None if the layer has no pixels.

Example:

from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)

Note

Not all of the PSD image modes are supported in PIL.Image. For example, ‘CMYK’ mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.

property vector_mask: VectorMask | None

Returns vector mask associated with this layer.

Returns:

VectorMask or None

property visible: bool

Layer visibility. Doesn’t take group visibility in account. Writable.

Returns:

bool

property width: int

Width of the layer.

Returns:

int

Group

class psd_tools.api.layers.Group(psd: Any, record: LayerRecord, channels: ChannelDataList, parent: TGroupMixin | None)

Group of layers.

Example:

group = psd[1]
for layer in group:
    if layer.kind == 'pixel':
        print(layer.name)

append(layer: Layer) → None

Add a layer to the end (top) of the group

Parameters:

layer – The layer to add

property bbox: tuple[int, int, int, int]

(left, top, right, bottom) tuple.

property blend_mode: BlendMode

Blend mode of this layer. Writable.

Example:

from psd_tools.constants import BlendMode
if layer.blend_mode == BlendMode.NORMAL:
    layer.blend_mode = BlendMode.SCREEN

Returns:

BlendMode.

property bottom: int

Bottom coordinate.

Returns:

int

clear() → None

Clears the group.

property clip_layers: list[Self]

Clip layers associated with this layer.

Returns:

list of layers

property clipping_layer: bool

Clipping flag for this layer. Writable.

Returns:

bool

composite(viewport: tuple[int, int, int, int] | None = None, force: bool = False, color: float | tuple[float, ...] | ndarray = 1.0, alpha: float | ndarray = 0.0, layer_filter: Callable | None = None, apply_icc: bool = True)

Composite layer and masks (mask, vector mask, and clipping layers).

Parameters:

• viewport – Viewport bounding box specified by (x1, y1, x2, y2) tuple. Default is the layer’s bbox.

• force – Boolean flag to force vector drawing.

• color – Backdrop color specified by scalar or tuple of scalar. The color value should be in [0.0, 1.0]. For example, (1., 0., 0.) specifies red in RGB color mode.

• alpha – Backdrop alpha in [0.0, 1.0].

• layer_filter – Callable that takes a layer as argument and returns whether if the layer is composited. Default is is_visible().

Returns:

PIL.Image.

count(layer: Layer) → int

Counts the number of occurences of a layer in the group.

Parameters:

layer

delete_layer() → Self

Deletes the layer and all its child layers if the layer is a group from its parent (group or psdimage).

descendants(include_clip: bool = True) → Iterator[Layer]

Return a generator to iterate over all descendant layers.

Example:

# Iterate over all layers
for layer in psd.descendants():
    print(layer)

# Iterate over all layers in reverse order
for layer in reversed(list(psd.descendants())):
    print(layer)

Parameters:

include_clip – include clipping layers.

property effects: Effects

Layer effects.

Returns:

Effects

extend(layers: Iterable[Layer]) → None

Add a list of layers to the end (top) of the group

Parameters:

layers – The layers to add

static extract_bbox(layers, include_invisible: bool = False) → tuple[int, int, int, int]

Returns a bounding box for layers or (0, 0, 0, 0) if the layers have no bounding box.

Parameters:

include_invisible – include invisible layers in calculation.

Returns:

tuple of four int

find(name: str) → Layer | None

Returns the first layer found for the given layer name

Parameters:

name

findall(name: str) → Iterator[Layer]

Return a generator to iterate over all layers with the given name.

Parameters:

name

classmethod group_layers(layers: list[Layer], name: str = 'Group', parent: GroupMixin | None = None, open_folder: bool = True)

Create a new Group object containing the given layers and moved into the parent folder.

If no parent is provided, the group will be put in place of the first layer in the given list. Example below:

Parameters:

• layers – The layers to group. Can by any subclass of Layer

• name – The display name of the group. Default to “Group”.

• parent – The parent group to add the newly created Group object into.

• open_folder – Boolean defining whether the folder will be open or closed in photoshop. Default to True.

Returns:

A Group

has_clip_layers() → bool

Returns True if the layer has associated clipping.

Returns:

bool

has_effects() → bool

Returns True if the layer has effects.

Returns:

bool

has_mask() → bool

Returns True if the layer has a mask.

Returns:

bool

has_origination() → bool

Returns True if the layer has live shape properties.

Returns:

bool

has_pixels() → bool

Returns True if the layer has associated pixels. When this is True, topil method returns PIL.Image.

Returns:

bool

has_stroke() → bool

Returns True if the shape has a stroke.

has_vector_mask() → bool

Returns True if the layer has a vector mask.

Returns:

bool

property height: int

Height of the layer.

Returns:

int

index(layer: Layer) → int

Returns the index of the specified layer in the group.

Parameters:

layer

insert(index: int, layer: Layer) → None

Insert the given layer at the specified index.

Parameters:

• index

• layer

is_group() → bool

Return True if the layer is a group.

Returns:

bool

is_visible() → bool

Layer visibility. Takes group visibility in account.

Returns:

bool

property kind: str

Kind of this layer, such as group, pixel, shape, type, smartobject, or psdimage. Class name without layer suffix.

Returns:

str

property layer_id: int

Layer ID.

Returns:

int layer id. if the layer is not assigned an id, -1.

property left: int

Left coordinate. Writable.

Returns:

int

lock(lock_flags: int = ProtectedFlags.COMPLETE) → None

Locks a layer accordind to the combination of flags.

Parameters:

lockflags – An integer representing the locking state

Example using the constants of ProtectedFlags and bitwise or operation to lock both pixels and positions:

layer.lock(ProtectedFlags.COMPOSITE | ProtectedFlags.POSITION)

property mask: Mask | None

Returns mask associated with this layer.

Returns:

Mask or None

move_down(offset: int = 1) → Self

Moves the layer down a certain offset within the group the layer is in.

Parameters:

offset

move_to_group(group: GroupMixin) → Self

Moves the layer to the given group, updates the tree metadata as needed.

Parameters:

group – The group the current layer will be moved into.

move_up(offset: int = 1) → Self

Moves the layer up a certain offset within the group the layer is in.

Parameters:

offset

property name: str

Layer name. Writable.

Returns:

str

classmethod new(name: str = 'Group', open_folder: bool = True, parent: GroupMixin | None = None) → Self

Create a new Group object with minimal records and data channels and metadata to properly include the group in the PSD file.

Parameters:

• name – The display name of the group. Default to “Group”.

• open_folder – Boolean defining whether the folder will be open or closed in photoshop. Default to True.

• parent – Optional parent folder to move the newly created group into.

Returns:

A Group object

numpy(channel: str | None = None, real_mask: bool = True) → ndarray | None

Get NumPy array of the layer.

Parameters:

channel – Which channel to return, can be ‘color’, ‘shape’, ‘alpha’, or ‘mask’. Default is ‘color+alpha’.

Returns:

numpy.ndarray or None if there is no pixel.

property offset: tuple[int, int]

(left, top) tuple. Writable.

Returns:

tuple

property opacity: int

Opacity of this layer in [0, 255] range. Writable.

Returns:

int

property origination: list[Origination]

Property for a list of live shapes or a line.

Some of the vector masks have associated live shape properties, that are Photoshop feature to handle primitive shapes such as a rectangle, an ellipse, or a line. Vector masks without live shape properties are plain path objects.

See psd_tools.api.shape.

Returns:

List of Invalidated, Rectangle, RoundedRectangle, Ellipse, or Line.

property parent: TGroupMixin | None

Parent of this layer.

pop(index: int = -1) → Layer

Removes the specified layer from the list and returns it.

Parameters:

index

remove(layer: Layer) → Self

Removes the specified layer from the group

Parameters:

layer

property right: int

Right coordinate.

Returns:

int

property size: tuple[int, int]

(width, height) tuple.

Returns:

tuple

property stroke: Stroke | None

Property for strokes.

property tagged_blocks: TaggedBlocks

Layer tagged blocks that is a dict-like container of settings.

See psd_tools.constants.Tag for available keys.

Returns:

TaggedBlocks.

Example:

from psd_tools.constants import Tag
metadata = layer.tagged_blocks.get_data(Tag.METADATA_SETTING)

property top: int

Top coordinate. Writable.

Returns:

int

topil(channel: int | None = None, apply_icc: bool = True) → Image | None

Get PIL Image of the layer.

Parameters:

• channel – Which channel to return; e.g., 0 for ‘R’ channel in RGB image. See ChannelID. When None, the method returns all the channels supported by PIL modes.

• apply_icc – Whether to apply ICC profile conversion to sRGB.

Returns:

PIL.Image, or None if the layer has no pixels.

Example:

from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)

Note

Not all of the PSD image modes are supported in PIL.Image. For example, ‘CMYK’ mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.

property vector_mask: VectorMask | None

Returns vector mask associated with this layer.

Returns:

VectorMask or None

property visible: bool

Layer visibility. Doesn’t take group visibility in account. Writable.

Returns:

bool

property width: int

Width of the layer.

Returns:

int

PixelLayer

class psd_tools.api.layers.PixelLayer(psd: Any, record: LayerRecord, channels: ChannelDataList, parent: TGroupMixin | None)

Layer that has rasterized image in pixels.

Example:

assert layer.kind == 'pixel':
image = layer.composite()
image.save('layer.png')

property bbox: tuple[int, int, int, int]

(left, top, right, bottom) tuple.

property blend_mode: BlendMode

Blend mode of this layer. Writable.

Example:

from psd_tools.constants import BlendMode
if layer.blend_mode == BlendMode.NORMAL:
    layer.blend_mode = BlendMode.SCREEN

Returns:

BlendMode.

property bottom: int

Bottom coordinate.

Returns:

int

property clip_layers: list[Self]

Clip layers associated with this layer.

Returns:

list of layers

property clipping_layer: bool

Clipping flag for this layer. Writable.

Returns:

bool

composite(viewport: tuple[int, int, int, int] | None = None, force: bool = False, color: float | tuple[float, ...] | ndarray = 1.0, alpha: float | ndarray = 0.0, layer_filter: Callable | None = None, apply_icc: bool = True) → Image | None

Composite layer and masks (mask, vector mask, and clipping layers).

Parameters:

• viewport – Viewport bounding box specified by (x1, y1, x2, y2) tuple. Default is the layer’s bbox.

• force – Boolean flag to force vector drawing.

• color – Backdrop color specified by scalar or tuple of scalar. The color value should be in [0.0, 1.0]. For example, (1., 0., 0.) specifies red in RGB color mode.

• alpha – Backdrop alpha in [0.0, 1.0].

• layer_filter – Callable that takes a layer as argument and returns whether if the layer is composited. Default is is_visible().

Returns:

PIL.Image or None.

delete_layer() → Self

Deletes the layer and all its child layers if the layer is a group from its parent (group or psdimage).

property effects: Effects

Layer effects.

Returns:

Effects

classmethod frompil(pil_im: Image, psd_file: Any | None = None, layer_name: str = 'Layer', top: int = 0, left: int = 0, compression: Compression = Compression.RLE, **kwargs: Any) → PixelLayer

Creates a PixelLayer from a PIL image for a given psd file.

Parameters:

• pil_im – The Image object to convert to photoshop

• psdfile – The psd file the image will be converted for.

• layer_name – The name of the layer. Defaults to “Layer”

• top – Pixelwise offset from the top of the canvas for the new layer.

• left – Pixelwise offset from the left of the canvas for the new layer.

• compression – Compression algorithm to use for the data.

Returns:

A PixelLayer object

has_clip_layers() → bool

Returns True if the layer has associated clipping.

Returns:

bool

has_effects() → bool

Returns True if the layer has effects.

Returns:

bool

has_mask() → bool

Returns True if the layer has a mask.

Returns:

bool

has_origination() → bool

Returns True if the layer has live shape properties.

Returns:

bool

has_pixels() → bool

Returns True if the layer has associated pixels. When this is True, topil method returns PIL.Image.

Returns:

bool

has_stroke() → bool

Returns True if the shape has a stroke.

has_vector_mask() → bool

Returns True if the layer has a vector mask.

Returns:

bool

property height: int

Height of the layer.

Returns:

int

is_group() → bool

Return True if the layer is a group.

Returns:

bool

is_visible() → bool

Layer visibility. Takes group visibility in account.

Returns:

bool

property kind: str

Kind of this layer, such as group, pixel, shape, type, smartobject, or psdimage. Class name without layer suffix.

Returns:

str

property layer_id: int

Layer ID.

Returns:

int layer id. if the layer is not assigned an id, -1.

property left: int

Left coordinate. Writable.

Returns:

int

lock(lock_flags: int = ProtectedFlags.COMPLETE) → None

Locks a layer accordind to the combination of flags.

Parameters:

lockflags – An integer representing the locking state

Example using the constants of ProtectedFlags and bitwise or operation to lock both pixels and positions:

layer.lock(ProtectedFlags.COMPOSITE | ProtectedFlags.POSITION)

property mask: Mask | None

Returns mask associated with this layer.

Returns:

Mask or None

move_down(offset: int = 1) → Self

Moves the layer down a certain offset within the group the layer is in.

Parameters:

offset

move_to_group(group: GroupMixin) → Self

Moves the layer to the given group, updates the tree metadata as needed.

Parameters:

group – The group the current layer will be moved into.

move_up(offset: int = 1) → Self

Moves the layer up a certain offset within the group the layer is in.

Parameters:

offset

property name: str

Layer name. Writable.

Returns:

str

numpy(channel: str | None = None, real_mask: bool = True) → ndarray | None

Get NumPy array of the layer.

Parameters:

channel – Which channel to return, can be ‘color’, ‘shape’, ‘alpha’, or ‘mask’. Default is ‘color+alpha’.

Returns:

numpy.ndarray or None if there is no pixel.

property offset: tuple[int, int]

(left, top) tuple. Writable.

Returns:

tuple

property opacity: int

Opacity of this layer in [0, 255] range. Writable.

Returns:

int

property origination: list[Origination]

Property for a list of live shapes or a line.

Some of the vector masks have associated live shape properties, that are Photoshop feature to handle primitive shapes such as a rectangle, an ellipse, or a line. Vector masks without live shape properties are plain path objects.

See psd_tools.api.shape.

Returns:

List of Invalidated, Rectangle, RoundedRectangle, Ellipse, or Line.

property parent: TGroupMixin | None

Parent of this layer.

property right: int

Right coordinate.

Returns:

int

property size: tuple[int, int]

(width, height) tuple.

Returns:

tuple

property stroke: Stroke | None

Property for strokes.

property tagged_blocks: TaggedBlocks

Layer tagged blocks that is a dict-like container of settings.

See psd_tools.constants.Tag for available keys.

Returns:

TaggedBlocks.

Example:

from psd_tools.constants import Tag
metadata = layer.tagged_blocks.get_data(Tag.METADATA_SETTING)

property top: int

Top coordinate. Writable.

Returns:

int

topil(channel: int | None = None, apply_icc: bool = True) → Image | None

Get PIL Image of the layer.

Parameters:

• channel – Which channel to return; e.g., 0 for ‘R’ channel in RGB image. See ChannelID. When None, the method returns all the channels supported by PIL modes.

• apply_icc – Whether to apply ICC profile conversion to sRGB.

Returns:

PIL.Image, or None if the layer has no pixels.

Example:

from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)

Note

Not all of the PSD image modes are supported in PIL.Image. For example, ‘CMYK’ mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.

property vector_mask: VectorMask | None

Returns vector mask associated with this layer.

Returns:

VectorMask or None

property visible: bool

Layer visibility. Doesn’t take group visibility in account. Writable.

Returns:

bool

property width: int

Width of the layer.

Returns:

int

ShapeLayer

class psd_tools.api.layers.ShapeLayer(*args: Any)

Layer that has drawing in vector mask.

property bbox: tuple[int, int, int, int]

(left, top, right, bottom) tuple.

property blend_mode: BlendMode

Blend mode of this layer. Writable.

Example:

from psd_tools.constants import BlendMode
if layer.blend_mode == BlendMode.NORMAL:
    layer.blend_mode = BlendMode.SCREEN

Returns:

BlendMode.

property bottom: int

Bottom coordinate.

Returns:

int

property clip_layers: list[Self]

Clip layers associated with this layer.

Returns:

list of layers

property clipping_layer: bool

Clipping flag for this layer. Writable.

Returns:

bool

composite(viewport: tuple[int, int, int, int] | None = None, force: bool = False, color: float | tuple[float, ...] | ndarray = 1.0, alpha: float | ndarray = 0.0, layer_filter: Callable | None = None, apply_icc: bool = True) → Image | None

Composite layer and masks (mask, vector mask, and clipping layers).

Parameters:

• viewport – Viewport bounding box specified by (x1, y1, x2, y2) tuple. Default is the layer’s bbox.

• force – Boolean flag to force vector drawing.

• color – Backdrop color specified by scalar or tuple of scalar. The color value should be in [0.0, 1.0]. For example, (1., 0., 0.) specifies red in RGB color mode.

• alpha – Backdrop alpha in [0.0, 1.0].

• layer_filter – Callable that takes a layer as argument and returns whether if the layer is composited. Default is is_visible().

Returns:

PIL.Image or None.

delete_layer() → Self

Deletes the layer and all its child layers if the layer is a group from its parent (group or psdimage).

property effects: Effects

Layer effects.

Returns:

Effects

has_clip_layers() → bool

Returns True if the layer has associated clipping.

Returns:

bool

has_effects() → bool

Returns True if the layer has effects.

Returns:

bool

has_mask() → bool

Returns True if the layer has a mask.

Returns:

bool

has_origination() → bool

Returns True if the layer has live shape properties.

Returns:

bool

has_pixels() → bool

Returns True if the layer has associated pixels. When this is True, topil method returns PIL.Image.

Returns:

bool

has_stroke() → bool

Returns True if the shape has a stroke.

has_vector_mask() → bool

Returns True if the layer has a vector mask.

Returns:

bool

property height: int

Height of the layer.

Returns:

int

is_group() → bool

Return True if the layer is a group.

Returns:

bool

is_visible() → bool

Layer visibility. Takes group visibility in account.

Returns:

bool

property kind: str

Kind of this layer, such as group, pixel, shape, type, smartobject, or psdimage. Class name without layer suffix.

Returns:

str

property layer_id: int

Layer ID.

Returns:

int layer id. if the layer is not assigned an id, -1.

property left: int

Left coordinate. Writable.

Returns:

int

lock(lock_flags: int = ProtectedFlags.COMPLETE) → None

Locks a layer accordind to the combination of flags.

Parameters:

lockflags – An integer representing the locking state

Example using the constants of ProtectedFlags and bitwise or operation to lock both pixels and positions:

layer.lock(ProtectedFlags.COMPOSITE | ProtectedFlags.POSITION)

property mask: Mask | None

Returns mask associated with this layer.

Returns:

Mask or None

move_down(offset: int = 1) → Self

Moves the layer down a certain offset within the group the layer is in.

Parameters:

offset

move_to_group(group: GroupMixin) → Self

Moves the layer to the given group, updates the tree metadata as needed.

Parameters:

group – The group the current layer will be moved into.

move_up(offset: int = 1) → Self

Moves the layer up a certain offset within the group the layer is in.

Parameters:

offset

property name: str

Layer name. Writable.

Returns:

str

numpy(channel: str | None = None, real_mask: bool = True) → ndarray | None

Get NumPy array of the layer.

Parameters:

channel – Which channel to return, can be ‘color’, ‘shape’, ‘alpha’, or ‘mask’. Default is ‘color+alpha’.

Returns:

numpy.ndarray or None if there is no pixel.

property offset: tuple[int, int]

(left, top) tuple. Writable.

Returns:

tuple

property opacity: int

Opacity of this layer in [0, 255] range. Writable.

Returns:

int

property origination: list[Origination]

Property for a list of live shapes or a line.

Some of the vector masks have associated live shape properties, that are Photoshop feature to handle primitive shapes such as a rectangle, an ellipse, or a line. Vector masks without live shape properties are plain path objects.

See psd_tools.api.shape.

Returns:

List of Invalidated, Rectangle, RoundedRectangle, Ellipse, or Line.

property parent: TGroupMixin | None

Parent of this layer.

property right: int

Right coordinate.

Returns:

int

property size: tuple[int, int]

(width, height) tuple.

Returns:

tuple

property stroke: Stroke | None

Property for strokes.

property tagged_blocks: TaggedBlocks

Layer tagged blocks that is a dict-like container of settings.

See psd_tools.constants.Tag for available keys.

Returns:

TaggedBlocks.

Example:

from psd_tools.constants import Tag
metadata = layer.tagged_blocks.get_data(Tag.METADATA_SETTING)

property top: int

Top coordinate. Writable.

Returns:

int

topil(channel: int | None = None, apply_icc: bool = True) → Image | None

Get PIL Image of the layer.

Parameters:

• channel – Which channel to return; e.g., 0 for ‘R’ channel in RGB image. See ChannelID. When None, the method returns all the channels supported by PIL modes.

• apply_icc – Whether to apply ICC profile conversion to sRGB.

Returns:

PIL.Image, or None if the layer has no pixels.

Example:

from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)

Note

Not all of the PSD image modes are supported in PIL.Image. For example, ‘CMYK’ mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.

property vector_mask: VectorMask | None

Returns vector mask associated with this layer.

Returns:

VectorMask or None

property visible: bool

Layer visibility. Doesn’t take group visibility in account. Writable.

Returns:

bool

property width: int

Width of the layer.

Returns:

int

SmartObjectLayer

class psd_tools.api.layers.SmartObjectLayer(psd: Any, record: LayerRecord, channels: ChannelDataList, parent: TGroupMixin | None)

Layer that inserts external data.

Use smart_object attribute to get the external data. See SmartObject.

Example:

import io
if layer.smart_object.filetype == 'jpg':
    image = Image.open(io.BytesIO(layer.smart_object.data))

property bbox: tuple[int, int, int, int]

(left, top, right, bottom) tuple.

property blend_mode: BlendMode

Blend mode of this layer. Writable.

Example:

from psd_tools.constants import BlendMode
if layer.blend_mode == BlendMode.NORMAL:
    layer.blend_mode = BlendMode.SCREEN

Returns:

BlendMode.

property bottom: int

Bottom coordinate.

Returns:

int

property clip_layers: list[Self]

Clip layers associated with this layer.

Returns:

list of layers

property clipping_layer: bool

Clipping flag for this layer. Writable.

Returns:

bool

composite(viewport: tuple[int, int, int, int] | None = None, force: bool = False, color: float | tuple[float, ...] | ndarray = 1.0, alpha: float | ndarray = 0.0, layer_filter: Callable | None = None, apply_icc: bool = True) → Image | None

Composite layer and masks (mask, vector mask, and clipping layers).

Parameters:

• viewport – Viewport bounding box specified by (x1, y1, x2, y2) tuple. Default is the layer’s bbox.

• force – Boolean flag to force vector drawing.

• color – Backdrop color specified by scalar or tuple of scalar. The color value should be in [0.0, 1.0]. For example, (1., 0., 0.) specifies red in RGB color mode.

• alpha – Backdrop alpha in [0.0, 1.0].

• layer_filter – Callable that takes a layer as argument and returns whether if the layer is composited. Default is is_visible().

Returns:

PIL.Image or None.

delete_layer() → Self

Deletes the layer and all its child layers if the layer is a group from its parent (group or psdimage).

property effects: Effects

Layer effects.

Returns:

Effects

has_clip_layers() → bool

Returns True if the layer has associated clipping.

Returns:

bool

has_effects() → bool

Returns True if the layer has effects.

Returns:

bool

has_mask() → bool

Returns True if the layer has a mask.

Returns:

bool

has_origination() → bool

Returns True if the layer has live shape properties.

Returns:

bool

has_pixels() → bool

Returns True if the layer has associated pixels. When this is True, topil method returns PIL.Image.

Returns:

bool

has_stroke() → bool

Returns True if the shape has a stroke.

has_vector_mask() → bool

Returns True if the layer has a vector mask.

Returns:

bool

property height: int

Height of the layer.

Returns:

int

is_group() → bool

Return True if the layer is a group.

Returns:

bool

is_visible() → bool

Layer visibility. Takes group visibility in account.

Returns:

bool

property kind: str

Kind of this layer, such as group, pixel, shape, type, smartobject, or psdimage. Class name without layer suffix.

Returns:

str

property layer_id: int

Layer ID.

Returns:

int layer id. if the layer is not assigned an id, -1.

property left: int

Left coordinate. Writable.

Returns:

int

lock(lock_flags: int = ProtectedFlags.COMPLETE) → None

Locks a layer accordind to the combination of flags.

Parameters:

lockflags – An integer representing the locking state

Example using the constants of ProtectedFlags and bitwise or operation to lock both pixels and positions:

layer.lock(ProtectedFlags.COMPOSITE | ProtectedFlags.POSITION)

property mask: Mask | None

Returns mask associated with this layer.

Returns:

Mask or None

move_down(offset: int = 1) → Self

Moves the layer down a certain offset within the group the layer is in.

Parameters:

offset

move_to_group(group: GroupMixin) → Self

Moves the layer to the given group, updates the tree metadata as needed.

Parameters:

group – The group the current layer will be moved into.

move_up(offset: int = 1) → Self

Moves the layer up a certain offset within the group the layer is in.

Parameters:

offset

property name: str

Layer name. Writable.

Returns:

str

numpy(channel: str | None = None, real_mask: bool = True) → ndarray | None

Get NumPy array of the layer.

Parameters:

channel – Which channel to return, can be ‘color’, ‘shape’, ‘alpha’, or ‘mask’. Default is ‘color+alpha’.

Returns:

numpy.ndarray or None if there is no pixel.

property offset: tuple[int, int]

(left, top) tuple. Writable.

Returns:

tuple

property opacity: int

Opacity of this layer in [0, 255] range. Writable.

Returns:

int

property origination: list[Origination]

Property for a list of live shapes or a line.

Some of the vector masks have associated live shape properties, that are Photoshop feature to handle primitive shapes such as a rectangle, an ellipse, or a line. Vector masks without live shape properties are plain path objects.

See psd_tools.api.shape.

Returns:

List of Invalidated, Rectangle, RoundedRectangle, Ellipse, or Line.

property parent: TGroupMixin | None

Parent of this layer.

property right: int

Right coordinate.

Returns:

int

property size: tuple[int, int]

(width, height) tuple.

Returns:

tuple

property smart_object: SmartObject

Associated smart object.

Returns:

SmartObject.

property stroke: Stroke | None

Property for strokes.

property tagged_blocks: TaggedBlocks

Layer tagged blocks that is a dict-like container of settings.

See psd_tools.constants.Tag for available keys.

Returns:

TaggedBlocks.

Example:

from psd_tools.constants import Tag
metadata = layer.tagged_blocks.get_data(Tag.METADATA_SETTING)

property top: int

Top coordinate. Writable.

Returns:

int

topil(channel: int | None = None, apply_icc: bool = True) → Image | None

Get PIL Image of the layer.

Parameters:

• channel – Which channel to return; e.g., 0 for ‘R’ channel in RGB image. See ChannelID. When None, the method returns all the channels supported by PIL modes.

• apply_icc – Whether to apply ICC profile conversion to sRGB.

Returns:

PIL.Image, or None if the layer has no pixels.

Example:

from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)

Note

Not all of the PSD image modes are supported in PIL.Image. For example, ‘CMYK’ mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.

property vector_mask: VectorMask | None

Returns vector mask associated with this layer.

Returns:

VectorMask or None

property visible: bool

Layer visibility. Doesn’t take group visibility in account. Writable.

Returns:

bool

property width: int

Width of the layer.

Returns:

int

TypeLayer

class psd_tools.api.layers.TypeLayer(*args: Any)

Layer that has text and styling information for fonts or paragraphs.

Text is accessible at text property. Styling information for paragraphs is in engine_dict. Document styling information such as font list is is resource_dict.

Currently, textual information is read-only.

Example:

if layer.kind == 'type':
    print(layer.text)
    print(layer.engine_dict['StyleRun'])

    # Extract font for each substring in the text.
    text = layer.engine_dict['Editor']['Text'].value
    fontset = layer.resource_dict['FontSet']
    runlength = layer.engine_dict['StyleRun']['RunLengthArray']
    rundata = layer.engine_dict['StyleRun']['RunArray']
    index = 0
    for length, style in zip(runlength, rundata):
        substring = text[index:index + length]
        stylesheet = style['StyleSheet']['StyleSheetData']
        font = fontset[stylesheet['Font']]
        print('%r gets %s' % (substring, font))
        index += length

property bbox: tuple[int, int, int, int]

(left, top, right, bottom) tuple.

property blend_mode: BlendMode

Blend mode of this layer. Writable.

Example:

from psd_tools.constants import BlendMode
if layer.blend_mode == BlendMode.NORMAL:
    layer.blend_mode = BlendMode.SCREEN

Returns:

BlendMode.

property bottom: int

Bottom coordinate.

Returns:

int

property clip_layers: list[Self]

Clip layers associated with this layer.

Returns:

list of layers

property clipping_layer: bool

Clipping flag for this layer. Writable.

Returns:

bool

composite(viewport: tuple[int, int, int, int] | None = None, force: bool = False, color: float | tuple[float, ...] | ndarray = 1.0, alpha: float | ndarray = 0.0, layer_filter: Callable | None = None, apply_icc: bool = True) → Image | None

Composite layer and masks (mask, vector mask, and clipping layers).

Parameters:

• viewport – Viewport bounding box specified by (x1, y1, x2, y2) tuple. Default is the layer’s bbox.

• force – Boolean flag to force vector drawing.

• color – Backdrop color specified by scalar or tuple of scalar. The color value should be in [0.0, 1.0]. For example, (1., 0., 0.) specifies red in RGB color mode.

• alpha – Backdrop alpha in [0.0, 1.0].

• layer_filter – Callable that takes a layer as argument and returns whether if the layer is composited. Default is is_visible().

Returns:

PIL.Image or None.

delete_layer() → Self

Deletes the layer and all its child layers if the layer is a group from its parent (group or psdimage).

property document_resources: Dict

Resource set relevant to the document.

property effects: Effects

Layer effects.

Returns:

Effects

property engine_dict: Dict

Styling information dict.

has_clip_layers() → bool

Returns True if the layer has associated clipping.

Returns:

bool

has_effects() → bool

Returns True if the layer has effects.

Returns:

bool

has_mask() → bool

Returns True if the layer has a mask.

Returns:

bool

has_origination() → bool

Returns True if the layer has live shape properties.

Returns:

bool

has_pixels() → bool

Returns True if the layer has associated pixels. When this is True, topil method returns PIL.Image.

Returns:

bool

has_stroke() → bool

Returns True if the shape has a stroke.

has_vector_mask() → bool

Returns True if the layer has a vector mask.

Returns:

bool

property height: int

Height of the layer.

Returns:

int

is_group() → bool

Return True if the layer is a group.

Returns:

bool

is_visible() → bool

Layer visibility. Takes group visibility in account.

Returns:

bool

property kind: str

Kind of this layer, such as group, pixel, shape, type, smartobject, or psdimage. Class name without layer suffix.

Returns:

str

property layer_id: int

Layer ID.

Returns:

int layer id. if the layer is not assigned an id, -1.

property left: int

Left coordinate. Writable.

Returns:

int

lock(lock_flags: int = ProtectedFlags.COMPLETE) → None

Locks a layer accordind to the combination of flags.

Parameters:

lockflags – An integer representing the locking state

Example using the constants of ProtectedFlags and bitwise or operation to lock both pixels and positions:

layer.lock(ProtectedFlags.COMPOSITE | ProtectedFlags.POSITION)

property mask: Mask | None

Returns mask associated with this layer.

Returns:

Mask or None

move_down(offset: int = 1) → Self

Moves the layer down a certain offset within the group the layer is in.

Parameters:

offset

move_to_group(group: GroupMixin) → Self

Moves the layer to the given group, updates the tree metadata as needed.

Parameters:

group – The group the current layer will be moved into.

move_up(offset: int = 1) → Self

Moves the layer up a certain offset within the group the layer is in.

Parameters:

offset

property name: str

Layer name. Writable.

Returns:

str

numpy(channel: str | None = None, real_mask: bool = True) → ndarray | None

Get NumPy array of the layer.

Parameters:

channel – Which channel to return, can be ‘color’, ‘shape’, ‘alpha’, or ‘mask’. Default is ‘color+alpha’.

Returns:

numpy.ndarray or None if there is no pixel.

property offset: tuple[int, int]

(left, top) tuple. Writable.

Returns:

tuple

property opacity: int

Opacity of this layer in [0, 255] range. Writable.

Returns:

int

property origination: list[Origination]

Property for a list of live shapes or a line.

Some of the vector masks have associated live shape properties, that are Photoshop feature to handle primitive shapes such as a rectangle, an ellipse, or a line. Vector masks without live shape properties are plain path objects.

See psd_tools.api.shape.

Returns:

List of Invalidated, Rectangle, RoundedRectangle, Ellipse, or Line.

property parent: TGroupMixin | None

Parent of this layer.

property resource_dict: Dict

Resource set.

property right: int

Right coordinate.

Returns:

int

property size: tuple[int, int]

(width, height) tuple.

Returns:

tuple

property stroke: Stroke | None

Property for strokes.

property tagged_blocks: TaggedBlocks

Layer tagged blocks that is a dict-like container of settings.

See psd_tools.constants.Tag for available keys.

Returns:

TaggedBlocks.

Example:

from psd_tools.constants import Tag
metadata = layer.tagged_blocks.get_data(Tag.METADATA_SETTING)

property text: str

Text in the layer. Read-only.

Note

New-line character in Photoshop is ‘\r’.

property text_type: TextType | None

Text type. Read-only.

Returns:

• psd_tools.constants.TextType.POINT for point type text (also known as character type)

• psd_tools.constants.TextType.PARAGRAPH for paragraph type text (also known as area type)

• None if text type cannot be determined or information is unavailable

See psd_tools.constants.TextType.

property top: int

Top coordinate. Writable.

Returns:

int

topil(channel: int | None = None, apply_icc: bool = True) → Image | None

Get PIL Image of the layer.

Parameters:

• channel – Which channel to return; e.g., 0 for ‘R’ channel in RGB image. See ChannelID. When None, the method returns all the channels supported by PIL modes.

• apply_icc – Whether to apply ICC profile conversion to sRGB.

Returns:

PIL.Image, or None if the layer has no pixels.

Example:

from psd_tools.constants import ChannelID

image = layer.topil()
red = layer.topil(ChannelID.CHANNEL_0)
alpha = layer.topil(ChannelID.TRANSPARENCY_MASK)

Note

Not all of the PSD image modes are supported in PIL.Image. For example, ‘CMYK’ mode cannot include alpha channel in PIL. In this case, topil drops alpha channel.

property transform: tuple[float, float, float, float, float, float]

Matrix (xx, xy, yx, yy, tx, ty) applies affine transformation.

property vector_mask: VectorMask | None

Returns vector mask associated with this layer.

Returns:

VectorMask or None

property visible: bool

Layer visibility. Doesn’t take group visibility in account. Writable.

Returns:

bool

property warp: DescriptorBlock | None

Warp configuration.

property width: int

Width of the layer.

Returns:

int