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.
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.
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).
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).
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).
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).
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".
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.
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.
x2 The right co-ordinate.
y2 The bottom co-ordinate.
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.
lineto(<path>, <x>, <y>);
Adds a straight line segment to the specified path:
name The name of the path.
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:
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).
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.
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.