Layers

Overview

PsdImage.getLayers() returns the Layer objects of a document. A Layer carries the metadata of one PSD layer: name, visibility, opacity, clipping, blend mode and position, plus channel, mask and blending-range information. The library reads and writes this metadata; it does not decode layer pixels.


Reading Layer Metadata

MemberMeaning
getName()The layer name
isVisible()Whether the layer is visible
getOpacity()Opacity as a byte that holds 0 to 255; read it with & 0xFF to get the unsigned value
getClipping()The clipping value
getBlendModeKey()A BlendMode value, for example Normal or LinearBurn; getRawBlendModeKey() returns the stored text
getLeft(), getTop(), getRight(), getBottom(), getWidth(), getHeight()The position and size of the layer
getBounds()A rectangle at (0, 0) with the layer’s width and height, not its position
getChannelsCount(), getChannels()The channels of the layer
getMaskInfo(), getBlendingRangesInfo()Read-only information about the mask and the blending ranges

Changing Layer Metadata

setName(String), setVisible(boolean) and setOpacity(byte) change a layer. The Layer objects that getLayers() returns belong to the image, so saving the image writes the change. After you save the document and load it again, the new name, visibility and opacity are there. hasMutated() reports whether a layer was changed after loading. The position, clipping and blend mode key also have setters and their changes are written too, but the library does not change the layer’s channel data when you change the position.


Layer Names

Layer names are written as ASCII text of at most 255 characters:

  • A character that is not ASCII is saved as ?.
  • A name longer than 255 characters makes save throw a RuntimeException whose cause is PsdSaveException.
  • Saving a document that you have edited rewrites every layer record, so the non-ASCII names of layers that you did not edit are saved as ? too. Do not edit documents whose layer names contain non-ASCII characters.
  • The library updates the layer record’s name only. A PSD file can also carry the name in a separate Unicode block that the library leaves unchanged, so other tools may still show the old name after a rename.

The Layer Array

getLayers() returns a new array on every call, so keep the array if you loop over it. Passing the same array back to setLayers(Layer[]) is accepted and the saved file reloads with the same layers, but the call counts as a layer edit: the writer then rewrites every layer record instead of copying the loaded bytes, so non-ASCII layer names are saved as ?. Adding, removing or reordering layers through setLayers is not a supported edit: the saved file keeps the channel data of the original layer list, and this documentation does not describe it as a feature.


Setters That Are Not Supported

Layer.setChannelInformation, Layer.setLayerMaskData and Layer.setLayerBlendingRangesData always throw UnsupportedOperationException. The matching getters work.


Tips and Best Practices

  • Convert getOpacity() with & 0xFF; a plain byte is negative above 127.
  • Check isVisible() before you assume a layer is shown in Photoshop; hidden layers load like any other.
  • Reload the saved file when you need to confirm an edit.

Common Issues

IssueCauseFix
Opacity prints as a negative numbergetOpacity() returns a signed byteUse getOpacity() & 0xFF
UnsupportedOperationException when setting mask dataThat setter is not supported in this editionLeave mask and blending-range data as loaded
The layer count is wrong after setLayers with a shorter arrayRemoving layers is not a supported editKeep the layer array as loaded
Layer names contain ? after savingNames are written as ASCIIKeep layer names ASCII

FAQ

Can I read layer pixels?

No. The library does not decode pixels.

Does getActiveLayer() give the layer selected in Photoshop?

No. It returns the first layer, or null when the document has no layers.


API Reference Summary

ClassDescription
LayerOne layer and its metadata
BlendModeThe blend modes
LayerMaskInfoRead-only mask information
LayerBlendingRangesInfoRead-only blending-range information
PsdImageHolds the layers

See Also