How to Read and Edit PSD Layer Metadata in Java
View as Markdown

How to Read and Edit PSD Layer Metadata in Java

This guide shows how to list the layers of a document, read their metadata, change a layer’s name, visibility and opacity, and save. A Layer carries metadata only; the library does not decode layer pixels.

Step-by-Step Guide

Step 1: Add the Library

<dependency>
  <groupId>org.aspose</groupId>
  <artifactId>aspose-psd-foss</artifactId>
  <version>26.11.0</version>
</dependency>

Step 2: Load the Document and Get the Layers

Load the file with PsdImage.load(String) and call getLayers(). It returns a new array on every call, so keep the array if you loop over it. The Layer objects in it belong to the image.


Step 3: Read Layer Metadata

For each Layer, read getName(), isVisible(), getOpacity(), getClipping() and getBlendModeKey(), and the position with getLeft(), getTop(), getRight() and getBottom(). getOpacity() returns a byte that holds 0 to 255, so use getOpacity() & 0xFF to get the unsigned value. getBounds() is not the position: it returns a rectangle at (0, 0) with the layer’s width and height.


Step 4: Change the Metadata

Call setName(String), setVisible(boolean) or setOpacity(byte) on a layer. Because the layers belong to the image, the change is part of the document at once.


Step 5: Save and Check

Save with PsdImage.save(String) or PsdImage.save(OutputStream). Load the saved file again to confirm that the new name, visibility and opacity are there.

Things to Know

  • Layer names are saved as ASCII text of at most 255 characters. A character that is not ASCII is saved as ?, and because saving an edited document rewrites every layer record, the non-ASCII names of layers 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. Other tools may still show the old name if the file carries the name in a separate Unicode block.
  • Layer.setChannelInformation, Layer.setLayerMaskData and Layer.setLayerBlendingRangesData are not supported in this edition and always throw UnsupportedOperationException.
  • Adding, removing or reordering layers through setLayers is not a supported edit. Passing the same array back is accepted, but it counts as a layer edit and the writer then rewrites every layer record.
  • PsdImage.getActiveLayer() returns the first layer (or null when there are no layers), not the layer that was active in Photoshop.

See Also