Expressions

From FreeCAD Documentation
Revision as of 19:41, 21 September 2015 by Eivindkvedalen (talk | contribs) (Created page with "{{Version|0.16}} It is now possible to drive properties using mathematical expressions. From the GUI, spin boxes or input fields, that are bound to properties contain a blue...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

introduced in version 0.16

It is now possible to drive 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 it.

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).

Supported Functions

In expressions, the following functions are supported, taking one or two arguments: abs, acos, asin, atan, atan2, cos, cosh, exp, log, log10, mod, pow, sin, sinh, sqrt, tan, tanh, ceil, floor, trunc, and round.

Trigonometric functions use degrees as its default unit; supply "rad" if you want them to use radians.

The constants pi and e are predefined.

The conditional statement works like this: = condition ? resultTrue : resultFalse

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

Formulas are written as e.g follows: 2 * Length, where Length is a property in the object holding the expression.

Reference To CAD-Data

It is possible to use data from other parts of the construction in an expression. The syntax for a reference to a field is as follows: object.property. If the property is a compound of fields, they can be accessed by e.g object.property.field.

The following table shows some examples:

CAD-Data Call in expression Result
Parametric Length of a Part-Workbench Cube Cube.Length Length with units mm
Volume of the Cube Cube.Shape.Volume Volume in mm³ without units
Type of the Cube-shape Cube.Shape.ShapeType String: Solid
Label of the Cube Cube.Label String: Cube
x-coordinate of center of mass of the Cube Cube.Shape.CenterOfMass.x x-coordinate in mm without units
Value of constraint in a sketch Constraints.Width Numeric value of the named constraint 'Width' in the sketch

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.

Known issues / remaining tasks

  • The dependency graphs is based on the relationship between document objects, not properties. This means that you cannot provide data to and query the same object in e.g a spreadsheet, even though there are no cyclic dependency when just the properties are considered. As a work-around, use multiple spreadsheets, e.g one to drive your model, and one for reporting.
  • There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queries, etc.
  • The Data properties tab does not yet support expressions.
  • Renaming aliases or inserting/removing rows/columns in a spreadsheet will not propagate changes to expressions in the document.