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
| Member | Returns |
|---|---|
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
| Situation | What 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 exist | FileNotFoundException |
A null path | IllegalArgumentException |
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
PsdLoadExceptionwhere you load from a stream. - Read
getLayers()once and keep the array if you loop over it.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
A checked exception is not caught by catch (IOException) | PsdLoadException extends Exception, not IOException | Catch PsdLoadException as well |
getVersion() is 6 for a PSB file | It is a constant in this edition | Use the file extension to tell PSB from PSD |
A stream is closed after save | save(OutputStream) closes the stream | Pass 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
| Class | Description |
|---|---|
| PsdImage | A PSD or PSB document |
| Image | Base class with load and save |
| ColorModes | The color modes of a document |
| CompressionMethod | The compression methods |
| PsdLoadException | Thrown when loading fails |