Expressions: Difference between revisions

From FreeCAD Documentation
m (grammar, no translation necessary)
(Transfer from spreadsheet)
Line 18: Line 18:
== Supported Functions == <!--T:5-->
== Supported Functions == <!--T:5-->


<!--T:6-->
<!--T:7-->
The mathematical functions listed below are available.
In expressions, the following functions are supported, taking one or two arguments: abs, acos, asin, atan, atan2, cos, cosh, exp, log, log10, mod, pow, sin, sinh, sqrt, tan, tanh, ceil, floor, trunc, and round.


<!--T:26-->
<!--T:58-->
Multiple arguments to a function may be separated by either a semicolon (';') or
Aggregate functions: min, max, count, sum, stddev, and average.
a comma <em>followed by a space</em> (", ").
Aggregate functions can take one or more arguments, separated by comma or semicolon. Arguments may include ranges (two cells separated by a colon), e.g =average(B1:B8). These are interpreted as the properties B1, B2, ... B8.
In the latter case, the comma is converted to a semicolon after entry.


<!--T:7-->
<!--T:36-->
Trigonometric functions use degrees as its default unit; supply "rad" if you want them to use radians.
Trigonometric functions use degrees as their default unit;
for radian measure, add '''rad''' following the <em>first</em> value in an expression.
Example: cos(45) is the same as cos(pi rad / 4).


<!--T:8-->
<!--T:59-->
{{APIFunction |abs|x| Absolute value | value &gt;&#61; 0 }}
The constants pi and e are predefined.
{{APIFunction |acos|x| Arc cosine; -1 &lt;&#61; x &lt;&#61; 1 | acos(x) }}
{{APIFunction |asin|x| Arc sine; -1 &lt;&#61; x &lt;&#61; 1 | asin(x) }}
{{APIFunction |atan|x| Arc tangent | atan(x) }}
{{APIFunction |atan2|y, x| Arc tangent of y / x; | atan2(y,x) }}
{{APIFunction |ceil|x| Ceiling | The smallest integer value greater than or equal to x {{Version|0.16}} }}
{{APIFunction |cos|angle| Cosine; angle is in degrees (any value) | -1 &lt;&#61; cos(x) &lt;&#61; 1 }}
{{APIFunction |cosh|x| Hyperbolic cosine of x | cosh(x) }}
{{APIFunction |exp|y| Natural exponent | e<sup> y</sup> }}
{{APIFunction |floor|x| Floor | The largest integer value less than or equal to x {{Version|0.16}} }}
{{APIFunction |log|x| Natural logarithm | log<sub>e</sub> x }}
{{APIFunction |log10|x| Logarithm base 10 | log<sub>10</sub> x }}
{{APIFunction |mod|x, y| Remainder x/y | Remainder after dividing x by y }}
{{APIFunction |pow|x, y| Power function| x<sup> y</sup> }}
{{APIFunction |round|x| | x rounded to the nearest integer {{Version|0.16}} }}
{{APIFunction |sin|angle| Cosine; angle in degrees (any value) | -1 &lt;&#61; sin(x) &lt;&#61; 1 }}
{{APIFunction |sinh|x| Hyperbolic sine of x | sinh(x) }}
{{APIFunction |sqrt|x| Square root; x &gt;&#61; 0 | Square root of x }}
{{APIFunction |tan|angle| Tangent; angle in degrees (any value) | tan(angle) }}
{{APIFunction |tanh|x| Hyperbolic tangent of x | tanh(x) }}
{{APIFunction |trunc|x| Truncate | x truncated to the nearest integer {{Version|0.16}} }}


=== Statistical / Aggregating Functions === <!--T:8-->
<!--T:9-->
The aggregating functions listed below are supported.
The conditional statement works like this: = condition ? resultTrue : resultFalse
Aggregating functions take one or more arguments, separated by a semicolon ';' or a comma <em>and</em> 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).
Example: ''average(B1:B8)''

<!--T:60-->
{{APIFunction |average|x y| Average of values in cells x through y | sum(x, y) / count(x, y) }}
{{APIFunction |count|x y| Number of cells from x through y | The number of cells from x through y, inclusive }}
{{APIFunction |max|x y| Maximum value in cells x through y | Maximum value }}
{{APIFunction |min|x y| Minimum value in cells x through y | Minimum value }}
{{APIFunction |stddev|x y| Standard deviation of values in cells x through y | Standard deviation }}
{{APIFunction |sum|x y| Sum of values in cells x through y | Sum }}

=== Conditional Expressions === <!--T:61-->


<!--T:10-->
<!--T:10-->
Conditional expressions are of the form ''condition ? resultTrue : resultFalse''
The condition is defined as an expression that evaluates to either 0 (for false) or non-zero for true. The following comparison operators are defined: ==, !=, >, <, >=, and <=.

<!--T:34-->
The condition is defined as an expression that evaluates to either 0 (false) or non-zero (true). The following comparison operators are defined: ==, !=, >, <, >=, and <=.


<!--T:11-->
<!--T:49-->
The conditional statement has a bug regarding nested conditional statements. Only the true-result may contain another conditional statement. This is because parentheses are removed after an expression is entered. Trying to put a nested conditional statement in the false-result may result in incorrect parentheses causing a different result after saving and reopening the document.
Formulas are written as e.g follows: 2 * Length, where Length is a property in the object holding the expression.
Note: This may no longer be true; at least <em>some</em> false result conditionals work properly.


== Reference To CAD-Data == <!--T:12-->
== Reference To CAD-Data == <!--T:12-->

Revision as of 00:09, 10 March 2019

]

Template:InProgress

introduced in version 0.16

It is now possible to drive properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon File:Sketcher Expressions.png. 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 normal notation for the standard mathematical operators (+, -, * and /) 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.

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

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

Trigonometric functions use degrees as their default unit; for radian measure, add rad following the first value in an expression. Example: cos(45) is the same as cos(pi rad / 4).

abs(x)

Description: Absolute value

Returns: value >= 0

acos(x)

Description: Arc cosine; -1 <= x <= 1

Returns: acos(x)

asin(x)

Description: Arc sine; -1 <= x <= 1

Returns: asin(x)

atan(x)

Description: Arc tangent

Returns: atan(x)

atan2(y, x)

Description: Arc tangent of y / x;

Returns: atan2(y,x)

ceil(x)

Description: Ceiling

Returns: The smallest integer value greater than or equal to x introduced in version 0.16

cos(angle)

Description: Cosine; angle is in degrees (any value)

Returns: -1 <= cos(x) <= 1

cosh(x)

Description: Hyperbolic cosine of x

Returns: cosh(x)

exp(y)

Description: Natural exponent

Returns: e y

floor(x)

Description: Floor

Returns: The largest integer value less than or equal to x introduced in version 0.16

log(x)

Description: Natural logarithm

Returns: loge x

log10(x)

Description: Logarithm base 10

Returns: log10 x

mod(x, y)

Description: Remainder x/y

Returns: Remainder after dividing x by y

pow(x, y)

Description: Power function

Returns: x y

round(x)

Description:

Returns: x rounded to the nearest integer introduced in version 0.16

sin(angle)

Description: Cosine; angle in degrees (any value)

Returns: -1 <= sin(x) <= 1

sinh(x)

Description: Hyperbolic sine of x

Returns: sinh(x)

sqrt(x)

Description: Square root; x >= 0

Returns: Square root of x

tan(angle)

Description: Tangent; angle in degrees (any value)

Returns: tan(angle)

tanh(x)

Description: Hyperbolic tangent of x

Returns: tanh(x)

trunc(x)

Description: Truncate

Returns: x truncated to the nearest integer introduced in version 0.16

Statistical / Aggregating Functions

The aggregating functions listed below are supported. Aggregating 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). Example: average(B1:B8)

average(x y)

Description: Average of values in cells x through y

Returns: sum(x, y) / count(x, y)

count(x y)

Description: Number of cells from x through y

Returns: The number of cells from x through y, inclusive

max(x y)

Description: Maximum value in cells x through y

Returns: Maximum value

min(x y)

Description: Minimum value in cells x through y

Returns: Minimum value

stddev(x y)

Description: Standard deviation of values in cells x through y

Returns: Standard deviation

sum(x y)

Description: Sum of values in cells x through y

Returns: Sum

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). The following comparison operators are defined: ==, !=, >, <, >=, and <=.

The conditional statement has a bug regarding nested conditional statements. Only the true-result may contain another conditional statement. This is because parentheses are removed after an expression is entered. Trying to put a nested conditional statement in the false-result may result in incorrect parentheses causing a different result after saving and reopening the document. Note: This may no longer be true; at least some false result conditionals work properly.

Reference To CAD-Data

It is possible to use data from other parts of the construction in an expression. The syntax for a reference to a field is as follows: object.property. If the property is a compound of fields, they can be accessed by e.g object.property.field.

The following table shows some examples:

CAD-Data Call in expression Result
Parametric Length of a Part-Workbench Cube Cube.Length Length with units mm
Volume of the Cube Cube.Shape.Volume Volume in mm³ without units
Type of the Cube-shape Cube.Shape.ShapeType String: Solid
Label of the Cube Cube.Label String: Cube
x-coordinate of center of mass of the Cube Cube.Shape.CenterOfMass.x x-coordinate in mm without units
Value of constraint in a sketch Constraints.Width Numeric value of the named constraint 'Width' in 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.

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's possible that you have a spreadsheet in one document and reference values from there in other documents.

Important note: You use a document's name to reference it from other documents. Now, when saving the document the first time you choose a certain file name and this is usually different to "Unnamed1" (or its translated version) and then the links are lost after reopening it. So, it's recommended to create first the master document, create a spreadsheet, save and close it. After reopening the name is set to the above file name. Afterwards you can still make changes and save the file but you shouldn't rename it.

Then create the further documents where you want to add expressions to. Assuming you named the master document "master" you can access an alias like this: master#Spreadsheet.Length

Unfortunately, the integrated checker is more confusing than helping because it always gives parser errors or claims that this or that doesn't exist. So, just continue on typing. When you are finished and the content is correct the OK suddenly becomes 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 graphs is based on the relationship between document objects, not properties. This means that you cannot provide data to and query the same object in e.g a spreadsheet, even though there are no cyclic dependency when just the properties are considered. As a work-around, use multiple spreadsheets, e.g one to drive your model, and one for reporting.
  • There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queries, etc.
  • Open bugs/tickets for Expressions can be found in the FreeCAD Bugtracker Expressions category