scripting image replacement within numbers

A subtle problem that, for sure, Apple could fix, but I think I understand why.

Ultimately, when you embed an image, the image is stored within the .numbers file and is, essentially, disassociated with the source file (especially bearing in mind that the image could be a file from disk or a photo from your Photos library. That's essentially why it doesn't update with changes to the source file.

The easiest workaround I could come up with is this:

ell application "Numbers"
	tell sheet 1 of document 1
		-- get the image
		set myImage to image 1
		-- grab its properties
		tell myImage
			set {fn, h, l, o, pos, refs, refv, rot, w} to its {file name, height, locked, opacity, position, reflection showing, reflection value, rotation, width}
		end tell
		delete myImage
		
		-- this assumes the image is on your desktop. Amend to your image path
		set newImage to make new image with properties {file:(POSIX path of (path to desktop) as text) & fn}
		tell newImage
			set {height, locked, opacity, position, reflection showing, reflection value, rotation, width} to {h, l, o, pos, refs, refv, rot, w}
			
		end tell
	end tell
end tell

It works by identifying the image (in this case I'm just assuming 'image 1'), and grabs all its properties.

It then deletes the image and immediately recreates it with the same filename (assuming it was a file on disk). The script then (re)sets all the image properties to match the original image.

Not quite the same as updating in-place, but pretty close.

Since the image is embedded, there is no record of where the original source image came from, so you'll have to set that part yourself.

This is essentially the same thing as happens if you click the 'Replace' button in the Image sidebar when the image is selected, but you wanted a scripted version.

What a beautiful rathole that is...

There seems to be some internal confusion within Numbers when it relates to file references - actually this is a long-standing problem with multiple ways to define a 'file' in AppleScript, and not all applications are clear about which form they accept (and when).

I was able to replicate the problem with the documents folder. That occurs because Numbers.app overrides the path to command:

set sysPath to path to documents folder
-- > alias "Macintosh HD:Users:<username>:Documents:"


tell application "Numbers"
	set nPath to path to documents folder
	-- > alias "Macintosh HD:Users:<username>:Library:Containers:com.apple.iWork.Numbers:Data:Documents:"
end tell

which I guess kind of makes sense since you're asking Numbers for its Documents folder, but I didn't expect that (and don't see why it should affect the Desktop, which should be universal).

in either case, it's then further complicated by the fact path to returns an alias object whereas Numbers wants a file (hence the levels of coercion - file.. POSIX file... text.. yada yada yada).

Upshot, if you want to reference an image from your Documents folder, grab that path outside of a tell application "Numbers" block:

set docPath to POSIX path of (path to documents folder)

tell application "Numbers"
	-- ... existing script stripped for clarity 
		
		-- used the saved path to Documents
		set newImage to make new image with properties {file:POSIX file ((docPath) & fn as text)} --at end of images
		tell newImage
			set {height, locked, opacity, position, reflection showing, reflection value, rotation, width} to {h, l, o, pos, refs, refv, rot, w}
		end tell
	end tell
end tell

> First, my scripts and SVG file are stored in the same directory as my Numbers spreadsheet. Rather than hardcode the path I want to build it programmatically based upon some manipulations of '(path to me)' for the helper script.

path to me returns the path to the running application, not the current document.

To get the current document's path, ask it for its file:

tell application "Numbers"
	tell document 1
		set f to its file		
	end tell
end tell

Now you have the path to the .numbers file. There are a couple of ways of finding the directory from there - the easiest is to ask the Finder.

Here's a revised script that looks for a file in the same folder as the .numbers file:

use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions

tell application "Numbers"
	set docPath to file of document 1
	tell sheet 1 of document 1
		-- get the image
		set myImage to image 1
		-- grab its properties
		tell myImage
			set {fn, h, l, o, pos, refs, refv, rot, w} to its {file name, height, locked, opacity, position, reflection showing, reflection value, rotation, width}
		end tell
		delete myImage
		
	end tell
end tell

-- have to drop out of Numbers here due to property name conflicts
tell application "Finder"
	set d to container of (file docPath) -- find the folder containing the .numbers file
	-- build a path to the image by combining the folder path and the image name
	set newImagePath to (file fn of d) as text
end tell

-- and back to Numbers
tell application "Numbers"
	tell sheet 1 of document 1
		
		set newImage to make new image with properties {file:newImagePath}
		tell newImage
			set {height, locked, opacity, position, reflection showing, reflection value, rotation, width} to {h, l, o, pos, refs, refv, rot, w}
			
		end tell
	end tell
end tell

With a little work you could add a safeguard to verify the file exists before deleting the current one

> The one remaining thing I'm curious about now is whether it's possible to specify an explicit image name directly (thereby extending how increadibly usefult this is), or if

As above, you can reference an image by index (... image 1 ...) or by file name.

If you know the filename, you can reference it by that:

tell application "Numbers"
	tell sheet 1 of document 1
		set myImage to first image whose file name is "Sample Image.svg"
	end tell
end tell

However, you can reference images by any of their properties:

tell application "Numbers"
	tell sheet 1 of document 1
		set myImageByHeight to first image whose height is 600 -- based on height
		set myImageByWidth to first image whose width is 450 -- based on width
		set myImagebyPosition to first image whose position is {72, 19} -- at a specific location
		set myImageByRotation to first image whose rotation is 101 -- at a specific orientation
		set myImageByDescription to first image whose description is "blah" -- with a specific description
	end tell
end tell

(note: in writing this post I realized I forgot to copy the original image's description into the replacement image, which you may want to do if you're using image descriptions)

> I did a lot of digging before posting my query here, and Camelot was able to sort through some fairly esoteric layers determining how Numbers seems to actually be interacting with Applescript.

I've been doing this AppleScript thing for a while. For better or worse, core AppleScript hasn't changed much over the years, so lessons learned years ago still apply :)

> I don't know if Apple actually documents Numbers document object structure or the API abstraction model, but it would be super helpful for things like this if they do.

The starting point for any script is the target application's dictionary. In Script Editor: File -> Open Dictionary -> choose your target app.

This will show you the commands and object hierarchy, properties and structure that you can use in your script.

Experience tells you how to apply that to real-world scenarios.

For most scripts, though, I prefer Script Debugger. It's like Script Editor on steroids, with debugging features (hence its name) such as code stepping, breakpoints, variable inspection (see what your variables are as your script executes, and change them on the fly!), as well as the Explorer which lets you examine the application's state real-time. Well worth it for serious AppleScripting.

(Note: I'm not affiliated with Script Debugger or Late Night Software, just a fan :) )

> I haven't been able to determine how to interpret the cryptic 'coordinate' references (1178:1188 and 414:498, respectively), so i haven't been able to pinpoint the specific source of the errors (assuming that's what thoose numeric references are supposed to help with).

That is exactly what the numbers relate to.

They represent the actual characters in the (plain text) script that are throwing the error.

In this case (assuming you're using the earlier version of the script ), it's telling you that the error occurs between characters 414 and 498, which relates to:

... make new image with properties {file:(POSIX path of (path to documents) as text) & fn}

You're on your own for mapping the number to characters in the script (I used BBEdit), but it's really only an issue when running via osascript since both Script Editor and Script Debugger would highlight the offending command if you run the script within them.

I was able to get the script to work on Numbers 14.2 running under macOS 14.6.1 (Sonoma). I ran it from Script Editor.

I'm always curious about new uses of Numbers. Your efforts to automate suggest you must be working with a lot of images in Numbers. Otherwise manual replacement would be more efficient.

Can you share a little more about your project? In your experience how good is Numbers at handling images?

SG

.m. wrote:

Indeed I do. :)

Well, I'm glad! My upvotes of Camelot's posts here have been a bit lonely.😀

For Numbers-specific AppleScripting you may also find some useful explanations and examples at this site.

SG

Nice! In pasting the script into the post, the "t" in the opening "tell" went missing.

SG