Expressions/ru

Обзор

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.

Аргументы функции

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.

Ссылка на объект в выражении

As already shown above, you can reference an object by its ДанныеName. But you can also use its ДанныеLabel. In the case of a ДанныеLabel, 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 <<Label_of_cylinder>>.Height.

For more information about referencing objects, see Reference to CAD data.

наверх

Поддерживаемые константы

Поддерживаются следующие константные значения:

наверх

Поддерживаемые операторы

Поддерживаются следующие операторы:

наверх

Поддерживаемые функции

Основные математические функции

Поддерживаются следующие математические функции:

Функции тригонометрии

Trigonometric functions use degree as their default unit. For radians 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 1deg, 1° or 1rad as appropriate, e.g. (360 - X) * 1deg; (360 - X) * 1°; (0.5 + pi / 2) * 1rad.

Экспоненциальные и логарифмические функции

Функции округления, усечения и вычисления остатка от деления

наверх

Функции агрегирования и статистики

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

Поддерживаются следующие функции агрегирования:

наверх

Операции со строками

Идентификация строк

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

Объединение строк

Строки могут быть объединены с помощью символа "+".

Например строки <<МОЙ>> + <<ТЕКСТ>> будут объединены в "МОЙТЕКСТ".

Преобразование числа в строку

Числовые значения могут быть преобразованы в строки с помощью функции str:

str(Box.Length.Value)

Форматирование строк

Форматирование строк поддерживается с использованием (старого) Python способа в стиле %.

Сведения о всех %-спецификаторах, можно узнать из документации Python.

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

Пример файла FreeCAD с применением форматирования строк доступен на форуме

наверх

matrix(
  a11; a12; a13; a14;
  a21; a22; a23; a24;
  a31; a32; a33; a34;
  a41; a42; a43; a44
)

наверх

Vector functions

Functions: introduced in version 1.0.

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 ${\displaystyle v_{1}\times v_{2}}$.
v1 * v2	Dot product of two vectors ${\displaystyle v_{1}\cdot v_{2}}$.
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)

наверх

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.

наверх

Условные выражения

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 to use a boolean property as the condition this syntax must be used: VarSet.MyBool == 1 ? 10 mm : 15 mm.

The following relational operators are defined:

наверх

Единицы измерений

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:

Количество вещества

Угол

Ток

Electric capacitance

Electric charge

Electric conductivity

Electric inductance

Electric potential

Электрический потенциал:

Electric resistance

Энергия/работа

Сила

Длина

Интенсивность света

Magnetic flux

Magnetic flux density

Масса

Мощность

Давление

Температура

Время

Объем

Special imperial units

Неподдерживаемые единицы измерения

The following commonly used units are not yet supported, for some an alternative is provided:

наверх

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:

For example, the label Sketch\002 must be referenced as <<Sketch\\002>>.

Названия

Names of objects like dimensions, sketches, etc. may not have the characters or character sequences listed below, otherwise the name is invalid:

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 use object_name.property or <<object_label>>.property, labels must be enclosed in << and >>. If you want to use labels they must be unique.

All next examples reference the object by its name, but in all cases the object label can also be used.

If the property is a compound of fields, the individual fields can be accessed as object_name.property.field.

To reference list objects use object_name.list[list_index]. If you want to reference a constraint in a sketch, use Sketch.Constraints[16]. If you are in the same sketch you may omit its name and just use Constraints[16]. Note that the index starts with 0, therefore Constraint17 has to be referenced as Constraints[16].

To reference the object itself use the _self pseudo property: object_name._self.

The following table shows some more examples:

Cyclic dependencies

FreeCAD checks dependencies 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. You have to use two spreadsheets, one to drive your model and the other for reporting.

As a workaround it is possible to display a cell range from the second spreadsheet in the first (or vice versa) by creating a cell binding with the Hide dependency of binding option.

Another way to workaround cyclic dependencies is to hide the reference by using the href or hiddenref function for individual expressions, for example: href(Box.Length).

Please note that both mentioned workarounds should be used with caution, and that they do not work if the properties that are reported depend on dimensions that are driven from the same spreadsheet.

наверх

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

Of course, it's up to you to load the corresponding documents later when you want to change anything.

наверх

Известные проблемы / нерешённые задачи

• 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 on GitHub.

наверх

Scripting

import FreeCAD as App

doc = App.ActiveDocument
box = doc.addObject("Part::Box", "Box")
cyl = doc.addObject("Part::Cylinder", "Cylinder")
cyl_name = cyl.Name

box.setExpression("Height", f"{cyl_name}.Height / 2")
box.setExpression("Length", f"{cyl_name}.Radius * 2")
box.setExpression("Width", "Length")

doc.recompute()

# Expressions are stored in the ExpressionEngine property:
for prop, exp in box.ExpressionEngine:
    val = getattr(box, prop)
    print(f"Property: '{prop}' -- Expression: '{exp}' -- Current value: {val}")

наверх

Power user documentation

• 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