Operators Dialog / Operator Details

§ 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

§ - 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...

You type Preview shows Line contains
dodge [Amount=0...100]

...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.

#a=1One line of one block, commented out
a=1:#b=2:c=3One line with three blocks, b=2 commented out

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.

§ - 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:

0bN...binary (base 2)Digits (N) may be 0 or 1
0tN...trinary (base 3)Digits (N) may be 0 ... 2
0qN...quaternary (base 4)Digits (N) may be 0 ... 3
0QN...quinary (base 5)Digits (N) may be 0 ... 4
0sN...seximal (base 6)Digits (N) may be 0 ... 5
0SN...septimal (base 7)Digits (N) may be 0 ... 6
0oN...octal (base 8)Digits (N) may be 0 ... 7
0nN...nonary (base 9)Digits (N) may be 0 ... 8
0dN...decimal (base 10)Digits (N) may be 0 ... 9
0xN...hexadecimal (base 16)Digits (N) may be 0 ... 9 and A ... F
0hN...hexadecimal (base 16)Digits (v) may be 0 ... 9 and A ... F
[-]N...[.N...]decimal real numbersDigits (N) may be 0 ... 9

§ - 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:

alphamod [Amount=0...255] [Mode=0...9]

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:

alphamod [Amount=0...255] [Mode=0...9]
annotation [content="text"]
author [content="text"]
bend [Mode=0...1] [Amount=-100...100]
burn [Amount=0...100]
camera [shutter=0...50000] [aperture=.1...100] [focallength=1...50000] [iso=1...1000000]
caricature [Amount=0...100]
ceiling [Sample=0...1] [Mode=0...2]
 center selection 
channelmove [Select=0...4]
chromanoise [Degree=0...100] [Radius=1...20] [Threshold=0...100] [Hue=0...1] [Sat=0...1]
colorfill [Red=0...255] [Green=0... 255] [Blue=0... 255]
colorize [Red=0...255] [Green=0...255] [Blue=0...255] [Mixture=0...100] [ApplySat=0...1]
convolve [Cell=-1000...1000] (x9) [Mono=0...1] [mix=0...100]
contbrit [Contrast=-100...100] [Brightness=-100...100] [Center=-100...100] [R=0...1] [G=0...1] [B=0...1]
copyright [content="text"]
creduce [Depth=3...7] [Dither=0...1] [Dithtype=0...2] [Save=0...1] [Fixed=0...1] [Force=0...1]
crop [ToEdgeAlpha=0...1] [AlphaLevel=0...255] [Reflect=0...3]
darken [Amount=0...200] [Limit=0...255]
darknessgain [Gain=0...100] [Hump=0...100] [Range=0...100]
dodge [Amount=0...100]
dome [Amount=0...500]
dpi [xDPI=1...3200] [yDPI=1...3200]
edgedetection [Amount=-100...100]
emboss [Amount=-100...100] [Absolute=0...1] [Direction=0...7]
exposure [Amount=-100...100] [Mode=0...1]
flip [Horizontal=0...1] [Vertical=0...1]
floor [Sample=0...1] [Mode=0...2]
forcedynamic [Sample=0...1] [Exclude=0...1]
fractals [Mode=0...3] [P1=-100..100] [P2=-100...100] [Z=1...100=] [Px=-100...100] [Py=-100...100] [Po=0..255] [Sm=0...1]
frame [Outer=0...50] [2nd=0...50] [3rd=0...50] [Inner=0...50]
gain [Black=0...200] [Gain=0...200] [White=0...200]
gamma [Gamma=.25...4.0]
gaussian [Radius=1...20] [Intensity=0...100]
gps [latitude=-90...90] [longitude=-180...180] [altitude=meters]
halftone [dither=0...1] [cropedge=0...1] [threshold=1...254] [gamma=0...100] [DMethod=0...7]
hremove [red=0...1] [green=0...1] [blue=0...1]
hue [Hue=-100...100]
infill [method=0...1] [texture=0...1] [xcent=0...50000] [ycent=0...50000] [mix=0...100]
jumble [Horizontal=0...1] [Jumble=keyword(s)]
kaleidoscope [Degrees=0.0...360.0] [Mirrors=2...100] [Rotational=0...1] [Center=0...1]
keystone [Mode=0...3] [Amount=-100...100]
layerclear [Copper=0...1] [Drill=0...1] [Mask=0...1] [Legend=0...1]
legendlabel [Vertical=0...1] [Spacing=1...n] [Mode=0...5] [Justify=0...2] [Points=5...100] [Start=1...1000] [Count=1...1000] [Red=0...255] [Green=0...255] [Blue=0...255] [Stutter=1...100] [Font=fontname] [Prefix=text] [Postfix=text]
levels [blk=-100...100] [shad=0...100] [mid=0...100] [high=0...100] [whit=-100...100]
loccontrast [Amount=0...100] [Density=0...9]
math [Mode=0...7]
maximum [Mode=0...5]
median [Size=0...4] [Mode=0...8] [take=0...3] [R=0...1] [G=0...1] [B=0...1] [A=0...1]
merge [Xoff=-100...100] [Yoff=-100...100] [Tile=0...1]
minimum [Mode=0...5]
mirror [Degrees=-360...360] [Center=0...1]
 monochrome [Preset=0...7]
 monochrome [Red=0...255] [Green=0...255] [Blue=0...255]
notchf [Bandwidth=0...100] [Frequency=0...100] [Depth=0...100] [Skirts=0...100]
perlin [Density=0...100] [Seed=1...9999] [Offset=0...255] [Turb=0...7] [Gain=0...100] [Contrast=0...200] [Floor=0...100] [Smooth=0...1]
perspective [Xr=-90...90] [Yr=-90...90] [Zr=-90...90] [Center=0...1]
pixelize [Size=2...200] [Offset=0...200]
place [mode=0...9] [under=0...1] [aspectcorrect=0...1] [alphalevel=0...255]
radwave [dst=0...100] [fr=0...100] [hw=0...100] [rad=0...100] [ph=0...100]
random [Monochrome=0...1] [Shapemask=0...1] [Additive=0...1] [Amount=0...100] [Key=word(s)]
rgbshift [Shift=1...200] [Channel=0...3] [Right=0...1]
rip [Intensity=0...100] [Mode=0...3]
ris [Intensity=0...100] [Threshold=0...100]
roll [Xroll=-100...100] [Yroll=-100...100]
rot90 [Mode=0...2]
rotate [Degrees=-360.0...360.0] [Center=0...1]
sample [Accumulate=0...1] [Subtract=0...1]
saturation [Saturation=-100...100]
sharpen [Radius=1...10] [Threshold=0...100] [Amount=0...100]
skew [Xskew=-100...100] [Yskew=-100...100]
stretch [Hamount=-100...100] [Vamount=-100...100]
swirl [Amount=1...620]
software [content="text"]
spherize [width=8...n] [height=8...n] [maptofront=0...1] [material=0...4] [ambient=0...1.0] [scale=0.1...1.5] [assign=0...1] [xtranslate=-100...100] [ytranslate=-100...100] [rotation=-100...100] [threads=1...n]
ctime [time="YYYYMMDD:HHMMSS"] [mtime="YYYYMMDD:HHMMSS"]
tunnel [Top=0...1] [Left=0...1] [Right=0...1] [Bottom=0...1] [Percent=1...100] [Indents=1...100] [Alpha=0...1]
vignette [Contrast=-100...100] [Brit=-100...100] [Rad=0...100] [Cmult=0...9]
vload [filePathAndName=noSpaces] [LoadAsOrigin=0...1] [ReLoad=0...1]
vremove [red=0...1] [green=0...1] [blue=0...1]
windowlevel [Window=0...255] [Level=0...255] [Clip=0...1]
yrbconvert [Direction=0...1]

§ - Variables

§ - 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.

v=5A numeric variable named v that contains the whole number 5.
Will always produce the value 5 in any numeric context, and the character "5" in any character context.
Whole number use example:
alphamod value 0
...evaluates to:
alphamod 128 0
yvalue=2.7A numeric variable named yvalue that contains the real number 2.7.
Will produce the value 2.7 in a real number context; will produce the value 3 in an integer context (that's 2.7 rounded to the nearest whole number), and the character string "2.7" in any character context.
Real number use example:
text Courier 100 100 MyScale testing
...evaluates to:
text Courier 100 100 1.1 testing
foo=2+3A numeric variable named foo that will produce the number 5 if referred to in lower case (literally as "foo") in either a numeric or a string expression, and which will produce the string "2+3" if referred to with its first letter capitalized in the context of a text expression, literally (Foo).
random 0 0 0 100 foo
...evaluates to:
random 0 0 0 100 10
random 0 0 0 100 Foo
...evaluates to:
random 0 0 0 100 7+3
mykey~"Testing 1, 2, 3"A string variable named mykey that contains the characters Testing 1, 2, 3
String variables may only be used where an operator expects a character string, or when being concatinated into other string variables. If a string variable is used in a numeric context of any kind, this will result in an error. Double quotes surrounding a string cause the variable to be loaded with the string without evaluation. In string variable formulations, the plus sign (+) character concatenates quoted strings, variables and string function results.
Simple character string variable use example:
myrandomkey~"My cat \"Twinkie\""
random 0 0 0 100 myrandomkey
...evaluates to:
random 0 0 0 100 My cat "Twinkie"

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.

text Courier 100 100 1.1 testingA literal, single-word font name
font~"Marker Felt"
text font 100 100 1.1 testing
A multi-word font name contained in a variable
§ - 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:

Special Variables
voidThis variable always exists, and is set by any statement or function that is not a variable assignment or an image command, but only until the next such statement comes along. If void is used as an if condition, as in if(void), the result will always be false. void can also have values assigned to it, as it is mutable, though it tends to be ephemeral. In string context, using Void instead of void will return the formulation that resulted in the value presently contained in the variable void. Finally, void is used to pass desired results back from user-defined functions (details here.)
trueThis variable always exists, and is always equal to 1. Its value cannot be changed.
falseThis variable always exists, and is always equal to 0. Its value cannot be changed.
debugThis variable always exists, and defaults to true. iToolBox provides debugging information when errors are encountered if debug is true.
Math Constants
The speed of light, in meters/sec, in free space.
Euler's number.
Planck's constant.
Image circumstances at script run time
m_widthImage width in pixels
m_heightImage height in pixels
m_originOne if an origin image is available, zero otherwise.
m_owidthOrigin image width in pixels (zero if no origin set)
m_oheightOrigin image height in pixels (zero if no origin set)
m_altitudeGPS element
m_latitudeGPS element
m_longitudeGPS element
m_dateCurrent date (see also string functions createtime, modtime)
m_timeCurrent time (see also string functions createtime, modtime)
m_xdpiImage x dpi
m_ydpiImage y dpi
m_apertureImage camera lens aperture
m_focallengthImage camera lens focal length
m_isoImage camera ISO
m_shutterImage camera shutter speed
m_leadingText line leading after text operator runs
m_ascentText line ascent after text operator runs
m_descentText line descent after text operator runs
m_lineheightText line height after text operator runs
Numeric to text conversion control
Range is 10 to 200.
Range is zero to four:
  1. Format as [-]9.9e[+/-]999
  2. Format as [-]9.9E[+/-]999
  3. Format as [-]9.9
  4. Use the more concise of 0 or 2 format
  5. use the more concise of 1 or 2 format
Range 2-16
Range is -80 to 80. A negative fieldwidth forces left-justification.
range -1 to 15
You might set this to "0", etc.
Range Zero to one. Set this to 1 if you don't want commas in numbers
Internally used variable
m_xyzzyplughI pass information around inside iToolBox with this, so it's likely not to keep what you put in it, if you try to put anything in it.

§ - 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.

result: tt is "5"Numeric value of variable test as a string
result: tt is "2+3"The expression that created variable test as a string
result: tt is "2+3=5"Both, concatenated as a string

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 ( \" )

§ - 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 (... \" )
Text operator (~) functions
t=altitude([prepend][,postpend])GPS information
t=annotation([prepend][,postpend])Up to 80 characters of image annotation
t=ask([title[,prompt[,preset]]])Ask user for input
t=author([prepend][,postpend])Up to 80 characters of image author
t=copyright([prepend][,postpend])Up to 80 characters of image copyright
t=createtime([prepend][,postpend])UTC time and date
t=imagename([prepend][,postpend])Name of action image
t=latitude([prepend][,postpend])GPS information
t=layername([prepend][,postpend])Name of an image layer (same as imagename())
t=longitude([prepend][,postpend])GPS information
t=mastername([prepend][,postpend])Name of a layer's master image
t=modtime([prepend][,postpend])UTC time and date
void=pops()Pull/pop a value from the user text stack[synonym for pulls()]
void=pulls()Pull/pop a value from the user text stack [synonym for pops()]
void=pushs(expression)Push a value to the user text stack.
In text expression context, the following expressions are valid:
  1. String variable names
  2. numeric variable names
  3. Numeric variable names
  4. "String literals"
t=software([prepend][,postpend])Up to 80 characters of image software signature
t=tparm(index)Fetches a passed text value within a user-defined function. The first parameter is 0, the second is 1, and so on.
t=truth(variablename[,prepend][,postpend])Returns true or false depending on variable
t=verbatim([content])No content results in a space character

§ - 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.

The variable y now contains 7
y=a + 2
The variable y now contains 7
The variable y now contains 3
y=a + -2
The variable y now contains 3
alphamod foo+b*2-1 0
The result here is this command: alphamod 37 0
Here's how that happened: First, b is added to foo, which results in 19. Then 19 is multiplied by 2, which results in 38. Finally, 38 has 1 subtracted from it, which results in 37. Note that there are no spaces in this formulation, because that would result in multiple parameters.

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.

x=2+2*3The variable x now contains 12
x=2+(2*3)The variable x now contains 8
§ - Unary Operations

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

Unary Operation(s):
§ - 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.

Function for obtaining user input
x=slider(title,prompt,minimum,maximum,preset)Dialog with slider
Functions related to variables
count=declare(variableName[,...])Pre-declare variables. This optional statement does these things:
  1. Makes script operations slightly more efficient
  2. Alerts the syntax coloring engine that a variable exists before it is assigned
  3. Alerts the syntax coloring engine to array names
Avoid these errors:
  • Specifying a variable that has already been assigned
  • Specifying an illegal variable name
  • Specifying a variable twice
  • Specifying a constant
If there are no errors, declare() returns the number of variables declared.
x=dparm(index)Fetches a passed numeric parameter within a user-defined function. The first parameter is 0, the second is 1, and so on.
x=exists(variablename)Returns 0 if the variable does not exist, 1 if it does.
x=notexists(variablename)Returns 1 if the variable does not exist, 0 if it does.
x=pop()Pull/pop a value off the user numeric stack [synonym for pull()]
x=pull()Pull/pop a value off the user numeric stack [synonym for pop()]
void=push(expression)Place a value on the user numeric stack
void=pushs(expression)Place a value on the user text stack
The following expressions are valid:
  1. String variables
  2. numeric variables, all lower case, for literal value
  3. Numeric variables, uppercase 1st letter, for instantiating text expression
  4. "String literals"
  5. Numeric literals
  6. Numeric expressions
Direct image functions
x=chup(0-255)Converts 0-255 to 0-65535 clipped and scaled
x=readch(x,y,ch,[,source])ch is 0123 for RGBA, source as [,1] means read origin
x=writep(x,y,r,g,b[,a])returns 1 on success, rgba are 0-65535
x=readm(x,y)Returns 0-65535, or 0 if you read outside the image
x=writem(x,y,m)m is 0-65535, returns 1 on success
x=cmix(c1,c2)Channel blending
x=amix(a1,a2)Alpha blending
x=setm(m)m may be 0 to 65535. Sets entire mask to this value. Returns one on success.
x=linem(x1,y1,x2,y2,m)Writes a line into the mask. Returns the length of the line.
x=aam(radius,amount)Antialias the mask, returns one on success.
Math functions (trig functions use radians for angles)
x=sin(y)Sine of y
x=sinh(y)Hyperbolic sine of y
x=asin(y)Arc sine of y
x=asinh(y)Hyperbolic arc sine of y
x=cos(y)Cosine of y
x=cosh(y)Hyperbolic cosine of y
x=acos(y)Arc cosine of y
x=acosh(y)Hyperbolic arc cosine of y
x=tan(y)Tangent of y
x=tanh(y)Hyperbolic tangent of y
x=atan(y)Arc tangent of y
x=atanh(y)Hyperbolic arc tangent of y
c=hypo(a,b)Hypotenuse (side c) of right triangle with sides a, b
x=round(y[,places])y is rounded to the nearest value, where decimal 5 rounds up.
x=negate(y)Negation: same as -y
x=seed(y)Seeds the random number generator
x=rdm(y)Returns a value from 0 to y
x=ln(y)Logarithm, base e
x=exp(y)Anti-logarithm, base e
x=log(y)Logarithm, base 10
x=alog(y)Anti-logarithm, base 10
x=fact(y)Factorial of y
x=int(y)strips all fractional value and returns a whole number
x=floor(y)strips all fractional value and returns y's whole-number portion
x=ceil(y)strips all fractional value and returns y's whole-number portion + 1
x=percent(y,p)Returns y as a percentage of p
x=atan2(x,y)Returns angle of x,y relative to 0,0
x=pow(x,y)Returns x to the power of y
x=length(x1,y1,x2,y2)returns the length of line x1,y1:x2:y2
x=mean(x1[,...,xn])Returns the mean of one or more values
x=median(x1[,...,xn])Returns the median of one or more values
x=avg(x1[,...,xn])Returns the average of one or more values
x=sum(x1[,...,xn])Returns the sum of one or more values
x=count(x1[,...,xn])Returns the number of one or more values
x=min(x1[,...,xn])Returns the minimum of one or more values
x=max(x1[,...,xn])Returns the maximum of one or more values
General conversion functions
lbs=ntol(newtons)Newtons to pounds of force
newtons=lton(lbs)Pounds of force to newtons
degrees=rtod(radians)Converts radians to degrees
radians=dtor(degrees)Converts degrees to radians
feet=mtof(meters)Converts meters to feet
meters=ftom(feet)Converts feet to meters
gradians=dtog(degrees)Converts degrees to gradians
degrees=gtod(gradians)Converts gradians to degrees
btu=wtob(watts)Converts watts to BTUs
watts=btow(btus)Converts BTUs to watts
Temperature conversion functions
f=ctof(c)Converts Centigrade to Fahrenheit
f=ktof(k)Converts Kelvin to Fahrenheit
f=rtof(r)Converts Rankine to Fahrenheit
c=ftoc(f)Converts Fahrenheit to Centigrade
c=ktoc(k)Converts Kelvin to Centigrade
c=rtoc(r)Converts Rankine to Centigrade
k=ctok(c)Converts Centigrade to Kelvin
k=ftok(f)Converts Fahrenheit to Kelvin
k=rtok(r)Converts Rankine to Kelvin
r=ctor(c)Converts Centigrade to Rankine
r=ftor(f)Converts Fahrenheit to Rankine
r=ktor(k)Converts Kelvin to Rankine
dc=dftodc(df)Converts delta Fahrenheit to delta Centigrade
df=dctodf(dc)Converts delta Centigrade to delta Fahrenheit
Electronics functions
e=irtoe(i,r)Ohm's law: volts from amperes and watts
e=pitoe(p,i)Ohm's law: volts from watts and amperes
e=prtoe(p,r)Ohm's law: volts from watts and ohms
i=ertoi(e,r)Ohm's law: amperes from volts and ohms
i=petoi(p,e)Ohm's law: amperes from watts and volts
i=prtoi(p,r)Ohm's law: amperes from watts and ohms
r=eitor(e,i)Ohm's law: ohms from volts and amperes
r=eptor(e,p)Ohm's law: ohms from volts and watts
r=pitor(p,i)Ohm's law: ohms from watts and amperes
p=eitop(e,i)Ohm's law: watts from volts and amperes
p=ertop(e,r)Ohm's law: watts from volts and ohms
p=irtop(i,r)Ohm's law: watts from amperes and ohms
Lp=lpar(L1[,L2,...,Ln])Parallel inductance (no coupling)
Ls=lser(L1[,L2,...,Ln])Series inductance (no coupling)
Rp=rpar(R1[,R2,...,Rn])Parallel resistance
Rs=rser(R1[,R2,...,Rn])Series resistance
Cp=cpar(C1[,C2,...,Cn])Parallel capacitance
Cs=cser(C1[,C2,...,Cn])Series capacitance
e=dtov(dbm)Converts dbm to volts
pr=prat(dB)dB to Power ratio
vr=vrat(dB)dB to Voltage ratio
dbm=dbm(e[,r])Volts and ohms to dbm. r is 50 unless specified otherwise
dbm=stod(s)Converts sunitsnote 1 to dbm
s=sunits(e[,r])Converts volts to sunitsnote 1. r is 50 unless specified otherwise
s=dbmtos(dbm)Converts dbm to sunitsnote 1
f=wtof=(w)Converts wavelength to frequency
w=ftow(f)Converts frequency to wavelength
w=dtow(d)Converts dbm to watts
d=wtod(w)Converts watts to dbm
s=etos(e)Converts "effective number of bits" to "signal to noise and distortion ratio"

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.

§ - 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:

text [Font=fontname] [X=integer] [Y=integer] [Scale=0.1...2.0] [content=text]*
rect [Left=integer] [Top=integer] [Right=integer] [Bottom=integer]
ellipse [XCenter=integer] [YCenter=integer] [XRadius=integer] [YRadius=integer]
rellipse [Left=integer] [Top=integer] [Right=integer] [Bottom=integer]
wand [X=integer] [Y=integer] [Tolerance=1...100]
Note: The text command's [Y=integer] parameter specifies the baseline of the text area selection; that means that characters with descenders will create selection regions below the baseline.

The system variables m_lineheight, m_ascent, m_descent, and m_leading can be used to calculate spacing between lines in various ways. They are valid after the text area selection command runs, so you can't use them unless you do a small test selection first, or after the first line has been generated (which tends to be when you actually need them, so there's that.)

Those four values incorporate both the m_fontpoints setting and the [Scale=0.1...2.0] parameter you supply to the text area selection command.

* Numeric conversion rules are set with these system variables.

Tip: If you use one of the above area selection commands, doing so will override any area selection that was manually made. The selection you make will only trigger the script, and the actual selection used will be the one the specified in the script.

§ - Miscellaneous Commands

Miscellaneous Commands:
mix [Amount=0...100]Mix the result of the last operation with the prior image state
pause [Seconds=1...10]Sleep iToolBox for N seconds
vload [filePathAndName=noSpaces] [LoadAsOrigin=0...1] [ReLoad=0...1]Load an image if not already loaded, optionally set to origin, or if ReLoad=1, load it again if it's already loaded

§ - 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:


Here's one that will colorfill in orange:

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

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

cfill~"colorfill dparm(0) dparm(1) dparm(2)"

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.

Caution: x=dparm(index) and text=tparm(index) values are only valid until another function is called. So if your function calls another function, be sure to load the parms into your own variables before doing so. If you try to use them in your function after another function is called from within your function, the values will either be gone, or changed.

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
  • If you need to represent an actual semicolon within a text string in a user-defined function, use a digraph: ;;
  • When you create literal text strings in a user-defined function, represent the double-quotes with the sequence backslash-double-quote ( \" 
§ - 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:

# variable x is now set to 1802
§ - 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:

# 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.

§ - Arrays

§ - 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.

§ - Array Functions

The following functions deal with numeric arrays:

columns=acols(name)Get column count of existing array
sum=add(name)Sums all elements in the array
size=append(name,value[,...])Add one or more values to the end of an array. Resets dimensions to one row by n columns.
rows=arows(name)Get row count of existing array
size=array(name[,x0[,xn]])Array creation or re-creation. If n optional array elements are included, array will be dimensioned to one row by n columns.
void=assign(name,x,index[,indexb])Set one already-existing array value x at position index or at position row index, column indexb. See value() for more details.
size=bits(name,x,size)Create a 1 to 64 element array of bits of x, MSb at 0, LSb at size-1
void=convolve(name,n[,mode])Run an image convolution using array name of n x n dimensions. n must match both the row and column dimensions of the array.
n must be odd, and it must be 3 or more, for example, 3, 5, 7 etc.
mode defaults to zero if not specified or out of range. Modes are as follows:
  1. Color (RGB) (default)
  2. Monochrome (RGB average)
  3. Monochrome (luminance)
  4. Monochrome (red channel)
  5. Monochrome (green channel)
  6. Monochrome (blue channel)
For example:

append(n, 1, 4, 7, 4, 1)
append(n, 4, 16, 26, 16, 4)
append(n, 7, 26, 41, 26, 6)
append(n, 4, 16, 26, 16, 4)
append(n, 1, 4, 7, 4, 1)
void=dim(name,rows,columns)Dimension an existing array. rows*columns must equal array size.
size=duplicate(name,newArrayName)Duplicate an existing array to newArrayname
void=divide(name,divisor)Divides each array value by divisor; scalar division (note division by zero results in warning and division by smallest possible value)
void=dividend(name,dividend)Divides dividend by each array value; scalar division (note division by zero results in warning and division by smallest possible value)
index=indexof(name,value[,start])Searches array name for value beginning at start. If start is not provided, starts at element 0. If the value is found, returns the index into the array; otherwise, returns -1.
size=insert(name,index,x)Insert a new array value x at position index. Resets dimensions to one row by n columns.
void=limit(name,v1,v2)All elements of the array are limited to v1 and v2
void=matadd(matA,matB,matC)C=A+B - matrix addition. A.size must equal B.size
rowsC=matmul(matA,matB,matC)C=A*B - matrix multiplication. A.cols must equal B.rows. Arrays must have been dimensioned. For example:
void=matand(matA,matB,matC)C=A&B - matrix logical AND. A.size must equal B.size
void=matnegate(matA,matB)B=-A - matrix logical twos-complement.
void=matnot(matA,matB)B=~A - matrix logical complement.
void=mator(matA,matB,matC)C=A|B - matrix logical OR. A.size must equal B.size
void=matsub(matA,matB,matC)C=A-B - matrix subtraction. A.size must equal B.size
void=matxor(matA,matB,matC)C=A^B - matrix logical XOR. A.size must equal B.size
digitcount=maxdigits(name)Returns the maximum number of characters in any array element. Can be used for formatting text output of the array, for instance: m_fieldwidth=maxdigits(myarray).
void=maximize(name,minValue)All elements of the array are no less than minValue
void=minimize(name,maxValue)All elements of the array are no more than maxValue
void=minuend(name,minuend)Subtracts each array value from minuend; scalar subtraction
void=minus(name,subtrahend)Subtracts subtrahend from each array value; scalar subtraction
void=multiply(name,multiplier)Multiplies each array value by multiplier; scalar multiplication
void=normalize(name[,maxValue])Divides all elements by maxValue, or max value found in array if maxValue is not provided
void=plus(name,addend)Adds addend to each array value; scalar addition
size=prepend(name,value[,...])Insert one or more values at the beginning of an array. Resets dimensions to one row by n columns.
size=remove(name,index)Remove the value at position index from an array. Resets dimensions to one row by n columns.
void=reverse(name)Reverse the order of values in an array
size=size(name)Obtain number of values in an array
out=shiftleft(name[,in])Shift array values left. If you provide the optional in parameter, that's what will shift in on the right. Otherwise, a zero shifts in.
out=shiftright(name[,in])Shift array values right. If you provide the optional in parameter, that's what will shift in on the left. Otherwise, a zero shifts in.
void=swap(name,indexA,indexB)Swap two already-existing array values at positions indexA and indexB
x=value(name,index1[,index2])Obtain the value at position index1 (array treated as one row by n columns) or at position index1,index2 (array treated as two-dimensional) from an array. In the single index case, index1 must be less than the total size of the array. In the dual-index case, index1 must be less than the number of rows the array has been dimensioned to, and index2 must be less than the number of columns the array has been dimensioned to. Example:

x=value("ay",4:#x == 50
x=value(1,1):#x == 40

§ - Comparative math operators

Comparative math operators:
x==yx equal to y is 1, otherwise 0
x!=yx not equal to y is 1, otherwise 0
x<=yx less than or equal to y is 1, otherwise 0
x>=yx greater than or equal to y is 1, otherwise 0
x<yx less than y is 1, otherwise 0
x>yx greater than y is 1, otherwise 0

§ - Conditionals

Conditional statements:
if([expression])For example, if(a<b); content after if() executes when the if() expression evaluates to anything other than 0. Conditionals such as a<b evaluate to either 1 or 0.
elseoptional after if; content after else executes when the if expression evaluates to 0
endifTerminates if and optional else sections
§ - If() Examples
if() examples
if((10+1)-11)False. (0)
if(10-(2+9))True. (-1 is non-zero)
if(m_pi)True. (m_pi [3.14159...] is non-zero)
if(a)When a does not exist, always false
True. Any text variable with content that begins with t or T is always true
True. Any text variable with content that begins with t or T is always true
False. Any text variable containing content that does not begin with t or T is always false
if("")False. Empty string.
if("tumbleweed")True. String begins with t
if("bananas")False. String begins with b

§ - 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...


...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...


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


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.)

Caution: You can change the value of the m_maxops variable in your script, or in your script presets. If you do so unwisely, you can set up a condition where a script will never end, practically speaking.
Document Keyboard Navigation
, Previous Page . Next Page
t TOC i Index k Keyboard o Operators g Glossary c Changes

Valid HTML 4.01 Loose

This manual was generated with wtfm
wtfm uses aa_macro and SqLite
wtfm and aa_macro are coded in python 2.7
iToolBox 3.12
This Documentation and Associated Application Executables are Public Domain
Please consider supporting my iToolBox development efforts with a small PayPal donation.