Expressions

It is now possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon. Clicking on the icon or typing the equal sign (=) brings up the expression editor for that particular property.

A FreeCAD expression is a mathematical expression following normal notation for the standard mathematical operators (+, -, * and /) and functions as described below. In addition, the expression may reference other properties, and also use conditionals. Numbers in an expression may have an optional unit attached to them.

Numbers may use either a comma ',' or a decimal point '.' separating whole digits from decimals. When the decimal marker is used, it must be followed by at least one digit. Thus, the expressions 1.+2. and 1,+2, are invalid, but 1.0+2.0 and 1,0+2,0 are valid.

The constants pi and e are predefined, and must be written in lowercase.

Operators and functions are unit-aware, and require valid combinations of units, if supplied. For example, 2mm+4mm is a valid expression, while 2mm+4 is not (the reason for this is that an expression like 1in + 4 will most likely be interpreted as 1in + 4in by humans, but all units are converted to the SI system internally, and the system is not able to guess this).

General Mathematical Functions
The mathematical functions listed below are available.

Multiple arguments to a function may be separated by either a semicolon (';') or a comma followed by a space (", "). In the latter case, the comma is converted to a semicolon after entry. When a semicolon is used, no trailing space is necessary.

Trigonometric functions use degrees as their default unit; for radian measure, add rad following the first value in an expression. Example: cos(45) is the same as cos(pi rad / 4).

Statistical / Aggregating Functions
The aggregating functions listed below are supported. Aggregating functions take one or more arguments, separated by a semicolon ';' or a comma and a space ", ". Arguments may include references to cells in a spreadsheet; cell references consist of the (CAPITAL) row letter followed by the column number. Arguments may include ranges of cells (two cell references separated by a colon). Example: average(B1:B8)

Conditional Expressions
Conditional expressions are of the form ''condition ? resultTrue : resultFalse''

The condition is defined as an expression that evaluates to either 0 (false) or non-zero (true). The following comparison operators are defined: ==, !=, >, <, >=, and <=.

Reference To CAD-Data
It is possible to use data from the model itself in an expression. To reference a property use "object.property". If the property is a compound of fields, the individual fields can be accessed as "object.property.field".

The following table shows some examples:

Document-wide global variables
There is no concept of global variables in FreeCAD at the moment. Instead, arbitrary variables can be defined as cells in a spreadsheet using the Spreadsheet workbench, and then be given a name using the alias property for the cell (right-click on cell). Then they can be accessed from any expression just as any other object property.

Cross-document linking
It's possible that you have a spreadsheet in one document and reference values from there in other documents.

Important note: You use a document's name to reference it from other documents. Now, when saving the document the first time you choose a certain file name and this is usually different to "Unnamed1" (or its translated version) and then the links are lost after reopening it. So, it's recommended to create first the master document, create a spreadsheet, save and close it. After reopening the name is set to the above file name. Afterwards you can still make changes and save the file but you shouldn't rename it.

Then create the further documents where you want to add expressions to. Assuming you named the master document "master" you can access an alias like this: master#Spreadsheet.Length

Unfortunately, the integrated checker is more confusing than helping because it always gives parser errors or claims that this or that doesn't exist. So, just continue on typing. When you are finished and the content is correct the OK suddenly becomes active.

Of course, it's up to you to load the corresponding documents later when you want to change anything.

Known issues / remaining tasks

 * The dependency graph is based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. As a work-around, use multiple spreadsheets -- one to drive your model, and one for reporting.
 * The expression parser does not handle parentheses well, and is unable to properly parse some expressions. For example: "= (A1 > A2) ? 1 : 0" results in an error, while "= A1 > A2 ? 1 : 0" is accepted.  The expression "= 5 + ((A1>A2) ? 1 : 0)" cannot be entered in any form.
 * There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc.
 * Open bugs/tickets for Expressions can be found in the FreeCAD Bugtracker Expressions category