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
| Member | Meaning |
|---|---|
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
savethrow aRuntimeExceptionwhose cause isPsdSaveException. - 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 plainbyteis 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
| Issue | Cause | Fix |
|---|---|---|
| Opacity prints as a negative number | getOpacity() returns a signed byte | Use getOpacity() & 0xFF |
UnsupportedOperationException when setting mask data | That setter is not supported in this edition | Leave mask and blending-range data as loaded |
The layer count is wrong after setLayers with a shorter array | Removing layers is not a supported edit | Keep the layer array as loaded |
Layer names contain ? after saving | Names are written as ASCII | Keep 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
| Class | Description |
|---|---|
| Layer | One layer and its metadata |
| BlendMode | The blend modes |
| LayerMaskInfo | Read-only mask information |
| LayerBlendingRangesInfo | Read-only blending-range information |
| PsdImage | Holds the layers |