BIM | What is GDL and why you should learn it

IamJKM's picture

Short of time? Here's the short version...

Geometric Description Language (GDL) is the programming language of ArchiCAD library parts. The native file format that it uses is GSM.

These objects are similar to blocks in AutoCAD or families in Revit, but unlike blocks or families there's an extensive amount of customization and "logic" that you can program in GDL to make a very complex object. Here's a good write-up on the difference between GDL and Families for further reading.

GDL is a free technology (although ArchiCAD itself is a commercial software) and as such anyone can develop their own objects if they choose to do so. But this doesn't mean that all objects created in GDL has to be free, there's a good amount of providers who offer professional objects commercially.

One of the many advantages of GDL is its forward compatibility, which means that an ArchiCAD library part created in a lower version can be opened with the latest version of the software.

Opening an existing object and looking through its code might scare you off but believe me when I say that learning GDL is a lot easier than it looks.

In fact, learning GDL is so much easier with the help of the following resources:

GDL Cookbook 3This book is how I started to learn coding GDL. It follows a somewhat familiar approach to what you'd expect from a "For Dummies" book. Highly recommended for beginners who are looking to start GDL content creation.
GDL Cookbook 4This version of the GDL Cookbook is still a work in progress. It follows the same easy-to-learn format of the Cookbook 3 but with updated content.
Cadimage GDL HandbookAnother book that focuses on GDL and its many syntax. Its not entirely a For Dummies kind of handbook like the GDL Cookbook. There's a good amount of very technical codes and examples.
Graphisoft GDL CenterGDL Center is an online repository of GDL topics curated by Graphisoft. It has improved a lot from its previous iterations and is a good resource if you want to look deeper on GDL technicalities.
noscriptgdlAn series of online articles that walks you through on how to create GDL with very little coding required. Topics are categorized based on GDL basics, some scripting required, more scripting required, modeling and saving tips. Very handy for beginners who are anxious on coding GDL.

GDL enables you to create precise objects that could be missing from any of the resources available. Having this capability alone could improve your project deliverables considerably.

Now, for the long version...

GDL is similar in many ways to BASIC, certain syntax and logic are used on both programming language. BASIC became popular in mid-1970s to 1980s, most computers came with BASIC as their primary programming language and operating environment.

The most influential achievement of BASIC is the introduction of Microsoft's Visual Basic. This then evolved into VBScript in 1996 and Visual Basic .NET in 2001, to which the latter has essentially the same power as C# and Java but with syntax that reflects the original Basic language.

BASIC became popular due to its core benefit, ease of use. As such, it was widely used during the early home computer era. In fact, there are bits and pieces of BASIC incarnations implemented on varying technologies likeApple's App Store, Android devices, Basic, programmable calculators, Nintendo Famicom, just to mention a few.

GDL is similar in many ways to BASIC, certain syntax and logic are used on both programming language.

The Coordinate System: X, Y, Z

GDL can be a 2D object, a 3D object or both! All the elements within a library object is created via the use of a coordinate system, this can be in either 2D or 3D space. Depending on the object you are creating, this can involve the location of your elements that are always specified with an X, Y and Z coordinates.

The GDL environment gives you an environment and a cursor, quite similar to an ArchiCAD project where you have the model space and mouse. For you to start building up your project in ArchiCAD, you'd normally place elements by using your mouse within the model space. This is exactly the same when you start working in GDL, but instead of using a mouse you start instructing the software where your cursor go with a series of commands.

You create elements in a space based on your global coordinates and local coordinates. For ArchiCAD users, Global coordinates is what we commonly call the origin of your project. The Local coordinates is your moving cursor.

Save Selection As...

Save Selection as... is an elegant solution to quickly create simple custom objects

You don't always have to create objects purely in GDL. In fact, there are times where I have to resort in modeling elements within ArchiCAD then later on using the Save Selection as... feature to create an object. Then later on modifying the necessary codes to suit what I need or to make it parametric.

Personally, I prefer to create objects from scratch.

There's a good amount of resources (written and in video format) that can walk you through on how to convert existing objects of differing formats (i.e.: DWG, IFC, 3DS, SKP, etc.) into an ArchiCAD object. This playlist is a good start: Eric Bobrow | Creating and Customizing Library Parts. There are certain situations where modeling elements with ArchiCAD basic tools and saving it as an object can be an adequate approach to start building-up your library database.

Personally though, I prefer to create objects from scratch. Coding your objects from scratch can help you prepare for necessary parameters and codes that you might consider to include in the future. It enables you to develop your object to include features that you might end up needing once you start using the object in your projects. Adding additional parameters and features on your objects are so much easier if you created it from scratch!

Since there are an ample amount of resources online focusing on creating 3D objects for ArchiCAD, I wanted to share an example on how to create your own 2D symbol object. Interested? Read on...

Draw IRL, then start coding in GDL

Creating your custom GDL object doesn't have to always start immediately in the GDL interface. In fact, it is always a good idea to draw or sketch your object on paper. This helps you to identify the parts which can help you create a structure of your object. The image below shows you an example of how you can split a basic 2D symbol object (i.e.: drop symbol) into small parts and figure out what to call each. Once you have identified the parts that make up your object, you can start coding them in the appropriate scripts window.

Start creating a new object...

Create a new object in ArchiCAD by clicking File New Libraries and Objects New Object.... Select the appropriate Subtype of your object, for this case I selected Library Global Settings: Select Subtype... General GDL Object Documentation Element Drawing Symbol Library Global Settings. Put your name under Author and key-in appropriate descriptons and keywords accordingly.

Once you are done, click the Parameters button and copy the parameters on the image below. The name doesn't need to be copied exactly as it is but the variable needs to be exactly the same. This is very important as the variables will be the same as what will be used for the codes on the 2D and Parameter scripts.

Note that GDL uses meter as default units, but you can use inches if you want to. All the numeric values you'll see here are based on millimeter for the Parameters, meter on the 2D and Parameters scripts.

Code your GDL parameters with easy to identify keywords, drawing them before you start coding is always a good idea

All set? Let's start with the 2D script...

HOTSPOT2 should always be included on all of your library objects, there should be no exemptions! This lets you create clickable nodes that enables your users to easily select the objects you create. In the example below, I have created 4 lines of hotspot commands to create nodes based on the lines of the symbol. This helps the user to easily place the 2D symbol in their projects, for this case in the middle of doors or along slabs that requires a drop symbol.

!Default syntax: HOTSPOT2 xvalue, yvalue

You will notice on the above code that the first line includes a ! symbol, followed by the default syntax for hotspot example. It is always a good habit to practice this in all your codes, this is especially helpful for beginners. This type of remark lets you easily identify what the numbers or variables represent. This technique is what's commonly known as comment in computer programming environment.

In this case, instead of using a numerical value for the hotspots, use the values for A and B parameters. This makes it easier to change the size of these lines in the future if we need to instead of changing the values one by one.

It is also a good idea to enable users the ability to change the PEN color of parts within your object. For this case, we want the user to be able to change the pen color of the lines and arrow head.

!Default syntax: PEN indexPen
PEN dp_linepen

Starting with a LINE2 syntax, this draws the first line horizontally from origin towards the right. Instead of a numeric value use the variable A instead, which is equivalent to 250mm. To draw the next line, move the cursor from origin to the end point of the 1st line. This is done using ADD2 syntax and use the A parameter for the xvalue.

!Default syntax: LINE2 xStartPoint, yStartPoint, xEndPoint, yEndPoint
!1st Line, Horizontal
LINE2 A, 0, 0, 0
!Default syntax: ADD2 xvalue,yvalue
!Move the cursor to the end point of 1st Line
ADD2 A, 0

Continue drawing the next 2 lines to complete the drop line symbol. After each LINE2 command, make sure to move the cursor to the end of each line before continuing with the next by using the ADD2 syntax.

!2nd Line, Vertical
LINE2 0, -B, 0, 0
!Move the cursor to the end point of 2nd Line
ADD2 0, -B

!3rd Line, Horizontal
LINE2 A, 0, 0, 0
!Move the cursor to the end point of 3rd line
ADD2 A, 0

At the end of the 3rd line, you can start drawing the arrowheads individually, for this case use the ROT2 syntax to change the axis into a 45 degree angle. Use dp_arrowhead as the value for the arrowhead length itself.

!Default syntax: ROT2 anglevalue
!1st Line of the arrow head
ROT2 -45
LINE2 -dp_arrowhead, 0, 0, 0

At this point, change the angle to the other side to complete the arrow head. Use the DEL syntax to undo the cursor movement one at a time by specifying a numeric value (i.e.: DEL 1, DEL 2, and so on). All that's left to do now is to complete the other half of the arrow head.

!Default syntax: DEL value
!Move back the cursor to end point of 3rd Line
!2nd Line of the Arrowhead
ROT2 45
LINE2 -dp_arrowhead, 0, 0, 0

Since the cursor is at the end point of the 3rd line, we want the cursor back to the origin. This is done by using a DEL 4 syntax. Note that ADD2 and ROT2 are considered cursor movements and have to be considered whenever you are using the DEL syntax.

!Move back the cursor to origin

Start identifying the PEN and FILL parameters to setup the circle marker.

!Setup the circle marker parameters
PEN dp_fillpen
!Default syntax: FILL value
FILL dp_filltype

To draw the circle marker, use the POLY2_B syntax. n value is the number of points that makes up the shape, +1 point to close the shape. While framefill lets you choose whether lines and/or fills are shown, the value of 7 is used to make the object show everything. Using the dp_circlesize parameter here makes it easier for us to code the shape, this also enables the user to change the circle marker size if needed.

!Draw the circle marker
!Default syntax: POLY2_B n, framefill, x1, y1, ..., xn, yn
POLY2_B 7, 7+64, dfillp, dfillt,
	0, -dp_circlesize, 1,
	0, 0, 901,
	0, 180, 4001,
	0, dp_circlesize, 1,
	0, 0, 901,
	0, 180, 4001,
	0, -dp_circlesize, -1

At this point, inserting an IF statement enables the user the ability to turn off or on the text itself. Make sure that the text codes are inside the IF ~ ENDIF statement for this to work.

!IF statement to give an option to turn text on or off
IF dp_displaytext then

Setup the text parameters with appropriate PEN syntax, thus giving the user freedom to choose which pen color is appropriate. DEFINE STYLE sorts out the appropriate style and size of the text itself. ROT2 syntax lets the user rotate the text if needed.

!Setup the text parameters
PEN dp_textpen
DEFINE STYLE "dp_textstyle" dp_fontstyle, dp_fontsize, 8, 0
SET STYLE "dp_textstyle"
ROT2 dp_textrot

To end the 2D script, don't forget to put an ENDIF syntax.

!Close the IF statement

Put in a single line of code in the Master script to give the user ability to change the style of the dp_text.

VALUES 'dp_fontstyle' 'Arial', 'Times New Roman', 'Verdana', 'Courier'

To finish up the object, you could put in some logic on the Parameter script.

IF NOT(dp_displaytext) then
	LOCK "dp_text", "dp_fontstyle", "dp_fontsize", "dp_fontsize", "dp_textpen1", "dp_textrot"
	HIDEPARAMETER "dp_droptext", "dp_fontstyle", "dp_fontsize", "dp_fontsize", "dp_textpen", "dp_textrot"

The code above checks the dp_displaytext parameter is turned on or off. If it is off, appropriate parameters are locked or hidden. This helps the user to focus on the parameters that are relevant instead of changing values that have no effect on the current available settings.

Upgrade your Object

There are a lot of things that you can do to improve your object further. Personally, I shorten the values of the parameters that I use by converting them to short codes within the Master script.

dln1 = A
dln2 = B
dln3 = A
dahd = dp_arrowhead
dcirz = dp_circlesize
dlpen = dp_linepen
dtpen = dp_textpen

ddist = dp_displaytext

dfillp = dp_fillpen
dfillt = dp_filltype

dropt = dp_text

In fact, you can code an interactive interface instead of just giving the user a generic parameters list. This makes your object user friendly and more professional.

You can improve the usability of your object further by coding an interface in place of the default parameters list

In anyone's ArchiCAD career, there comes a point where you need a certain object and most of the resources you know doesn't have what you require. Don't be scared to learn GDL and you'll soon realize how powerful it is. All the pros that comes with learning GDL outweighs its cons, you can pretty much create any type of object you'd ever need in all your projects.

Add new comment