Clip Rectangle Help

I want to use clipRectangle but I can’t find any documentation on it anywhere.
I found an instance of it here in the forums but it was just telling a user to use it.

How does it work? Where can I find documentation on it?

I tried playing with it setting clipRectangle: (2,7), (44,12) but the image I was creating seemed to ignore the first set of coordinates.

I should add:
I’m running on an Intel mac mini
Eggplant Version 3.31

The more I play with clipRectangle the more I’m finding that I do not get consistent results with it.

I’ve gotten it to actually work how I would have thought it should work about 1 out of every 5 tries.

The ClipRectangle property of an image was introduced in Eggplant 3.0 to provide a mechanism for trimming an image at search time in order to look for a smaller, “clipped” version of that image. This was intended mainly to provide a fallback means of dealing with text images that might need to be trimmed in some special cases, such as to find text that might be underlined in a different way than underlined text images are generated (we’ve found that underlining is not always done in a consistent way by different applications, so sometimes ignoring the underline may be the only way to get generated text images to match).

Because text images were new at the time, and the clipRectangle property was a potentially confusing approach to a problem that we hoped not many people would run into, it wasn’t initially included in the documentation (although it shows up briefly in the release notes!). I expect we will document it properly in the future, but for the moment, here’s a brief description of how to use it.

First, here’s what it says in the release notes: “Image property lists may now include a ClipRectangle property. If present, its value should be a rectangle. The image will be clipped to the intersection of this rectangle with the image’s rectangle before searching.”

The most likely way to use this is to adjust from the original size of the image. Each image has a size (width and height) that can be found by accessing the ImageSize property of the image property list returned by the ImageInfo() function:

set imageSize to ImageInfo("MyImage").ImageSize

You can then use this size to calculate a ClipRectangle that will trim off part of the image. For example, to trim 2 pixels off the bottom (keeping in mind that the coordinate origin in Eggplant is at the top left) you might do this:

set clipRect to (0, 0, imageSize.width, imageSize.height-2)
click (ImageName:"MyImage", ClipRectangle:clipRect)

To keep the example simple I used a named image above. But of course ClipRectangle can be used with text images, too.

click (Text:"File", TextStyle:"WindowsMenu", ClipRectangle:clipRect)

Hopefully this explanation is enough to make the ClipRectangle property useful. Happy clipping!