🎉 Imaging API Documentation update, plus expanded TextItem capabilities

@samgannaway has updated the Photoshop documentation with the following:

The Imaging API … will enable UXP plugins/scripts to get and set pixel data into directly into layers and masks (and even selections in a way). We are considering these functions to be properly “beta” in that we are hoping to receive feedback before we cement them. In fact, access to them is via an “imaging_beta” property to drive home the point:


TextItem is a regular DOM update. However, this update goes far beyond what was possible in ExtendScript. I won’t list all the properties here because the number is large.


Please leave feedback for these new capabilities in this forum.


Great to see. There are two comments in the documentation:

First off, all Imaging API methods that return pixels are asynchronous. This is needed because modifying and even querying pixel data may incur disk I/O.

Converting image data between different color spaces or color profiles is somewhat time consuming.

The docs say the API is run async meaning other code can run while this occurs in the background.

Will there be a way to get the progress of the calls? That way we can inform users that progress is happening and how far along it is.

IMO it would be a much better to store pixels like:

[[R1, G1, B1], [R2, G2, B2], [R3, G3, B3]]


[[R1, R2, R3], [G1, G2, G3], [B1, B2, B3]]

Would be much easier to parse pixel by pixel or channel by channel

From the docs I don’t understand how to use PhotoshopImageData :confused: In the example:

const pixelData = await imageObj.imageData.getData()

What is imageObj?

Edit: Oh, you get it with any other getter of Imaging API and imageData is there. IMHO this should be mentioned in PhotoshopImageData section

It’s super exciting to see UXP develop beyond ExtendScript’s capabilities! :smiley:

One suggestion that I have is to consider support for putting raw pixel data, i.e. support for image data without color profile. That would require PhotoshopImageData to represent such a state. This would support the use-case in which Photoshop’s color management is disabled (via Edit > Assign Profile). This is actually pretty common in environments where ICC profiles are not widely used anymore in the pipeline (notably VFX pipelines relying on OpenColorIO).

Another minor point is the use of the term “color space” to refer to RGB, Grayscale, Lab etc. I would argue that this should rather be “color model” (in the GUI actually referred to as color mode). (i.e. sRGB or Linear RGB are both color spaces for the RGB color model). I know this sounds like a nit-picky note and the two terms are sometimes (unfortunately) used interchangeably in literature, but since this API is brand new there’s a chance here to do it right and future proof :wink:


To everyone that has posted here so far (and in the future):

Your comments are exactly why we released this in Beta+(Beta). We will be collecting all the comments here and elsewhere to further the discussion and development of this feature.

Thank you for contributing.



Slightly related, can you add in the features to encode and save to PNG, JPEG, etc.

Why? There are JS libraries that take pixel data and create a PNG but in some cases native support may offer orders of magnitude performance improvements over library support, as in 10ms versus 5000ms. So having native support for this would make a huge difference.

Note: I now see there’s encodeImageData method for JPEG. It looks like it returns a base64 string. This is great. Add to the wish list a PNG support.


textItem showing up as undefined. When I access a text layer with the following:

let layer = utls.getLayerByID(layerID);
utls.showAlert(layer.name  + ': "' + layer.textItem.contents + '"');

layer.name works fine, but layer.textItem shows up in the debugger as “undefined.” And in the debugger, if I plow down into the properties, textItem doesn’t show up at all, which is consistent with undefined.

1 Like

same for me, although docs say available in 24.1

I’m trying the “imaging -test” plugin, I noticed that on pc the execution is very slow. I tried the desaturation function, on two different PCs and on a Mac. there is a noticeable performance difference, it is about 10-15 times slower on pc. i think there is a bug.

:point_up_2:t2: Pinging @samgannaway for the alleged one order of magnitude performance difference PC/Mac with the Imaging API

1 Like

Very late comment on this thread, but I’ve just noticed that the imaging API page does not have any flags on the Photoshop version from which each call is available.

1 Like

Yes… also there were some bug fixes with layer masks later on. Bug fixes should be documented as well along with the version.