The GDL Cookbook 4

First 3D object: a simple Chair

You want to do something

practical? Well try this
VERY simple little kitchen
chair for a starter.
From the File > GDL Objects
> New Object, you will get a
new GDL Dialog and from this,
you can bring up the 3D
Script.

I DEALLY, you make everything parametric, but we

shall start with a 3D Script for a small chair using
non parametric dimensions. Later, we can convert it
This simple chair starts life from its front right leg. Do each part
in stages, and move the cursor back to its origin at the end.
As we develop it further, we can add more 3D options, but we
to parametric scripting. You can do it in Metric or Im- keep it simple for now.
perial.
You start by looking at the object 'with half closed set whatever colour you want. If you do not have ‘Pine,
eyes' and decide what simple elements it really con- Shiny’ in your Materials library, then find another wood
sists of - leaving out inessential detail. Next, each ob- material name to use for the chair.
ject has an 'Origin' so in this case, we decide on the This example is done in Metric and Imperial – to
front left hand leg. please the U.S. readers of the GDL Cookbook. All na-
We build this entirely with BLOCK and CONE, to tive GDL scripting has to be done in Metres (not Mil-
keep things simple. We move the 3D cursor around limetres). If you wish to write in Imperial, you can, but
the model, drawing a BLOCK or CONE in each place. each number must be clearly signified with Foot and
The syntax of BLOCK and CONE are very easy. Inch apostrophes. For Imperial users, the first things I
Notice that the stages of the script are marked suggest (apart from changing to Metric) is to work en-
with labels (or ‘comments’) which all start with an ex- tirely in Decimal Inches, as this avoids spurious punc-
clamation mark. When you look at the script later, you tuation marks and maths operators. And of course,
will know what’s what if you have labelled frequently. future scripts will be neither: they will be parametric!
As you build each Block or Cylinder, you use
the ADDx, ADDy, ADDz or ADD commands to move 2D Symbol
the cursor to the next location, then build the next 3D The ArchiCAD objects that are autoscripted from the
shape. After a group of commands is completed, get Wall/Floor/Roof tools always have their own 2D sym-
the cursor back to the start before doing the next group, bol or script. When you write a script yourself, you
using the DEL command – this ‘undoes’ the number need to create the 2D symbol.
of ADDs that you have made. Make sure that at the So here, you can write a tiny script. Open the 2D
very end, you move the cursor back to the origin of Script Window and use this one-line ‘killer command’:
the model using DEL. PROJECT2 3,270,2. It is very powerful and solves
If you do not specify a material, your objects will your need for a 2D symbol at a stroke. It draws a Plan
turn out all one colour, which can be disconcerting. view of the 3D object [3], with a camera angle of 270˚
So the PEN and MATERIAL command is one of the [270] and it is in hidden line [2]. Your 2D symbol will
first ones you learn. PEN 1 in my ArchiCAD is black – be given bounding box Hotspots by ArchiCAD.

10 Copyright Marmalade Graphics ©2004

 Your First 3D Object : a Chair

!Simple Chair Example !Simple Chair Example

!Non-Parametric, Metric Start with the Title, set a Pen and a !Non-Parametric, Imperial
curve control (RESOL) early on.
PEN 1 PEN 1
RESOL 12 RESOL 12
For the first operation, state your
!--All the legs-----------
material - it’s better to use a !--All the legs
MATERIAL "Wood-Pine, shiny" parameter in future! All four cones are MATERIAL "Wood-Pine, shiny"
CONE 0.5, 0.015,0.03, 90,90 the same, get one right, you get them CONE 20", 5/8",1.2", 90,90
ADDx 0.45 all right. Use ADD to move about and ADDx 1'-6"
CONE 0.5, 0.015,0.03, 90,90 place them. DEL 3 because we needed CONE 20", 5/8",1.2", 90,90
ADDy 0.55 3 moves. ADDy 22"
CONE 0.5, 0.015,0.03, 90,90 CONE 20", 5/8",1.2", 90,90
ADDx -0.45 Start the seat with a new Title. The ADDx -18"
CONE 0.5,0.015,0.03,90,90 seat is a block, with a thin covering of CONE 20", 5/8",1.2", 90,90
DEL 3 fabric on top. DEL back to the Origin DEL 3
before building the legs.
!--The Seat and upholstery----- !--The Seat and upholstery
ADDz 0.45 Start the back with a new Title and ADDz 18"
BLOCK 0.45,0.55,0.045 BLOCK 18",22",1.75"
restate material. We can use an ADD
MATERIAL "Surface-Fabric"
command which can go in X,Y,Z MATERIAL "Surface-Fabric"
ADD 0.025,0.025,0.045 directions at one leap. The Cones are ADD 1",1",1.75"
BLOCK 0.40,0.50,0.005 similar to the legs, but with the narrow BLOCK 16",20",1/4"
DEL 2 radii at the top. Returning to the seat DEL 2
height (not all the way back to the
!--Back Legs, panel & upholstery origin) place a wood block for the !--Back Legs, panel and upholstery
MATERIAL "Wood-Pine, shiny" back infill, then make another small MATERIAL "Wood-Pine, shiny"
ADD 0,0.55,0.5 ADD move to instal a thin layer of ADD 0,22",20"
CONE 0.6,0.03,0.02, 90,90 Fabric for the back upholstery. Then CONE 24",1.2",0.8", 90,90
ADDx 0.45 you DEL right back to the origin – ADDx 18"
CONE 0.6,0.03,0.02, 90,90 and you are finished. CONE 24",1.2",0.8", 90,90
DEL 2 DEL 2
Now all you need is a 2D symbol. This
ADD 0,0.54,0.70 can be generated from a short one-line ADD 0, 21.8", 26"
BLOCK 0.45,0.025,0.35 2D Script, using PROJECT2. BLOCK 18",1",14" !Backpanel

MATERIAL "Surface-Fabric" MATERIAL "Surface-Fabric"

ADD 0.05,-0.01,0.02 Now it’s time to think about ways ADD 2", -3/8", 1"
BLOCK 0.35,0.01,0.30 to make this parametric. BLOCK 14", 3/8", 12" !Cushion
DEL 2 DEL 2
!Chair - 2D-Script
PROJECT2 3,270,2

Make your Chair Parametric!

THE first chair isn’t
Smart and it isn’t Para-
metric, so let’s do something
to make it better. Open the
chair object you made ear-
lier, and make some param-
eters. Click the <NEW> but-
ton a few times and make
some parameters for lengths
and materials. Hold the
mouse down on the param-
eter icon, and up pops an
iconic palette so you can set
its purpose.
Parameters can be:
Dimension (based on your
system preferences, metric
or imperial), Angle, Real
number, Integer, Boolean choice, Text, Material, Line type, Fill pattern, Pen colour, Separator (white
space), or Title (bold font). Keep the parameter names to between 2 and 10 characters.
You can rearrange the order of parameters using the little <up-down> arrows, so group them into a logical
order. You can put in some titles for groups of parameters, e.g. Materials, and then click on the little <indent>
button to make the parameters part of that group under the title.

Copyright Marmalade Graphics ©2004 11

The GDL Cookbook 4

Make your chair parametric! 3D Script

When you create parameters, change their Variable Take the 3D Script of the Simple chair, and change all
names to sensible ones like ‘lsec’ for leg section and the 2” or 0.05 to ‘lsec’ (leg section). Continue to work
‘sthit’ for seat height. The Description here is what through all the dimensions changing them to param-
the User will see when using the dialog box that you eters.
are now creating. Put in nominal Values for each pa- We will return to this chair later to learn about Sub-
rameter. In this example, they are in millimetres. routines.

!Simple Chair Example !Simple Chair Example

!Non-Parametric !Parametric

PEN 1 Make the Pen parametric... and PEN cont_pen

RESOL 12 add a parameter for the material RESOL 12
for the legs.
!--All the legs----------- !--All the legs-----------
MATERIAL "Wood-Pine, shiny" Now we can use A as a parameter MATERIAL framat
CONE 0.5, 0.015,0.03, 90,90 for the width and B for the depth CONE sthit, lsec/3,lsec/2, 90,90
ADDx 0.45 of the chair. This means that we ADDx A
CONE 0.5, 0.015,0.03, 90,90 can make the chair stretchy. CONE sthit, lsec/3,lsec/2, 90,90
ADDy 0.55 ADDy B
CONE 0.5, 0.015,0.03, 90,90 CONE sthit, lsec/3,lsec/2, 90,90
ADDx -0.45
Because blocks are built from the ADDx -A
CONE 0.5,0.015,0.03,90,90 bottom left corner, you raise the CONE sthit,lsec/3,lsec/2,90,90
DEL 3 seat block to the seatheight and DEL 3
then drop it by the frame section,
!--The Seat and upholstery----- so that its top surface is at the !--The Seat and upholstery-----
ADDz 0.45 correct height. ADDz sthit-frsec
BLOCK 0.45,0.55,0.045 BLOCK A,B,frsec-0.002
The fabric material should also be
MATERIAL "Surface-Fabric" parametric, this is one area where MATERIAL seatmat
ADD 0.025,0.025,0.045 the user must have a choice! ADD lsec/2,lsec/2,frsec
BLOCK 0.40,0.50,0.005 BLOCK A-lsec,B-lsec,0.005
DEL 2 With the cones we have made DEL 2
some fairly arbitrary assumptions
!--Back Legs, panel & upholstery !--Back Legs, panel and upholstery
MATERIAL "Wood-Pine, shiny"
about the ratio of width for top MATERIAL framat
ADD 0,0.55,0.5 and bottom, and the heights of the ADD 0,B,sthit
CONE 0.6,0.03,0.02, 90,90 back panel. These are ‘designer’s CONE bhit,lsec/2,lsec/3, 90,90
ADDx 0.45 decisions’ – you have to decide ADDx A
CONE 0.6,0.03,0.02, 90,90 what the user is going to be CONE bhit,lsec/2,lsec/3, 90,90
DEL 2 allowed to decide, and what the DEL 2
designer decides. Novice GDL
ADD 0,0.54,0.70 writers tend to make too many ADD 0,B-0.01,sthit+bhit*0.3
BLOCK 0.45,0.025,0.35 parameters (in their new-found BLOCK A,lsec/2,bhit*0.6!Backpanel
enthusiasm) and then the object is
MATERIAL "Surface-Fabric" confusing to the user with so many MATERIAL seatmat
ADD 0.05,-0.01,0.02 parameters. ADD lsec/2,-0.01,lsec/2
BLOCK 0.35,0.01,0.30 BLOCK A-lsec,0.01,bhit*0.6-lsec
DEL 2 DEL 2

2D Symbol
We can stay with PROJECT2 to make the 2D symbol, Dimensional settings
but we can be a bit clever with HOTSPOTs. Previously
we relied on default bounding-box hotspots, but now
we can write our own. HOTSPOT2 x,y is the word!
E VERYBODY works in different dimensions
depending on their country and regional building stand-
ards. The first simple Chair was hard coded (written into
Since you now converted the chair to use A and B the script) in metres and in feet/inches.
as parameters for width and depth, you can easily de- The improved Chair is parametric. Most of the exer-
fine the XY positions of the HOTSPOTs in the 2D GDL. cises here are in metric, in millimetres – even if the scripts
HOTSPOT2 0,0 are parametric, the Parameter Tables are usually metric.
HOTSPOT2 A,0 The settings you use do not affect the hard coding in the
HOTSPOT2 A,B scripts, but they make the Parameter Table look different.
HOTSPOT2 0,B If you are not sure of your Units, open a NEW Library ob-
HOTSPOT2 A/2,B/2
PROJECT2 3,270,2
ject and look at A and B. If A is 1.00 you are in metres, and
if A is 1000 you are in millimetres. If A is 3’-3.37” it’s feet
Now the Hotspots will and decimal inches. If you wish to develop GDL in non-
show in the plan. The cor- metric, I advise you to work in Decimal Inches.
ner ones will enable You are advised to have a project floor plan file open
stretching, and the central in the background while you work in GDL to get the navi-
A/2,B/2 spot is a good gator palette to work correctly, and to set the dimensional
‘Pickup’ spot. environment. If you modify dimensional settings remem-
ber to set the number of decimals you can display.

12 Copyright Marmalade Graphics ©2004

 About 2D Scripting

About 2D Scripting
U NLESS you have a 2D Symbol or a 2D Script,
your object will not appear on the Project Plan!
If you been using ArchiCAD’s conventional tools to
With ArchiCAD 8, hotspots have acquired massive
importance as it possible to apply hotspots to differ-
ent parts of a GDL model and articulate parts of the
make library objects, you have been used to it making model – e.g. opening doors and pulling/pushing draw-
automatically generated scripts, and automatically ers in a furniture cabinet. Of which much more anon!
drawn 2D symbols generated from the view of the
object. But now, you have to do it! LINE2 x1,y1, x2,y2 : draws a line from one XY lo-
cation to another XY location – relative to your cur-
HOTSPOT2 x,y places a Hotspot at the point rent cursor position.
x,y in the 2D symbol of the object. It lights up when
you select the object.
HOTLINE2 x1,y1, x2,y2 : following a LINE2,
makes the whole line sensitive to your mouse – easy
The purpose of HOTSPOTs are 4-fold:
selection of objects!
1. To enable you to see objects when touched or
marqueed, RECT2 x1,y1, x2,y2 : draws a rectangle from one
2. to pick up the object, XY location to another XY location diagonally oppo-
3. to make objects stretchy, and site – relative to your current cursor position and an-
4. to provide ‘gravity’ for snapping objects to line or gle. RECT2 is always wireline (you can see through it).
to other hotspots. CIRCLE2 x,y, rad : draws a circle at point x,y with
radius rad.

PROJECT2

P ROJECT2 is a command that you MUST

learn, even with your first scripted Object!
Syntax: PROJECT2 Viewtype, Camera Angle, Visibility
Until you learn parametric 2D Scripting, the easiest
thing is to write a short 2D Script containing
PROJECT2 3,270,2. This reads the 3D Script and
draws whatever it can see, faithfully, in wireline or hid-
den line view. Be warned – it can slow down the time
it takes to draw the symbol if the object is complex. Complex objects may be very slow to draw in 2D if
PROJECT2 should be learnt parrot fashion, you will you use the PROJECT2 command. A 2D Script using
use it many times! LINE2 and accurately reflecting the trigonometry of
PROJECT2 has interesting possibilities. For exam- the object without showing excess detail may be per-
ple, it can be told to display the object in the Project fectly adequate for the 2D symbol, as above. You could
Plan in elevation or axonometric form or from the un- offer the user an option to show greater detail if the
derside: very useful if you wish to generate drawings plan is larger than 1/50 or 1/4”-1’ scale. With win-
of your object from all directions without having to dows and doors, the frame sections are so small that
organise sections in ArchiCAD. Note that -7, -8 and -9 they would just be a dense blob of ink at 1/50 or 1/
are the same as their +ve equivalent, just upside down! 100, so some intelligent 2D Scripting is very desirable.
Visibility value: the last digit. 1 gives you Wireline, !Typical short 2D Script for any 3D object
2 gives you Hidden Line, 3 gives a solid material qual- !using A and B for width and depth
HOTSPOT2 0,0
ity to the 2D symbol, -1 gives you a vectorial fill. HOTSPOT2 A,0
HOTSPOT2 A,B
HOTSPOT2 0,B
!Typical very short 2D Script for any 3D object
HOTSPOT2 A/2,B/2
PROJECT2 3,270,2
PROJECT2 3,270,2

3,270,2 4,270,2 5,270,2 6,270,2 7,270,2 8,270,2 9,270,2 -3,270,2 -6,270,2

Copyright Marmalade Graphics ©2004 13

The GDL Cookbook 4

2D Script for the simple

chair
F OR the Simple Chair, we used a PROJECT2 com-
mand – the killer command that does most of
the 2D work for you! But you can see the compari-
son here – Project2 (right) is untidy, with too many
pen lines. A scripted 2D symbol (left) is faster for Ar-
chiCAD to draw, and it puts you into the driving seat
– enabling you to decide how the object looks. Let’s
write a 2D Script. Find and open your Simple Chair
!Simple Chair Example
model. Open the 2D Script. !Parametric 2D Script
This chair is built with the parameters A and B for HOTSPOT2 0,0
stretchiness. Have Project2 in the script at first, write HOTSPOT2 A,0 LINE2 s2,B-s4, A-s2,B-s4 !back
HOTSPOT2 A,B LINE2 s2,B+s4, A-s2,B+s4 !back
your script after it, make sure that your new lines HOTSPOT2 0,B LINE2 0, s2, 0,B-s2 !side
follow the outline correctly, and when the scripted HOTSPOT2 A/2,B/2 LINE2 A, s2, A,B-s2 !side
version looks good enough, comment out the LINE2 s2,0, A-s2,0 !front
!PROJECT2 3,270,2
Project2. Put the Hotspots before the 2D statements. s4=lsec/4 !Quarter diam
You can build the whole chair symbol from CIR- s2=lsec/2 !Half diameter
CLE2 and LINE2. We can’t use RECT2 because the PEN cont_pen
CIRCLE2 0,0,s2 Notice that the use of variables
corners intersect the round legs – this looks fine in CIRCLE2 A,0,s2 like ‘s2’ and ‘s4’ saves a lot of
3D, but horrid in 2D. Some skillful work with LINE2 CIRCLE2 A,B,s2 typing and reduces the risk of
simulates the rectangular seat intersecting the legs. CIRCLE2 0,B,s2 spelling errors.
You cannot make your own Pen
PEN This has always been most frustrating to me. You can
Define Material, so why shouldn’t you Define a Pen?
P EN sets the pen colour. But remember, this also
changes the pen thickness. If you use True Line
Weight, this matters hugely.
You can use a REQUEST() statement to suggest a PEN,
and it will find the one with the closest RGB value, but
you will only request it by RGB colour and have no
On PEN, there are some points to note: PEN must control over pen thickness. There ought to be a DE-
have a value. You cannot have PEN zero. PEN 1 gives FINE PEN r,g,b,t statement – but there isn’t.
you a Black line – but if you have recently opened a
DWG file then PEN 1 might now be Red: this demon- Consistent parameter names
strates immediately the benefit of making your object You are advised to work with standard parameter
parametric. People might modify the pen palette in names. GS used to use ‘cpn’ for contour pen, but with
ArchiCAD and the palette values can be re-assigned AC8 and IFC in mind, GS now use ‘gs_cont_pen’ as
in colour and line thickness. This can have mischie- their primar y pen name. I also recommend
vous effects on your model. It is best therefore not to ‘gs_symb_pen’ if you make a separate one for 2D – if
hard code the pen colours, but to make them with pa- you have a scripted 2D object with polygons and lines
rameters so that the user can select them. So every and text. You will also need pen values for Background
good object should have a pen parameter. and Fills. In this case, try to use the correct Subtype,
PEN can be changed during the execution of the which will prompt you with suitable parameter names
script, so that different parts of the model can be drawn for most of your pens. It is worth the short time it takes
separately. My advice is: it is best to keep the pen to a to get your head round POLY2_A and B in which you
single colour in the 3D, so that the object looks right in can specify all these pens.
wireline and in hidden line. Use Material as a way to Material obtained from Pen
vary the appearance of the object. I also recommend PEN can be used as a convenient way to create bright
a separate pen for the 2D symbol, different from the coloured surfaces. If you set MATERIAL to zero, then
one you use for the 3D. If you choose one pen for both, the surface colour becomes the PEN colour. This is
the pen that looks right in 3D might be too dark and why most of your first efforts at modelling come out
chunky for the drawing scale in the 2D. as GREEN, BLACK, PINK or another colour – the ma-
It is not essential to set any pen colour for simple terial is becoming the same colour as your default pen
objects as the pen colour can be set by the user in the colour if no material has been specified.
main Object Settings dialog box. If you are making a But this method produces a very matte effect. It is
GDL macro, you should avoid setting a pen param- possible to generate a full material definition from a
eter, because these will be inherited from the senior pen colour using REQUEST() statement. This will give
object. a far better appearance, with characteristics like shini-
ness, transparency and emission fully controllable by
you. See later exercises for this.
14 Copyright Marmalade Graphics ©2004
 About 2D Scripting

More about GDL 2D

First advice on 2D Scripting Modifying Objects

W HENEVER you can, and if you have the

skill, always try to write a 2D Script with a para-
metric quality to match your 3D object.
A UTOSCRIPTED objects saved from the 3D view
are given a drawn symbol, and some code in the
3D Script makes them stretchy.
2D Scripting is good because... Autoscripted objects saved directly from the Floor
1. You get faster speed of drawing in the project plan. Plan are fully scripted in 2D as a mass of LINE2s and
With PROJECT2, AC must do a 3D hidden line pro- HOTSPOT2s. I often delete the whole lot and replace
jection of the object before drawing it – slow! Scripted them with a single PROJECT2 command. This is es-
objects draw instantly. sential if you intend to alter or rotate the object in the
2. A Symbol drawn into the 2D symbol window might 3D code. If you are willing to, you could try to rescript
be pretty, but it is not parametric. it in a much simpler, more usable, parametric form.
3. The 2D Script can itself be highly parametric, error Another method is to write a PROJECT2, place the
checking, allowing hotspots, informative, self labelling, object in the Floor Plan, Explode the object, then
and scale aware. Copy the 2D symbol thus created and Paste it into
the 2D symbol window of the object. Add the com-
If it is too complex to script in 2D, and too slow to mand FRAGMENT2 ALL,1 to the 2D Script. Retain
generate a PROJECT2 image from the 3D Script, con- Project2 until you get the symbol and drawing aligned.
sider using a symbol: use a PROJECT2, and follow the Then delete PROJECT2. You can add Hotspots
advice on the right (explode> copy> paste> frag- manually to the 2D symbol. If the symbol is too full of
ment2> hotspot). lines, replace them with fills, much tidier.

More about 2D Hotspots: stretching!

HOTSPOT2 x,y should be used in every 2D Script. HOTSPOT2 0,0 HOTSPOT2 -A/2,-B/2
HOTSPOT2 A,0 HOTSPOT2 A/2,-B/2
They make your objects stretchy: if you use A and HOTSPOT2 A/2, B/2
HOTSPOT2 A,B
B as dimensions, the Hotspots at the outer corners HOTSPOT2 0,B HOTSPOT2 -A/2, B/2
may enable you to stretch the object. Stretchy objects
are most useful and user friendly.
If the Hotspots are written as illustrated here, and Stretchy: A typical listing Stretchy: A typical listing
if A and B are the distances apart of the corner of HOTSPOTs when the of HOTSPOTs when the
hotspots, then the object will be STRETCHY! Origin of the model is at the Origin of the model is at
bottom left. the centre of the model.

ARC2 draws a circular line, which you can control

by location, radius and angles (in degrees). Angles start You can send a Hotspot directly to a location, e.g.
from the Horizontal and move in an anticlockwise HOTSPOT2 1.6,0.9 or you can write it the long way
direction. as:
!Syntax: ARC2 x,y,radius,startangle,endangle
ARC2 0,0,0.5,90,180 ADD2 1.6,0.9 !The same result
You also have HOTARC2 (AC9) which has the same HOTSPOT2 0,0 HOTSPOT2 1.6,0.9
DEL 1
syntax, but allows easy selection in the plan.

Are your HotSpots Stretchy AND

TEXT2 x,y,’string’ is for adding text to an ob-
ject’s symbol. Apart from being able to label the ob- Squeezy?
ject, the object can use it to display a level of intelli-
gence, e.g. flashing up a text warning if the object has I F you want objects to be Squeezy as well as Stretchy,
you need to utter your HOTSPOT2 commands <BEFORE>
the commands which actually draw the 2D objects. Other-
bad parameters, or displaying the final size of a
stretched object, the pitch of a stretched staircase, or wise, objects may stretch, but not reduce in size correctly.
the serial number of a manufacturers component. You must also provide some hotspots that are not on
It is only worth using if you are first prepared to the stretchy corners or you will have trouble picking up
learn how to DEFINE STYLE; if you do not, you will your object – it may stretch every time you try to drag it!
have no control over the size of the text, or how it If you write any scripted hotspots at all, the default
plots at different drawing scales. The text can be adapt- bounding box will disappear. If you WANT the bounding
able to different scales, including not displaying itself box, hit ‘Details’ button to force them to appear.
at all when it would be too small to read (e.g above 1/ A and B based Hotspots are somewhat redundant, be-
200). Define Style needs more space for explanation, cause Graphical Hotspots can make EVERY part of a GDL
so it will come later in the book. model manipulable with hotspots for sliding and rotating.

Copyright Marmalade Graphics ©2004 15