Advanced automation and scripting with AppleScript

Pixelmator Pro includes extensive and full-featured support for AppleScript, the scripting language created by Apple that lets you directly control apps using instructions written in an English-like scripting language.

There are many different ways you can use AppleScript to speed up and enhance your image editing workflows. For example, you can use it to automate repetitive tasks, such as changing the color of the background in, say, 100 images to a specific shade of blue. You can also create workflows that involve multiple applications — for example, if you need to take a set of texts from a Numbers spreadsheet and use them to label a series of images. You can even use AppleScript to extend the functionality of Pixelmator Pro itself, for example by writing a script that creates a 3D text effect using the built-in tools in the app.

AppleScript basics

In this tutorial, we won’t go too in depth into the Script Editor, dictionaries, or the syntax of the AppleScript language, as these are covered on many different websites dedicated to AppleScript. However, we’d like to share a couple example scripts with you and there are a few main pieces of information that should help you understand these scripts and get started with AppleScript in general. We’ll also point you to useful resources if you’d like to learn more about AppleScript itself.

Getting started and opening the Script Editor

To get started with writing, compiling, running, and saving scripts, you’ll need to open the Script Editor app. You can find it in the Utilities folder inside the Applications folder. You can also use Spotlight to search for “Script Editor” and open it that way.

Tip

You can learn more about using the Script Editor here.

Finding the Pixelmator Pro dictionary

Along with the standard AppleScript terms, every scriptable application has its own dictionary with the words and phrases specific to a particular app. To open the dictionary for Pixelmator Pro, choose File > Open Dictionary, then find Pixelmator Pro and click Choose.

In the Pixelmator Pro dictionary, you’ll find various example scripts that show you how to use each of these app-specific terms.

AppleScript syntax fundamentals

AppleScript syntax is heavily based on English syntax, so even if you have no programming experience, you can often find out what a script does by simply reading it. We won’t delve too deep into AppleScript syntax as there are many resources that focus on this, but there are a few basic concepts that should help you understand the example scripts in the following section of the tutorial.

The Tell Block

You use the ‘tell’ phrase to tell an application what you want it to do. In fact, that’s the very first word of many simple scripts. An empty application tell block looks like this:

tell application "Pixelmator Pro"
    --Your instructions would go here
end tell

Inside the tell block, you place the commands you’d like Pixelmator Pro to execute.

Object Hierarchy

There is a set hierarchy of objects, starting with the application object at the top. To edit an object, you have to tell that specific object to change something. As the hierarchy starts with the application object, when writing scripts for Pixelmator Pro, the first phrase will always be:

tell application "Pixelmator Pro"

When you want to make changes to a specific layer inside a specific document, you’ll need to make sure you’re targeting it. There are different ways to do this, but here’s one simple example that sets the stroke width of the first layer in the current document to 5 pixels using a number of nested tell blocks:

tell application "Pixelmator Pro"
    tell its front document
        tell its first layer
            tell its styles
                set the stroke width to 5.0
            end tell
        end tell
    end tell
end tell

Open in Script Editor

The basic Pixelmator Pro hierarchy is: Application Documents Layers  Effects.

First, you specify which application you’re instructing. Then, the application may have multiple documents, so you need to say which one you’d like to edit. A specific document can also have a number of different layers, so you need to say which layer you’d like to edit, and how you’d like to edit it. Finally, layers can also contain effects. Note that color adjustments and styles are properties of layers, rather than separate objects contained by layers.

AppleScript is a very flexible language, so you can also write the command above like this:

tell application "Pixelmator Pro"
    tell the styles of the first layer of the front document to set the stroke width to 5.0
end tell

Open in Script Editor

Or even:

tell application "Pixelmator Pro"
    tell the front document's first layer's styles to set the stroke width to 5.0
end tell

Open in Script Editor

Note how, in both cases, you’re still navigating down the hierarchy to the object you’d like to edit and, in this case, you’re changing one of its properties.

Along with setting properties, you can also use verbs such as ‘select’ to perform actions. Like this:

tell application "Pixelmator Pro"
    select every layer of the front document
end tell

Open in Script Editor

Color adjustments and layer styles are properties of layers, so you can use the syntax above to edit them. Each layer will always have these properties and they will be editable.

Effects are a little different. They are elements that are contained by layers or layer masks. In the same way that a number of different layers might belong to a document, a number of different effects might belong to a layer and these need to be created using the standard ‘make’ verb. Here’s the basic syntax:

tell application "Pixelmator Pro"
    tell its front document
        tell its first layer
            make new gaussian effect at the beginning of effects with properties {radius:5}
        end tell
    end tell
end tell

Open in Script Editor

Tip

To find out the properties of each object and the values they take, look them up in the app dictionary. To lean more about the AppleScript language itself, check out the list of useful resources at the end of this tutorial.

A few example scripts

For some inspiration, here are a few example scripts, showing the kinds of things you can do with AppleScript and Pixelmator Pro.

A simple “Hello, world!” alert

The first script is a very basic script that will make Pixelmator Pro show an alert containing the phrase “Hello, world!”.

tell application "Pixelmator Pro"
    display alert "Hello, world!"
end tell

Open in Script Editor

Even if Pixelmator Pro isn’t open, the script will automatically launch the app and show the alert. You can click here to learn more about displaying dialogs and alerts with AppleScript.

Find and replace text

Pixelmator Pro doesn’t currently include a way to find and replace text, but you’ll notice we’ve added a ‘replace’ command for replacing text to the Pixelmator Pro dictionary, so you could actually script this feature yourself. Here’s one way to replace some text:

tell application "Pixelmator Pro"
    tell the front document
        replace text "Bob" with "Jim"
    end tell
end tell

Open in Script Editor

Note

If no document is open, the script will encounter an error and will not run. And if there are no instances of “Bob” in the document, it will run but nothing will happen.

This isn’t the most useful script as it will always simply replace “Bob” with “Jim” but you could also expand this script to prompt a user for the text to find and replace. Here’s what that would look like:

tell application "Pixelmator Pro"
    tell the front document
        set theSearchString to text returned of (display dialog ¬
           "What text would you like to find?" default answer ¬
           "" buttons {"Cancel", "Continue"} default button "Continue")
        set theReplacementString to text returned of (display dialog ¬
           "What would you like to replace the text with?" default answer ¬
           "" buttons {"Cancel", "Continue"} default button "Continue")
        replace text theSearchString with theReplacementString
    end tell
end tell

Open in Script Editor

In this more complex example, the user is prompted for both the search string and the replacement string each time the script is run, making it much more useful and versatile!

Creating a 3D text effect

One of our tutorials describes how to create a 3D text effect and one of its steps involves duplicating a layer 27 times and moving it down and to the right by 1 pixel. This is just the kind of repetitive task that AppleScript is perfect for!

This is a more complex script and checks to make sure a single text layer is selected to avoid as many errors and accidental duplications as possible. It also adjusts the size of the effect to work equally well with smaller as well as larger layers. What’s more, because it has to hide certain layers while merging, the script also has to keep in mind which layers were originally hidden and which were visible to restore the original state of the composition. Here’s what that looks like:

tell application "Pixelmator Pro"
    activate
    tell front document
        if not (count selected layers) = 1 then
            display alert "Make sure a single text layer is selected."
        else
            if not class of current layer = text layer then
                display alert "Make sure a single text layer is selected."
            else
                set originalVisibleLayers to index of every layer ¬
                  whose visible is true
                set fontSize to size of the text content of the current layer
                tell current layer
                    set color of text content to {65535, 61096, 51260}
                    convert into shape
                end tell
                tell styles of current layer
                    set stroke width to (fontSize / 25)
                    set stroke position to center
                end tell
                set {coordX, coordY} to position of current layer
                repeat with stripeThickness from 1 to (fontSize / 18)
                    set currentLayerIndex to (index of current layer)
                    duplicate layer currentLayerIndex
                    set the position of layer currentLayerIndex to ¬
                      {coordX - stripeThickness, coordY - stripeThickness}
                end repeat
                set currentLayerIndex to (index of current layer)
                set visible of every layer whose index is less than ¬
                  (currentLayerIndex + 1) to false
                set visible of every layer whose index is greater than ¬
                  (currentLayerIndex + stripeThickness) to false
                merge visible
                set visible of layer currentLayerIndex to true
                select (layer (currentLayerIndex + 1))
                repeat with numberOfAdditionalStripes from 1 to 3
                    set currentLayerIndex to (index of current layer)
                    duplicate layer currentLayerIndex
                    set {coordX, coordY} to position of layer currentLayerIndex
                    set currentLayerIndex to currentLayerIndex + 1
                    set the position of layer currentLayerIndex to ¬
                      {coordX + stripeThickness, coordY + stripeThickness}
                    select layer currentLayerIndex
                end repeat
                select (second layer whose visible is true)
                set currentLayerIndex to index of current layer
                set rgbCodeList to {{10000, 12543, 23808}, {20736, 44544, 42752}, ¬
                  {62976, 43776, 23040}, {55552, 22528, 20992}}
                set rgbColor to 1
                repeat with colorIndex from 1 to (1 + numberOfAdditionalStripes)
                    set the fill color of the styles of layer currentLayerIndex to ¬
                      {item rgbColor of rgbCodeList}
                    set rgbColor to rgbColor + 1
                    if rgbColor > 4 then
                        set rgbColor to 1
                    end if
                    set currentLayerIndex to currentLayerIndex + 1
                end repeat
                select (first layer whose visible is true)
                tell styles of current layer
                    set stroke width to 0.0
                end tell
                merge visible
                repeat with a from 1 to count originalVisibleLayers
                    set visible of layer (item a of originalVisibleLayers) to true
                end repeat
            end if
        end if
    end tell
end tell

Open in Script Editor

Creating a luminosity mask

A luminosity mask is a mask based on the brightness values of the image that usually masks out the brightest or darkest areas of the image, letting you adjust just one set of tones without affecting the others. In order to create a luminosity mask, you need to follow quite a complex set of steps but, using AppleScript, you can extend the functionality of Pixelmator Pro to automate creating luminosity masks. Here’s the script:

use scripting additions

tell application "Pixelmator Pro"
    tell the front document
        if class of current layer = image layer then
            set listOfMaskChoices to {"Brights", "Darks"}
            set maskChoice to choose from list listOfMaskChoices with prompt ¬
              "Choose a luminosity mask:" default items {"Brights"}
            if not maskChoice = false then
                set temporaryMaskFile to ((path to temporary items from user domain ¬
                  as text) & "PixelmatorProLuminosityMask.tif")
                set originalLayer to current layer
                repeat 2 times
                    duplicate originalLayer
                end repeat
                set blackAndWhiteLayer to current layer
                tell color adjustments of blackAndWhiteLayer
                    set black and white to true
                end tell
                if maskChoice = {"Darks"} then
                    invert colors of blackAndWhiteLayer
                end if
                set visible of every layer to false
                set visible of blackAndWhiteLayer to true
                export to temporaryMaskFile as TIFF
                set visible of every layer to true
                set luminosityMaskLayer to layer after blackAndWhiteLayer
                delete blackAndWhiteLayer
                mask luminosityMaskLayer
                make new image fill effect at the beginning of effects of layer mask ¬
                  of luminosityMaskLayer with properties {image:temporaryMaskFile}
            end if
        else
            display dialog ¬
              "A luminosity mask can only be created from an image layer." with icon note ¬
                buttons {"OK"} default button "OK"
        end if
    end tell
end tell

Open in Script Editor

Questions and More Resources

If you have any questions about scripting Pixelmator Pro, feel free to ask them on our Community forum. And if you’d like to learn more about the syntax of the AppleScript language or writing scripts, there are many different resources online to help you get started and get inspired. Here are a few of our favorites along with some apps that make scripting easier and more convenient:

Add Comment