How to Work with the Aspose.PSD FOSS Core API in Python

Aspose.PSD FOSS for Python loads and inspects PSD/PSB document structure through PsdImage, a subclass of Image. This article covers loading a document, reading its header and image resources, and saving it back to disk.

Step-by-Step Guide

Step 1: Install the Package

git clone https://github.com/aspose-psd-foss/Aspose.PSD-FOSS-for-Python.git
cd Aspose.PSD-FOSS-for-Python
# No packaging manifest is published yet -- run from this folder,
# or add it to PYTHONPATH:
export PYTHONPATH=$PWD:$PYTHONPATH

Step 2: Import Required Classes

from aspose_psd_foss.psdimage import PsdImage

Step 3: Load a PSD/PSB Document

PsdImage.load() opens a document from a file path or a stream:

from aspose_psd_foss.psdimage import PsdImage

image = PsdImage.load("input.psd")

Step 4: Inspect the Document Header

PsdImage exposes header fields read from the parsed document: width, height, bits_per_channel, color_mode (a ColorModes value), and compression (a CompressionMethod value):

print(f"{image.width}x{image.height}, {image.bits_per_channel} bpc")
print(f"Color mode: {image.color_mode}")    # e.g. ColorModes.RGB
print(f"Compression: {image.compression}")  # e.g. CompressionMethod.RLE
print(f"Flattened: {image.is_flatten}")

ColorModes values are BITMAP, GRAYSCALE, INDEXED, RGB, CMYK, MULTICHANNEL, DUOTONE, and LAB. CompressionMethod values are RAW, RLE, ZIP_WITHOUT_PREDICTION, and ZIP_WITH_PREDICTION.

Step 5: Read Image Resource Blocks

image_resources returns the document’s parsed ResourceBlock entries. Each block exposes id, name, and size:

for resource in image.image_resources:
    print(f"Resource {resource.id} \"{resource.name}\" - {resource.size} bytes")

image_resources is read-only in this FOSS build — assigning to it raises NotSupportedException (see Known Limitations in the FAQ).

Step 6: Save the Document

image.save("output.psd")
image.dispose()

Common Issues and Fixes

PsdLoadException when loading a file. The input is not a valid PSD/PSB document, or its header failed validation. Confirm the file is a genuine PSD/PSB file before loading.

NotSupportedException when setting image_resources or global_layer_resources. These setters are not supported in this FOSS build. Treat image_resources as read-only.

Frequently Asked Questions

Can I load a PSD file from a stream instead of a file path?

Yes — PsdImage.load() accepts either a file path string or a readable stream (io.BytesIO/io.BufferedIOBase).

Does `image_resources` include layer data?

No. image_resources holds document-level resource blocks (parsed from the PSD image resources section). Layer-level data is read through PsdImage.layers — see Working with Layers.

Is `PsdImage.version` the PSD file format version?

No. PsdImage.version reports an internal Aspose.PSD-compatible API version number (currently 6) — it is unrelated to whether the loaded file is PSD or PSB. Its setter only accepts the value 6; any other value raises ValueError.