i.Mage Scripting

IndexToolsUsageScripting
Scripting
Scripting is a way of generating content based on exact parameters in a repeatable way. You can tweak a script over time to produce the result you want. Currently the number of commands available in the scripting language are limited but it's easy to add more in future versions. Almost all of i.Mage's functionality could be exposed through script commands.

To start scripting, open the script window with F8 or Tools -> Scripting and enter your script in the window provided. Then click "Run" to execute the script. Also there are examples at the end of this page.

Language Syntax
The language is made up of a list of statements, which can be either function calls, assigments, flow control or loops. Execution starts at the first statement at the top and continues to the bottom of the script. Statements tend to use expressions as arguments. An expression can be a literal value, a variable or a combinations of literals, variables and operators that combine the values.

Statement syn: function(); function (expression); function (expression, expression);

-or-
variable = expression; variable++; variable--;
-or-
for (initial statement; condition expression; post statement)
{
    statements;
}
-or-
if (condition expression)
{
    statements executed if expression is true;
}
 
Expression syn: value value infix operator value
where a value can be one of:
"string" integer double variable name (nested expression)
and an infix operator can be one of:
+ - * / < > <= >= == !=
 
Variables:

Variables do not need to be declared, just assign them a value to get started. Internally variables are stored as variants and type converted as required. The + operator can be used for string concatenation: a = 7;
Msg = "Variable a is: " + a;

Msg will contain "Variable a is: 7".

However if the string is numeric, it will be treated as a number and normal addition will take place: a = 7;
Msg = "5" + a;

Msg will contain 12.

At the moment variables have 3 basic types, integer, double and string. Generally if at least one of the values being combined with an infix operator is of type double (floating point) then the other argument is converted to double and the result is a double. Otherwise the arguments are generally treated as integers, except for the + operator where checks for string concatenation are done.

Integers may be represented as decimals (one or more characters in the range "0-9") or as hex ("0x" + one or more characters in the range "0-9|a-f|A-F").

All the variables used and their values at the end of the script are printed at the end of the output log.

Function Reference
Document Path Brush Drawing Utils
create
save
newpath
fillpath
rgb
rgba
lineargradient
radialgradient
addstop
setfillrule
rect
roundrect
circle
moveto
lineto
quadto
cubicto
font
text
blur
msgbox
print


create(<x>, <y>, <bits>); Creates a new document with the specified parameters. In the case that you already have a document open it will be closed and a new document is created. You don't always need to use this command at the start of the script, i.e. if you want to use a script to draw on some document you've opened manually.
x The width of the image.
y The height of the image.
bits The bit depth of the image.
save(<filename>[, <options>]); Saves the current document to the specified file.
filename The file to save to. The right export filter is selected by the file's extension
options [Optional] list of options for saving the file in the form:
field1=value1[;field2=value2]
e.g.
save("c:\test.jpg", "quality=20");
The available fields are:
  • Quality - JPEG quality setting (10 to 90?).
  • Transparent - 0 means opaque, 1 means use background colour as a colour key.
  • Fore - Foreground colour (not used yet)
  • Back - An over-ride for the background colour. When mixed with 'Transparent', pixels matching the background will be saved as transparent in formats that support transpareny.
If fields aren't supplied a dialog will appear asking the user to supply values.
rgb(<r>, <g>, <b>); Sets the current foreground colour to a RGB value:
r The red component, in the form 0x## for a hex value, otherwise in decimal (0-255).
g The green component.
b The blue component.
rgba(<r>, <g>, <b>, <a>); Sets the current foreground colour to a RGBA value:
r The red component, in the form 0x## for a hex value, otherwise in decimal (0-255).
g The green component.
b The blue component.
a The alpha level (0 = transparent, 255 = opaque).
lineargradient(<x1>, <y1>, <x2>, <y2>); Sets the current brush to a linear gradient, which by default has no stop colours. You need to add stops using the addstop command after using lineargradient:
x1 x co-ordinate for the start position (stop=0).
y1 y co-ordinate for the start position (stop=0).
x2 x co-ordinate for the end position (stop=1).
y2 y co-ordinate for the end position (stop=1).
radialgradient(<cx>, <cy>, <rad>); Sets the current brush to a radial gradient, which by default has no stop colours. You need to add stops using the addstop command after using radialgradient:
cx x co-ordinate for the center (stop=0).
cy y co-ordinate for the center (stop=0).
rad The radius (stop=1).
addstop(<pos>, <r>, <g>, <b>, <a>); Adds a stop to the previous radial or linear gradient command:
pos The stop position, which can take a value from 0.0 to 1.0.
r The red component, in the form 0x## for a hex value, otherwise in decimal (0-255).
g The green component.
b The blue component.
a The alpha level (0 = transparent, 255 = opaque).
setfillrule(<path>, <rule>); Sets the fill rule for the specified path:
path The name of the path to set.
rule The rule, either "oddeven" or "nonzero". The default is "oddeven".
g The green component.
b The blue component.
a The alpha level (0 = transparent, 255 = opaque).
newpath(<name>); Creates a new path object called "name". All paths are automatically deleted at the end of the script. Once you create a path you need to add some line segments and curves to it then use the fillpath command to draw it to the document in the current foreground colour. A path has a current position from which line segments start from. When a path has just been created it doesn't have a current point yet and the first thing you should do is use the moveto command to set the starting position for the path.
name The name of the path.
fillpath(<name>); Draws the specified path to the current document in the current foreground colour.
name The name of the path.
rect(<path>, <x1>, <y1>, <x2>, <y2>); Adds a rectangle to the specified path:
name The name of the path to add to.
x1 The left co-ordinate.
y1 The top co-ordinate.
x2 The right co-ordinate.
y2 The bottom co-ordinate.
roundrect(<path>, <x1>, <y1>, <x2>, <y2>, <radius>); Adds a rectangle with rounded corners to the specified path:
name The name of the path to add to.
x1 The left co-ordinate.
y1 The top co-ordinate.
x2 The right co-ordinate.
y2 The bottom co-ordinate.
y2 The corner radius.
circle(<path>, <center-x>, <center-y>, <radius>); Adds a circle to the specified path:
name The name of the path to add to.
center-x The x part of the center co-ordinate.
center-y The y part of the center co-ordinate.
radius The radius of the circle.
moveto(<path>, <x>, <y>); Starts a new line segment by moving the drawing position for the specified path:
name The name of the path.
x The x co-ordinate.
y The y co-ordinate.
lineto(<path>, <x>, <y>); Adds a straight line segment to the specified path:
name The name of the path.
x The x co-ordinate.
y The y co-ordinate.
quadto(<path>, <cx>, <cy>, <x>, <y>); Adds a quadratic curve segment to the specified path:
name The name of the path.
cx The x co-ordinate of the control point.
cy The y co-ordinate of the control point.
x The x co-ordinate of the final point.
y The y co-ordinate of the final point.
cubicto(<path>, <c1x>, <c1y>, <c2x>, <c2y>, <x>, <y>); Adds a cubic curve segment to the specified path:
name The name of the path.
c1x The x co-ordinate of the first control point.
c1y The y co-ordinate of the first control point.
c2x The x co-ordinate of the second control point.
c2y The y co-ordinate of the second control point.
x The x co-ordinate of the final point.
y The y co-ordinate of the final point.
font(<face>, <point-size>, <style>); Sets the current font:
face The name of the font's family/face.
point-size The point size of the font.
style Combination of various comma separated style parameters. e.g. "bold,italic", "underline" or "" for normal text:
  • bold
  • italic
  • underline
text(<path>, <x>, <y>, <str>); Adds curves to a specific path to represent a string using the current font:
path The path to add the text to.
x The x co-ordinate of the text.
y The y co-ordinate of the text (i.e. the base line).
str The string to add.
blur(<radius>); Blurs the entire document by the specified radius:
radius The radius of the blur.
msgbox(<message>); Pops up a message box:
message The content of the message.
print(<message>); Prints a message to the output terminal:
message The content of the message.
Examples
A simple example script that draws a little 16 x 16 curve suitable for the bottom right of a rounded rectangle:
create(16, 16, 32);

newpath(p);
moveto(p, 0, 0);
lineto(p, 0, 16);
lineto(p, 16, 16);
cubicto(p, 7.16, 16, 0, 7.16, 0, 0);

rgb(0x20, 0x20, 0x50);
fillpath(p);

save("C:\Documents and Settings\Matthew.MALLEN\Desktop\bottom-left.png");
Or this which draws a nice little red to blue gradient:
create(32, 32, 32);

lineargradient(0, 0, 32, 0);
addstop(0, 255, 0, 0, 255);
addstop(1, 0, 0, 255, 255);

newpath(p);
rect(p, 0, 0, 32, 32);

fillpath(p);
Some text with a drop shadow:
create(190, 80, 32);
font(Verdana, 60, "");

x = 5;
y = 65;
drop = 3;

newpath(p);
rgba(0, 0, 0, 128);
text(p, x + drop, y + drop, "Test");
fillpath(p);

blur(2.5);

newpath(p);
rgb(255, 0, 0);
text(p, x, y, "Test");
fillpath(p);
And this is a more complex web button:
w = 80;
h = 26;
edge = 2;
r = 7;

create(w, h, 32);

// Draw the fill first
newpath(p);
roundrect(p, edge, edge, w - edge, h - edge, r - edge);
lineargradient(edge, edge, edge, h - edge);
addstop(0, 255, 255, 255, 255);
addstop(1, 222, 222, 222, 255);
fillpath(p);

// Border + text in one render
newpath(p);
roundrect(p, 0, 0, w, h, r);
roundrect(p, edge, edge, w - edge, h - edge, r - edge);
font(Verdana, 14, "");
text(p, 9, 20, "Button");
lineargradient(0, 0, 0, h);
addstop(0, 0xc0, 192, 192, 255);
addstop(1, 128, 128, 128, 255);
fillpath(p);
Scripts should be saved externally to i.Mage and copied into the script editor as needed.
© 1999-2006 Matthew Allen