GDL Handbook: A Comprehensive Guide to Creating Powerful ArchiCAD Objects

489 Pages·2011·5.96 MB·English

by  Andrew Watson

GDL Handbook
A COMPREHENSIVE GUIDE TO CREATING POWERFUL ARCHICAD OBJECTS
2nd Edition

Andrew Watson
PUBLISHED BY
Cadimage Group Ltd.
41 Taharoto Road
Takapuna
Auckland, New Zealand
www.cadimageworld.com

Copyright © 2011 Cadimage Group Ltd.
All rights reserved. No part of the contents of this book may be reproduced or transmitted without the written permission of the
publisher.

National Library of New Zealand Cataloguing-in-Publication Data

Watson, Andrew, 1970-
GDL handbook : a comprehensive guide to creating powerful ArchiCAD
objects / Andrew Watson. 2nd ed.
Previous ed.: 2009.
Includes index.
ISBN 978-0-473-18838-2 (pbk.)—978-0473-18839-9 (ebook)
1. ArchiCAD (Computer file). 2. Architectural design—Data processing.
3. Computer-aided design—Handbooks, manuals, etc.
I. Title.
729.0285—dc 22

Cover Design: Campbell Yule

ArchiCAD® and GDL are registered trademarks of GRAPHISOFT®, Virtual Building™ is a trademark of GRAPHISOFT®.
i
TABLE OF CONTENTS
1 Introduction .................................................................................................................. 1
1.1 GDL.................................................................................................................................. 1
1.2 What can be Modeled using GDL? ........................................................................... 2
1.3 Cadimage...................................................................................................................... 3
1.4 Resources ....................................................................................................................... 4
1.5 How to Use this Book ..................................................................................................... 4
2 Anatomy of a GDL Object ........................................................................................ 6
2.1 What is a GDL Object? ................................................................................................ 6
2.2 Creating an Object ...................................................................................................... 8
2.3 Open an Existing Object for Editing ........................................................................... 9
2.4 Placeable Objects ...................................................................................................... 10
2.5 Object Subtype ........................................................................................................... 11
2.6 Parameters ................................................................................................................... 12
2.7 The Parameters List ..................................................................................................... 13
2.8 Subtypes, Parameters & Template Objects ............................................................ 16
2.9 Object Details .............................................................................................................. 18
2.10 The GDL Scripts ............................................................................................................ 19
2.11 Preview Window .......................................................................................................... 23
2.12 Drawing Fragments .................................................................................................... 23
2.13 2D Symbol .................................................................................................................... 24
2.14 2D Full View .................................................................................................................. 25
2.15 3D View ......................................................................................................................... 25
2.16 Preview Picture ............................................................................................................ 25
3 Variables ..................................................................................................................... 26
3.1 Assigning a Value to a Variable ............................................................................... 26
3.2 Naming Variables ....................................................................................................... 28
3.3 Variable Type............................................................................................................... 30
3.4 Array and Vector Variables....................................................................................... 32
3.5 Scope ............................................................................................................................ 36
4 Operators and Expressions ...................................................................................... 38
4.1 The Equals Operator ................................................................................................... 38
ii

4.2 The Inequality Operator ............................................................................................. 40
4.3 Brackets and the Order of Operations .................................................................... 41
4.4 Logical Operators ....................................................................................................... 42
4.5 Bit Operators ................................................................................................................ 45
5 Working with Text Strings .......................................................................................... 49
5.1 Number of Characters in a String ............................................................................ 49
5.2 Search for a Text within a String................................................................................ 50
5.3 Read Part of a String .................................................................................................. 50
5.4 Substitute Text .............................................................................................................. 50
5.5 Display Numeric Data as a String ............................................................................. 51
5.6 Display the Current Date and Time as a String ...................................................... 55
5.7 Extract Numeric Data from a String ......................................................................... 57
5.8 Include a Quotation Mark in a String Constant ..................................................... 58
6 Using the Stack .......................................................................................................... 59
6.1 Put, Use and Get Values ............................................................................................ 59
6.2 Use ‘Put’ and ‘Get’ to Simplify Scripts ..................................................................... 60
6.3 When to Use the Stack ............................................................................................... 62
6.4 Clearing the Stack ...................................................................................................... 62
6.5 Put and Get Data within a Block ............................................................................. 63
7 Loops ........................................................................................................................... 64
7.1 The ‘for–next’ Loop ..................................................................................................... 64
7.2 The ‘repeat – until’ and ‘while – endwhile’ Loops ................................................. 67
7.3 Infinite Loops ................................................................................................................ 68
7.4 Practically Infinite Loops ............................................................................................ 72
8 Scripting Style ............................................................................................................ 76
8.1 Readable Code .......................................................................................................... 76
8.2 Structured Scripting .................................................................................................... 82
8.3 Managing Transformations........................................................................................ 84
8.4 Legible vs. Efficient ..................................................................................................... 84
9 Macros and Sub-Routines ....................................................................................... 86
9.1 Macros .......................................................................................................................... 86
9.2 Sub-Routines ................................................................................................................ 96
iii
9.3 Re-Usable Sub-Routines ............................................................................................. 98
9.4 Which to Use? ............................................................................................................ 103
10 The 2D Symbol ......................................................................................................... 107
10.1 2D Transformations .................................................................................................... 107
10.2 Attributes .................................................................................................................... 110
10.3 Quick-and-Dirty Ways to Produce a 2D Symbol .................................................. 111
10.4 Parametric 2D Elements ........................................................................................... 116
10.5 Drawindex .................................................................................................................. 133
11 The 3D Model ........................................................................................................... 136
11.1 General Controls ....................................................................................................... 136
11.2 3D Transformations .................................................................................................... 139
11.3 Basic 3D Elements ..................................................................................................... 140
11.4 3D Polygons and Planes........................................................................................... 145
11.5 Prisms, Slabs and Extrusions ...................................................................................... 147
11.6 Revolved Forms ......................................................................................................... 154
11.7 Tubes ........................................................................................................................... 157
12 Groups and Solid Element Operations ................................................................ 161
12.1 Solid Element Operations ........................................................................................ 161
12.2 Defining a Group of Elements ................................................................................. 163
12.3 Placing a Group ........................................................................................................ 164
12.4 Nested Groups .......................................................................................................... 164
12.5 Group Operations ..................................................................................................... 164
13 Text ............................................................................................................................. 167
13.1 Selecting a Font ........................................................................................................ 167
13.2 Define a Text Style ..................................................................................................... 168
13.3 Text Size ....................................................................................................................... 170
13.4 Place a Single Line of Text ....................................................................................... 171
13.5 Define a Paragraph .................................................................................................. 172
13.6 Using Paragraphs ...................................................................................................... 176
13.7 Text Orientation ......................................................................................................... 178
13.8 Text in 3D .................................................................................................................... 181
14 Working with Graphics ........................................................................................... 183
iv

14.1 File Types .................................................................................................................... 183
14.2 Create an Image with Transparency .................................................................... 183
14.3 Images for the Object Settings Dialog .................................................................. 184
15 User Interface .......................................................................................................... 188
15.1 Selection and Referencing ..................................................................................... 188
15.2 Graphic Editing ......................................................................................................... 191
15.3 Customizing the Settings Dialog ............................................................................. 198
15.4 Images in the Settings Dialog ................................................................................. 201
15.5 Outfields ..................................................................................................................... 202
15.6 Basic Input Fields ....................................................................................................... 203
15.7 Values Lists & Graphic Infields ................................................................................. 205
15.8 Buttons ........................................................................................................................ 212
15.9 Tool Tips....................................................................................................................... 214
15.10 Organizing Data........................................................................................................ 215
15.11 Interactive Parameters ............................................................................................ 217
16 Approximating Curves ........................................................................................... 220
16.1 Circular Arcs .............................................................................................................. 220
16.2 Ellipses ......................................................................................................................... 223
16.3 Helices ........................................................................................................................ 224
16.4 Bezier Splines .............................................................................................................. 226
16.5 Traditional Cubic Splines .......................................................................................... 240
17 Linear Algebra 101 ................................................................................................. 253
17.1 Scalars and Vectors ................................................................................................. 253
17.2 Vector Components ................................................................................................ 255
17.3 Vector Notation ........................................................................................................ 255
17.4 Vector Diagrams ....................................................................................................... 256
17.5 Length of a Vector ................................................................................................... 256
17.6 Equivalent Vectors .................................................................................................... 257
17.7 Adding Vectors ......................................................................................................... 257
17.8 Scalar Multiplication ................................................................................................. 259
17.9 Unit and Zero Vectors ............................................................................................... 260
17.10 Cross Product ............................................................................................................ 261
17.11 Perpendicular Vector in 2D ..................................................................................... 264
v
17.12 Dot Product ................................................................................................................ 265
17.13 Equation of a Line ..................................................................................................... 266
17.14 Equation of a Plane .................................................................................................. 267
18 Linear Algebra Applications ................................................................................. 268
18.1 Does a Point Lie on a Line Segment? .................................................................... 268
18.2 A Test for Parallel Lines ............................................................................................. 273
18.3 Intersection of Two Lines in 2D ................................................................................ 276
18.4 Intersect 2 Line Segments in 2D .............................................................................. 279
18.5 Intersect a Line Segment and an Arc in 2D .......................................................... 280
18.6 Calculate an Angle .................................................................................................. 287
18.7 Intersection of Two Arcs ........................................................................................... 289
18.8 Equation of a 2D Arc through Three Points ........................................................... 292
18.9 Closest Point on a Line ............................................................................................. 298
18.10 Closest Point on a Line Segment ............................................................................ 302
18.11 Closest Point on a Polygon ...................................................................................... 305
18.12 Distance between a Point and a Line Segment ................................................. 305
18.13 Distance between Two Lines .................................................................................. 306
18.14 Find the Points of Closest Approach ...................................................................... 310
18.15 Distance between a Point and a Plane ................................................................ 314
18.16 Closest Point on a Plane .......................................................................................... 314
18.17 Intersection of a Line and a Plane ......................................................................... 315
19 Matrices and Transformations ............................................................................... 316
19.1 Elementary Transformation Matrices ..................................................................... 316
19.2 Matrix Multiplication ................................................................................................. 318
19.3 Combined Transformations ..................................................................................... 320
19.4 Translations ................................................................................................................. 321
19.5 The xform Command ............................................................................................... 321
19.6 Calculating Natural Co-ordinates .......................................................................... 323
20 Freeform 3D Modeling............................................................................................ 324
20.1 GDL Primitives ............................................................................................................ 324
20.2 Cardboard Cut-Outs ................................................................................................ 328
20.3 Basic Texture Mapping ............................................................................................. 337
20.4 3D Modeling .............................................................................................................. 340
vi

20.5 Freeform Modeling ................................................................................................... 347
20.6 Advanced Texture Mapping .................................................................................. 357
20.7 Randomizing Objects ............................................................................................... 361
20.8 Trouble Shooting ....................................................................................................... 363
21 Polygon Operations ............................................................................................... 364
21.1 Defining a Polygon ................................................................................................... 364
21.2 Polygon Area ............................................................................................................. 365
21.3 Ensure a Positive Polygon Sense ............................................................................. 368
21.4 Check if a Point Lies Inside a Polygon ................................................................... 369
21.5 Polygon Addition ...................................................................................................... 372
21.6 Intersection of Two Polygons................................................................................... 381
21.7 Subtract One Polygon from Another ..................................................................... 383
21.8 Offset a Polygon ....................................................................................................... 385
21.9 Closest Point on a Polygon ...................................................................................... 390
21.10 Center of Gravity ...................................................................................................... 391
21.11 Optimizing the Polygon Operations ....................................................................... 394
22 Quality Control ........................................................................................................ 396
22.1 Scripting Style ............................................................................................................ 396
22.2 Testing ......................................................................................................................... 400
22.3 Fixing Issues ................................................................................................................ 402
22.4 Optimising for Speed ................................................................................................ 403
22.5 Reduce the Polygon Count .................................................................................... 408
22.6 Provide Optional Data ............................................................................................. 413
22.7 Use Group Operations Sparingly ............................................................................ 413
23 Development Strategies........................................................................................ 414
23.1 A Model for Development ...................................................................................... 415
23.2 Opportunity ............................................................................................................... 418
23.3 Some Thoughts on Planning and Design .............................................................. 421
23.4 Improving the Resource Pool .................................................................................. 424
23.5 Implementation ........................................................................................................ 426
23.6 Testing ......................................................................................................................... 427
23.7 Maintenance ............................................................................................................. 427
vii
24 Example Objects ..................................................................................................... 428
24.1 Playground Equipment/Barrel Bridge .................................................................... 428
24.2 Playground Equipment/Swing ................................................................................ 431
24.3 Wine Glass .................................................................................................................. 450
ix
Acknowledgements
The GDL Handbook reflects on some of what I have learned over several years of GDL programming. Many people have
contributed to my GDL education over this time. Some names in particular come to mind.
 Theo de Klerk without whom my GDL programming career would never have started.
 Campbell Yule, Tracey Gatland and the team at Cadimage for providing a secure and challenging
programming role, and for taking the risk of publishing this book.
 Debbie Garrett, Michael Posthuma and Johanna Bilton for their help with proof-reading.
 Glen Richardson for many valuable discussions on GDL programming.
The help given by each of you has been much appreciated. Thank you.
Finally I would like to acknowledge the involvement of all ArchiCAD users who have become a part of the Cadimage
community over the years. You guys have provided the challenges and at times criticism necessary to shape and test the
validity of my ideas.
I trust that the GDL Handbook will in turn help other GDL programmers, both as a learning resource and as a daily
reference.