Core API

Overview

PsdImage is the entry point. It represents a PSD or PSB document that can be loaded, inspected and saved without rendering. Image is its base class.


Loading a Document

PsdImage.load(String) takes the path of a file. PsdImage.load(InputStream) takes a stream and declares the checked PsdLoadException. Image.load(String) and Image.load(InputStream) return an Image; for a PSD or PSB file it is a PsdImage. PSD and PSB files load through the same calls, and PsdImage does not report which of the two a file is: use the file extension if you need to know.


Streams

When you load from a stream that supports mark and reset, such as a ByteArrayInputStream, the position is restored after loading. load(InputStream) and dispose() do not close the stream that you passed in. save(OutputStream) is different: it closes the stream that you pass in, so do not give it a stream that you still need, such as an entry of a ZipOutputStream.


Reading the Header

MemberReturns
getWidth(), getHeight()Document size in pixels
getSize(), getBounds()Size and bounds objects
getBitsPerChannel()Bits stored per channel
getColorMode()A ColorModes value; RGB, CMYK and indexed-color PSD files and RGB PSB files were tried
getCompression()A CompressionMethod value
getChannelsCount()Number of channels
getLayers()The Layer objects; a new array on every call
getImageResources()The image resource blocks, read-only

Saving

save(String) writes a file and save(OutputStream) writes a stream. In the library’s own tests a document that is saved without changes is identical to the file that was loaded, for PSD and PSB. save declares only IOException; a save problem such as a layer name longer than 255 characters surfaces as a RuntimeException whose cause is PsdSaveException.


Errors

SituationWhat you get
Invalid signature or header, an empty stream, or data that ends before the end of the image resources or layer sections, in load(InputStream)A checked PsdLoadException
The same problems in load(String)A RuntimeException that wraps the PsdLoadException
A path that does not existFileNotFoundException
A null pathIllegalArgumentException

The loader does not check the merged image data at the end of the file. A file that is cut off or damaged there still loads, so loading successfully is not a proof that a file is complete.


After Close

After close() or dispose(), getWidth() and getLayers() still return values, and save throws an IllegalStateException. Calling close() a second time is harmless.


Limitations

setActiveLayer, setImageResources, setGlobalLayerResources and setHasTransparencyData always throw UnsupportedOperationException. getVersion() returns 6 for PSD and PSB alike. getActiveLayer() returns the first layer, or null when the document has no layers. There is no rendering, export or pixel decoding.


Tips and Best Practices

  • Use try-with-resources so that the image is always closed.
  • Catch PsdLoadException where you load from a stream.
  • Read getLayers() once and keep the array if you loop over it.

Common Issues

IssueCauseFix
A checked exception is not caught by catch (IOException)PsdLoadException extends Exception, not IOExceptionCatch PsdLoadException as well
getVersion() is 6 for a PSB fileIt is a constant in this editionUse the file extension to tell PSB from PSD
A stream is closed after savesave(OutputStream) closes the streamPass a stream that you do not need afterwards, or wrap it so that close() does nothing

FAQ

Does load(String) throw PsdLoadException?

No. It wraps it in a RuntimeException. load(InputStream) throws the checked exception.

Is the input stream closed for me?

load(InputStream) does not close it. save(OutputStream) closes the output stream.


API Reference Summary

ClassDescription
PsdImageA PSD or PSB document
ImageBase class with load and save
ColorModesThe color modes of a document
CompressionMethodThe compression methods
PsdLoadExceptionThrown when loading fails

See Also