NanDECK Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 179
| Download | |
| Open PDF In Browser | View PDF |
nanDECK Manual
by Andrea “Nand” Nini
Program version 1.24.1 – 2018-10-05
Index
An overview ....................................................................................................................................................................... 6
Editor commands ................................................................................................................................................................ 9
Getting started… ............................................................................................................................................................... 11
Ranges .............................................................................................................................................................................. 15
Colors ............................................................................................................................................................................... 16
Labels and sequences ........................................................................................................................................................ 19
Label functions ................................................................................................................................................................. 25
AUTOLABEL .............................................................................................................................................................. 25
AUTORANGE ............................................................................................................................................................. 25
CASESTRING .............................................................................................................................................................. 25
CONCAT ...................................................................................................................................................................... 26
CONCAT1 .................................................................................................................................................................... 26
COOFRAME ................................................................................................................................................................ 26
COOFRAMES .............................................................................................................................................................. 26
DIRFILES ..................................................................................................................................................................... 26
ENVIRONMENT ......................................................................................................................................................... 27
EVAL............................................................................................................................................................................ 27
EXPAND ...................................................................................................................................................................... 27
FILTER ......................................................................................................................................................................... 27
GRADIENTSEQ .......................................................................................................................................................... 29
GROUP ......................................................................................................................................................................... 29
JOIN ............................................................................................................................................................................. 30
JOINIF .......................................................................................................................................................................... 30
LABELRANGE ............................................................................................................................................................ 30
LABELSTRING ........................................................................................................................................................... 31
LABELSUB .................................................................................................................................................................. 31
LENGTH ...................................................................................................................................................................... 32
PRODUCT.................................................................................................................................................................... 32
RANGEADD ................................................................................................................................................................ 32
RANGECOUNT ........................................................................................................................................................... 33
RANGEMUL................................................................................................................................................................ 33
RANGEREM ................................................................................................................................................................ 33
RANGESUB ................................................................................................................................................................. 33
REPLACE .................................................................................................................................................................... 34
ROUND ........................................................................................................................................................................ 34
SAVELABEL ............................................................................................................................................................... 34
STRINGLABEL ........................................................................................................................................................... 34
TOKENIZE .................................................................................................................................................................. 34
TOKENIZESEQ ........................................................................................................................................................... 35
TRANSLATE ............................................................................................................................................................... 35
Frames .............................................................................................................................................................................. 36
Frame functions ................................................................................................................................................................ 40
FRAMEBAR ................................................................................................................................................................ 40
FRAMEBEZIER........................................................................................................................................................... 40
FRAMEBOX ................................................................................................................................................................ 40
FRAMECLOCK ........................................................................................................................................................... 41
FRAMECOUNT ........................................................................................................................................................... 42
FRAMEDISK ............................................................................................................................................................... 42
FRAMEHEX ................................................................................................................................................................ 42
FRAMELINE ............................................................................................................................................................... 43
FRAMELIST ................................................................................................................................................................ 43
FRAMEMELD ............................................................................................................................................................. 44
FRAMEMOSAIC ......................................................................................................................................................... 44
FRAMENET ................................................................................................................................................................. 45
FRAMEPATH .............................................................................................................................................................. 45
FRAMEPER ................................................................................................................................................................. 46
FRAMERECT .............................................................................................................................................................. 46
FRAMESUB ................................................................................................................................................................. 46
FRAMETRANS ........................................................................................................................................................... 46
FRAMETRI .................................................................................................................................................................. 47
2
Expressions ....................................................................................................................................................................... 48
Comments ......................................................................................................................................................................... 49
Script lists ......................................................................................................................................................................... 50
Create PDF ....................................................................................................................................................................... 51
Save images ...................................................................................................................................................................... 52
Convert a PDF to images .................................................................................................................................................. 52
Command-line parameters ................................................................................................................................................ 53
Keyword wizards .............................................................................................................................................................. 54
Linked data editor ............................................................................................................................................................. 56
Virtual table ...................................................................................................................................................................... 57
Visual editor ..................................................................................................................................................................... 59
Configuration .................................................................................................................................................................... 61
Compare decks ................................................................................................................................................................. 64
Shortcuts ........................................................................................................................................................................... 65
References ........................................................................................................................................................................ 65
F.A.Q. ............................................................................................................................................................................... 65
Directives .......................................................................................................................................................................... 67
BASERANGE .............................................................................................................................................................. 67
BATCH ......................................................................................................................................................................... 67
BEZIER ........................................................................................................................................................................ 68
BEZIERS ...................................................................................................................................................................... 69
BLEED ......................................................................................................................................................................... 70
BORDER ...................................................................................................................................................................... 70
BRUSH ......................................................................................................................................................................... 71
BUTTON ...................................................................................................................................................................... 73
CANVAS ...................................................................................................................................................................... 74
CANVASSIZE ............................................................................................................................................................. 75
CANVASWORK .......................................................................................................................................................... 75
CARDS ......................................................................................................................................................................... 75
CARDSIZE ................................................................................................................................................................... 75
CASE ............................................................................................................................................................................ 76
CASEELSE .................................................................................................................................................................. 76
CHROMAKEY............................................................................................................................................................. 76
COLOR ......................................................................................................................................................................... 77
COLORCHANGE ........................................................................................................................................................ 78
COLORS ...................................................................................................................................................................... 78
COMMENT .................................................................................................................................................................. 79
COMPARE ................................................................................................................................................................... 79
COPY............................................................................................................................................................................ 80
COPYCARD ................................................................................................................................................................ 81
CORRECTION ............................................................................................................................................................. 81
COUNTER ................................................................................................................................................................... 82
DECK ........................................................................................................................................................................... 82
DICE ............................................................................................................................................................................. 83
DISPLAY ..................................................................................................................................................................... 83
DOWNLOAD ............................................................................................................................................................... 84
DPI ................................................................................................................................................................................ 84
DRAW .......................................................................................................................................................................... 84
DUPLEX ...................................................................................................................................................................... 85
EDGE............................................................................................................................................................................ 85
ELLIPSE ....................................................................................................................................................................... 87
ELSE ............................................................................................................................................................................. 88
ELSEIF ......................................................................................................................................................................... 88
END .............................................................................................................................................................................. 88
ENDFRAME ................................................................................................................................................................ 88
ENDIF .......................................................................................................................................................................... 88
ENDLAYER ................................................................................................................................................................. 89
ENDLINK .................................................................................................................................................................... 89
ENDSECTION ............................................................................................................................................................. 89
ENDSELECT ............................................................................................................................................................... 90
ENDSEQUENCE ......................................................................................................................................................... 90
ENDVISUAL ............................................................................................................................................................... 90
3
FILL .............................................................................................................................................................................. 91
FOLDER ....................................................................................................................................................................... 91
FONT ............................................................................................................................................................................ 92
FONTALIAS ................................................................................................................................................................ 93
FONTCHANGE ........................................................................................................................................................... 94
FONTRANGE .............................................................................................................................................................. 94
FOOTER ....................................................................................................................................................................... 95
FOR .............................................................................................................................................................................. 96
FRAME ........................................................................................................................................................................ 97
GAP .............................................................................................................................................................................. 97
GRID ............................................................................................................................................................................ 98
HEADER ...................................................................................................................................................................... 99
HEXGRID .................................................................................................................................................................. 100
HTMLFILE ................................................................................................................................................................ 101
HTMLFONT .............................................................................................................................................................. 102
HTMLIMAGE ............................................................................................................................................................ 103
HTMLKEY ................................................................................................................................................................. 103
HTMLMARGINS....................................................................................................................................................... 104
HTMLTEXT ............................................................................................................................................................... 105
ICON .......................................................................................................................................................................... 106
ICONS ........................................................................................................................................................................ 107
IF................................................................................................................................................................................. 108
IMAGE ....................................................................................................................................................................... 110
IMAGEFILTER .......................................................................................................................................................... 113
IMAGESIZE ............................................................................................................................................................... 113
INCLUDE ................................................................................................................................................................... 113
INPUTCHOICE .......................................................................................................................................................... 115
INPUTLIST ................................................................................................................................................................ 116
INPUTNUMBER ....................................................................................................................................................... 117
INPUTTEXT .............................................................................................................................................................. 118
LAYER ....................................................................................................................................................................... 119
LAYERDRAW ........................................................................................................................................................... 119
LIMIT ......................................................................................................................................................................... 120
LINE ........................................................................................................................................................................... 121
LINERECT ................................................................................................................................................................. 122
LINK ........................................................................................................................................................................... 123
LINKCOLOR ............................................................................................................................................................. 124
LINKENCCSV ........................................................................................................................................................... 124
LINKENCODE........................................................................................................................................................... 124
LINKFILTER ............................................................................................................................................................. 125
LINKMULDIS ........................................................................................................................................................... 125
LINKMULTI .............................................................................................................................................................. 126
LINKNEW .................................................................................................................................................................. 127
LINKRANDOM ......................................................................................................................................................... 127
LINKSEP .................................................................................................................................................................... 127
LINKSTYLES ............................................................................................................................................................ 128
LINKTRIM ................................................................................................................................................................. 128
LINKUNI .................................................................................................................................................................... 128
LOG ............................................................................................................................................................................ 128
MACRO...................................................................................................................................................................... 130
MARGINS .................................................................................................................................................................. 131
MOSAIC ..................................................................................................................................................................... 131
NANDECK ................................................................................................................................................................. 132
NEXT.......................................................................................................................................................................... 132
ORIGIN ...................................................................................................................................................................... 132
OVERSAMPLE .......................................................................................................................................................... 133
PAGE .......................................................................................................................................................................... 133
PAGEFONT ............................................................................................................................................................... 134
PAGEIMAGE ............................................................................................................................................................. 134
PATTERN .................................................................................................................................................................. 136
PIE .............................................................................................................................................................................. 137
POLYGON ................................................................................................................................................................. 138
4
PRINT ......................................................................................................................................................................... 139
QRCODE .................................................................................................................................................................... 139
RECTANGLE............................................................................................................................................................. 140
RENDER .................................................................................................................................................................... 141
RHOMBUS ................................................................................................................................................................ 142
ROUNDRECT ............................................................................................................................................................ 143
RTFFILE .................................................................................................................................................................... 144
RTFTEXT ................................................................................................................................................................... 145
SAVE .......................................................................................................................................................................... 146
SAVEGIFA ................................................................................................................................................................ 147
SAVEPAGES ............................................................................................................................................................. 147
SAVEPDF .................................................................................................................................................................. 147
SECTION ................................................................................................................................................................... 148
SELECT...................................................................................................................................................................... 148
SEQUENCE ............................................................................................................................................................... 149
SET ............................................................................................................................................................................. 150
SPECIAL .................................................................................................................................................................... 150
STAR .......................................................................................................................................................................... 151
STORE........................................................................................................................................................................ 152
TABLE ....................................................................................................................................................................... 152
TAG ............................................................................................................................................................................ 152
TEXT .......................................................................................................................................................................... 154
TEXTFONT................................................................................................................................................................ 156
TEXTLIMIT ............................................................................................................................................................... 156
THREADS .................................................................................................................................................................. 157
TOKEN....................................................................................................................................................................... 157
TRACK ....................................................................................................................................................................... 158
TRACKRECT............................................................................................................................................................. 159
TRIANGLE ................................................................................................................................................................ 160
UNIT........................................................................................................................................................................... 161
VECTOR .................................................................................................................................................................... 161
VISUAL...................................................................................................................................................................... 162
ZOOM ........................................................................................................................................................................ 162
Code examples ................................................................................................................................................................ 163
Wargame counters ...................................................................................................................................................... 163
Dice results ................................................................................................................................................................. 164
Score track .................................................................................................................................................................. 165
Boggle dice ................................................................................................................................................................. 166
Catan map ................................................................................................................................................................... 167
Clock ........................................................................................................................................................................... 168
Hex board ................................................................................................................................................................... 169
Triangle map ............................................................................................................................................................... 170
Chess board................................................................................................................................................................. 171
Trivia cards ................................................................................................................................................................. 172
Hex racetrack .............................................................................................................................................................. 173
Tuckbox ...................................................................................................................................................................... 174
Number wheel ............................................................................................................................................................. 175
Tripples tiles ............................................................................................................................................................... 176
Path tiles ..................................................................................................................................................................... 177
Combinations .............................................................................................................................................................. 178
Standard 52-deck of cards........................................................................................................................................... 179
5
An overview
nanDECK is a program capable of creating graphic elements from scripts: every line of a script contains a command,
for rendering texts, rectangles and other graphic elements. The program was made for creating cards, but it can be used
for many other graphic objects; each card is treated like a different page, in which you can draw different graphical
elements. At the start, you can write the script in the large edit box in the center of the window:
You can load a script with the “Open deck” button, save it with “Save” and “as” buttons, and create the deck with the
buttons “Validate deck” and “Build deck”.
Tip: You can do both if you right-click the “Validate deck” button.
All commands start with a keyword, an equal sign (=) and a list of parameters; for many commands, the 1 st parameter is
a range of “cards” in which the command will be executed. The commands without a range will be evaluated only once
(for example the BORDER directive to draw a border on all cards, or the CARDS directive for setting the number of the
cards in the deck), or for every card (like the FONT directive); in other words, the program creates the 1 st card in the
deck, and executes all the script on it, then it switches on the 2 nd card, and executes all the script and so on; each ranged
directive is executed only if the range match.
Note: the CARDS directive is no longer needed, now the program creates automatically a deck using the information
from all the directives in the script. For example, if you have a 10-30 range, the deck will be created with 30 cards.
For example, in a game of Werewolf, I need a card with a word “SEER”, three “WEREWOLF” and thirteen
“VILLAGER”. The first card will be:
FONT = Arial, 32, B, #0000FF
TEXT = 1,"SEER", 0, 0, 100%, 100%, center, center
With the 1st line, I choose a font: Arial 32, bold, and blue (the #0000FF parameter); with the 2 nd line I draw the word
“SEER” in the center of the whole card #1 (starting from 0,0 – top left of the card, 100% width and 100% height). The
other cards will be drawn with these lines:
FONT = Arial, 24, B, #FF0000
TEXT = 2-4, "WEREWOLF", 0, 0, 100%, 100%, center, center
6
FONT = Arial, 28, B, #000000
TEXT = 5-18, "VILLAGER", 0, 0, 100%, 100%, center, center
Note the range 2-4 and 5-18, for three and thirteen cards. Other elements can be added, for example a rectangle:
RECTANGLE = 1-18, 0, 0, 100%, 100%, #FFFFFF#000000#FFFFFF@90, empty, 1
The rectangle is on all the cards (range 1-18), from 0,0 – top left, 100% width and 100% height, with a gradient starting
from white (#FFFFFF), to black (#000000), again to white, rotated 90°; not filled (empty parameter) and with a border
thickness of 1”.
The flexibility of the program is that an element can be added on one or more than one card, changing only the range
parameter. If you want to add an image on all the cards, you can add a line like this:
IMAGE = 1-18, "Logo.png", 0, 0, 20%, 20%, 0, TP
In the left bar in the main window you can use these command buttons:
New deck: creates a new script.
wiz: creates a new script selecting some options.
Open deck: open a saved script.
Reopen deck: open a saved script, picking one from a list of the last accessed.
Save: save the current script.
as: save the current script with another name.
Exit program: close the program.
Validate deck: the program check the syntax of the script.
Build deck: the program builds the deck of cards.
Print deck: the program print the deck of cards.
Save images: the program saves the images of each card of the deck, see page 52.
MT: the program can launch several instances of itself, each with a range of the deck.
PDF: the program creates a PDF file with all the cards’ images, see page 51.
CP: the program creates one image from each page of a PDF, see page 52.
GIFa: with this option, you can save the current deck into an animated GIF image (you can choose the delay between
images and select an optimized palette).
TIFF: with this option, you can save a multi-page TIFF image (with RGB or CMYK color space).
Print script: print the current script.
Insert >: this button open a menu, where you can insert a color, a font, an image, a symbol, a gradient, an include file, a
linked file, a label, a frame or a folder.
Linked data: you can edit the data from a linked csv file, see page 56.
Find: find a string in the script editor.
rpl: find and replace a string in the script editor.
7
Add (CTRL+R): the program adds a comment in the current line / selected block of the script.
Com (CTRL+E): the program toggles a comment in the current line / selected block of the script.
Rem (CTRL+U): the program removes a comment in the current line / selected block of the script.
Help (F1): the program shows a help page for the current directive.
(F2): the program shows a window for modifying the current directive.
Config: the configuration options, see page 61.
Info: info about the author.
In the right bar, you can use these command buttons:
Link first: if you check this option, only the first line from a data file (csv or spreadsheet) is read, for testing purpose.
Link dis.: if you check this option, the data file (csv or spreadsheet) is not read, and are shown only the fields’ names,
for testing purpose.
Preview: remove the check in this option if you want to hide the card preview (the rendering is faster).
Goto card: click to select a card from the deck to be viewed.
Auto build: check this option if you want to see in real time the script’s changes in the preview.
Highlight (checkbox): check this option to highlight with colors each line of the editor and each graphic element of the
preview.
Highlight (button): click to highlight the graphic element of the preview corresponding to the current line of the editor.
Partial: the program renders the current card only until the position of the cursor in the editor.
Arrow buttons: with these buttons, you move between the cards of the deck (first, prior, next, and last).
Card preview: this button shows you an enlarged view of the current card.
Canv: this button shows you the canvas (the “zero” card).
Visual Editor: the program opens the visual editor window, see page 59.
Comp: this button shows a window for comparing different decks of cards.
Script list: in this window, you can execute several scripts, in a batch mode, see page 50.
Edit: in this window, you can edit the content of a linked spreadsheet file.
Table: the program opens the virtual table window, see page 57.
The Game Crafter: in this window, you can upload a deck
http://www.thegamecrafter.com for printing and/or publishing your game.
of
card
directly
to
the
website
All deck: this button selects all the cards in the deck to be rendered (the start-end range is in the two edit box to the left
and right of this button).
8
Editor commands
CTRL+X
CTRL+C
CTRL+V
Cut
Copy
Paste
CTRL+A
CTRL+B
CTRL+I
CTRL+O
CTRL+P
CTRL+R
CTRL+U
CTRL+E
Select all
Validate and build the current card
Insert card’s number (character §)
Insert frame’s number (character °)
Insert frame’s number (character µ)
Comment current line/selected text
Remove comment from current line/selected text
Toggle comment on/off in current line/selected text
SHIFT+CTRL+I
SHIFT+CTRL+U
SHIFT+ALT+UP
SHIFT+ALT+DOWN
Block indent
Block un-indent
Move block up one line
Move block down one line
CTRL+D
SHIFT +CTRL+D
CTRL+M
CTRL+N
CTRL+T
CTRL+Y
SHIFT+CTRL+Y
CTRL+Z
SHIFT+CTRL+Z
Add new tab with a new version
Duplicate current line
Line break
Add new tab (empty)
Show windows side by side
Delete line
Delete EOL
Undo
Redo
CTRL+0…9
SHIFT+CTRL+0…9
Go to marker 0…9
Set/remove marker 0…9
SHIFT+CTRL+C
SHIFT+CTRL+L
SHIFT+CTRL+N
SHIFT+CTRL+B
Set columns selection
Set lines selection
Set standard selection
Match bracket
CTRL+F
CTRL+H
CTRL+G
Find
Replace
Go to line
F1
CTRL+F1
F2
CTRL+F2
F3
CTRL+F3
F4
F5
F6
F7
CTRL+F7
F8
CTRL+F8
F9
CTRL+F9
F10
Help (current line directive)
Auto layout (white on black)
Modify (current line directive)
Auto layout (color)
Modify (current line directive, visual mode)
Auto layout (black on white)
Visual editor
Auto build switch
Go to card
Highlight current line
Highlight all lines switch
Insert label
Insert frame
Insert color
Insert gradient
Partial build switch (build source until current line)
Tip: You can copy the current card’s image if you press CTRL+C after a click on the card image.
9
Tip: You can validate and build the current card’s image if you right-click on the card image.
Tip: You can validate and build the whole deck if you right-click on the “Validate deck” button.
Tip: You can edit more than one script simultaneously, right click on the tab on the upper side of the screen and choose
the voice “Add new tab” to add another tab to the editor.
Tip: You can move between cards using the mouse wheel.
10
Getting started…
This is a simple yet complete tutorial about how to create a deck of cards starting from a spreadsheet file.
First, I wrote some data, and save them as Data.xlsx:
Note: each column will be identified with the name in the first line (each must be different).
I start nanDECK, and as first line I link that file:
LINK = Data.xlsx
Then I save the script, as tut01.txt, in the same folder with the Excel file (if I want to save it in a different folder, in the
LINK line I must specify also the path, for example c:\users\nand\desktop\data\data.xls).
I want to put the title in the top of the card, then I select a font with the line:
FONT = Arial, 24, , #000000
Font name for the 1st parameter, size for the 2nd, and color for the 4th. The 3rd is empty, this is the place for flags like B
(bold), I (italic), U (underline) and so on (among others, if you want to shrink the font size to fit the space, use a N flag,
if you don’t want to see the text background, use a T flag). If you use more than one flag, put them all in this parameter
(for example: BTN).
And add the title with this line:
TEXT = 1-3, [name], 0, 0, 100%, 20%
The 1st parameter is the range, and I want to put this text on three cards (from 1 to 3, then the syntax is 1-3), the 2nd
parameter is the column name from the Excel file (enclosed in square brackets), the others are the position (0, 0 is top
left), width (100% of the card’s width) and height (20% is a fifth of the card’s height).
Note: I can use also values in cm, and I can specify 0, 0, 6, 1.8 (for a default card of 6 x 9 cm), but with percent values I
can change the size of the card without having to change every size of every element.
With a click on “Validate deck” button, “Build deck” button, the deck is created with three (ugly) cards:
Let’s add some images:
11
IMAGE = 1-3, [img], 0, 20%, 100%, 40%, 0, P
The 0 in the 7th parameter is the angle of rotation for the image, and the P is for proportionally resize the image, if you
have transparent PNGs, add a N flag in the same parameter (i.e. PN).
I’ve added the images’ files in the same folder with the spreadsheet and the script, and this is the result after Validate +
Build:
These lines are for the description:
FONT = Arial, 10, , #000000
TEXT = 1-3, [desc], 5%, 65%, 90%, 30%, left, wordwrap
I choose a smaller font, and since the description is more than one line, I add left as horizontal alignment and wordwrap
as vertical. This is the result:
These lines are for the value column:
FONT = Arial, 32, T, #FF0000
TEXT = 1-3, [value], 0, 20%, 20%, 40%
To make the number readable on every background, I can add an outlined text:
FONT = Arial, 32, T, #FFFFFF
TEXT = 1-3, [value], 0, 20%, 20%, 40%, center, center, 0, 100, 0.1
The “0, 100, 0.1” are respectively for angle, transparency and outline width.
Note that these lines must be added before, because every element in a script is drawn accordingly to its position: first
are drawn elements in the first lines, the last drawn are those in the bottom lines.
I have four icons (one for each element), each identified with a letter in my Excel file (and on each card, there may be
more than one icon). I add these lines in the script:
ICON
ICON
ICON
ICON
=
=
=
=
1-3,
1-3,
1-3,
1-3,
A,
E,
F,
W,
air.png
earth.png
fire.png
water.png
ICONS = 1-3, [icons], 80%, 20%, 20%, 40%, 20%, 10%, 0, PN
12
In the last line, I specify the icons’ area (80%, 20%, 20%, 40%), the size of each icon (20%, 10%), the angle of rotation
(0) and to use proportional resize (P) and PNG transparency (N).
I’ve added the four png files in the same folder. And this is the result:
Finally, I want to duplicate each card for the number specified in the “num” column, then I add, as first line (before the
LINK), this directive:
LINKMULTI = num
I must also change every range 1-3 into 1-7. This is the result page:
This is a more compact version of the script, here the 1 st parameter (the range) is empty for most directives because I
want to put the text/images on all the cards, and if I leave the 1 st parameter empty, nanDECK uses as a default 1-n,
where n is the number of lines in the Excel file.
13
LINKMULTI = num
LINK = Data.xlsx
FONT = Arial, 24, , #000000
TEXT = , [name], 0, 0, 100%, 20%
IMAGE = , [img], 0, 20%, 100%, 40%, 0, P
FONT = Arial, 10, , #000000
TEXT = , [desc], 5%, 65%, 90%, 30%, left, wordwrap
FONT
TEXT
FONT
TEXT
=
=
=
=
Arial, 32,
, [value],
Arial, 32,
, [value],
ICON
ICON
ICON
ICON
=
=
=
=
,
,
,
,
A,
E,
F,
W,
T,
0,
T,
0,
#FFFFFF
20%, 20%, 40%, center, center, 0, 100, 0.1
#FF0000
20%, 20%, 40%
air.png
earth.png
fire.png
water.png
ICONS = , [icons], 80%, 20%, 20%, 40%, 20%, 10%, 0, PN
14
Ranges
Many directives (like IMAGE or TEXT) have a parameter for specifying for which cards will be executed that
directive. A card in a range may be specified directly with a number, a list of cards with a list of numbers separated by a
comma “,” and a range of cards with the first and last cards separated with a dash “-” or the first card and a number,
separated with a number sign “#”.
Examples:
RECTANGLE
RECTANGLE
RECTANGLE
RECTANGLE
=
=
=
=
1, 0, 0, 6, 9, #0000FF
"1,3,5,7", 0, 0, 6, 9, #0000FF
1-10, 0, 0, 6, 9, #0000FF
10#5, 0, 0, 6, 9, #0000FF
Note: in the 2nd line the range must be enclosed in quote for the presence of commas, however, you can always enclose
all ranges in quotes.
You can mix the two methods, and use a complex range, like:
RECTANGLE = "1-10,12,15,19-20,35#3", 0, 0, 6, 9, #0000FF
A number in a range can be the result of an expression (see page 40), and must be enclosed between “{” and “}. For
example:
RECTANGLE = 1-{2*5}, 0, 0, 6, 9, #0000FF
Usually, the order doesn’t matter (1-10 is equal to 10-1) but for one command, COPYCARD, the order is important,
because the source range is uses as specified, these two rows are different:
COPYCARD = 11-20, 1-10
COPYCARD = 11-20, 10-1
The 1st row gives as result this sequence of cards:
1,2,3,4,5,6,7,8,9,10,1,2,3,4,5,6,7,8,9,10
The 2nd row gives as result this sequence of cards:
1,2,3,4,5,6,7,8,9,10,10,9,8,7,6,5,4,3,2,1
There is a syntax that can be used to change that behavior, useful, for example, to invert sub-ranges of cards (for
printing front-back). For example:
COPYCARD = 10-18, 1-9$abc>cba
The first group of characters is the start pattern, the second group is the destination pattern, reversed in groups of three
cards. You can obtain the same result manually writing:
COPYCARD = 10-18, "3-1,6-4,9-7"
This syntax is useful also if you want to specify a “hollow” range, for example, if you want a rectangle only on even
cards:
RECTANGLE = 1-10$ab>a, 1, 1, 4, 4, #FF0000
Note: the $abc>cba syntax works only when the card number is defined using a CARDS command.
See also: Labels and sequences chapter (page 19), AUTORANGE label function (page 25), and BASERANGE
directive (page 67) about the interaction between ranges and sequences.
15
Colors
In this program, the colors will be defined by a string of seven characters, starting with a number sign “#” and six
hexadecimal digits (using the HTML syntax), two for each component (red-green-blue), for example:
White
#FFFFFF
Black
#000000
Red
#FF0000
Green
#00FF00
Blue
#0000FF
Cyan
#00FFFF
Magenta
#FF00FF
Yellow
#FFFF00
Tip: if you use the wizard for a new deck (the “wiz” button, to the right of “New deck” button), you can check the
“Include labels for HTML colors” to obtain a set of 140 label definition for many colors.
Tip: you can choose a color from a color picker, clicking on the button “Insert” and choosing the menu voice “Color”.
If instead of a hexadecimal digit you specify a letter “H”, you obtain a random value from 0 to 15. For example, if you
want a complete random color, with this syntax you can use #HHHHHH, instead for a random hue of blue, you can use
#0000HH, and so on. The letter “L” stands for the last color used, then #LLLLLL is the last color, instead #0000LL is
the last blue component used.
You can concatenate more than one color to obtain a gradient, followed by a “@” to specify the angle. If you use these
special values for the angle, you obtain a special gradient:
360
361
362
363
Radial gradient
Elliptical gradient
Square gradient
Star gradient
These are some examples:
16
From black to white, horizontal
#FFFFFF#000000@0
From red to blue, vertical
#0000FF#FF0000@90
From cyan to magenta, radial
#FF00FF#00FFFF@360
From cyan to magenta, elliptical
#FF00FF#00FFFF@361
From teal to yellow, square
#FFFF00#008080@362
From orange to purple, star
#400080#FFA500@363
From red, to green, to blue, horizontal
#0000FF#00FF00#FF0000@0
If you omit the “@”, the colors are randomized (and smoothed); specifying a "%" and a number, you set a threshold for
the 2nd color, for example:
Blue and red, randomized
#0000FF#FF0000
Blue and red, randomized 50%
#0000FF#FF0000%50
Red and blue, randomized 50%
#FF0000#0000FF%50
Blue, green, and red, randomized
#0000FF#00FF00#FF0000
Specifying a $ and a number, the colors are smoothed that number of times (without specifying it, the color is smoothed
only one time), for example:
Blue and red
#0000FF#FF0000
Blue and red, no smoothing
#0000FF#FF0000$0
Red and blue, two smoothing
#FF0000#0000FF$2
If you add a & and a number in the color, the pattern is created with a Perlin Noise algorithm, with a number of
iteration equal to the numeric parameter, for example:
Blue and red, eight iterations
#0000FF#FF0000&8
Blue and red, six iterations
#0000FF#FF0000&6
Blue and red, three iterations
#0000FF#FF0000&3
If you add a ç in the color, the random pattern is made of stripes (and you can use more ç to make the stripes longer),
for example:
17
Blue and red, randomized
#0000FF#FF0000
Blue and red, striped
#0000FF#FF0000ç
Blue and red, striped x 2
#0000FF#FF0000çç
Tip: you can choose a gradient from a visual form, clicking on the button “Insert” and choosing the menu voice
“Gradient”.
18
Labels and sequences
A label is used as a variable value in a script, and may be initialized and used several times in the code. It can be
initialized with this syntax:
[name] = value
And used specifying its name (always delimited with “[” and “]”). This is an example:
[alpha] = "This is a text"
FONT = Arial, 32, , #000000
TEXT = 1-10, [alpha], 0, 0, 6, 9, center
A sequence is a list of values used as a parameter in a directive. Each value is separated using the character pipe “|”. For
each card in the directive’s range the program uses a different element in a sequence (restarting from the first if the
sequence’ size isn’t enough to fill the range), for example, if you want ten cards, half with the word “odd” and half with
the word “even”, you can use the TEXT directive, with a range 1-10 and a sequence of the two words as text parameter
(“odd|even”).
FONT = Arial, 32, , #000000
TEXT = 1-10, "odd|even", 0, 0, 6, 9, center
Sequences may be very long, you can manipulate them in a clearer manner if you use them in labels. Usually a
sequence must be on a single line, but you can split a long sequence into multiple lines, starting the first line with a “{”
and ending the last line with a “}”. For example:
{[long] = "one|
two|
three|
four|
five|
six|
seven|
eight|
nine|
ten"}
FONT = Arial, 32, , #000000
TEXT = 1-10, [long], 0, 0, 6, 9, center
Tip: The split-line syntax with “{” and “}” can be used not only for sequences, but with every command.
If the label contains a sequence (like in the above example), you can obtain the number of elements contained using the
syntax “(name)”. It can be used directly as a parameter or in an expression. For example:
[alpha] = one|two|three
FONT = Arial, 32, , #000000
TEXT = 1-{(alpha)*2}, [alpha], 0, 0, 6, 9, center
The result deck will be composed of six cards, with the word sequence one-two-three-one-two-three.
When you define a label, there are some characters you can use as prefix or postfix for the [name] to obtain special
behavior.
[name]number = value
The resulting value is the original value repeated number times. Instead, with these letters as a prefix, you can use this
program as a combinatorial engine:
C
P
E
combination
permutation
derangement (permutation with no element in its original position)
19
F
B
CR
PR
ER
Tn
circular shift (right)
circular shift (left)
combination with repetitions
permutation with repetitions
derangement with repetitions
extracts only a random sample of n elements instead of the full set
C[name]number
P[name]number
E[name]number
F[name]number
B[name]number
=
=
=
=
=
object1|object2…objectN
object1|object2…objectN
object1|object2…objectN
object1|object2…objectN
object1|object2…objectN
These syntaxes create two labels with a combination and a permutation of number objects from the sequences, for
example:
C[label1]2
P[label2]2
E[label3]2
F[label4]2
B[label5]2
=
=
=
=
=
A|B|C
A|B|C
A|B|C
A|B|C
A|B|C
these labels will be translated into:
[label1]
[label2]
[label3]
[label4]
[label5]
=
=
=
=
=
AB|AC|BC
AB|AC|BA|BC|CA|CB
BA|BC|CA
AB|BC|CA
AB|CA|BC
With repetitions:
CR[label1]2 = A|B|C
PR[label2]2 = A|B|C
ER[label3]2 = A|B|C
the result will be:
[label1] = AA|AB|AC|BB|BC|CC
[label2] = AA|AB|AC|BA|BB|BC|CA|CB|CC
[label3] = BA|BC|CA|CC
A sample of three elements:
CRT3[label1]2 = A|B|C
one of the possible result could be:
[label1] = BC|AA|CC
Special flags:
D
X
S
N
A
Z
I
O
remove duplicate elements
remove “rotated” elements
remove elements with the same “structure”
randomize elements
sort elements in ascending order
sort elements in descending order
keep only crossing paths
keep only paths that doesn’t cross themselves
The “D” flag is useful when you have multiple elements in combinations/repetitions, for example:
20
C[label1]2 = A|B|C|C
will be evaluated as:
[label1] = AB|AC|AC|BC|BC|CC
If you don’t want repetitions, you can add the “D” flag (as a prefix) and the result will be:
[label1] = AB|AC|BC|CC
The “X” flag need a longer explanation. Let’s say, you need to create tiles with 4 quadrants, with all the combination of
three elements (plains, woods and mountains), this is the starting script:
CARDSIZE =
[QUARTER1]
[QUARTER2]
[QUARTER3]
[QUARTER4]
4, 4
= 0,
= 0,
= 4,
= 0,
0,
0,
0,
4,
2,
4,
4,
2,
2,
0,
4,
2,
0,
2,
2,
4,
4
2
2
4
PR[SCHEMA]4 = P|F|M
[ALL] = 1-{(SCHEMA)}
[COLOR_P] = #00FF00
[COLOR_F] = #008000
[COLOR_M] = #C0C0C0
TRIANGLE
TRIANGLE
TRIANGLE
TRIANGLE
=
=
=
=
[ALL],
[ALL],
[ALL],
[ALL],
[QUARTER1],
[QUARTER2],
[QUARTER3],
[QUARTER4],
[COLOR_[SCHEMA:1,1]]
[COLOR_[SCHEMA:2,1]]
[COLOR_[SCHEMA:3,1]]
[COLOR_[SCHEMA:4,1]]
This is the result (4 pages of 81 tiles):
The tiles are all different, but not if you rotate them, for example, PFPF is equal to FPFP (rotated 90°). To eliminate
them, you can use the “X” prefix. This is the result (1 page of 24 tiles):
The “X” flag can be used more than once, to specify that not all the “rotations” will be considered as equals; for
example, with only one “X”, the sequence 0102 is equal to:
1020
0201
21
2010
In a square token with a number on each side, this is equal to 90° rotations. Instead, with “XX”, the sequence 0102 is
equal only to 0201 (in a square token, this is equal to considering only rotations of 180°, or rather, that rotations of 90°
aren’t considered).
The “S” flag remove elements with the same structure: for example, the sequence 0102 has the same structure of the
sequence 1210. In the previous example, from the 24 tiles, only six have a different structure:
The “N” flag will be used if you want to randomize the sequence, if you write, for example:
N[elements] = alpha|beta|gamma|delta
it will be randomly evaluated each time you validate the deck, for example as:
[elements] = beta|gamma|delta|alpha
If you want to analyze only a sub-string from the result of the permutation/combination engine or an external linked
file, you can use the “:” syntax to extract a sub-string, the syntax is [label:start,number] where start is the starting
character and number is the length of the sub-string in characters. For example, in the script about tiles in the previous
page, every line extracts only a character from the label (composed of four characters), and associates it with another
label:
TRIANGLE
TRIANGLE
TRIANGLE
TRIANGLE
=
=
=
=
[ALL],
[ALL],
[ALL],
[ALL],
[QUARTER1],
[QUARTER2],
[QUARTER3],
[QUARTER4],
[COLOR_[SCHEMA:1,1]]
[COLOR_[SCHEMA:2,1]]
[COLOR_[SCHEMA:3,1]]
[COLOR_[SCHEMA:4,1]]
If the label [SCHEMA] was, as an example, “PFPM”, these lines will be evaluated as:
TRIANGLE
TRIANGLE
TRIANGLE
TRIANGLE
=
=
=
=
[ALL],
[ALL],
[ALL],
[ALL],
[QUARTER1],
[QUARTER2],
[QUARTER3],
[QUARTER4],
[COLOR_P]
[COLOR_F]
[COLOR_P]
[COLOR_M]
Tip: you can view a list of labels, their contents, and choose one of them from a list, clicking on the button “Insert” and
choosing the menu voice “Label”.
You can extract a single element in a sequence using the ? operator in an expression (delimited with curly brackets {
and }). If you omit the number, it’s used the current card (i.e. is the same to use ? or ?§).
For example, this script will print the letter “c”:
[ALPHA] = a|b|c|d|e
FONT = ARIAL, 32, , #000000
TEXT = 1, {ALPHA?3}, 0, 0, 100%, 100%
There is also a syntax for creating labels with a condition and with a for…next cycle (note that you can’t define a label
between standard IF…ENDIF or FOR…NEXT blocks):
[label]%[condition], variable, start, end, step = value
The [condition] parameter must be a label, it cannot be written directly because a condition is too complex to be
evaluated correctly in a single line. This is an example:
[check1]=[a]=1
[check2]=[a]<>1
[color]%[check1]=#FF0000
22
[color]%[check2]=#0000FF
In this example, if [a] is 1, the label [color] is red (#FF0000), if [a] isn’t 1, the label [color] is blue (#0000FF).
The condition can be omitted, in this case the label is defined only if it doesn’t already exist. In this example, the label
[alpha] is red, and the label [beta] is blue:
[alpha]=#FF0000
[alpha]%=#0000FF
[beta]%=#0000FF
The label creation can be repeated in a for…next cycle, for example, if you want to define ten labels, with powers of
two, you can write:
[lab(count)]%,(count),1,9 = {(count)^2}
Note that the condition parameter is empty (the comma after the % symbol), and that if the step parameter is omitted,
its value is assumed equal to one. The variable (count) can be anything (the parentheses aren’t really needed). The result
is equal to write this code:
[lab1]=1
[lab2]=4
[lab3]=9
[lab4]=16
[lab5]=25
[lab6]=36
[lab7]=49
[lab8]=64
[lab9]=81
An alternate syntax for the definitions of labels in a loop is this:
[label]%[condition], variable, [sequence] = value
In this syntax, a step in the loop is executed for each value of the sequence (value that is replaced in the variable), for
example:
[seq] = alpha|beta|gamma
[lab_(var)]%, (var), [seq] = test_(var)
The result is equal to this code:
[lab_alpha]=test_alpha
[lab_beta]=test_beta
[lab_gamma]=test_gamma
Note that the interaction between ranges and sequences is based on the extraction of the Nth element from a sequence
when is rendered the Nth card in the range, i.e. if you have a range that doesn't starts with the 1 st card of the deck, the
elements from the sequence are apparently extracted wrongly. Example:
[ALPHA] = a|b|c|d|e
FONT = ARIAL, 32, , #000000
TEXT = 3-5, [ALPHA], 0, 0, 100%, 100%
In the 3rd card (the 1st of the range) shows the letter a (the 1st of the sequence). If you instead want to show the letter c
you must add a BASERANGE directive:
BASERANGE = 1-5, ON
[ALPHA] = a|b|c|d|e
FONT = ARIAL, 32, , #000000
TEXT = 3-5, [ALPHA], 0, 0, 100%, 100%
23
With the BASERANGE directive (see page 67), nanDECK uses the position of the Nth card from all the deck (and not
from the range) to evaluate what element to extract from the sequence, and therefore in the 3rd card it goes the 3rd
element (i.e. the letter c).
24
Label functions
AUTOLABEL
This function creates a label containing a sequence of numbers. This is the syntax:
[name] = AUTOLABEL(start, end, step, separator, padding)
For example, this line:
[a] = AUTOLABEL(1, 10, 2)
will be evaluated as:
[a] = 1|3|5|7|9|11
The standard separator is the pipe (the “|” character), if you want a different separator, you can specify it as the 4 th
parameter. If you specify a number in the 5th parameter, the result number is padded to the left with zeroes until the
length of the number reach that parameter.
AUTORANGE
This function calculates a range starting from the previous AUTORANGE (or card 1, if it was the first), the only
parameter is a number of cards. This is the syntax:
[name] = AUTORANGE(number)
For example, these rows:
[a] = AUTORANGE(10)
[b] = AUTORANGE(5)
[c] = AUTORANGE(8)
will be evaluated as:
[a] = 1-10
[b] = 11-15
[c] = 16-23
You can reset the counter, using a negative number as parameter. For example, these rows:
[a] = AUTORANGE(10)
[b] = AUTORANGE(-5)
[c] = AUTORANGE(8)
will be evaluated as:
[a] = 1-10
[b] = 1-5
[c] = 6-13
CASESTRING
This function modifies the capitalization of a string, this is the syntax:
[label] = CASESTRING(string, flag)
You can choose one of these flags:
U
the string changes to uppercase
25
L
F
the string changes to lowercase
every first character in a string is changed to uppercase, the others to lowercase
If the flag is not specified, the string is changed to uppercase.
CONCAT
This function creates a label concatenating different strings, this is the syntax:
[name] = CONCAT(parameter1, repeat1, parameter2, repeat2, …parameterN, repeatN)
Each parameter is repeated a number of times equal to the next parameter. This is an example:
[test] = CONCAT(#000000, 3, #FFFFFF, 2)
Will be evaluated as:
[test] = #000000#000000#000000#FFFFFF#FFFFFF
CONCAT1
This function is equivalent to CONCAT, with a repetition of each parameter of one, this is the syntax:
[name] = CONCAT(parameter1, parameter2, …parameterN)
COOFRAME
This function outputs the four coordinates of a frame (see page 36); instead of using the standard syntax, that
is evaluated in the Validate step, this function is evaluated later, in the Build step. This is the syntax:
[name] = COOFRAME(frame)
COOFRAMES
This function is similar to COOFRAME, and is used when there are more than one frame that can be selected. The 1 st
parameter is the number of the frame, selected from all that have the name specified in the 2 nd parameter (you can use
also wildcard characters like * and ?):
[name] = COOFRAMES(number, frame)
DIRFILES
This function creates a sequence label using names of files from a folder (and subfolders), this is the syntax:
[name] = DIRFILES(path, extension)
The extension can be a sequence of extensions, like jpg|bmp|gif.
This is an example:
[img] = DIRFILES("c:\images\", jpg)
and it will be evaluated as:
[img] = "c:\images\one.jpg|c:\images\two.jpg|c:\images\three.jpg"
Instead of an extension, you can specify in the 2nd parameter a file mask (with * and ? as wildcards). For example:
[img] = DIRFILES("c:\images\", "img*.jpg")
26
You can also combine the two parameters in one. For example:
[img] = DIRFILES("c:\images\img*.jpg")
ENVIRONMENT
This function reads an environment variable from the operating system, this is the syntax:
[name] = ENVIRONMENT(variable)
For example, this reads the path for the user folder:
[folder] = ENVIRONMENT(userprofile)
EVAL
This function creates a sequence with the results of the evaluation of another sequence, this is the syntax:
[name] = EVAL(sequence)
This is an example:
[alpha] = {1+1}|{2*3}|{3^3}
[beta] = EVAL([alpha])
These two lines are equivalent to:
[beta] = 2|6|27
Note: you obtain the same result with a single line:
[beta] = EVAL({1+1}|{2*3}|{3^3})
EXPAND
This function creates a sequence replicating itself numseq times, with each element replicated numele times (this
parameter is option, if not specified is treated equal to one):
[name] = EXPAND(sequence, numseq, numele)
This is an example:
[alpha] = a|b|c
[beta] = EXPAND([alpha], 2, 3)
These two lines are equivalent to:
[beta] = a|a|a|b|b|b|c|c|c|a|a|a|b|b|b|c|c|c
FILTER
This function creates a sequence taking elements from another sequence, filtering and grouping them using some rules.
The basic syntax is:
[name] = FILTER([name], filter1, filter2 …filterN)
In the filterN parameters you can use wildcards: ? for any character, * for any characters, and use ranges of characters
within parenthesis (as an example, 1(0-9) matches a number from 10 to 19). For example, this script will print only
elements that start with a zero (four elements on eight):
27
[ALPHA] = 000|001|010|011|100|101|110|111
[BETA] = FILTER([ALPHA], 0*)
FONT = ARIAL, 32, , #000000
TEXT = 1-{(BETA)}, [BETA], 0, 0, 100%, 100%
In the 1st parameter you can specify these additional flags:
§
>
<
+
@
#
$
^
~
=
£
°
%
!
&
¬
_
ç
.
the sorted/added elements are used to create the new sequence
(multiple, header) sort characters from an element in ascending order before comparing it to the filters
(multiple, header) sort characters from an element in descending order before comparing it to the filters
(multiple, header) add numbers from an element before comparing it to the filters
keep only the characters specified after this flag
discard all the characters specified after this flag
(multiple, header) counts the maximum occurrences of a character(s) in the same element
(multiple, header) counts the maximum occurrences of specific character(s) in all positions on the previous
accepted elements
(header) counts all the occurrences of specific character(s) in all positions on the previous accepted elements
(multiple, header) counts the maximum occurrences of specific character(s) in the same position on the
previous accepted elements
(header) counts the maximum occurrence of a straight of characters
set the rule for evaluating a straight (if not specified, is used the ASCII sequence of letters/numbers)
(multiple) replace a character(s) with another(s), all the couples are specified after this flag
counts the distance (in characters) between two copies of the same characters, specified after this flag
(header) the element is evaluated from his position within the sequence, starting from one
the condition (for including or not an element) is reversed (for inserting the symbol, type ALT + 0172)
if an element is not included, a null string is added in its position
the result isn’t padded with zeroes to the length of the longest element
(multiple, header) the starting characters in each element are permutated
You can combine multiple flags, and use a space if you want to mix two similar functions, for example, a $ followed by
$$ can be coded as “$ $$”. The flags marked with header must be specified before the sequence, not after.
For example, this script will print only elements that contains a zero and two ones (three elements on eight):
[ALPHA] = 000|001|010|011|100|101|110|111
[BETA] = FILTER(>[ALPHA], 011)
FONT = ARIAL, 32, , #000000
TEXT = "1-{(BETA)}", [BETA], 0, 0, 100%, 100%
The flags marked with (multiple) in the above list (i.e.: > < + $ ^ = % .) can be repeated, when you must consider
elements not as single characters, but as strings composed with more than one character. For example, the element
“0123” gives these results:
+
++
>
>>
<
<<
6
24
0123
0123
3210
2301
This is as example for utilization of “$” flag. First, a label is created with all the permutations (with repetitions) of four
elements from a set of five (a, b, c, d, and e), then, another label is created filtering only the occurrence of a three-of-akind and four-of-a-kind:
pr[a]4 = a|b|c|d|e
[b] = FILTER($[a], 3, 4)
FONT = ARIAL, 64, , #000000
TEXT = 1-{(b)}, [b], 0, 0, 100%, 100%
In this example, the same sequence is filtered to get only the labels that contains one or less repetitions of the same
character in the same position:
28
pr[a]4 = a|b|c|d|e
[b] = FILTER(=[a], 0, 1)
FONT = ARIAL, 64, , #000000
TEXT = 1-{(b)}, [b], 0, 0, 100%, 100%
In this example of the replacement option (with the % option), the characters “a”, “d”, and “g” are replaced with the
numbers “1”, “2”, and “3”:
[test_a] = abc|def|ghi
[test_b] = FILTER(§[test_a]%a1d2g3)
The result sequence [test_b] is equal to:
1bc|2ef|3hi
Usually the strings found and replaced with the % option are the same length, but you can specify a null character using
a ¢ symbol (for inserting it, type ALT + 0162). Example:
[test_a] = abc|def|ghi
[test_b] = FILTER(§ç[test_a]%%abx¢de¢¢)
Note the ç symbol added to disable the padding; the result sequence [test_b] is equal to:
xc|f|ghi
You can create a sequence of parameters with a “FOR=” keyword, for example, if you want ten numbers, instead of
adding all of them you can use a single parameter like “1-10FOR=-” (the 2nd minus symbol is the position of the counter
in the result.
Instead of a parameter used as a filter, you can specify a “mask” (with the prefix “MASK=”), that is used to apply the
filter only to some characters of the elements from the sequence; you specify a character that you want to consider with
a “1”, and a character to ignore with a “0”. For example, if you want to apply the rules only to the even characters of a
ten-character string, use this parameter: MASK=0101010101
If there are more than one rule in the 1st parameter, and if you specify a number before the mask keyword, that mask is
applied only to a single rule (1 for the 1 st rule, 2 for the 2nd, and so on).
GRADIENTSEQ
This function creates a sequence of gradients, splitting one into several sections, the syntax is:
[name] = GRADIENTSEQ(gradient, number, element)
For example, with this line the program creates a sequence of three gradients:
[gradient] = GRADIENTSEQ(#000000#FF0000@0, 3)
If you don’t specify the 3rd parameter, the sequence contains number element; instead it contains only the Nth
parameter, where N is the 3rd parameter.
GROUP
This function takes all the elements in a sequence and removes all the duplicate elements, optionally, it can return a
count of all the elements adding the keyword COUNT in the 2nd parameter. The syntax is
[name] = GROUP(sequence, function)
For example:
[alpha] = a|b|a|e|c|c|c|a|b|f|d|e
[beta] = GROUP([alpha])
29
[gamma] = GROUP([alpha], COUNT)
The two resulting sequences contain these values:
[beta] = a|b|c|d|e|f
[gamma] = 3|2|3|1|2|1
JOIN
This function uses alternatively the elements from two (or more) sequences for building a new sequence, the syntax is:
[name] = JOIN(sequence1, sequence2, …sequenceN)
The length of the new sequence is equal to the longest source sequence. This is an example:
[label1] = A|B
[label2] = 1|2|3|4
[label3] = JOIN([label1], [label2])
The 3rd label will be evaluated as:
[label3] = A1|B2|A3|B4
JOINIF
This function add elements to a sequence using a condition to choose from two other sequences, the syntax is:
[name] = JOINIF(sequence, value1, condition, value2, sequence true, sequence
false)
Every parameter can be a single value or a sequence. The condition can be one of this symbol:
=
<>
>
<
>=
<=
@
#
equal
different
major
minor
major or equal
minor or equal
contained
not contained
This is an example:
[label] = JOINIF(A|B|C, 1|2|3, <=, 2, D|E|F, X)
The label will be evaluated as:
[label] = AD|BE|CX
LABELRANGE
This function creates a range, using elements from a sequence. The syntax for this function is:
[name] = LABELRANGE(sequence, value, offset)
If you specify the optional value parameter, the range is created with only the cards matching the value parameter
position (wildcards * and ? are accepted). If you don’t specify the value parameter, the default element from a sequence
is considered “1”. The offset parameter, if specified, will be added to every card of the range.
30
For example:
[sequence] = 0|1|1|0|0|1
[label] = LABELRANGE([sequence])
Result:
[label] = "2,3,6"
The item parameter can also accept these operators (in the format operatorvalue):
=
<>
>
<
>=
<=
@
#
the item’s position from the sequence is included if it’s equal to the value (this operator can be omitted)
the item’s position from the sequence is included if it’s different from the value
the item’s position from the sequence is included if it’s greater than the value
the item’s position from the sequence is included if it’s smaller than the value
the item’s position from the sequence is included if it’s greater or equal to the value
the item’s position from the sequence is included if it’s smaller or equal to the value
the item’s position from the sequence is included if the value is contained in it
the item’s position from the sequence is included if the value isn’t contained in it
For example:
[sequence] = 1|2|3|4|5|6|7|8|9|10
[label] = LABELRANGE([sequence], >=5)
Result:
[label] = "5,6,7,8,9,10"
LABELSTRING
This function creates a string with elements taken from a sequence. The syntax for this function is:
[name] = LABELSTRING(sequence, number)
Without the optional number parameter, the result is a single string, taken from concatenating every element of the
sequence. If you specify a number as 2nd parameter, for every nth element a new element of the sequence is created. For
example:
[sequence] = A|B|C|D|E|F
[label] = LABELSTRING([sequence])
These two lines are equivalent to:
[label] = ABCDEF
Another example:
[sequence] = A|B|C|D|E|F
[label] = LABELSTRING([sequence], 2)
Result:
[label] = AB|CD|EF
LABELSUB
This function extracts a sequence from another, taken only the elements in a range, the syntax is:
[name] = LABELSUB(sequence, "range")
31
For example:
[sequence] = LABELSUB(alpha|beta|gamma|delta, "1,3-4")
Result:
[sequence] = alpha|gamma|delta
LENGTH
This function creates a new sequence with the lengths of the elements of the sequence in the 1 st (and only) parameter,
the syntax is:
[name] = LENGTH(sequence)
For example:
[sequence] = ABC|DE|F|GH|IJK|LMNO
[label] = LENGTH([sequence])
Result:
[label] = 3|2|1|2|3|4
PRODUCT
This function combines two (or more) sequences, in the result every element of the first sequence is combined with
every element of the second sequence (and so on), the syntax is:
[name] = PRODUCT(sequence1, sequence2, …sequenceN)
The length of the new sequence is equal to the product of the length of all source sequences. This is an example:
[label1] = A|B
[label2] = 1|2|3|4
[label3] = PRODUCT([label1], [label2])
The 3rd label will be evaluated as:
[label3] = A1|A2|A3|A4|B1|B2|B3|B4
RANGEADD
This function combines several ranges in one, the syntax is:
[range] = RANGEADD("range1", "range2", …"rangeN")
For example:
[range1] = "1-3"
[range2] = "2-4"
[range3] = "8-10"
[range] = RANGEADD([range1],[range2],[range3])
Result:
[range] = "1-4,8-10"
32
RANGECOUNT
This function returns the number of cards in a range, the syntax is:
[number] = RANGECOUNT("range")
For example:
[number] = RANGECOUNT("1,4-6,10-15")
Result:
[number] = 10
RANGEMUL
This function creates a new range from pairs of range/number of repetition of that range:
[range] = RANGEMUL("range1", num1, "range2", num2, …"rangeN", numN)
For example:
[range] = RANGEMUL(1,2,3,4)
Result:
[range] = "1,1,3,3,3,3"
RANGEREM
This function extracts a sub-range from another range, this is the syntax:
[range] = RANGEREM("range1", "range2", …"rangeN")
This directive removes the ranges range2, ... rangeN from range1.
For example:
[range1] = "1-10"
[range2] = "3,4"
[range3] = "7-9"
[range] = RANGEREM([range1], [range2], [range3])
Result:
[range] = "1-2,5-6,10"
RANGESUB
This function extracts a sub-range from another range, this is the syntax:
[range] = RANGESUB("range", start, number)
The sub-range starts from the element specified by the start parameter, and is composed of number elements. If the
number parameter is missing (or equal to zero) the sub-range goes to the end of the initial range; if the start parameter is
equal to zero, the sub-range starts from the last element taken with another RANGESUB function (or from the start of
the initial range), in a behavior like that implemented with AUTORANGE function.
For example:
33
[range1] = "1-10"
[range] = RANGESUB([range1], 3, 4)
Result:
[range] = "3-6"
REPLACE
This function replaces in a string (or a sequence) all instances of a substring with another. The syntax for this function
is:
[name] = REPLACE("string", "from", "to")
ROUND
This function returns the 1st parameter rounded, the 2nd parameter specify the number of decimal digits (if not specified,
it is zero, if it’s a negative number, the rounding is by power of tens), the 3 rd parameter is a keyword that specify if the
rounding is UP, or DOWN (if you don't specify it, the rounding is down when the rounded digit is 4 or less, and up if
it's 5 or more). The syntax is:
[name] = ROUND(value, precision, keyword)
SAVELABEL
This function saves the content of a label (or more than one label) into a CSV text file or a spreadsheet file (if the
extension of the filename is .xls or .xlsx). The syntax for this function is:
[name] = SAVELABEL("filename", label1 , label2, …labelN)
The result label [name] contains the filename. Note: do not use the [ ] in the label parameters.
STRINGLABEL
This function creates a sequence label with elements taken from a string. The syntax for this function is:
[name] = STRINGLABEL("string", length)
The optional length parameter sets the number of characters taken for each element of the sequence. If omitted, the
length is one character. For example, these two lines are equivalent:
[label] = STRINGLABEL("This is a test")
[label] = "T|h|i|s| |i|s| |a| |t|e|s|t"
TOKENIZE
This function extracts a substring from a string, using a separator that slices the string into several tokens, and a number
that specify the single token extracted. The syntax for this function is:
[name] = TOKENIZE("string", number, separator)
If the separator is not specified, is assumed to be equal to “|” (pipe), note that is the same separator for the elements in a
sequence. For example:
[result] = TOKENIZE("Alpha-Beta-Gamma", 2, -)
The [result] label would be equal to “Beta”
34
TOKENIZESEQ
This function extracts a sequence from another sequence, using a separator that slices each element of that sequence
into several tokens, and a number that specify which tokens are extracted; all the tokens are concatenated in the result
sequence. The syntax for this function is:
[name] = TOKENIZE("string", number, separator)
For example:
[result] = TOKENIZE("Alpha-Beta-Gamma|Delta-Epsilon-Zeta|Eta-Theta-Iota", 2, -)
The [result] label would be equal to “Beta|Epsilon|Theta”
TRANSLATE
This function replaces in a sequence (specified in the 1 st parameter) all the elements found in another sequence
(specified in the 2nd parameter) with elements taken from another sequence (specified in the 3 rd parameter). The syntax
is:
[label] = TRANSLATE(sequence, sequence key, sequence value)
For example, this script:
[test] = x|y|x|w|x|y|y|z
[from] = x|y|z
[to] = a|b|c
[result] = TRANSLATE([test],[from],[to])
Gives this sequence as a result:
[result] = a|b|a||a|b|b|c
35
Frames
A frame is a special label, used when you need to identify a rectangular area used for placing a graphical content. A
frame is defined used this syntax:
= position x, position y, width, height
And can be used for example with a RECTANGLE directive:
RECTANGLE = 1, , #000000
This is a behavior that can be done also with a label, but in a frame, you can add an alignment and a specific size, with
this syntax:
The “alignment” can be a flag from this list:
TL
TC
TR
CL
CC
CR
BL
BC
BR
top-left
top-center
top-right
center-left
center-center
center-right
bottom-left
bottom-center
bottom-right
An example with all these nine alignments:
= 1, 1, 4, 7
FONT = Arial, 16, , #FFFFFF, #0000FF
RECTANGLE = 1, , #CCCCFF
TEXT = 1, "TL", , CENTER,
TEXT = 1, "TC", , CENTER,
TEXT = 1, "TR", , CENTER,
TEXT = 1, "CL", , CENTER,
TEXT = 1, "CC", , CENTER,
TEXT = 1, "CR", , CENTER,
TEXT = 1, "BL", , CENTER,
TEXT = 1, "BC", , CENTER,
TEXT = 1, "BR", , CENTER,
CENTER
CENTER
CENTER
CENTER
CENTER
CENTER
CENTER
CENTER
CENTER
Image 1
Result: Image 1
One between width and height can be expanded to the full extent of frame’s width or height, using this syntax and one
of these alignments for width:
TW
CW
BW
top aligned, full width
center aligned, full width
bottom aligned, full width
Example:
= 1, 1, 4, 7
FONT = Arial, 16, , #FFFFFF, #0000FF
RECTANGLE = 1, , #CCCCFF
TEXT = 1, "TW", , CENTER, CENTER
TEXT = 1, "CW", , CENTER, CENTER
TEXT = 1, "BW", , CENTER, CENTER
Result: Image 2
36
Image 2
This syntax and these alignments are used for a full height:
HL
HC
HR
full height, left aligned
full height, center aligned
full height, right aligned
= 1, 1, 4, 7
FONT = Arial, 16, , #FFFFFF, #0000FF
RECTANGLE = 1, , #CCCCFF
TEXT = 1, "HL", , CENTER, CENTER
TEXT = 1, "HC", , CENTER, CENTER
TEXT = 1, "HR", , CENTER, CENTER
Image 3
Result: Image 3
Another type of syntax can be used to extract only a position (useful with lines):
PTL
PTC
PTR
PCL
PCC
PCR
top-left
top-center
top-right
center-left
center-center
center-right
PBL
PBC
PBR
bottom-left
bottom-center
bottom-right
=
RECTANGLE
LINE = 1,
LINE = 1,
Image 4
1, 1, 4, 7
= 1, , #CCCCFF
, , #FF0000, 0.2
, , #FF0000, 0.2
Result: Image 4
Instead of using two frames, you can also combine two alignment of this type in a single frame, for example, with this
script the result is the same of the Image 4:
=
RECTANGLE
LINE = 1,
LINE = 1,
1, 1, 4, 7
= 1, , #CCCCFF
, #FF0000, 0.2
, #FF0000, 0.2
Instead of using a size (width or height) in cm, you can use a fraction of the whole frame size, using a
number followed by “%%” (instead, a single “%” gives you a size equal to a fraction of the whole
card). For example:
= 1, 1, 4, 7
FONT = Arial, 16, , #FFFFFF, #0000FF
RECTANGLE = 1, , #CCCCFF
TEXT = 1, "TL", , CENTER, CENTER
Result: Image 5
Image 5
Tip: you can view a list of frames, their contents, and choose one of them from a list, clicking on the button “Insert”
and choosing the menu voice “Frame”.
With these syntaxes, you can align a sub-frame starting from the last sub-frame, in the four directions:
TS
BS
top aligned, full width
bottom aligned, full width
37
SL
SR
left aligned, full height
right aligned, full height
= 1, 1, 4, 7
FONT = Arial, 16, , #FFFFFF, #0000FF
TEXT = 1, TS1, , CENTER,
FONT = Arial, 16, , #FFFFFF, #00FF00
TEXT = 1, TS2, , CENTER,
FONT = Arial, 16, , #FFFFFF, #FF0000
TEXT = 1, TS3, , CENTER,
FONT = Arial, 16, , #000000, #FFFF00
TEXT = 1, TS4, , CENTER,
CENTER
CENTER
CENTER
CENTER
Result: Image 6
In this example, the first frame can also be referenced with TW, and the result didn’t change.
If you specify a zero as the width/height of the element, it fills all the available space (the 4th frame
in this example).
Image 6
With these flags, the program extracts three coordinates from the four of a frame, useful when using the TRIANGLE
directive (see page 160), for a shape that fills half of the frame:
HTL
HTR
HBL
HBR
top left, top right, and bottom left
top left, top right, and bottom right
top left, bottom left, and bottom right
top right, bottom left, and bottom right
For example:
= 1, 1, 4, 7
RECTANGLE = 1, , #CCCCFF
TRIANGLE = 1, , #FF0000
Image 7
Result: Image 7
These flags give also three coordinates:
TTL
TTC
TTL
TCL
TCR
TBL
TBC
TBR
an arrowhead with the point to the top-left corner of the frame
an arrowhead with the point to the center of the top side of the frame
an arrowhead with the point to the top-right corner of the frame
an arrowhead with the point to the center of the left side of the frame
an arrowhead with the point to the center of the right side of the frame
an arrowhead with the point to the bottom-left corner of the frame
an arrowhead with the point to the center of the bottom side of the frame
an arrowhead with the point to the bottom-right corner of the frame
For example:
Image 8
= 1, 1, 4, 7
RECTANGLE = 1, , #CCCCFF
TRIANGLE = 1, , #FF0000
Result: Image 8
38
With several functions, you can create groups of frames, and referencing them with wildcards (the list is after this
chapter):
*
?
~
!
/
°
µ
a group of any characters,
any one character,
a random frame from a group,
the first frame from a group, the frame is then deleted from the frame group (instead of the first frame, a
random frame is selected if used with the “~” symbol),
normally, the frames created with a function are added to the existing ones; with this
character in the frames’ name, the definition rewrites the previous frames (the name is
considered without “/”),
this is not a wildcard used in a frame name, but instead is used when the frame number is
needed in a standard expression (with “{” and “}” delimiters),
this is not a wildcard used in a frame name, but instead is used when the frame name is
needed in a text (without “{” and “}” delimiters).
Finally, in a frame name with ! or ~ wildcards, you can specify more than one frame adding a
number before the symbol. For example, if you want three random green box from a grid, three
blue and three red you can write:
Image 9
[base] = FRAMEBOX(0, 0, 6, 9, 1, 1, E)
RECTANGLE = 1, <3!~base*>, #00FF00
RECTANGLE = 1, <3!~base*>, #0000FF
RECTANGLE = 1, <3!~base*>, #FF0000
GRID = 1, 0, 0, 6, 9, #000000, 0.1, 6, 9
Result: Image 9
Note: without the “!” symbol, the randomized frames may overlay themselves. Instead, without
the “~” symbol, the frames are extracted from the start of the group. For example, with this script:
[base] = FRAMEBOX(0, 0, 6, 9, 1, 1, E)
RECTANGLE = 1, <3!base*>, #00FF00
RECTANGLE = 1, <3!base*>, #0000FF
RECTANGLE = 1, <3!base*>, #FF0000
GRID = 1, 0, 0, 6, 9, #000000, 0.1, 6, 9
Result: Image 10
Image 10
39
Frame functions
FRAMEBAR
This function creates a list of frames (see page 36) arranged in a line. The syntax for this function is:
[name] = FRAMEBAR(pos x1, pos y1, pos x2, pos y2, frame width, frame height,
number, zoom)
The frames are created with a name composed from the [name] and a number, the number goes from “1” to the 7 th
parameter.
Example:
[bar] = FRAMEBAR(0, 0, 6, 6, 1, 1, 5)
You can use frames with wildcards (? for any one character, * for a group of any characters), can use the tilde (~)
symbol as a flag for addressing a random frame, the exclamation mark (!) as a flag for deleting the frame after use, and
referencing the current frame’s number with the degree (°) symbol (in an expression) or the current frame’s name with
the micro (µ) symbol (in a text).
The zoom optional parameter is used if you want to resize the frame of a percent (100 is equal to no change).
FRAMEBEZIER
This function creates a list of frames (see page 36) arranged in a Bezier curve. The syntax for this function is:
[name] = FRAMEBEZIER(pos x1, pos y1, handle x1, handle y1, handle x2, handle y2,
pos x2, pos y2, frame width, frame height, number, zoom)
The frames are created with a name composed from the [name] and a number, the number goes from “1” to the 11 th
parameter.
Example:
[bezier] = FRAMEBEZIER(0, 0, 3, 0, 3, 6, 6, 6, 1, 1, 10)
You can use frames with wildcards (? for any one character, * for a group of any characters), can use the tilde (~)
symbol as a flag for addressing a random frame, the exclamation mark (!) as a flag for deleting the frame after use, and
referencing the current frame’s number with the degree (°) symbol (in an expression) or the current frame’s name with
the micro (µ) symbol (in a text).
The zoom optional parameter is used if you want to resize the frame of a percent (100 is equal to no change).
FRAMEBOX
This function creates a list of frames (see page 36), based on a rectangular grid. The syntax for this function is:
[name] = FRAMEBOX(pos x, pos y, width, height, frame width, frame height, flags,
zoom x, zoom y)
The last parameters (zoom x and zoom y) are optional, if not specified are equal to 100 (no zoom); if you want half
sized frames, you can specify 50, if you want double sized frames, the value is 200, and so on. The zoom can be
different between horizontal and vertical values.
The frames are created with a name composed from the [name] and the flag in the 7th parameter. You can use these
flags:
L
N
P
C
E
letters
numbers
zero-padded numbers
coordinates
coordinates with letters and numbers
40
R
.
_
W
B
coordinates with letters and numbers (numbers are reversed)
dot separator for C flag
minus separator for C flag
underscore separator for C flag
add only “white” squares in a chessboard
add only “black” squares in a chessboard
With these flags, coordinates are added to each frame name:
L
N
P
C
E
C.
CC_
A, B, C, D…
1, 2, 3, 4…
01, 02, 03, 04…
0101,0102,0103…0201,0202,0203…
A1,A2,A3…B1,B2,B3…
1.1,1.2,1.3…2.1,2.2,2.3…
1-1,1-2,1-3…2-1,2-2,2-3…
1_1,1_2,1_3…2_1,2_2,2_3…
If you didn’t specify any flag, the frames are created with the same name.
Example:
[box] = FRAMEBOX(0, 0, 4, 3, 1, 1, C_)
The resulting frames will be:
=
=
=
=
=
=
=
=
=
=
=
=
0,
0,
0,
1,
1,
1,
2,
2,
2,
3,
3,
3,
0,
1,
2,
0,
1,
2,
0,
1,
2,
0,
1,
2,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1
1
1
1
1
1
1
1
1
1
1
1
You can use frames with wildcards (? for any one character, * for a group of any characters), can use the tilde (~)
symbol as a flag for addressing a random frame, the exclamation mark (!) as a flag for deleting the frame after use, and
referencing the current frame’s number with the degree (°) symbol (in an expression), or the current frame’s name with
the micro (µ) symbol (in a text). For example, if you want to split an image into 4 images (in a 2 x 2 pattern) and save
them, you can use this script:
[a] = FRAMEBOX(0, 0, 6, 9, 3, 4.5, N)
IMAGE = 1, "c:\my images\earth.jpg", 0, 0, 6, 9, 0
SAVE = 1, "c:\my images\earth _{°}.jpg",
FRAMECLOCK
This function creates a list of frames (see page 36) arranged in a circle (like a clock’s quadrant). The syntax for this
function is:
[name] = FRAMECLOCK(pos x, pos y, width, height, frame width, frame height,
number, angle, zoom, start, end, factor)
The frames are created with a name composed from the [name] and a number, the number goes from “1” to the 7 th
parameter.
Example:
41
[clock] = FRAMECLOCK(0, 0, 4, 4, 1, 1, 8)
You can use frames with wildcards (? for any one character, * for a group of any characters), can use the tilde (~)
symbol as a flag for addressing a random frame, the exclamation mark (!) as a flag for deleting the frame after use, and
referencing the current frame’s number with the degree (°) symbol (in an expression) or the current frame’s name with
the micro (µ) symbol (in a text).
The angle optional parameter is used if you want to rotate all the frames of a precise degree.
The zoom optional parameter is used if you want to resize the frame of a percent (100 is equal to no change).
The start and end optional parameters are used if you want to draw only an arc instead of full circle (both are degrees).
The factor optional parameter, if not zero, creates a spiral of frames, instead of a circle (positive for clockwise spirals,
negative for anti-clockwise spirals).
FRAMECOUNT
This function creates a label with the number of frames from a single frame name, or a list of frame names. The syntax
for this function is:
[name] = FRAMECOUNT(frame1, frame2, …frameN)
In the [name] parameter you can use wildcards (? for any one character, * for a group of any characters).
FRAMEDISK
With this function, you can define a group of frames, specifying two frames, and including all the frames in the circle
drawn used the first frame as a center and the latter as a radius. It works with frames created from FRAMEBOX and
FRAMEHEX functions. The syntax is:
[diskgroup] = FRAMEDISK(frame center, frame radius)
For example:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1,, #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
[diskgroup] = FRAMEDISK(basee6, basee4)
POLYGON = 1, , 6, 90, #FF0000
FRAMEHEX
This function creates a list of frames (see page 36), based on a hexagonal grid. The syntax for this function is:
[name] = FRAMEHEX(pos x, pos y, width, height, hex size, flags, zoom x, zoom y)
The last parameters (zoom x and zoom y) are optional, if not specified are equal to 100 (no zoom); if you want half
sized frames, you can specify 50, if you want double sized frames, the value is 200, and so on. The zoom can be
different between horizontal and vertical values.
The frames are created with a name composed from the [name] and the flag in the 6th parameter. You can use these
flags:
L
N
P
C
E
.
_
O
I
letters
numbers
zero-padded numbers
coordinates
coordinate with letters + numbers
dot separator for C flag
minus separator for C flag
underscore separator for C flag
outer frame (the default, it creates a frame suitable for drawing a circle outside the hex)
inner frame (it creates a frame suitable for drawing a circle inside the hex)
42
X
A
S
uses a pattern for obtaining “easy to cut” hexagons (“trihexagonal” tiling)
the hexes are arranged in horizontal lines instead of vertical
the line (or the column, if the A flag is specified) starts with a shifted hex
With these flags, coordinates are added to each frame name:
L
N
P
C
E
C.
CC_
A, B, C, D…
1, 2, 3, 4…
01, 02, 03, 04…
0101,0102,0103…0201,0202,0203…
A1,A2,A3…B1,B2,B3…
1.1,1.2,1.3…2.1,2.2,2.3…
1-1,1-2,1-3…2-1,2-2,2-3…
1_1,1_2,1_3…2_1,2_2,2_3…
If you didn’t specify any flag, the frames are created with the same name.
You can use frames with wildcards (? for any one character, * for a group of any characters), can use the tilde (~)
symbol as a flag for addressing a random frame, the exclamation mark (!) as a flag for deleting the frame after use and
referencing the current frame with the degree (°) symbol (in an expression) or the current frame’s name with the micro
(µ) symbol (in a text). For example, this script draws a circle on a random hex of the first column of a grid:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1, , #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
ELLIPSE = 1, <~basea*>, #FF0000
FRAMELINE
With this function, you can define a group of frames, specifying a first frame, a last frame, and including all the frames
in the shortest path between the two. It works with frames created from FRAMEBOX and FRAMEHEX functions. The
syntax is:
[linegroup] = FRAMELINE(frame start, frame end)
For example:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1,, #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
[linegroup] = FRAMELINE(basea1, baseh9)
POLYGON = 1, , 6, 90, #FF0000
FRAMELIST
With this function, you can define a group of frames, and use a single command on all of them. The syntax is:
[group] = FRAMELIST(frame1, frame2, …frameN)
You can specify a single frame for parameter, or use another group of frames, or specify a range of frames using the
syntax frameX..frameY (to add every frame with that name and numbered between X and Y). Before the name of the
frame you can use these flags:
£
the frames are reversed on each line (from top to bottom, from right to left)
$
the frames are in bidirectional order (from left to right in the first row, from right to left in the next row, and so
on…)
%
the frames are listed in vertical order (from left to right, from top to bottom)
%£
the frames are reversed on each vertical line (from left to right, from bottom to top)
%$
the frames are in bidirectional vertical order (from top to bottom in the first column, from bottom to top in the
next column, and so on…)
the order with the frames in a group are added is completely reversed (it can be added to each of the above
combinations
43
After the name of the frame you can specify how many frames are skipped with the syntax frame&N where N is the
number of the frames to skip.
For example, this script draws three circles on the first three hexes in the top-left corner of a grid:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1,, #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
[group] = FRAMELIST(basea1, basea2, baseb1)
ELLIPSE = 1, , #FF0000
FRAMEMELD
With this function, you create a new frame, merging several others. The syntax is
[newframe] = FRAMEMELD(frame1, frame2, …frameN)
For example:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1,, #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
[group] = FRAMEDISK(basef3, basef1)
POLYGON = 1, , 6, 90, #FF0000
[meld] = FRAMEMELD(based1, baseh5)
ELLIPSE = 1, , #0000FF, EMPTY, 0.2
FRAMEMOSAIC
This function reads all the images in a folder, arrange them in a rectangle, and creates a new group of frames, one for
each image. If the images fill more than one instance of that rectangle, you can use a page parameter to specify which
rectangle is drawn from all the possible choices. The frames are created with a name composed from the [name] and a
number, the number starts from “1”. The syntax for this function is:
[newframe] = FRAMEMOSAIC("folder", pos x, pos y, width, height, page, flags,
zoom)
Parameters:
"folder": a folder to search, eventually with a file pattern,
position x: horizontal position (in cm),
position y: vertical position (in cm),
width: width of the rectangle (in cm),
height: height of the rectangle (in cm),
page: if not specified, is equal to 1,
flags: one or more of these flags
H
V
S
the schema is mirrored horizontally
the schema is mirrored vertically
the images are read also in the subfolders
zoom: if not specified, is equal to 100
This function creates also a label named namePAGES (where name is the frames’ prefix) with a value equal to the
number of pages resulting.
44
FRAMENET
This function creates a new group of frames, composed with all possible couple from two groups of frames, eventually
including only these contained with a range of distances. The syntax is:
[newframe] = FRAMENET(frame group 1, frame group 2, min dist, max dist, flags)
In the flags parameter, you can use one or more of these flags:
L
N
1
2
3
4
the frame(s) added is from the center of the starting frame to the center of the ending frame (it can be used for
drawing lines), this is the default option,
the frame(s) added is the ending frame,
the frame(s) added are only from the 1st quadrant (top-right),
the frame(s) added are only from the 2nd quadrant (bottom-right),
the frame(s) added are only from the 3rd quadrant (bottom-left),
the frame(s) added are only from the 4th quadrant (top-left).
If you didn’t specify any of flags 1234, the frames are taken from all the starting lists.
For example, this is a net from all the points in a rectangular grid, with a maximum distance of four units:
[net0] = FRAMEBOX(0, 0, 6, 9, 1, 1, L)
[net1] = FRAMENET(net0*, net0*, 0, 4)
LINERECT = 1, , #000000
Another example, this is a “star map”, connecting ten random “planets” in a hexagonal grid with a distance from two to
four units:
[map0] = FRAMEHEX(0, 0, 6, 9, 0.1, L, 50%)
[map1] = FRAMELIST(10!~map0*)
[map2] = FRAMENET(map1, map1, 2, 4)
LINERECT = 1, , #000000
ELLIPSE = 1, , #0000FF
FRAMEPATH
With this function, you can define a group of frames, specifying a first frame, a last frame, and including all the frames
in the shortest path between the two, and optionally remove a list of frames (specified in the 4 th parameter) from the
result. It works with frames created from FRAMEBOX. The syntax is:
[pathgroup] = FRAMEPATH(frame start, frame end, flags, exclusions)
In the flags parameter, you can use one or more of these flags:
F
L
D
S
E
T
add frame1 to the result group
add frame2 to the result group
delete the frames used for the path
delete the frame used as 1st parameter (start frame)
delete the frame used as 2nd parameter (end frame)
use the shortest path
For example:
[grid] = FRAMEBOX(0, 0, 6, 9, 0.5, 0.5, C)
[path1] = FRAMEPATH(grid0203, grid1116, D)
[path2] = FRAMEPATH(grid0203, grid1116, D)
[path3] = FRAMEPATH(grid0203, grid1116, D)
RECTANGLE = 1, , #0000FF, #FF0000, 0.1
ELLIPSE = 1, , #AAAAAA, #00FF00, 0.05
ELLIPSE = 1, , #AAAAAA, #0000FF, 0.05
ELLIPSE = 1, , #AAAAAA, #FF0000, 0.05
45
FRAMEPER
This function creates a new group of frames, adding for each starting frame the four frames from its sides (the starting
frame is considered rectangular). The syntax is:
[newframe] = FRAMEPER(frame group, width, flags, margin)
The width parameter specifies the width of the left and right frames, and the height of top and bottom frames. In the
flags parameter, you can use one or more of these flags:
1
2
3
4
V
a frame for the top side of the rectangular frame is added to the result,
a frame for the right side of the rectangular frame is added to the result,
a frame for the bottom side of the rectangular frame is added to the result,
a frame for the left side of the rectangular frame is added to the result,
with this flag the frames are created in vertical order (instead of a horizontal order).
If you didn’t specify any of flags 1234, all the four frames are added. The margin parameter specifies how much space
is added to the left and to the right (for horizontal sides) and to the top and to the bottom (for vertical sides) of the
frame.
FRAMERECT
With this function, you can define a group of frames, specifying two frames, and including all the frames in the
rectangle drawn used the first frame as top-left and the latter as bottom-right. It works with frames created from
FRAMEBOX and FRAMEHEX functions. The syntax is:
[rectgroup] = FRAMERECT(frame start, frame end)
For example:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1,, #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
[rectgroup] = FRAMERECT(baseb3, basei6)
POLYGON = 1, , 6, 90, #FF0000
FRAMESUB
With this function, you can define a new frame from another frame (1 st parameter), removing items from a third frame
(2nd parameter). The syntax is:
[group] = FRAMESUB(frame1, frame2)
For example, this script uses two square group of frames for creating a third hollow group of frames (subtracting the
second from the first):
[grp_a]
[grp_b]
[grp_c]
ELLIPSE
=
=
=
=
FRAMEBOX(0, 0, 6, 6, 1, 1, C)
FRAMEBOX(1, 1, 4, 4, 1, 1, C)
FRAMESUB(grp_a*, grp_b*)
1, , #00FF00
FRAMETRANS
This function creates a new group of frames, taking all the frames from a group, and applying to them a horizontal and a
vertical offset, and optionally a change in width and height. The syntax is:
[newframe] = FRAMETRANS(frame group, x offset, y offset, width change, height
change)
46
For example, this line takes all frames from group test, and creates a group test_trans shifted right of 0.5:
[test_trans] = FRAMETRANS(test, 0.5, 0)
FRAMETRI
With this function, you can define a group of frames, specifying three frames, and including all the frames in the
triangle drawn used the frames as vertexes. It works with frames created from FRAMEBOX and FRAMEHEX
functions. The syntax is:
[trianglegroup] = FRAMETRI(frame1, frame2, frame3, flags)
You can use these flags in the 4th parameter:
O = doesn’t include the outer frames
I = doesn’t include the inner frames
For example:
CARDSIZE = 18, 20
HEXGRID = 1, 0, 0, 18, 20, 1,, #000000, EMPTY, 0.1
[base] = FRAMEHEX(0, 0, 18, 20, 1, E)
[trianglegroup] = FRAMETRI(baseb3, basei6, basec10)
POLYGON = 1, , 6, 90, #FF0000
47
Expressions
Expressions may be used to calculate numeric parameters or numbers in TEXT parameters, these delimited with “{”
and “}”. You can use numbers (integer and decimal separated with a dot “.”), parenthesis and these operators:
+
*
/
^
#
£
addition
subtraction
multiplication
division
exponentiation
modulus
integer division
For changing the order of operations, you can use “(“, “)”, “{” and “}”, these are treated like the same. You can’t use
“[” and “]” (used for labels).
For example, these are valid expressions:
RECTANGLE = 1, 0, 0, (1+2)*2, (1+2)^2, #FF0000
TEXT = 1, "Result {(2+2)^2}", 0, 0, 6, 9, center
This is a special variable: the paragraph character (§) gives you the current card number; for example, that script creates
ten cards, each with a number from 1 to 10:
FONT = Arial, 32, , #000000
TEXT = 1-10, "{§}", 0, 0, 6, 9, center
That script creates ten cards, each with a random number from 1 to 100:
FONT = Arial, 32, , #000000
TEXT = 1-10, "{1d100}", 0, 0, 6, 9, center
Counters are variables, that can be used in expressions; there are two kind of counter, these are used for integer values:
A B C D E F G H I J
And these are used for floating-point values:
AA BB CC DD EE FF GG HH II JJ
A counter can be initialized with COUNTER directive:
COUNTER = 1, A, 1
and later re-used in an expression:
RECTANGLE = 1, 0, 0, A, A, #00FF00
A counter can be auto-incremented with a pre- and/or a post- number. If A has a value of 10, this command:
TEXT = 1, "{1A2}", 0, 0, 3, 3, center
will give an output of 11, and A will have a value of 13 after that line.
The counter D is a special case, it has been changed for default into a dice (see DICE keyword, page 83), to give a
random value, the syntax is ndf, where n is the number of dice, each with f faces. If not specified, n is set to one, and f is
set to six.
These are special symbols:
48
Z
X
Format
Repeat
The “Z” symbol may be used when you need to format a decimal value with a fixed number of digits. The syntax is
valueZmask, where the mask is a sequence characters for the integer part, a dot (“.”) and a sequence characters for the
decimal part. The characters that can be used for the mask are:
0
#
a digit taken from the number, if there isn’t a digit in that position, a zero (“0”) is written instead.
a digit taken from the number, if there isn’t a digit in that position, a space (“ ”) is written instead.
For example:
FONT = Arial, 32, , #000000
TEXT = 1, "{4/3Z00.00}", 0, 0, 6, 9, center, center
The result will be a “01.33” printed on the card.
The syntax for the “X” symbol is textXnumber, and duplicates the text for a number of times. For example:
FONT = Arial, 32, , #000000
TEXT = 1-5, "{*X§}", 0, 0, 6, 9, center, center
Will output an asterisk on the 1st card, two asterisks on the 2 nd card, three on the 3rd and so on.
Comments
Comments can be inserted in scripts, marking them with a character on the start of the line. The character can be an
apostrophe (‘) or a semicolon (;) or a custom character selected from the “Config” window.
Example:
CARDS = 52
‘This is a standard deck
From the “Config” window you can also check the “Use in-line comments marked by …” option, and after that you can
use a syntax like that:
CARDS = 52 ‘‘ This is a standard deck
If you use a custom character, and open your script on another computer (with a different configuration) your comments
will not be evaluated as such. To avoid this problem, you must include a COMMENT directive at the start of your script
(see page 77).
You can apply or remove the current comment’s character in a block of selected text with two buttons on the right side
of the main window: “+Com” for apply comments and “-Com” for removing comments.
49
Script lists
If you must work on multiple scripts, you can create a list for manipulating them. You can activate this option clicking
on the button “Script list”:
With the buttons on the right side you can create a new list, open an old list, save the current list (with the current name
or specifying another), add another script to the list, remove a script and sort the list. You can also open the selected
script, or open all of them (in multiple tabs), create a list from all the current scripts and erase the selected script.
With the button “Run list” you can launch a “Validate and build” task on all the scripts listed in this window, choosing
the output for them with the “Output” box: you can print the result, create PDF, and save the images in bmp, jpg, png or
tiff format (the latter with standard and CMYK color space). With the “Filename number” box you can choose if the
filename must be chosen from card number or card count: it can be different if you use a PRINT directive (see page
139) in your scripts.
50
Create PDF
The button “PDF” in the main window opens this form:
With this form, you can specify a filename and an author for the PDF file.
PDF/A: with this option, the PDF file is saved in this format.
Use JPEG Compression form images: with this option enabled all the images in the PDF file are internally stored in
JPEG format.
Use scaled images: with this option enabled, the program uses a high image compression for the PDF file, reducing its
size (and its quality).
PDF compression level: you can choose between four standard compression level for the images (None, Low, Default
and Max).
Save a copy with a CMYK color space: if you have installed Ghostscript (http://www.ghostscript.com) you can also
save it with CMYK color space (instead of RGB), specifying the path for the executable (Gswin32c.exe), and use an
ICC color profile.
51
Save images
The button “MT” in the main window opens this form:
With this form, you can specify a path for saving the cards’ images, the file format, the number of threads to be used,
the DPI (see page 84) and oversampling (see page 132) values.
Note: every thread uses a separate memory pool, thus it’s possible to use more than 4GBytes of memory.
Convert a PDF to images
The button “CP” in the main window opens this form:
If you have installed Ghostscript (http://www.ghostscript.com) you can convert PDF files into images. The first field is
for the Ghostscript’s executable; the second is the name of the PDF file, the third is for the resulting images (you can
use the § character for the page number); the fourth field is for the DPI resolution of the final images.
52
Command-line parameters
You can run nanDECK from the command line (if you want to execute a script in a batch, for example). The syntax is:
nanDECK