An Introduction to Photo Editing with PhotoLine: Scripting
PhotoLine now supports scripting. Version 21.50 has been updated to include all the basic functionalities. Features may be added from time to time; see the Beta Tester forum | Google Translate for the latest developments.
A brief overview: PhotoLine does not use a built-in scripting language, but may be scripted with a variety of languages. Documentation is provided for VBScript (Windows) and AppleScript (macOS); they are installed with the download, as well as some sample scripts. (In Windows, see \PhotoLine\Infos\Scripting.zip; in macOS there is a “Scripting” folder.) I have written a number of Windows scripts in JavaScript, partly because I prefer it, and partly because it is cross-platform.
Since OS X 10.10 Yosemite, Macintosh computers are able to use JXA (Javascript for Automation). This in itself seems to be a work in progress, and still has a way to go. But I would hope that it is the wave of the future. Tip to get started: in the Script Editor, File – Open Dictionary – PhotoLine.app opens a window that shows all the accessible properties and methods.
Script files go into the script folder. The native folder is \PhotoLine\Defaults\Automation. I recommend using \PhotoLine\PhotoLineSettings\Automation (you have to create it) so that you may easily copy your scripts between installations. (The PhotoLineSettings folder also stores all of your settings as described elsewhere. You may need to change its security settings via Properties – Security – Edit – Users, allow Modify and Write.) Then run the scripts via Filter – Script. Note that PhotoLine sometimes creates a second Script menu item in the dropdown.
Of note, I have not been able to get PhotoLine VBScripts to work in Wine at all, using Fedora and Ubuntu, and JavaScript only partly works.
Download the scripts: scripts.zip includes the libraries and all of the sample scripts below.
The script libraries
The native scripting properties and methods are rather low-level and verbose; this allows for fine control over things like paragraph formatting, but complicates simple procedures. I have written two script libraries that may make life easier. js_library.js wraps a number of complex procedures in simple functions. Creating a text layer, for example:
function createTextLayer(text, fontName, fontSize, fontColor, left, top, width, height, paragraphAlignment, insert) {
var pl = new ActiveXObject("PhotoLine.Application");
var doc, aLayer, fontDict, paragraphDict, textLayer, range;
doc = pl.ActiveDocument;
aLayer = doc.ActiveLayer || doc.RootLayer.Last;
fontDict = new ActiveXObject("PhotoLine.Dictionary");
fontDict.Add("FamilyName", fontName, "Size", fontSize);
paragraphDict = new ActiveXObject("PhotoLine.Dictionary");
paragraphDict.Add("Alignment", paragraphAlignment);
textLayer = new ActiveXObject("PhotoLine.Text");
textLayer.Text = text;
range = [0, textLayer.TextLength];
textLayer.Origin = [left, top];
textLayer.Size = [width, height];
textLayer.SetAttribute(range, "Color", fontColor);
textLayer.SetAttribute(range, "Font", fontDict);
textLayer.SetAttribute(range, "Paragraph", paragraphDict);
if (insert) {
aLayer.Parent.Insert(textLayer, aLayer);
doc.ActiveLayer = textLayer;
}
return textLayer;
}
And js_constants.js lists all the PhotoLine enumerations, such as paragraph alignment, for use in any function:
PALeft = 0; PARight = 1; PACenter = 2; PAJustified = 4; PAJustifiedAll = 5;
It also includes values such as ForReading, ForWriting, and ForAppending for opening text files, and all the CSS color names for use with color functions. Some examples of the latter:
color = hexColor(Indigo, 0.5); // 0.5 is optional transparency color = HSVColor(0, 100, 73);
Place the library files into \PhotoLine\Defaults\Automation\lib or \PhotoLine\PhotoLineSettings\Automation\lib . Then load the libraries by putting the following at the beginning of all of your scripts:
var pl = new ActiveXObject("PhotoLine.Application");
function loadLibrary(file) { var fso = new ActiveXObject("Scripting.FileSystemObject"), p; with (fso) { p = GetAbsolutePathName("."); p = BuildPath(p, "lib"); p = BuildPath(p, file); } var f = fso.OpenTextFile(p, 1); eval(f.ReadAll()); f.Close(); } loadLibrary("js_constants.js"); loadLibrary("js_library.js");
Updated since the original release: the functions createImageLayer, createTextLayer, drawPolygon, and drawEllipse, which return new layers, now have an optional parameter to insert them after the active layer. The latter two also have an optional parameter to merge them with the active layer.
Sample scripts
posterScreen.js — adds faux matting and a title to an image. Intended for screen display, but could be printed as well.
listAllLayers.js — lists all the layers of a document and writes them to a text file that accompanies the image.
It’s a photo editor! It’s a database! It’s . . .
database.js — turns an image into an ID badge with a number and a barcode, and saves the data to a .csv file that can be opened with a database program. Starts with a random number then adds a fixed or random increment; prevents entry of duplicate names.
taijitu.js
IChing.js
composite.js — runs both of the above and adds a background.
Custom dialogs
PhotoLine incorporates an input box for simple user input, but no ability to use custom form elements. A web browser may be used as a workaround. I like to use QtWeb as it is a small (7.5MB) standalone .exe that may be placed into the PhotoLineSettings folder and easily referenced; plus, the window elements may be hidden for simplicity. But you may use any browser; the path needs to be specified at the bottom of the js_library.js file.
Download the Windows stand-alone portable executable: QtWeb.exe (7.5 MB)
demo.js is a demo script which uses an .htm file as a dialog. It creates a new document based on dialog input. The dialog displays the resolution of the active document and uses it as the default resolution. Complete the form, then copy the parameter string to the input box. Could be worse . . . .
Scripted actions
Some operations do not have native scripting support, but may be recorded as actions. An action may be scripted by passing its binary data in the form of a hexadecimal or Base64 string. If you know the location of a parameter in the data, you can construct a string containing a custom parameter, and thus have scripting control over the operation. (This is similar to using what is called a script listener.)
The toolkit below enables you to find the parameters in an action’s hex string, and convert scripting parameters to the appropriate hex format. The string is then constructed by concatenating the fixed code blocks with the parameters. Updated since the original release: PhotoLine now includes the ability to right-click an action and select Copy Base64; no external hex editor is needed. The toolkit will convert the Base64 string to hex for editing.
The PhotoLine Scripted Actions Toolkit
Next: tips and tricks