Difference between revisions of "Expressions"
m (use VersionMinus) 
(Removed Code template around master#modelConstants.Length to avoid strange syntax highlighting.) 

Line 914:  Line 914:  
<!T:65>  <!T:65>  
−  +  master#modelConstants.Length  
<!T:66>  <!T:66> 
Revision as of 18:45, 23 November 2020
Overview
It is 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 notation for the standard mathematical operators 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.
Operators and functions are unitaware, 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). These units are currently recognized.
You can use predefined constants and functions.
Referencing objects
You can reference to an object by its Name
or by its Label
. In the case of a Label
, it must be enclosed in double <<
and >>
symbols, such as <<Label>>
.
You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use Cylinder.Height
or <<Long_name_of_cylinder>>.Height
.
To reference list objects, the syntax is <<object_label>>.list[list_index]
or object_name.list[list_index]
. If you want for example reference a constraint in a sketch, do it this way <<MySketch>>.Constraints[16]. If you are in the same sketch you can omit its name and just use Constraints[16].
Note: The index starts with 0, therefore constraint 17 has the index 16.
For more info about referencing objects, see this section.
The following operators are supported:
Operator  Description 

+  Addition 
  Subtraction 
*  Multiplication 
/  Floating point Division 
%  Remainder 
^  Exponentiation 
Supported Constants
The following constants are supported:
Constant  Description 

e  Euler's number 
pi  Pi 
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 degree as their default unit. For radian measure, add rad following the first value in an expression. So e.g. cos(45) is the same as cos(pi rad / 4). Expressions in degrees can use either deg or °, e.g. 360deg  atan2(3; 4) or 360°  atan2(3; 4). If an expression is without units and needs to be converted to degrees or radians for compatibility, multiply by 1 deg, 1 ° or 1 rad as appropriate, e.g. (360  X) * 1deg; (360  X) * 1°; (0.5 + pi / 2) * 1rad.
These trigonometric functions are supported:
Function  Description  Value range 

acos(x)  Arc cosine  1 <= x <= 1 
asin(x)  Arc sine  1 <= x <= 1 
atan(x)  Arc tangent  all 
atan2(x, y)  Arc tangent of x/y  all, except y = 0 
cos(x)  Cosine  all 
cosh(x)  Hyperbolic cosine  all 
sin(x)  Sine  all 
sinh(x)  Hyperbolic sine  all 
tan(x)  Tangent  all, except of x = n·90 with n = integer 
tanh(x)  Hyperbolic tangent  all 
These functions for exponentiation and logarithmization are supported:
Function  Description  Value range 

exp(x)  Exponential function  all 
log(x)  Natural logarithm  x > 0 
log10(x)  Common logarithm  x > 0 
pow(x, y)  Exponentiation  all 
sqrt(x)  Square root  x >= 0 
These functions for rounding, truncation and remainder are supported:
Function  Description  Value range 

abs(x)  Absolute value  all 
ceil(x)  Ceiling function smallest integer value greater than or equal to x  all 
floor(x)  Floor function, largest integer value less than or equal to x  all 
mod(x, y)  Remainder after dividing x by y  all, except y = 0 
round(x)  Rounding to the nearest integer  all 
trunc(x)  Truncation to the nearest integer  all 
Statistical / Aggregate Functions
Aggregate 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), for example average(B1:B8).
These aggregate functions are supported:
Function  Description  Value range 

average(x:y)  Arithmetic mean of values in cells x through y; sum(x:y) / count(x:y)  all 
count(x:y)  Counting of cells from x through y  all 
max(x:y)  Maximum value in cells x through y  all 
min(x:y)  Minimum value in cells x through y  all 
stddev(x:y)  Standard deviation of values in cells x through y  all 
sum(x: y)  Sum of values in cells x through y  all 
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 nonzero (true). Note that enclosing the conditional expression in parentheses is currently considered an error. version 0.19 and below
The following relational operators are defined:
Unit  Description 

==  equal to 
!=  not equal to 
>  greater than 
<  less than 
>=  greater than or equal to 
<=  less than or equal to 
Units
Units can directly be used in expressions. The parser connects them to the previous value. So '2mm' or '2 mm' is valid while ' mm' is invalid because there is no preceding value.
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.
In some cases it works even without a unit, for example if you have e.g. in spreadsheet cell B1 just the number 1.5 and refer to it for a pad height. This only works because the pad height predefines the unit mm that is used if no unit is given. It will nevertheless fail if you use for the pad height e.g. Sketch1.Constraints.Width  Spreadsheet.B1 because Sketch1.Constraints.Width has a unit and Spreadsheet.B1 has not.
Units with exponents can directly be entered. So e.g. mm^3 will be recognized as mm³ and m^3 will be recognized as m³.
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 

mmol  Millimole 
mol  Mole 
Angle:
Unit  Description 

°  Degree; alternative to the unit deg 
deg  Degree; alternative to the unit ° 
rad  Radian 
gon  Gradian 
S  Second of arc 
″  Second of arc; alternative to the unit S 
M  Minute of arc 
′  Minute of arc; alternative to the unit M 
Current:
Unit  Description 

mA  Milliampere 
A  Ampere 
kA  Kiloampere 
MA  Megaampere 
Electrical Capacitance:
Unit  Description 

pF  Picofarad, introduced in version 0.19 
nF  Nanofarad, introduced in version 0.19 
uF  Microfarad; alternative to the unit µF, introduced in version 0.19 
µF  Microfarad; alternative to the unit uF, introduced in version 0.19 
mF  Millifarad, introduced in version 0.19 
F  Farad; 1 F = 1 s^4·A^2/m^2/kg, introduced in version 0.19 
Electrical Conductance:
Unit  Description 

uS  Microsiemens; alternative to the unit µS, introduced in version 0.19 
µS  Microsiemens; alternative to the unit uS, introduced in version 0.19 
mS  Millisiemens, introduced in version 0.19 
S  Siemens; 1 S = 1 s^3·A^2/kg/m^2, introduced in version 0.19 
Electrical Inductance:
Unit  Description 

nH  Nanohenry, introduced in version 0.19 
uH  Microhenry; alternative to the unit µH, introduced in version 0.19 
µH  Microhenry; alternative to the unit uH, introduced in version 0.19 
mH  Millihenry, introduced in version 0.19 
H  Henry; 1 H = 1 kg·m^2/s^2/A^2, introduced in version 0.19 
Electrical Resistance:
Unit  Description 

Ohm  Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2, introduced in version 0.19 
kOhm  Kiloohm, introduced in version 0.19 
MOhm  Megaohm, introduced in version 0.19 
Electric Charge:
Unit  Description 

C  Coulomb; 1 C = 1 A·s, introduced in version 0.19 
Electric Potential:
Unit  Description 

mV  Millivolt 
V  Volt 
kV  Kilovolt 
Energy / Work:
Unit  Description 

mJ  Millijoule 
J  Joule 
kJ  Kilojoule, introduced in version 0.19 
eV  Electronvolt; 1 ev = 1.602176634e19 J, introduced in version 0.19 
keV  Kiloelectronvolt, introduced in version 0.19 
MeV  Megaelectronvolt, introduced in version 0.19 
kWh  Kilowatt hour; 1 kWh = 3.6e6 J, introduced in version 0.19 
Ws  Watt second; alternative to the unit Joule 
VAs  Voltamperesecond; alternative to the unit Joule 
CV  Coulombvolt; alternative to the unit Joule 
cal  Calorie; 1 cal = 4.184 J, introduced in version 0.19 
kcal  Kilocalorie, introduced in version 0.19 
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 
Magnetic Field Strength:
Unit  Description 

Oe  Oersted; 1 Oe = 79.57747 A/m, introduced in version 0.19 
Magnetic Flux:
Unit  Description 

Wb  Weber; 1 Wb = 1 kg*m^2/s^2/A, introduced in version 0.19 
Magnetic Flux Density:
Unit  Description 

G  Gauss; 1 G = 1 e4 T, introduced in version 0.19 
T  Tesla; 1 T = 1 kg/s^2/A, introduced in version 0.19 
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 
kW  Kilowatt, introduced in version 0.19 
VA  Voltampere 
Pressure:
Unit  Description 

Pa  Pascal 
kPa  Kilopascal 
MPa  Megapascal 
GPa  Gigapascal 
mbar  MilliBar, introduced in version 0.19 
bar  Bar, introduced in version 0.19 
uTorr  Microtorr; alternative to the unit µTorr 
µTorr  Microtorr; alternative to the unit uTorr 
mTorr  Millitorr 
Torr  Torr; 1 Torr = 133.32 Pa 
psi  Poundforce per square inch; 1 psi = 6.895 kPa 
ksi  Kilopoundforce per square inch 
Mpsi  Megapoundforce per square inch, introduced in version 0.19 
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 
Hz (1/s)  Hertz, introduced in version 0.19 
kHz  Kilohertz, introduced in version 0.19 
MHz  Megahertz, introduced in version 0.19 
GHz  Gigahertz, introduced in version 0.19 
THz  Terahertz, introduced in version 0.19 
Torque:
Unit  Description 

Nm  Newton metre 
Volume:
Unit  Description 

ml  Milliliter, introduced in version 0.19 
l  Liter 
cft  Cubicfoot, introduced in version 0.19 
Special imperial units:
Unit  Description 

mph  Miles per hour, introduced in version 0.19 
sqft  Square foot, introduced in version 0.19 
The following commonly used units are not yet supported:
Unit  Description  Alternative 

°C  Celsius  [°C] + 273.15 K 
°F  Fahrenheit;  ([°F] + 459.67) × 5/9 
u  Atomic mass unit; alternative to the unit 'Da'  1.66053906660e27 kg 
Da  Dalton; alternative to the unit 'u'  1.66053906660e27 kg 
sr  Steradian  not directly 
lm  Lumen  not directly 
lx  Lux  not directly 
px  Pixel  not directly 
Reference To CADData
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:
CADData  Call in expression  Result 

Parametric Length of a PartWorkbench Cube  Cube.Length

Length with units mm

Volume of the Cube  Cube.Shape.Volume

Volume in mm³ without units

Type of the Cubeshape  Cube.Shape.ShapeType

String: Solid 
Label of the Cube  Cube.Label

String: Label 
xcoordinate of center of mass of the Cube  Cube.Shape.CenterOfMass.x

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

Documentwide 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 (rightclick on cell). Then they can be accessed from any expression just as any other object property.
Crossdocument linking
It is possible (with limitations) to define a Property of an object in your current document (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the Length of a Part Cube, etc. in one document can be defined by an Expression that references the X Placement value or another Property of an object contained in a different 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. For example, assuming you name the master document "master
", the spreadsheet "modelConstants
", and give a cell an aliasname "Length
", you can then access the value as:
master#modelConstants.Length
Note: that the master document must 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 workaround, 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.
 As stated above, 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.
 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
 FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics
 Modules: Builtin modules, Units, Quantity
 Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
 Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC
 Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
 Scenegraph: Coin (Inventor) scenegraph, Pivy
 Graphical interface: Interface creation, Interface creation with UI files, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
 Macros: Macros, How to install macros
 Embedding: Embedding FreeCAD, Embedding FreeCADGui
 Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)
 Hubs: User hub, Power users hub, Developer hub