jamesbond wrote:How stable is the "interface", are you still in test/play phase, or is the commands are more or less fixed?
The commands are every bit as stable as menu structure and dialog items' naming is. Because the "commands" are the very same names - or, any prefix of any word in them that does still match uniquely.
This self-naming and self-documenting is part of the reason why scripting is implemented through the V-code.
The script is commands with their parameters. Commands are prefixed with "-" and match to menu items; parameters are followed by "=" and a value, and match to dialog items. If a command itself is followed by "=" and value, that matches the unnamed item in the dialog. But such an unnamed option can just stand alone: "-file/as=zad" is fully equivalent to "-file/as =zad".
The entire name of a menu option, including spaces, is the canonical name of its matching command - with shell quoting used to protect the spaces. Like this:
mtpaint --cmd -file/'save as ...'=zad
It is safe to shorten the "save as ..." to just "as", because no word in other items' names in the same submenu starts with "as". And so it is done in the examples.
But "save" on its own is a match for another item in the same submenu: "File->Save", which stands before "File->Save as".
Parts separated by "/" are matched to corresponding menu levels in order. So to call up "Effects->Isometric transformation->Top side right", you can write a command "-eff/iso/top". Or more verbosely, "-effect/isometric/top".
Same thing about parameters. I can write:
mtpaint --cmd -file/'save as' =zad 'file format'=png 'transparency index'=0 'png compression'=9
But it is just as unambiguous in this case to write this instead:
mtpaint --cmd -file/as=zad f=png t=0 p=9
Still, for the sake of understandability it's better to use some more chars per option. Say, like this:
mtpaint --cmd -file/as=zad format=png trans=0 png=9
But it is
not unambiguous to use "c=9", "comp=9" or even "compression=9", because there also exist "JPEG2000 compression" and "TGA RLE compression" in this same dialog (visible to user for different filetypes, but V-code sees them all at once).
So "-effect/unsharp r=1 am=0.4" in the example means the same as "-effects/'unsharp mask' radius=1 amount=0.4" would.
The unnamed parameter matches to the unnamed control in a dialog - usually it is the top one, but not always. For fileselector, it is filename; for most filters, it is value spinbutton; but for image scale, you can see it is filter name - everything above their list has names; for image resize - tiling mode, for the same reason. So you see "-image/scale=nearest" and "-image/resize=mirror" in the examples.
To select options from lists, such as filter names or file formats, values are matched to option names just the same way as parameters are matched to dialog items, and commands to menu items. So "image/scale=near" will select you the "Nearest neighbour" scaling method.
If you aren't sure whether a parameter would be present in the dialog at all (it is one such as might get disabled) but want to set it in case it's present, you prefix its name with "." Say, to scale an image of unknown type in a nearest neighbor mode, it's safe to write "-image/scale
.=near", but "-image/scale=near" will fail to match in case the image turns out to be a GIF or other indexed format.
For ease of use, the "Width" and "Height" fields in "Scale canvas" and "Resize canvas" dialogs are made to understand a couple formats that a regular spinbutton wouldn't. Like this:
w=x1.5 - multiplies the original value by 1.5;
w=33% - 33% of the original value.
If "Fix aspect ratio" is toggled on ("fix=1" if you aren't sure it is) then setting the width will correspondingly modify the height, or vice versa.
But only the first time; so you can write "w=200% h=x1" to make the image twice wider, and not bother with "Fix aspect ratio" setting.
This is how it works.