Expressions

    From FreeCAD Documentation

    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 Bound-expression.svg. 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 unit-aware, 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.

    Top

    Supported constants

    The following constants are supported:

    Constant Description
    e Euler's number
    pi Pi

    Top

    Supported operators

    The following operators are supported:

    Operator Description
    + Addition
    - Subtraction
    * Multiplication
    / Floating point Division
    % Remainder
    ^ Exponentiation

    Top

    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

    Top

    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

    Top

    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 10mm-side 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

    Top

    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 unit-less or Length unit values.

    Example: vector(2; 1; 3)

    create(<<vector>>; x; y; z)
    Matrix
    matrix(
      a11; a12; a13; a14;
      a21; a22; a23; a24;
      a31; a32; a33; a34;
      a41; a42; a43; a44
    )
    
    Create a 4x4 matrix in row-major order:

    A minimum of 1 argument can be supplied such as matrix(1) which creates an identity matrix.

    Example: matrix(1; 2; 3; 4; 5; 6; 7; 8; 9; 10; 11; 12; 13; 14; 15; 16)

    create(<<matrix>>; a11; a12; ...; a44)
    Rotation rotation(axis; angle) Create a Rotation by specifying its axis (Vector) and angle (Angle unit or unit-less), or three Euler angles α, β, γ.

    Examples:

    • rotation(vector(0; 1; 0); 45)
    • create(<<rotation>>; 30; 30; 30)
    rotation(α; β; γ)
    create(<<rotation>>; axis; angle)
    create(<<rotation>>; α; β; γ)
    Placement placement(base; rotation) Create a Placement with various parameters, including:
    • base: base location (Vector)
    • center: center location (Vector)
    • rotation: Rotation
    • axis: Rotation axis (Vector)
    • angle: Rotation angle (unit-less or Angle unit value)
    • matrix: Matrix

    Examples:

    • placement(vector(2; 1; 3); rotation(vector(0; 0; 1); 45))
    • create(<<placement>>; create(<<vector>>; 2; 1; 2); create(<<rotation>>; create(<<vector>>; 0; 1; 0); 45))
    placement(base; rotation; center)
    placement(base; axis; angle)
    placement(matrix)
    create(<<placement>>; ...)

    Top

    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) Non-uniformly 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)

    Top

    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:
    • a Rotation
    • an axis (Vector) and an angle (Angle unit or unit-less)
    • three Euler angles α, β, γ
    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)

    Top

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

    Top

    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.602176634e-19 J
    keV Kiloelectronvolt
    MeV Megaelectronvolt
    kWh Kilowatt hour; 1 kWh = 3.6e6 J
    Ws Watt second; alternative to the unit Joule
    VAs Volt-ampere-second; alternative to the unit Joule
    CV Coulomb-volt; 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 e-4 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 Pound-force per square inch; 1 psi = 6.895 kPa
    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
    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.66053906660e-27 kg
    Da Dalton; alternative to the unit u 1.66053906660e-27 kg
    sr Steradian not directly
    lm Lumen not directly
    lx Lux not directly
    px Pixel not directly

    Top

    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.

    Top

    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
    X-coordinate of center of mass of the Box Box.Shape.CenterOfMass.x X-coordinate in mm without units
    X-coordinate of the Box placement Box.Placement.Base.x X-coordinate with units (mm)
    X-component of the rotation axis of the Box placement Box.Placement.Rotation.Axis.x X-component 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.

    Top

    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.

    Top

    Cross-document 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 alias-name 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.

    Top

    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 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 built-in 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

    Top