# 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