Expressions
Overview
It is possible to define properties using mathematical expressions. In 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 using the standard mathematical operators, functions and predefined constants as described below. In addition, the expression may reference object 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 .
to separate 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. This also applies to references to object properties that have units, such as Length properties. Thus Pad001.Length + 1
is invalid since it adds a pure number to a property with length units, it requires Pad001.Length + 1mm
.
Some unit related errors can seem unintuitive, with expressions either being rejected or producing results that do not match the units of the property being set. Here are some examples:
1/2mm
is not interpreted as half a millimeter but as 1/(2mm)
, resulting in: 0.5 mm^1
.
sqrt(2)mm
is not valid because the function call is not a number. This has to be entered as sqrt(2) * 1mm
.
Function arguments
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.
Arguments may include references to cells in a spreadsheet. A cell reference consists of the cell's uppercase row letter followed by its column number, for example A1
. A cell may also be referenced by using the cell's alias instead, for example Spreadsheet.MyPartWidth
.
Referencing objects
You can reference an object by its DataName or by its DataLabel. In the case of a DataLabel, it must be enclosed in double <<
and >>
symbols, such as <<Label>>
.
You can reference any property of an object. For example, to reference a Cylinder's height, you may use Cylinder.Height
or <<Long_name_of_cylinder>>.Height
. To reference the object itself use the _self
pseudo property. For example, you may use Cylinder._self
or <<Label_of_cylinder>>._self
.
To reference list objects, use <<object_label>>.list[list_index]
or object_name.list[list_index]
. If you want for example to reference a constraint in a sketch, use <<MySketch>>.Constraints[16]
. If you are in the same sketch you may omit its name and just use Constraints[16]
.
Note: The index starts with 0, therefore Constraint17 has to be referenced as Constraints[16]
.
For more information about referencing objects, see Reference to CAD_data.
Supported constants
The following constants are supported:
Constant  Description 

e  Euler's number 
pi  Pi 
Supported operators
The following operators are supported:
Operator  Description 

+  Addition 
  Subtraction 
*  Multiplication 
/  Floating point Division 
%  Remainder 
^  Exponentiation 
Supported functions
General mathematical functions
The following mathematical functions are supported:
Trigonometric functions
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
.
Function  Description  Input range 

acos(x)

Arc cosine  1 <= x <= 1 
asin(x)

Arc sine  1 <= x <= 1 
atan(x)

Arc tangent, return value in the range 90° < value < 90°  all 
atan2(y; x)

Arc tangent of y/x accounting for quadrant, return value in the range 180° < value <= 180°  all, the invalid input x = y = 0 returns 0 
cos(x)

Cosine  all 
cosh(x)

Hyperbolic cosine  all 
sin(x)

Sine  all 
sinh(x)

Hyperbolic sine  all 
tan(x)

Tangent  all, except x = n*90 with n = odd integer 
tanh(x)

Hyperbolic tangent  all 
hypot(x; y)

Pythagorean addition (hypotenuse), e.g. hypot(4; 3) = 5  x and y >= 0 
cath(x; y)

Given hypotenuse, and one side, returns other side of triangle, e.g. cath(5; 3) = 4  x >= y >= 0 
Exponential and logarithmic functions
Function  Description  Input 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 
cbrt(x) introduced in version 0.21

Cubic root  all 
Rounding, truncation and remainder functions
Function  Description  Input 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, sign of result is that of the dividend.  all, except y = 0 
round(x)

Rounding to the nearest integer  all 
trunc(x)

Truncation to the nearest integer in the direction of zero  all 
Statistical / aggregate functions
Aggregate functions take one or more arguments.
Individual arguments to aggregate functions may consist of ranges of cells. A range of cells is expressed as two cell references separated by a colon :
, for example average(B1:B8)
or sum(A1:A4; B1:B4)
.
The cell references may also use cell aliases, for example average(StartTemp:EndTemp)
.
The following aggregate functions are supported:
Function  Description  Input range 

average(a; b; c; ...)

Average value of the arguments, same as sum(a; b; c; ...) / count(a; b; c; ...)  all 
count(a; b; c; ...)

Count of the arguments, typically used for cell ranges  all 
max(a; b; c; ...)

Maximum value of the arguments  all 
min(a; b; c; ...)

Minimum value of the arguments  all 
stddev(a; b; c; ...)

Standard deviation of the values of the arguments  all 
sum(a; b; c; ...)

Sum of the values of the arguments, typically used for cell ranges  all 
String manipulation
String identification
Strings are identified in expressions by surrounding them with opening/closing double chevrons (as are labels).
In following example, "TEXT" is recognized as a string : <<TEXT>>
String concatenation
Strings can be concatenated using the '+' sign.
Following example <<MY>> + <<TEXT>>
will be concatenated to "MYTEXT".
String conversion
Numerical values can be converted to strings with the str
function:
str(Box.Length.Value)
String formatting
String formatting is supported using the (old) %style Python way.
All %specifiers as defined in Python documentation.
As an example, supposing you have a default 10mmside cube named 'Box' (default FreeCAD naming), the following expression <<Cube length : %s>> % Box.Length
will expand to "Cube length : 10.0 mm"
For more than one %specifier use the following syntax: <<Cube length is %s and width is %s>> % tuple(Box.Length; Box.Width)
. Or use concatenation: <<Cube length is %s>> % Box.Length + << and width is %s>> % Box.Width
. Both will expand to "Cube length is 10.0 mm and width is 10.0 mm".
A FreeCAD sample file using string formatting is available in the forum
Object creation functions
The following objects may be created in expressions using the following functions:
Type  Function  Description 

Tuple

tuple(a; b; ...)

Example: tuple(2; 1; 2)

List

list(a; b; ...)

Example: list(2; 1; 2)

Vector

vector(x; y; z)

Create a vector using three unitless or Length unit values.
Example: 
create(<<vector>>; x; y; z)
 
Matrix

matrix( a_{11}; a_{12}; a_{13}; a_{14}; a_{21}; a_{22}; a_{23}; a_{24}; a_{31}; a_{32}; a_{33}; a_{34}; a_{41}; a_{42}; a_{43}; a_{44} ) 
Create a 4x4 matrix in rowmajor order:
A minimum of 1 argument can be supplied such as Example: 
create(<<matrix>>; a_{11}; a_{12}; ...; a_{44})
 
Rotation

rotation(axis; angle)

Create a Rotation by specifying its axis (Vector ) and angle (Angle unit or unitless), or three Euler angles α , β , γ .
Examples:

rotation(α; β; γ)
 
create(<<rotation>>; axis; angle)
 
create(<<rotation>>; α; β; γ)
 
Placement

placement(base; rotation)

Create a Placement with various parameters, including:
Examples:

placement(base; rotation; center)
 
placement(base; axis; angle)
 
placement(matrix)
 
create(<<placement>>; ...)

Vector functions
Functions: introduced in version 0.22.
Function / Operator  Description 

v1 + v2

Add two vectors. 
v1  v2

Subtract two vectors. 
v * s

Uniformly scale a vector by s .

vangle(v1; v2)

Angle between two vectors in degrees. 
vcross(v1; v2)

Cross product of two vectors . 
v1 * v2

Dot product of two vectors . 
vdot(v1; v2)
 
vlinedist(v1; v2; v3)

Distance between vector v1 and a line through v2 in direction v3 .

vlinesegdist(v1; v2; v3)

Distance between vector v1 and the closest point on a line segment from v2 to v3 .

vlineproj(v1; v2; v3)

Project vector v1 on a line through v2 in direction v3 .

vnormalize(v)

Normalize a vector to a unit vector. 
vplanedist(v1)

Distance between vector v1 and a plane defined by a point v2 and a normal v3 .

vplaneproj(v1)

Project vector v1 on a plane defined by a point v2 and a normal v3 .

vscale(v; sx; sy; sz)

Nonuniformly scale a vector by sx in the X direction, sy in the Y direction, and sz in the Z direction.

vscalex(v; sx)
 
vscaley(v; sy)
 
vscalez(v; sz)

Matrix functions
Rotation
and Placement
can each be represented by a Matrix
. The following functions all take in a Matrix
, Rotation
, or Placement
as their first parameter denoted in the table below by m
. The type of the returned object is the same as the object supplied in the first argument except when using mtranslate
on a Rotation
, in which case a Placement
will be returned.
Function  Description 

minvert(m)

Calculate the Inverse matrix. 
mrotate(m; rotation)

Rotate by either:

mrotate(m; axis; angle)
 
mrotate(m; α; β; γ)
 
mrotatex(m; angle)

Rotate around the X axis. 
mrotatey(m; angle)

Rotate around the Y axis. 
mrotatez(m; angle)

Rotate around the Z axis. 
mtranslate(m; vector)

Translate by a vector (Vector ) or X, Y, Z values. If a Rotation is translated, the returned object is a Placement .

mtranslate(m; x; y; z)
 
mscale(m; vector)

Scale by a vector (Vector ) or X, Y, Z values.

mscale(m; x; y; z)

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.
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 be used directly 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 whose name is that of a unit you must put the variable between << >>
to prevent it from being recognized as a unit. For example if you have the dimension Sketch.Constraints.A
it would be recognized as the 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; alternative to the unit ″ 
″  Second of arc; alternative to the unit S 
M  Minute of arc; alternative to the unit ′ 
′  Minute of arc; alternative to the unit M 
Current
Unit  Description 

mA  Milliampere 
A  Ampere 
kA  Kiloampere 
MA  Megaampere 
Electric capacitance
Unit  Description 

pF  Picofarad 
nF  Nanofarad 
uF  Microfarad; alternative to the unit µF 
µF  Microfarad; alternative to the unit uF 
mF  Millifarad 
F  Farad; 1 F = 1 s^4·A^2/m^2/kg 
Electric charge
Unit  Description 

C  Coulomb; 1 C = 1 A*s 
Electric conductivity
Unit  Description 

uS  Microsiemens; alternative to the unit µS 
µS  Microsiemens; alternative to the unit uS 
mS  Millisiemens 
S  Siemens; 1 S = 1 s^3·A^2/kg/m^2 
kS  KiloSiemens 
MS  MegaSiemens 
Electric inductance
Unit  Description 

nH  Nanohenry 
uH  Microhenry; alternative to the unit µH 
µH  Microhenry; alternative to the unit uH 
mH  Millihenry 
H  Henry; 1 H = 1 kg·m^2/s^2/A^2 
Electric potential
Unit  Description 

mV  Millivolt 
V  Volt 
kV  Kilovolt 
Electric resistance
Unit  Description 

Ohm  Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2 
kOhm  Kiloohm 
MOhm  Megaohm 
Energy/work
Unit  Description 

mJ  Millijoule 
J  Joule 
kJ  Kilojoule 
eV  Electronvolt; 1 eV = 1.602176634e19 J 
keV  Kiloelectronvolt 
MeV  Megaelectronvolt 
kWh  Kilowatt hour; 1 kWh = 3.6e6 J 
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 
kcal  Kilocalorie 
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 um 
mm  Millimeter 
cm  Centimeter 
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; alternative to the unit " 
"  Inch; alternative to the unit in 
ft  Foot; alternative to the unit ' 
'  Foot; alternative to the unit ft 
yd  Yard 
mi  Mile 
Luminous intensity
Unit  Description 

cd  Candela 
Magnetic flux
Unit  Description 

Wb  Weber; 1 Wb = 1 kg*m^2/s^2/A 
Magnetic flux density
Unit  Description 

G  Gauss; 1 G = 1 e4 T 
T  Tesla; 1 T = 1 kg/s^2/A 
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 
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; 1 Torr = 133.32 Pa 
psi  Poundforce per square inch; 1 psi = 6.895 kPa 
ksi  Kilopoundforce 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 
Hz (1/s)  Hertz 
kHz  Kilohertz, 
MHz  Megahertz 
GHz  Gigahertz 
THz  Terahertz 
Volume
Unit  Description 

ml  Milliliter 
l  Liter 
cft  Cubicfoot 
Special imperial units
Unit  Description 

mph  Miles per hour 
sqft  Square foot 
Unsupported units
The following commonly used units are not yet supported, for some an alternative is provided:
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 
Invalid characters and names
The expression feature is very powerful but to achieve this power it has some limitations concerning some characters. To overcome this, FreeCAD offers to use labels and reference them instead of the object names. In labels you can use almost all special characters.
In cases where you cannot use a label, such as the name of a sketch's constraints, you must be aware what characters are not allowed.
Labels
For labels there are no invalid characters, however some characters need to be escaped:
Characters  Description 

' , \ , "

Need to be escaped by adding \ in front of them.

For example, the label Sketch\002
must be referenced as <<Sketch\\002>>
.
Names
Names of objects like dimensions, sketches, etc. may not have the characters or character sequences listed below, otherwise the name is invalid:
Characters / Character sequences  Description 

+, , *, /, ^, _, <, >, (, ), {, }, [, ], ., ,, =  Characters that are math operators or part of mathematical constructs 
A, kA, mA, MA, J, K, ' , ft , °, and many more!  Characters and character sequences that are units (see the Units paragraph) 
#, !, ?, §, $, %, &, :, ;, \, , ~, ∆, ¿, and many more!  Characters used as placeholder or to trigger special operations 
pi, e  Mathematical constants 
´, `, ' , "  Characters used for accents 
space  A space defines the end of a name and can therefore not be used 
For example, the following name is valid: <<Sketch>>.Constraints.T2üßµ@
. While these are invalid names: <<Sketch>>.Constraints.test\result_2
(\r means "carriage return") or <<Sketch>>.Constraints.mol
(mol is a unit).
Since shorter names (especially if they have only one or two characters) can easily result in invalid names, consider using longer names and/or establishing a suitable naming convention.
Cell aliases
See Spreadsheet SetAlias.
Reference to CAD data
It is possible to use data from the model itself in an expression. To reference a property useobject.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 

Length of a Part Box  Box.Length

Length with units (mm) 
Volume of the Box  Box.Shape.Volume

Volume in mm³ without units 
Shape type of the Box  Box.Shape.ShapeType

String: Solid 
Label of the Box  Box.Label

String: Label 
Xcoordinate of center of mass of the Box  Box.Shape.CenterOfMass.x

Xcoordinate in mm without units 
Xcoordinate of the Box placement  Box.Placement.Base.x

Xcoordinate with units (mm) 
Xcomponent of the rotation axis of the Box placement  Box.Placement.Rotation.Axis.x

Xcomponent of the unit vector in mm without units 
Rotation angle of the Box placement  Box.Placement.Rotation.Angle

Rotation angle with units (deg) 
Full Box object  Box._self

Object of type <Part::PartFeature> 
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 DataLength property in e.g a Pad object, if the expression is used in e.g DataLength2 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 DataLength 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 the other 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.
 FreeCAD does not yet have a builtin expression manager where all expressions in a document are listed, and can be created, deleted, queried, etc. But an addon is available: fcxref expression manager.
 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 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