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 File:Sketcher Expressions.png. 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).
Supported Functions
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).
Description: Ceiling
Returns: The smallest integer value greater than or equal to x introduced in version 0.16
Description: Floor
Returns: The largest integer value less than or equal to x introduced in version 0.16
Description:
Returns: x rounded to the nearest integer introduced in version 0.16
Description: Truncate
Returns: x truncated to the nearest integer introduced in version 0.16
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)
Description: Number of cells from x through y
Returns: The number of cells from x through y, inclusive
Description: Standard deviation of values in cells x through y
Returns: Standard deviation
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 <=.
Units
Units can directly be used in expressions. The parser connects them the the previous value. So '2mm' or '2 mm' is valid while ' mm' is invalid because there is no preceding value.
If you have a variable with a name of a unit you must put the variable into << >> to prevent that it will be recognized as unit. For example if you have the dimension 'Sketch.Constraints.A' it would be recognized as unit ampere. Therefore you must write it in the expression as 'Sketch.Constraints.<<A>>'.
The following units are recognized by the expression parser:
Amount of substance:
Unit | Description |
---|---|
mol | Mole |
Angle:
Unit | Description |
---|---|
° | Degree; alternative to the unit deg |
deg | Degree; alternative to the unit ° |
rad | Radian |
gon | Gradian |
Current:
Unit | Description |
---|---|
mA | Milliampere |
A | Ampere |
kA | Kiloampere |
MA | Megaampere |
Energy / Work:
Unit | Description |
---|---|
J | Joule |
Ws | Watt second; alternative to the unit Joule |
VAs | Volt-ampere-second; alternative to the unit Joule |
Force:
Unit | Description |
---|---|
mN | Millinewton |
N | Newton |
kN | Kilonewton |
MN | Meganewton |
lbf | Pound of force |
Length:
Unit | Description |
---|---|
nm | Nanometer |
um | Micrometer; alternative to the unit µm |
µm | Micrometer; alternative to the unit mu |
mm | Millimeter |
cm | Centimeter |
mm | Millimeter |
dm | Decimeter |
m | Meter |
km | Kilometer |
mil | Thousandth of an inch; alternative to the unit thou |
thou | Thousandth of an inch; alternative to the unit mil |
in | Inch |
ft | Foot; alternative to the unit ' |
' | Foot; alternative to the unit ft |
yd | Yard |
mi | Mile |
Luminous intensity:
Unit | Description |
---|---|
cd | Candela |
Mass:
Unit | Description |
---|---|
ug | Microgram; alternative to the unit µg |
µg | Microgram; alternative to the unit ug |
mg | Milligram |
g | Gram |
kg | Kilogram |
t | Tonne |
oz | Ounce |
lb | Pound; alternative to the unit lbm |
lbm | Pound; alternative to the unit lb |
st | Stone |
cwt | Hundredweight |
Power:
Unit | Description |
---|---|
W | Watt |
VA | Volt-ampere |
Pressure:
Unit | Description |
---|---|
Pa | Pascal |
kPa | Kilopascal |
MPa | Megapascal |
GPa | Gigapascal |
uTorr | Microtorr; alternative to the unit µTorr |
µTorr | Microtorr; alternative to the unit uTorr |
mTorr | Millitorr |
Torr | Torr |
psi | Pound-force per square inch |
ksi | Kilopound-force per square inch |
Temperature:
Unit | Description |
---|---|
uK | Microkelvin; alternative to the unit µK |
µK | Microkelvin; alternative to the unit uK |
mK | Millikelvin |
K | Kelvin |
Time:
Unit | Description |
---|---|
s | Second |
min | Minute |
h | Hour |
Torque:
Unit | Description |
---|---|
Nm | Newton metre |
Volume:
Unit | Description |
---|---|
l | Liter |
The following commonly used units are not yet supported:
Unit | Description | Alternative |
---|---|---|
C | Coulomb | none |
V | Volt | none |
eV | Electronvolt | 1.602176634e-19 J |
kJ | Kilojoule | 1000 J |
MJ | Megajoule | 1000 J |
kWh | Kilowatt hour | 3600000 J |
u | Atomic mass unit; alternative to the unit 'Da' | 1.66053906660e-27 kg |
Da | Dalton; alternative to the unit 'u' | 1.66053906660e-27 kg |
cal | Calorie | 4.184 J |
kcal | Kilocalorie | 4184 J |
uA | Microampere; alternative to the unit µA | 0.001 mA |
µA | Microampere; alternative to the unit uA | 0.001 mA |
nA | Nanoampere | 0.000001 mA |
ng | Nanogram | 0.001 ug |
Mpsi | Megapound-force per square inch | 1000 ksi |
unknown but recognized: CV
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:
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: Label |
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, if the expression is used in the sketch itself. |
Value of constraint in a sketch | MySketch.Constraints.Width | Numeric value of the named constraint 'Width' in the sketch, if the expression is used outside of the sketch. |
Value of a spreadsheet alias | Spreadsheet.Depth | Value of the alias "Depth" in the spreadsheet "Spreadsheet" |
Value of a local property | Length | Value of the Length property in e.g a Pad object, if the expression is used in e.g Length2 in the same object. |
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 is possible to reference a spreadsheet in one document from another document.
A document's name is used to reference it from other documents. When saving a document the first time, you choose a file name; this is usually different from the initial default "Unnamed1" (or its translated equivalent). To prevent links being lost when the master document is renamed upon saving, it is recommended that you first create the master document, create a spreadsheet inside it, and save it. Subsequently, you can still make changes to the file and its spreadsheet but you should not rename it.
Once the master document with the spreadsheet is created and saved (named), it is safe to create dependent documents. Assuming the master document was named "master", the spreadsheet was renamed "modelConstants", and a cell was given an alias-name "Length", the value may be accessed as "master#modelConstants.Length". Note that the master document must always be loaded for the values in the master to be available to the dependent document.
Unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the OK button will become 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.
- The names of Sketcher constraints must not contain any blanks when the value is calculated by an expression, see forum discussion.
- Open bugs/tickets for Expressions can be found in the FreeCAD Bugtracker Expressions category
- Getting started
- Installation: Download, Windows, Linux, Mac, Additional components, Docker, AppImage, Ubuntu Snap
- Basics: About FreeCAD, Interface, Mouse navigation, Selection methods, Object name, Preferences, Workbenches, Document structure, Properties, Help FreeCAD, Donate
- Help: Tutorials, Video tutorials
- Workbenches: Std Base, Assembly, BIM, CAM, Draft, FEM, Inspection, Material, Mesh, OpenSCAD, Part, PartDesign, Points, Reverse Engineering, Robot, Sketcher, Spreadsheet, Surface, TechDraw, Test Framework
- Hubs: User hub, Power users hub, Developer hub