Quick Guide: Geometry Scripting

Geometry script­ing is really a cool thing! It allows you to create highly cus­tomized geometry parts — parts that are often impos­si­ble to create with the typical capa­bil­i­ties of a graph­i­cal user inter­face (GUI). Most of the CAD tools on the market offer at least some basic pos­si­bil­i­ties to write small programs or scripts which allow you to regen­er­ate geometry auto­mat­i­cally or to run repet­i­tive tasks with a single-click macro. Usually, these scripts can be recorded, or they are manually created by the user within some sort of pro­pri­etary pro­gram­ming envi­ron­ment. Some examples for tools with these script­ing capa­bil­i­ties are Space­Claim, FreeCAD or the online CAD platform Onshape with its Fea­ture­Script.

Script­ing and automa­tion of geometry gen­er­a­tion is THE core com­po­nent of CAESES®

With our CAD and opti­miza­tion platform CAESES®, this automa­tion phi­los­o­phy is really how things started off 10 years ago. This platform is nowadays a com­pletely command-based and object-oriented struc­ture, ded­i­cated to getting scripted and to automate geometry-related tasks. On top of this object-oriented struc­ture, we put an intu­itive GUI which is what the user sees in the first place and how they typ­i­cally start.

However, the fun part and the real magic comes up as soon as you dig into the under­ly­ing command concept. This quick guide gives you an overview of this concept and the pro­gram­ming capa­bil­i­ties that are inside of CAESES®.

Object Types and Commands

So let’s take a quick look at the foun­da­tion of CAESES®: Basi­cally every­thing is an object with a certain type. For instance, if you create a 3D point with a name ​“p1” it appears in the object tree and its type is F3DPoint (all types start with an ​“F”). As soon as you select the point, you can set the x‑, y- and z‑coordinates.

Ok, this is not a big deal. However, if you click on the help icon next to the editor field, you can see which command is actually trig­gered in the back­ground. In our case, it is the type command ​“setX()” of the point. In other words, as soon as you enter a value for x‑property, the command ​“p1.setX(0.5)” is executed.

Ref­er­ence Manual

There is also doc­u­men­ta­tion for each geometry type avail­able to check the commands and the type hier­ar­chy. Just click on the type icon in the object editor so that the doc­u­men­ta­tion appears in the main window. It gives you the creation commands, the property commands such as the setX()-command and more functions.

Hier­ar­chy

Hang on, did you say hier­ar­chy? As already men­tioned, CAESES® is an object-oriented platform — similar to what you can find the world of pro­gram­ming where you imple­ment classes. Child types can derive prop­er­ties and methods from parent types. As an example, the circle (FCircle) is a special type of a curve (FCurve). Other curve types are e.g. bspline curves or inter­po­la­tion curves. All these spe­cial­ized curves can use methods that are derived from the parent curve type.

Here are some examples: You can cal­cu­late the length of any curve using a ​“getLength()” command, cal­cu­late the cur­va­ture, grab a position on the curve, or ask for the start and end location. All these commands come from the parent type FCurve and they are avail­able for all derived curve types. On the other hand, only the circle has the command ​“getRa­dius()”.

Using Commands in the GUI

So far we know where to find the commands. How can we use them? Before we jump to the geometry script­ing, let’s take a look at the GUI first. You can directly define so-called expres­sions in any editor where you can make use of these type commands:

Commands can also be trig­gered through the CAESES® console widget if you want to try it out. Simply select the object, start the command with a dot and type e.g. “.setRadius(0.5)” to change the radius of the selected circle object. Alter­na­tively, if nothing is selected, use the full name plus the command, e.g. ​“circle.setRadius(0.5)”. That’s exactly what you do when writing a script for the batch mode of CAESES®, i.e. the non-GUI mode. We will talk about it in a minute.

The Feature Def­i­n­i­tion Editor

Ok, after this short intro­duc­tion, let’s move forward to automa­tion and geometry script­ing: CAESES® provides a script­ing envi­ron­ment that gives you auto-com­ple­tion, com­pre­hen­sive debug­ging pos­si­bil­i­ties and pre-defined code-snippets. An editor helps you to define your cus­tomized features using the entire command set of the platform. See the fol­low­ing screen­shot for an example of a feature def­i­n­i­tion where a simple circular arc with the name ​“inlet” is created.

The variable ​“R” has been defined before­hand in the ​“Argu­ments” tab of this editor, it will be user input. The result of this code snippet is given in the next screen­shot where an instance of this feature def­i­n­i­tion is shown in the tree:

The object ​“test” is an instance of the feature def­i­n­i­tion ​“myCompo­nent”, and the only input is the radius ​“R”. This feature def­i­n­i­tion is now visible in the tree, right below the node ​“Feature Def­i­n­i­tions” and can be exported e.g. for re-use. It also can be modified at any time and all existing instances will be auto­mat­i­cally updated to receive the changes.

The fol­low­ing video is taken from our tutorial section and shows the creation of a simple pipe geometry. In the first part, it is created inter­ac­tively in the GUI. In the second part of the video, the same geometry is scripted and wrapped into a feature:

Control State­ments

Compared to an inter­ac­tive geometry setup in the object tree, you can use a variety of control state­ments which gives you unlim­ited pos­si­bil­i­ties. It results in a higher flex­i­bil­ity and allows you to create any kind of complex geometry. CAESES® offers the fol­low­ing statements:

• if/​else
• while
• loop
• for each
• switch

Math­e­mat­i­cal Commands

In the doc­u­men­ta­tion browser of CAESES® you will find also a set of global commands such as math­e­mat­i­cal func­tions. These func­tions can also be used when you create your custom feature. Typical can­di­dates are:

• sin(), cos(), tan(), atan() etc.
• ln(), log()
• crossprod­uct(), dotproduct()
• floor(), ceil()
• min(), max(), modulo()
• pow(), sqrt()
• rand()

I/O File Processing

With CAESES® features, you can not only script geometry gen­er­a­tion process, but also make use of file I/O methods to write or read files. There is a blog post ​“Write your own export routine” that briefly shows you how this work. This a great and simple way to imple­ment pro­pri­etary import and export formats.

External Processes

What else can you do with this script­ing envi­ron­ment? Similar to typical pro­gram­ming lan­guages, there is also the pos­si­bil­ity to trigger external processes within such a feature. The feature waits for the process ter­mi­na­tion, and you can continue after­wards with e.g. col­lect­ing the result data. Here is an example where an external process is triggered:

Don’t panic. You don’t have to under­stand each detail from the feature def­i­n­i­tion above — we usually do not teach this in our basic training. It’s there just to let you know that this is possible with features in CAESES® ;-)

Batch Mode

All these features often wrap complex command sequences into a single object where you as the author define the input. Such an object can be used in the GUI, as a part of an assembly or to process any kind of repet­i­tive task.

Besides this, there is another inter­est­ing capa­bil­ity when it comes to script­ing and automa­tion: The batch mode of CAESES®. This mode does not start up the GUI and it is one reason why CAESES® is used in so many leading CAE com­pa­nies. It allows users to plug-in a powerful geometry engine into an existing design process without any serious workflow changes. As a result, new geometry design can­di­dates can be robustly gen­er­ated with a simple script call.

And how does it work? The design vari­ables of a CAESES® project are also just objects whose values can be changed by using a set()-command. Check out a typical control script to run CAESES® in the batch mode:

The command to run the batch mode is simply ​“CAESES_crt.exe turbocharger.fsc”. This script

1. opens the geometry setup (e.g. a para­met­ric tur­bocharger model),
2. changes the vari­ables accord­ing to the given values (typ­i­cally done by a third-part opti­miza­tion tool) and
3. exports the new geometry into the current project directory.

If you are inter­ested in this, there is plenty of infor­ma­tion about the batch mode in the CAESES user forum.

Example:
Solid Geometry Creation from an ASCII File

An example where geometry is gen­er­ated from an ASCII file is described in the article ​“Auto­mated Solid Gen­er­a­tion for Struc­tural Analysis at MTU Friedrichshafen”. Simple geometry data is read in using a pro­pri­etary format. From the data, a solid geometry is created auto­mat­i­cally. The entire process is scripted and auto­mated CAESES® using feature def­i­n­i­tions and func­tions for I/O, loops, control state­ments and geometry creator methods (API).

More Infor­ma­tion

Of course, this has been only an overview of the general concept and the main features. For an expert CAESES® user, these script­ing capa­bil­i­ties are essen­tial and really the stuff that makes CAESES® also a fun tool ;-) 

You can find several tutorial videos about script­ing and feature def­i­n­i­tions in our video section. There is also a post about meta surfaces, where feature def­i­n­i­tions play a central role for the creation of advanced sweep surfaces.

If you have more ques­tions, don’t hesitate to drop us a line.