§ 12.11.83 - Script

The script operator provides for running sequences of image command operations that modify image pixels on regions selected with your pointing device. Additional non-image commands supply mechanisms to manipulate values directly and via variables, create strings, loop, use conditionals, and set up user-defined functions. You can also select regions programmatically.

The script operator
Noise Reduction
Cursor at beginning of
notchf line

§ 12.11.83.1 - Creating Basic Scripts

You can edit scripts directly in the operator dialog. However, if the available space seems too cramped, use the ⇒ Edit button to open a larger editing dialog.

• You can build a script of image commands one-per-line by using the →Script button in various operators
• You can enter script commands directly in the text box in the Script operator
• You can enter scripts in a larger edit window accessed from the Script operator
• You can load previously saved scripts from mass storage using Load/Save

Scripts consist of one or more commands that are executed from top to bottom, one operation per block. A block can consist of a single line containing one command, or one of multiple blocks in a line separated by the : (colon) character.

Each image command in the script is checked for correctness. If any of the parameters for the image command are out of range, or the syntax is detectably incorrect, the debugging dialog will open and list the problems.

When typing image operator commands directly into the script box in the first block on a line, iToolBox will make suggestions in the prompt area below the script box as to what the possible command might be based on the characters you've typed so far. When you have typed enough characters such that there is only one possible candidate, that candidate will be the only one shown, and typing a tab will auto-complete the keyword for you. At this point the prompt area changes to a guide to the parameters for that command. Here's an example of how that can go starting with a blank line...

...at this point, the prompt area shows you have one value to provide to dodge, so you type a space and that value, and you're done.

Errors in supplying parameters to image commands will result in both a report of the error lines and a listing of the correct parameters and ranges for those operations at the top of the script when the script is executed.

You may place one command on a line (this is a good idea with image commands so you can take advantage of the suggestions feature), or you can place more than one command per line by separating them with a ":" (a colon.) Each command is a block; so one command on a line represents one block, and several commands separated by colons represent multiple blocks.

You can disable any block in a script by turning them into a comment by simply placing a # character at the beginning of the block(s.) Comment blocks are ignored.

This operator provides syntax highlighting. You can set the colors via the Script Settings dialog, available from the Settings button. There are other useful settings and presets available in the Script Settings dialog as well.

§ 12.11.83.2 - Numeric Constants

Often when writing programs, numeric constants such as decimal 69, 42, etc., are required. iToolBox's scripting language expects base ten, real numbers (positive or negative numbers, with or without a decimal point followed by base ten fractional values thereafter) by default.

You can also specify values using a format that provides you with the means to specify any base from two to ten, as well as base 16, for positive integer values up to 2,147,483,647 (that is the equivalent value in base 10.) Here are all the various possible numeric formats:

§ 12.11.83.3 - Operator Commands

Image operator commands generally consist of a keyword, followed by any required parameters, all separated by spaces, contained in one block. In the list below, the green information is what you type into the script; the red information is just to let you know what the parameters mean. In addition, the ellipsis (...) indicates a range, and is not entered into the script itself. Here's the information for the alphamod operator command:

So to use the alphamod command to create an alpha level of 128, you would follow that guidance and enter the following in a block:

 alphamod 128 0

The various parameters directly reflect the control settings for that specific operator.

For checkboxes, a value of 0 means the box is unchecked; a value of 1 means is is checked.

For drop-down selectors, the top entry in the drop-down is 0, and each entry lower is a value increased by one. Another way to look at it is, count the entries until you reach the one you want, then subtract one.

Some operators do not have supporting scripting commands. They are indicated by red, struck-out text in the table below:
 operator 

§ 12.11.83.4 - Variables

§ 12.11.83.4.1 - General

Numeric variables are created by writing a variable name, such as x or myvariable, followed immediately (without an intervening space) by an equals sign, and then the contents you want to put in the variable.

String variables are created by writing a variable name, such as x or myvariable, followed immediately (without an intervening space) by a tilde (~),and then the contents you want to put in the variable. You can use double-quotes (") to write out literal text; to contain double-quotes within a quoted string, use the escape backslash-double-quote (\")

Variable name rules:

• Variable names cannot begin with numbers: 2x is an illegal variable name, x2 is legal.
• Variable names cannot contain an '=' character
• Variable names cannot contain a '~' character
• Variable names are all lower case, even if you write them otherwise

There are two types of information you can put in a variable. Real numbers (decimal values, optionally with fractional parts), and strings.

Because image command block parameters are specified on a per-token basis by separating each token with a space, when a string value is required and it is not the last parameter, the only way you can specify a string containing spaces in anything other than the last parameter is to use a variable as an intermediary.

For instance, the text area selection command requires a font name as the first parameter. A single-word font name like Courier is fine, as it contains no spaces, so you can just write the command literally, whereas multiple word font names will require the use of a variable.

§ 12.11.83.4.2 - Preset System Variables

A number of preset or pre-defined system variables are available for use in scripts. The naming convention, other than the special variables debug, void, true and false, is that they begin with m_

The preset system variables are set as follows:

§ 12.11.83.5 - String Expressions

String expressions may be used wherever a string variable is being set using the ~ operator.

String expressions may contain variables and/or literal values.

Text expressions utilize the + operator to perform concatenation.

In a text expression, you can refer to a numeric variable with its first letter capitalized, and the result will be the expression that created the numeric result, rather than the result itself.

Neither string expressions or string literals may contain single colons, as these indicate the end of one block and the beginning of another. To represent a colon in a text expression or literal, use the digraph :: instead of a single colon character.

Because string literals are created by surrounding text strings with double-quotes, you can't directly use a double-quote inside a string. To represent a double-quote, use the sequence backslash-double-quote ( \" )

§ 12.11.83.5.1 - String operator (~) functions

The following functions may only be called from within a string assignment context (after the ~ operator or where an image command expects a text string.)

The following characteristics apply to string assignment context functions:

• All [prepend] and [postpend] parameters are optional
• These functions cannot be nested
• Returned values are limited to 80 characters
• Literal text strings must be double-quoted
• Newline sequences and tabs in variables are converted to spaces
• Literal commas within a text string are represented with the digraph ,,
• Double quotes within a text string are represented with the sequence backslash-double-quote (... \" )

§ 12.11.83.6 - Numeric Expressions

Numeric expressions may contain the arithmetic operators + for addition, - for subtraction and negation, * for multiplication, and / for division.

They may also contain the comparison operators ==, !=, <, >, <=, and >=

Comparison operators result in 1 if true, and 0 if false. The if(expression) conditional decides what to do based on 0 (skip the block), or non-zero (execute the block.)

Numeric expressions may not contain any spaces when used in the context of a parameter in an operator command; this allows expressions to be used as numeric parameters to an operator command where the operator command's individual parameters are separated by spaces.

In the context of an assignment (the = operator), the formulation to the right of the = character may contain any number of spaces.

Expressions are evaluated in a strict left-to-right order. Multiplication and division do not have priority over addition and subtraction. Operations occur in the order they are written.

When you need to control operation order, use ( and ) parentheses.

§ 12.11.83.6.1 - Unary Operations

An unary operation is one that directly affects the following value. There is only one unary operation:

§ 12.11.83.6.2 - Numeric Functions

Functions use reserved names; you must not use reserved names as variables. For instance, there is a function sin(angle), so naming a variable sin is unwise.

All numeric functions return numeric values due to the way the script parser functions, however,when a function is described as assigning to void, the value will not be useful to you and may be ignored.

Note 1: Above S9, sunits are represented as 9.x where the x contains dB-over divided by 1,000. For instance, [s9+10dB] reads out as 9.010, [s9+40dB] reads out as 9.040, etc. Below S9, the value reads out pure sunits, including valid decimal places. Above [S9+999dB], the value is invalid. Also, both your antenna and radio are on fire.

§ 12.11.83.7 - Area Selection Commands

There may be times when you want a script to do whatever it does at a particular location or within a known region on any image it is applied to, rather than to an area you select with the mouse or other pointing device. To facilitate that, the following area selection commands are available to you:

* Numeric conversion rules are set with these system variables.

§ 12.11.83.8 - Miscellaneous Commands

§ 12.11.83.9 - User-defined Functions

You can create user-defined functions. User-defined functions consist of quoted text variables containing one or more command blocks which are separated by ; (semicolon) characters (not colons!) You can put anything in a user-defined function that you can in any other block.

Here's a user-defined function that will add one to the variable a, and an example of its use:

inca~"a=a+1"
func(inca)

Here's one that will colorfill in orange:

orangefill~"r=255;g=128;b=64;colorfill r g b;#orange!"
func(orangefill)

Here's one that uses passed parameters to fill in any color:

cfill~"colorfill dparm(0) dparm(1) dparm(2)"
func(cfill,200,150,100)

You may optionally provide up to 32 parameters when calling a function; within the function itself, these are accessed with x=dparm(index) or text=tparm(index), where index may range from 0 to 31.

User-defined functions are evaluated when they are invoked. This makes them dynamic instead of static. Examples:

myfunk~"a=b+c":# function definition
b=1:c=2:# initial setup
void=func(myfunk):# variable a will now be 3
b=2:void=func(myfunk):# variable a will now be 4

§ 12.11.83.9.1 - Returning numeric values from user-defined functions

Use the special variable void for this. As the last action in your function, assign the value you want it to return. For example:

a=1801
b=17
myfn~"a=a+1;b=b+1;void=a"
x=func(myfn)
# variable x is now set to 1802

§ 12.11.83.9.2 - Returning string values from user-defined functions

You can also use the special variable void (or any other variable, actually) for this. String returns from functions are handled by passing through a variable, like this:

b=17
myfn~"a~\"foobar\";b=b+1;void~a"
func(myfn)
x~void
# variable x is now set to foobar

Using void is reasonable because it doesn't require another variable to serve in this role. Keep in mind that void changes often, so retrieve the returned value immediately after your function runs or you risk losing it.

§ 12.11.83.10 - Arrays

§ 12.11.83.10.1 - General

Arrays are different from numeric variables in that arrays may contain many values, while a numeric variable can contain only one numeric value.

Arrays can be dimensioned so as to have rows and columns, and when dimensioned, can serve as matrices supporting matrix operations, including matrix multiplication of two operand matrices into a third result matrix.

Arrays are manipulated using array functions, which provide array creation, mathematics operations, and access.

§ 12.11.83.10.2 - Array Functions

The following functions deal with numeric arrays:

§ 12.11.83.11 - Comparative math operators

§ 12.11.83.12 - Conditionals

§ 12.11.83.12.1 - If() Examples

§ 12.11.83.13 - Looping

Loops are built using two commands; a starting command, loop([expression]), that can include an optional expression specifying a maximum looping count, and an ending command, while([expression]), that can include an optional expression defining a condition under which the loop will continue.

Think of the while([expression]) condition as a statement of the form "continue while expression is true." So a loop like this...

a=1:loop():a=a+1:#etc.:while(a<10)

...will run until a is no longer less than 10.

Loops may be controlled by the count in the loop() statement, by the expression in the while() statement, or by both.

A loop without any expression specified in either the starting or ending statements is not sufficiently specified, and will run only once. This isn't an error, but the loop() and while() statements become redundant, as running once is exactly what would have happened without them being present anyway.

The loop(count), if provided, takes priority over any specified while([expression]) condition; the loop will terminate before the ending expression is satisfied if it executes the maximum number of loops initially specified.

The code within a loop always runs at least once. In a circumstance where a loop might need to run zero times, surround it with an if([expression]) statement, like this...

if(n>0):loop(n):a=a+1:#etc.:while():endif

Avoid setting up a condition where the loop cannot end naturally, such as...

loop():a+a+1:while(1)

In that case, the loop will not terminate until the number of blocks executed reaches the maximum count set by the pre-defined variable m_maxops because the expression is never false (always 1.)