Work with a picture

Details #

One step with many operations on a picture. op says which. Most ops follow the same pattern: read the picture from a place, change it, and put it back in the same place.

Where the picture lives. target chooses the place:

• clipboard (the default) is the system clipboard. A copied picture is read from it; the result is written back as a PNG.

• named is a named clipboard from Switchboard's clipboard history, with its name in name. Needs clipboard history running.

• file is a picture file at path. The change is written back to that file, in the format its extension picks.

Running variables. Every op that handles a picture sets the variable image to an object with width, height, dpiX and dpiY. composite also sets sourceImage for the second picture. find sets foundImage.

Ops

• new makes a picture of width by height, filled with red, green, blue (0 to 255, default 255) and alpha (percent opaque, default 100).

• draw draws a shape (line, oval, rectangle, roundedRectangle or text) at x, y with width and height. stroke and fill are colours, thickness the line width (default 1), and for text the text, font and size (default 18). The default stroke is opaque black and the default fill is clear.

• composite lays a second picture over the first at x, y. The second comes from from (clipboard, named or file, with fromName or fromPath). alpha is its opacity in percent (default 100) and blend names a blend mode such as multiply, screen, overlay, darken, lighten, softLight, hardLight, difference or exclusion. An unknown blend is treated as normal.

• scale stretches to exactly width by height, or by percent of the size it has (50 is half size, and no width or height is needed). scaleToFit fits inside that box and keeps the proportions. scaleTo is another spelling of scale.

• canvas changes the canvas size to width by height, placing the picture at x, y (left, top also work).

• margins adds left, top, right and bottom space.

• crop keeps the rectangle at x, y of width by height.

• setDPI sets the dots per inch to dpiX and dpiY (dpi sets both). It changes the picture's resolution tag, not its pixels.

• rotate turns the picture by degrees, clockwise (rotation is another spelling).

• flip mirrors it. direction is horizontal (the default) or vertical.

• trim cuts away the border that matches color (the top-left pixel if you give none). fuzz is a percentage of tolerance, 0 to 100.

• size stores the width in the variable named by widthVariable and the height in heightVariable. Both are optional; the output is the size object.

• display opens the picture in your default image viewer (a temporary PNG).

• save writes the picture to path (or to output when you give one; then path is the picture it reads, with target: file). format (jpeg, jpg, png, tiff, gif, heic or bmp) overrides the file extension. Missing folders are created. The output is the path.

• load reads the file at path into the target. A picture file becomes the picture; any other file becomes its text (and goes on the clipboard or into a named clipboard).

• capture takes a screenshot into the target. area picks what: all, main, window, or a rectangle {"type": "rect", "x": 0, "y": 0, "width": 400, "height": 300} in screen points. cursor includes the mouse pointer.

• ocr reads the text in a picture. from is screen (the default), clipboard, named or file. area limits a screen read and languages is a list of language codes. The text is the output and goes in into.

• find looks for a saved picture on screen. The picture and settings are given in locator (image file name, threshold, scope, pick). area narrows the search. The output, foundImage and into hold left, top, width, height and score.

Colours accept an object like {"red": 255, "green": 0, "blue": 0, "alpha": 100}, or text: #RRGGBB, or three or four numbers separated by commas or spaces.

Parameters #

Every step also accepts label, onFailure, timeout and dryRunSafe.

Examples #

Read the text on the screen (a dry run only simulates the capture):

Gotchas #

• capture, ocr from the screen, and find need Screen Recording permission for Switchboard Engine.

• find fails with the picture <file> isn't on screen (no match above 85%; the nearest was NN%) when nothing matches and required is on. Lower threshold, or check the right window is showing. It fails with a missing or unreadable picture error if the saved picture is gone.

• target: clipboard fails with the clipboard doesn't hold a picture when you copied text or files. target: named needs clipboard history running and a clipboard with that name.

• Missing numbers fail with image <op> needs <name> (a number). Missing degrees, path or a bad shape, direction, area type or target also fail with a message naming the problem.

• An unknown op fails and lists the valid ones.

• load puts a non-picture file on a clipboard; it cannot put it into another file.

• target: file overwrites the file with the changed picture. Keep a copy if you need the original.

• ocr returns an empty result, and the note says no text found, when the picture has no readable text.

• In a dry run every image step is simulated, so no picture is read or written.

See also #

Clipboard, Show message, Image found