Expressions/ru

Обзор
Свойства можно определять с помощью математических выражений. В графическом интерфейсе счетчики или поля ввода, привязанные к свойствам, содержат синий значок. Щелчок по значку или ввод знака равенства  вызывает редактор выражения для этого конкретного свойства.

Выражение FreeCAD - это математическое выражение, следующее за обозначениями стандартных математических операторов и функций, как описано ниже. Кроме того, выражение может ссылаться на другие свойства, а также использовать условные выражения. К числам в выражении может быть добавлена необязательная единица измерения.

В числах, для отделение целых цифр от десятичных, можно использовать запятую ',' или десятичную точку '.'. Когда используется десятичный маркер, за ним должна следовать хотя бы одна цифра. Таким образом, выражения 1.+2. и 1,+2, недопустимы, но 1.0 + 2.0 и 1,0 + 2,0 действительны.

Операторы и функции зависят от единиц измерения и требуют допустимых комбинаций единиц, если таковые имеются. Например, 2mm + 4mm является допустимым выражением, а 2mm + 4 - нет (причина в том, что выражение типа 1in + 4 люди обычно интерпретируют как 1 дюйм + 4 дюйма, но все единицы внутренне преобразуются в систему СИ, и система не может это угадать). В настоящее время распознаются такие единицы.

Вы можете использовать предопределенные константы и функции.

Referencing objects
You can reference to an object by its or by its. In the case of a, it must be enclosed in double and  symbols, such as.

You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use or.

To reference list objects, the syntax is or. If you want for example reference a constraint in a sketch, do it this way <>.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 Reference to CAD_data.

Поддерживаемые константы
The following constants are supported:

Supported operators
The following operators are supported:

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&deg; - 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:

These functions for exponentiation and logarithmization are supported:

These functions for rounding, truncation and remainder are supported:

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:

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:

Единицы измерений
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.<>.

The following units are recognized by the expression parser:

Amount of substance:

Angle:

Current:

Electrical capacitance:

Electrical conductance:

Electrical inductance:

Electrical resistance:

Electric charge:

Electric potential:

Energy / work:

Force:

Length:

Luminous intensity:

Magnetic field strength:

Magnetic flux:

Magnetic flux density:

Mass:

Power:

Pressure:

Temperature:

Time:

Torque:

Volume:

Special imperial units:

The following commonly used units are not yet supported:

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, like for example the name of a sketch 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 <>.

Names
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: <>.Constraints.T2üßµ@. While these are invalid names: <>.Constraints.test\result_2 (\r means "carriage return") or <>.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.

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:

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 "", the spreadsheet "", and give a cell an alias-name "", 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 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.
 * 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 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.
 * Open bugs/tickets for Expressions can be found in the FreeCAD Bugtracker Expressions category