/ Operator Details
§ 12.11.82 - 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
Cursor at beginning of
§ 126.96.36.199 - 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.
|#a=1||One line of one block, commented out|
|a=1:#b=2:c=3||One 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.
§ 188.8.131.52 - 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 numbers||Digits (N) may be 0 ... 9|
§ 184.108.40.206 - 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]
bend [Mode=0...1] [Amount=-100...100]
camera [shutter=0...50000] [aperture=.1...100] [focallength=1...50000] [iso=1...1000000]
ceiling [Sample=0...1] [Mode=0...2]
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]
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]
dpi [xDPI=1...3200] [yDPI=1...3200]
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]
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]
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=0...100] [shad=-100...100] [mid=-100...100] [high=-100...100] [whit=0...100]
loccontrast [Amount=0...100] [Density=0...9]
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]
mirror [Degrees=-360...360] [Center=0...1]
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]
rotate [Degrees=-360.0...360.0] [Center=0...1]
sample [Accumulate=0...1] [Subtract=0...1]
sharpen [Radius=1...10] [Threshold=0...100] [Amount=0...100]
skew [Xskew=-100...100] [Yskew=-100...100]
stretch [Hamount=-100...100] [Vamount=-100...100]
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]
§ 220.127.116.11 - Variables
§ 18.104.22.168.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.
|v=5||A 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
alphamod 128 0
|yvalue=2.7||A 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
text Courier 100 100 1.1 testing
|foo=2+3||A 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
random 0 0 0 100 10
random 0 0 0 100 Foo
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
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 testing||A literal, single-word font name|
text font 100 100 1.1 testing
|A multi-word font name contained in a variable|
§ 22.214.171.124.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:
|void||This 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.)|
|true||This variable always exists, and is always equal to 1. Its value cannot be changed.|
|false||This variable always exists, and is always equal to 0. Its value cannot be changed.|
|debug||This variable always exists, and defaults to true. iToolBox provides debugging information when errors are encountered if debug is true.|
The speed of light, in meters/sec, in free space.
|Image circumstances at script run time|
|m_width||Image width in pixels|
|m_height||Image height in pixels|
|m_origin||One if an origin image is available, zero otherwise.|
|m_owidth||Origin image width in pixels (zero if no origin set)|
|m_oheight||Origin image height in pixels (zero if no origin set)|
|m_date||Current date (see also string functions createtime, modtime)|
|m_time||Current time (see also string functions createtime, modtime)|
|m_xdpi||Image x dpi|
|m_ydpi||Image y dpi|
|m_aperture||Image camera lens aperture|
|m_focallength||Image camera lens focal length|
|m_iso||Image camera ISO|
|m_shutter||Image camera shutter speed|
|m_leading||Text line leading after text operator runs|
|m_ascent||Text line ascent after text operator runs|
|m_descent||Text line descent after text operator runs|
|m_lineheight||Text line height after text operator runs|
|Numeric to text conversion control|
Range is 10 to 200.
Range is zero to four:
- Format as [-]9.9e[+/-]999
Format as [-]9.9E[+/-]999
Format as [-]9.9
Use the more concise of 0 or 2 format
use the more concise of 1 or 2 format
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_xyzzyplugh||I 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.|
§ 126.96.36.199 - 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 ( \" )
§ 188.8.131.52.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 (... \" )
|Text operator (~) functions|
|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=layername([prepend][,postpend])||Name of an image layer (same as imagename())|
|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:
String variable names
numeric variable names
Numeric variable names
|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|
§ 184.108.40.206 - 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*3||The variable x now contains 12|
|x=2+(2*3)||The variable x now contains 8|
§ 220.127.116.11.1 - Unary Operations
An unary operation is one that directly affects the following value. There is only one unary operation:
§ 18.104.22.168.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.
|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:
Avoid these errors:
Makes script operations slightly more efficient
Alerts the syntax coloring engine that a variable exists before it is assigned
Alerts the syntax coloring engine to array names
If there are no errors, declare() returns the number of variables declared.
Specifying a variable that has already been assigned
Specifying an illegal variable name
Specifying a variable twice
Specifying a constant
|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:
numeric variables, all lower case, for literal value
Numeric variables, uppercase 1st letter, for instantiating text expression
|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=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|
|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)|
|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.
§ 22.214.171.124 - 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.
§ 126.96.36.199 - 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|
§ 188.8.131.52 - 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 ( \"
§ 184.108.40.206.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:
# variable x is now set to 1802
§ 220.127.116.11.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:
# 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.
§ 18.104.22.168 - Arrays
§ 22.214.171.124.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.
§ 126.96.36.199.2 - 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:
Color (RGB) (default)
Monochrome (RGB average)
Monochrome (red channel)
Monochrome (green channel)
Monochrome (blue channel)
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
§ 188.8.131.52 - Comparative math operators
|Comparative math operators:|
|x==y||x equal to y is 1, otherwise 0|
|x!=y||x not equal to y is 1, otherwise 0|
|x<=y||x less than or equal to y is 1, otherwise 0|
|x>=y||x greater than or equal to y is 1, otherwise 0|
|x<y||x less than y is 1, otherwise 0|
|x>y||x greater than y is 1, otherwise 0|
§ 184.108.40.206 - Conditionals
|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.|
|else||optional after if; content after else executes when the if expression evaluates to 0|
|endif||Terminates if and optional else sections|
§ 220.127.116.11.1 - If() Examples
|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|
§ 18.104.22.168 - 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
This manual was generated with wtfm
wtfm uses aa_macro and SqLite
wtfm and aa_macro are coded in python 2.7
This Documentation and Associated Application Executables are Public Domain