Difference between revisions of "Expressions"

From FreeCAD Documentation
Jump to navigation Jump to search
(add info how to reference lists and refactor page a bit)
m
 
(180 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 
<languages/>
 
<languages/>
 
+
{{TOCright}}
<div style="float:right; clean:both; margin-left:0.5em;">__TOC__</div>
 
 
<translate>
 
<translate>
  
Line 7: Line 6:
  
 
<!--T:2-->
 
<!--T:2-->
It is possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon [[Image:Sketcher_Expressions.png|24px]]. Clicking on the icon or typing the equal sign (=) brings up the expression editor for that particular property.
+
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 [[Image:Sketcher_Expressions.png|24px]]. Clicking on the icon or typing the equal sign {{KEY|&#61;}} brings up the expression editor for that particular property.
  
 
<!--T:3-->
 
<!--T:3-->
Line 13: Line 12:
  
 
<!--T:54-->
 
<!--T:54-->
Numbers may use either a comma ',' or a decimal point '.' separating whole digits from decimals.
+
Numbers may use either a comma {{incode|,}} or a decimal point {{incode|.}} separating whole digits from decimals.
 
When the decimal marker is used, it ''must'' be followed by at least one digit.   
 
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.
+
Thus, the expressions {{incode|1.+2.}} and {{incode|1,+2,}} are invalid, but {{incode|1.0 + 2.0}} and {{incode|1,0 + 2,0}} are valid.
  
 
<!--T:4-->
 
<!--T:4-->
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). These units are currently recognized.
+
Operators and functions are unit-aware, and require valid combinations of units, if supplied. For example, {{incode|2mm + 4mm}} is a valid expression, while {{incode|2mm + 4}} is not (the reason for this is that an expression like {{incode|1in + 4}} will most likely be interpreted as {{incode|1in + 4in}} by humans, but all units are converted to the SI system internally, and the system is not able to guess this). These [[#Units|units]] are currently recognized.
  
 
<!--T:27-->
 
<!--T:27-->
You can use [[#Supported Constants|predefined constants]] and [[#Supported Functions|functions]].
+
You can use [[#Supported_constants|predefined constants]] and [[#Supported_functions|functions]].
  
===Referencing objects===
+
===Function arguments=== <!--T:97-->
 +
 
 +
<!--T:28-->
 +
Multiple arguments to a function may be separated by either a semicolon {{incode|;}} or a comma <em>followed by a space</em> {{incode|, }}. In the latter case, the comma is converted to a semicolon after entry. When a semicolon is used, no trailing space is necessary.
 +
 
 +
<!--T:98-->
 +
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 {{incode|A1}}.  A cell may also be referenced by using the cell's alias instead, for example {{incode|Spreadsheet.MyPartWidth}}.
 +
 
 +
===Referencing objects=== <!--T:69-->
  
 
<!--T:67-->
 
<!--T:67-->
You can reference to an object by its {{incode|Name}} or by its {{incode|Label}}. In the case of a {{incode|Label}}, it must be enclosed in double {{incode|<<}} and {{incode|>>}} symbols, such as {{incode|<<Label>>}}.
+
You can reference an object by its {{PropertyData|Name}} or by its {{PropertyData|Label}}. In the case of a {{PropertyData|Label}}, it must be enclosed in double {{incode|<<}} and {{incode|>>}} symbols, such as {{incode|<<Label>>}}.
  
You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use {{incode|Cylinder.Height}} or {{incode|<<Long_name_of_cylinder>>.Height}}.
+
<!--T:70-->
 +
You can reference any numerical property of an object. For example, to reference a Cylinder's height, you may use {{incode|Cylinder.Height}} or {{incode|<<Long_name_of_cylinder>>.Height}}.
  
To reference list objects, the syntax is {{incode|object_name.feature_name.list[list_index]}}. If you want for example reference a constraint in a sketch, hover with the mouse over this constraint and look in the footer of FreeCAD's main window. Assuming you see there ''Object_name.Sketch_name.Constraint17'', then you reference it this way: '''Object_name.Sketch_name.Constraints[16]''' (The index starts with 0, therefore constraint 17 has the index 16.)
+
<!--T:71-->
 +
To reference list objects, use {{incode|<<object_label>>.list[list_index]}} or {{incode|object_name.list[list_index]}}. If you want for example to reference a constraint in a sketch, use {{incode|<<MySketch>>.Constraints[16]}}. If you are in the same sketch you may omit its name and just use {{incode|Constraints[16]}}.<br/>
 +
'''Note:''' The index starts with 0, therefore constraint 17 has the index 16.  
 +
 
 +
<!--T:72-->
 +
For more information about referencing objects, see [[#Reference_to_CAD_data|Reference to CAD_data]].
 +
 
 +
== Supported constants == <!--T:58-->
 +
 
 +
<!--T:59-->
 +
The following constants are supported:
 +
{| class="wikitable"
 +
!style="width: 33%;"|Constant
 +
!style="width: 66%;"|Description
 +
|-
 +
| style="text-align:center;" | '''e'''
 +
| [https://en.wikipedia.org/wiki/E_(mathematical_constant) Euler's number]
 +
|-
 +
| style="text-align:center;" | '''pi'''
 +
| [https://en.wikipedia.org/wiki/Pi Pi]
 +
|}
  
==Supported Operators== <!--T:52-->
+
== Supported operators == <!--T:96-->
  
 
<!--T:53-->
 
<!--T:53-->
 
The following operators are supported:
 
The following operators are supported:
{| class="wikitable float-right mw-collapsible mw-uncollapsed"
+
{| class="wikitable"
 
!style="width: 33%;"|Operator
 
!style="width: 33%;"|Operator
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
 
|-
 
|-
| +
+
| style="text-align:center;" |'''+'''
 
| [https://en.wikipedia.org/wiki/Addition Addition]
 
| [https://en.wikipedia.org/wiki/Addition Addition]
 
|-
 
|-
| -
+
| style="text-align:center;" |'''-'''
 
| [https://en.wikipedia.org/wiki/Subtraction Subtraction]
 
| [https://en.wikipedia.org/wiki/Subtraction Subtraction]
 
|-
 
|-
| *
+
| style="text-align:center;" | '''*'''
 
| [https://en.wikipedia.org/wiki/Multiplication Multiplication]
 
| [https://en.wikipedia.org/wiki/Multiplication Multiplication]
 
|-
 
|-
| /
+
| style="text-align:center;" | '''/'''
| [https://en.wikipedia.org/wiki/Division_(mathematics) Division]
+
| Floating point [https://en.wikipedia.org/wiki/Division_(mathematics) Division]
 +
|-
 +
| style="text-align:center;" | '''%'''
 +
| [https://en.wikipedia.org/wiki/Remainder Remainder]
 
|-
 
|-
| ^
+
| style="text-align:center;" | '''^'''
 
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
 
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
 
|}
 
|}
  
==Supported Constants== <!--T:58-->
+
== Supported functions == <!--T:5-->
 
 
<!--T:59-->
 
The following constants are supported:
 
{| class="wikitable float-right mw-collapsible mw-uncollapsed"
 
!style="width: 33%;"|Constant
 
!style="width: 66%;"|Description
 
|-
 
| e
 
| [https://en.wikipedia.org/wiki/E_(mathematical_constant) Euler's number]
 
|-
 
| pi
 
| [https://en.wikipedia.org/wiki/Pi Pi]
 
|}
 
 
 
== Supported Functions == <!--T:5-->
 
  
=== General Mathematical Functions === <!--T:55-->
+
=== General mathematical functions === <!--T:55-->
  
 
<!--T:7-->
 
<!--T:7-->
 
The mathematical functions listed below are available.
 
The mathematical functions listed below are available.
 
<!--T:28-->
 
Multiple arguments to a function may be separated by either a semicolon ';' or a comma <em>followed by a space</em> ', '. In the latter case, the comma is converted to a semicolon after entry. When a semicolon is used, no trailing space is necessary.
 
  
 
<!--T:29-->
 
<!--T:29-->
[https://en.wikipedia.org/wiki/Trigonometric_functions Trigonometric functions] use degree as their default unit. For radian measure, add '''rad''' following the <em>first</em> value in an expression. So e.g. '''cos(45)''' is the same as '''cos(pi rad / 4)'''.<br/>
+
[https://en.wikipedia.org/wiki/Trigonometric_functions Trigonometric functions] use degree as their default unit. For radian measure, add {{incode|rad}} following the <em>first</em> value in an expression. So e.g. {{incode|cos(45)}} is the same as {{incode|cos(pi rad / 4)}}.  Expressions in degrees can use either {{incode|deg}} or {{incode|°}}, e.g. {{incode|360deg - atan2(3; 4)}} or {{incode|360&deg; - atan2(3; 4)}}.  If an expression is without units and needs to be converted to degrees or radians for compatibility, multiply by {{incode|1&nbsp;deg}}, {{incode|1&nbsp;°}} or {{incode|1&nbsp;rad}} as appropriate, e.g. {{incode|(360 - X) * 1deg}}; {{incode|(360 - X) * 1°}}; {{incode|(0.5 + pi / 2) * 1rad}}. <br/>
 
These trigonometric functions are supported:
 
These trigonometric functions are supported:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
!style="width: 33%;"|Function
+
!style="width: 15%;"|Function
!style="width: 33%;"|Description
+
!style="width: 55%;"|Description
!style="width: 33%;"|Value range
+
!style="width: 30%;"|Value range
 
|-
 
|-
 
| acos(x)
 
| acos(x)
Line 101: Line 114:
 
| all
 
| all
 
|-
 
|-
| atan2(x, y)
+
| atan2(x; y)
 
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] of ''x/y''
 
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] of ''x/y''
 
| all, except y = 0
 
| all, except y = 0
Line 123: Line 136:
 
| tan(x)
 
| tan(x)
 
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Tangent]
 
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Tangent]
| all, except of x = n·90 with n = integer
+
| all, except x = n*90 with n = uneven integer
 
|-
 
|-
 
| tanh(x)
 
| tanh(x)
 
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic tangent]
 
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic tangent]
 
| all
 
| all
 +
|-
 +
| hypot(x; y)
 +
| [https://en.wikipedia.org/wiki/Pythagorean_addition Pythagorean addition] ('''hypot'''enuse). 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 and y > 0, x >= y
 
|}
 
|}
  
 
<!--T:30-->
 
<!--T:30-->
 
These functions for exponentiation and logarithmization are supported:
 
These functions for exponentiation and logarithmization are supported:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Function
 
!style="width: 33%;"|Function
 
!style="width: 33%;"|Description
 
!style="width: 33%;"|Description
Line 149: Line 170:
 
| x > 0  
 
| x > 0  
 
|-
 
|-
| pow(x, y)
+
| pow(x; y)
 
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
 
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation]
 
| all
 
| all
Line 160: Line 181:
 
<!--T:31-->
 
<!--T:31-->
 
These functions for rounding, truncation and remainder are supported:
 
These functions for rounding, truncation and remainder are supported:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 20%;"|Function
 
!style="width: 20%;"|Function
 
!style="width: 55%;"|Description
 
!style="width: 55%;"|Description
Line 170: Line 191:
 
|-
 
|-
 
| ceil(x)
 
| ceil(x)
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Ceiling function] smallest integer value greater than or equal to x
+
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Ceiling function], smallest integer value greater than or equal to x
 
| all  
 
| all  
 
|-
 
|-
Line 177: Line 198:
 
| all  
 
| all  
 
|-
 
|-
| mod(x, y)
+
| mod(x; y)
 
| [https://en.wikipedia.org/wiki/Remainder Remainder] after dividing ''x'' by ''y''
 
| [https://en.wikipedia.org/wiki/Remainder Remainder] after dividing ''x'' by ''y''
 
| all, except y = 0
 
| all, except y = 0
Line 186: Line 207:
 
|-
 
|-
 
| trunc(x)
 
| trunc(x)
| [https://en.wikipedia.org/wiki/Truncation Truncation] to the nearest integer
+
| [https://en.wikipedia.org/wiki/Truncation Truncation] to the nearest integer in the direction of zero
 
| all
 
| all
 
|}
 
|}
  
=== Statistical / Aggregate Functions === <!--T:8-->
+
=== Statistical / aggregate functions === <!--T:99-->
[https://en.wikipedia.org/wiki/Aggregate_function Aggregate functions] take one or more arguments, separated by a semicolon ';' or a comma ''and'' a space ', '.<br/>
+
 
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.<br/>
+
<!--T:8-->
Arguments may include ranges of cells (two cell references separated by a colon), for example '''average(B1:B8)'''.
+
[https://en.wikipedia.org/wiki/Aggregate_function Aggregate functions] take one or more arguments.<br>
 +
 
 +
<!--T:100-->
 +
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 {{Incode|:}}, for example {{Incode|average(B1:B8)}} or {{Incode|sum(A1:A4; B1:B4)}}.
 +
The cell references may also use cell aliases, for example {{Incode|average(StartTemp:EndTemp)}}.
  
 
<!--T:60-->
 
<!--T:60-->
 
These aggregate functions are supported:
 
These aggregate functions are supported:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 20%;"|Function
 
!style="width: 20%;"|Function
 
!style="width: 55%;"|Description
 
!style="width: 55%;"|Description
 
!style="width: 25%;"|Value range
 
!style="width: 25%;"|Value range
 
|-
 
|-
| average(x:y)
+
| average(a; b; c; ...)
| [https://en.wikipedia.org/wiki/Arithmetic_mean Arithmetic mean] of values in cells x through y; sum(x:y) / count(x:y)
+
| [https://en.wikipedia.org/wiki/Arithmetic_mean Average] value of the arguments; same as sum(a; b; c; ...) / count(a; b; c; ...)
 
| all
 
| all
 
|-
 
|-
| count(x:y)
+
| count(a; b; c; ...)
| [https://en.wikipedia.org/wiki/Counting Counting] of cells from x through y
+
| [https://en.wikipedia.org/wiki/Counting Count] of the arguments; typically used for cell ranges
 
| all  
 
| all  
 
|-
 
|-
| max(x:y)
+
| max(a; b; c; ...)
| [https://en.wikipedia.org/wiki/Maxima_and_minima Maximum] value in cells x through y
+
| [https://en.wikipedia.org/wiki/Maxima_and_minima Maximum] value of the arguments
 
| all  
 
| all  
 
|-
 
|-
| min(x:y)
+
| min(a; b; c; ...)
| [https://en.wikipedia.org/wiki/Maxima_and_minima Minimum] value in cells x through y
+
| [https://en.wikipedia.org/wiki/Maxima_and_minima Minimum] value of the arguments
 
| all
 
| all
 
|-
 
|-
| stddev(x:y)
+
| stddev(a; b; c; ...)
| [https://en.wikipedia.org/wiki/Standard_deviation Standard deviation] of values in cells x through y
+
| [https://en.wikipedia.org/wiki/standard_deviation Standard deviation] of the values of the arguments
 
| all
 
| all
 
|-
 
|-
| sum(x: y)
+
| sum(a; b; c; ...)
| [https://en.wikipedia.org/wiki/Summation Sum] of values in cells x through y
+
| [https://en.wikipedia.org/wiki/Summation Sum] of the values of the arguments; typically used for cell ranges
 
| all
 
| all
 
|}
 
|}
  
== Conditional Expressions == <!--T:32-->
+
=== String manipulation === <!--T:101-->
 +
 
 +
==== String identification ==== <!--T:102-->
 +
 
 +
<!--T:103-->
 +
Strings are identified in expressions by surrounding them with opening/closing double chevrons (as are labels).
 +
 
 +
<!--T:104-->
 +
In following example, "TEXT" is recognized as a string : {{incode|<<TEXT>>}}
 +
 
 +
==== String concatenation ==== <!--T:105-->
 +
 
 +
<!--T:106-->
 +
Strings can be concatenated using the '+' sign.
 +
 
 +
<!--T:107-->
 +
Following example {{incode|<<MY>> + <<TEXT>>}} will be concatenated to "MYTEXT".
 +
 
 +
==== String formatting ==== <!--T:108-->
 +
 
 +
<!--T:109-->
 +
String formatting is supported using the (old) %-style Python way.
 +
 
 +
<!--T:110-->
 +
All %-specifiers as defined in [https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting Python documentation].
 +
 
 +
<!--T:111-->
 +
As an example, supposing you have a default 10mm-side cube named 'Box' --default FreeCAD naming--, following expression {{incode|<<Cube length : %s>> % Box.Length}} will expand to "Cube length : 10.0 mm"
 +
 
 +
<!--T:112-->
 +
A limitation is that only one %-specifier is allowed in string, thus you have to use string concatenation if more than one is needed. With same above situation, expression {{incode|<<Cube length is %s>> % Box.Length + << and width is %s>> % Box.Width}} will expand to "Cube length is 10.0 mm and width is 10.0 mm".
 +
 
 +
<!--T:113-->
 +
A FreeCAD sample file using string formatting is available [https://forum.freecadweb.org/viewtopic.php?f=8&t=58657 in the forum]
 +
 
 +
=== Create function === <!--T:116-->
 +
 
 +
<!--T:117-->
 +
The following objects may be created in expressions via the {{incode|create}} function:
 +
* Vector
 +
* Matrix
 +
* Rotation
 +
* Placement
 +
 
 +
<!--T:118-->
 +
The {{incode|create}} function passes subsequent arguments to the underlying Python constructor when creating the object.
 +
 
 +
<!--T:119-->
 +
Various mathematical operations such as multiplication, addition, and subtraction are supported via standard mathematical operators (e.g. {{incode|*}}, {{incode|+}}, {{incode|-}}).
 +
 
 +
==== Vector ==== <!--T:120-->
 +
 
 +
<!--T:121-->
 +
When {{incode|create}} is passed {{incode|<<vector>>}} as the 1st argument, the next 3 arguments are the X, Y, and Z coordinates for the {{incode|Vector}} respectively.
 +
 
 +
<!--T:122-->
 +
Example:
 +
 
 +
<!--T:123-->
 +
{{incode|create(<<vector>>; 2; 1; 2)}}
 +
 
 +
==== Matrix ==== <!--T:124-->
 +
 
 +
<!--T:125-->
 +
When {{incode|create}} is passed {{incode|<<matrix>>}} as the 1st argument, the next 16 arguments are the elements for the {{incode|Matrix}} in [https://en.wikipedia.org/wiki/Row-_and_column-major_order row-major order].
 +
 
 +
<!--T:126-->
 +
Example:
 +
 
 +
<!--T:127-->
 +
{{incode|create(<<matrix>>; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10; 11; 12; 13; 14; 15; 16)}}
 +
 
 +
==== Rotation ==== <!--T:128-->
 +
 
 +
<!--T:129-->
 +
When {{incode|create}} is passed {{incode|<<rotation>>}} as the 1st argument, there are two ways to create a {{incode|Rotation}}:
 +
 
 +
<!--T:130-->
 +
1. Specify an axis vector and a rotation angle.
 +
 
 +
<!--T:131-->
 +
Example:
 +
 
 +
<!--T:132-->
 +
{{incode|create(<<rotation>>; create(<<vector>>; 0; 1; 0); 45)}}
 +
 
 +
<!--T:133-->
 +
2. Specify 3 rotations about the X, Y, and Z axes as Euler angles.
 +
 
 +
<!--T:134-->
 +
Example:
 +
 
 +
<!--T:135-->
 +
{{incode|create(<<rotation>>; 30; 30; 30)}}
 +
 
 +
==== Placement ==== <!--T:136-->
 +
 
 +
<!--T:137-->
 +
When {{incode|create}} is passed {{incode|<<placement>>}} as the 1st argument, there are five ways to create a {{incode|Placement}}.
 +
 
 +
<!--T:138-->
 +
These possible combinations are documented in the below table and are based on the [[Placement_API|Placement API]] page.
 +
 
 +
<!--T:139-->
 +
{| class="wikitable"
 +
!style="width: 33%;"|Number of arguments
 +
!style="width: 66%;"|Description
 +
|-
 +
| 2
 +
| {{incode|create(<<placement>>; Placement)}}
 +
|-
 +
| 2
 +
| {{incode|create(<<placement>>; Matrix)}}
 +
|-
 +
| 3
 +
| {{incode|create(<<placement>>; Base; Rotation)}}
 +
|-
 +
| 4
 +
| {{incode|create(<<placement>>; Base; Rotation; Center)}}
 +
|-
 +
| 4
 +
| {{incode|create(<<placement>>; Base; Axis; Angle)}}
 +
|}
 +
 
 +
<!--T:140-->
 +
The following example shows the syntax for creating a {{incode|Placement}} from a {{incode|Base}} (vector) and a {{incode|Rotation}}:
 +
 
 +
<!--T:141-->
 +
{{incode|create(<<placement>>; create(<<vector>>; 2; 1; 2); create(<<rotation>>; create(<<vector>>; 0; 1; 0); 45))}}
 +
 
 +
<!--T:142-->
 +
For readability, you can define vectors and rotations in separate cells, and then reference the cells in your expression.
 +
 
 +
=== Matrix functions === <!--T:143-->
 +
 
 +
==== mscale ==== <!--T:144-->
 +
 
 +
<!--T:145-->
 +
Scale a {{incode|Matrix}} with a given {{incode|Vector}}.
 +
 
 +
<!--T:146-->
 +
{{incode|mscale(Matrix; Vector)}}
 +
 
 +
<!--T:147-->
 +
{{incode|mscale(Matrix; x; y; z)}}
 +
 
 +
==== minvert ==== <!--T:148-->
 +
 
 +
<!--T:149-->
 +
Invert the given {{incode|Matrix}}, {{incode|Rotation}}, or {{incode|Placement}}.
 +
 
 +
<!--T:150-->
 +
{{incode|minvert(Matrix)}}
 +
 
 +
<!--T:151-->
 +
{{incode|minvert(Rotation)}}
 +
 
 +
<!--T:152-->
 +
{{incode|minvert(Placement)}}
 +
 
 +
=== Tuple & list === <!--T:153-->
 +
 
 +
<!--T:154-->
 +
You can create Python {{incode|tuple}} or {{incode|list}} objects via their respective functions.
 +
 
 +
<!--T:155-->
 +
{{incode|tuple(2; 1; 2)}}
 +
 
 +
<!--T:156-->
 +
{{incode|list(2; 1; 2)}}
 +
 
 +
== Conditional expressions == <!--T:32-->
  
 
<!--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' (false) or non-zero (true).  
+
Conditional expressions are of the form {{incode|condition ? resultTrue : resultFalse}}. The condition is defined as an expression that evaluates to either {{incode|0}} (false) or non-zero (true). Note that enclosing the conditional expression in parentheses is currently considered an error.
  
 
<!--T:33-->
 
<!--T:33-->
 
The following [https://en.wikipedia.org/wiki/Relational_operator#Standard_relational_operators relational operators] are defined:
 
The following [https://en.wikipedia.org/wiki/Relational_operator#Standard_relational_operators relational operators] are defined:
{| class="wikitable float-right mw-collapsible mw-uncollapsed"
+
{| class="wikitable"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
 
|-
 
|-
| ==
+
| style="text-align:center;" | '''=='''
 
| equal to
 
| equal to
 
|-
 
|-
| !=
+
| style="text-align:center;" | '''!='''
 
| not equal to
 
| not equal to
 
|-
 
|-
| >
+
| style="text-align:center;" | '''>'''
 
| greater than  
 
| greater than  
 
|-
 
|-
| <
+
| style="text-align:center;" | '''<'''
 
| less than
 
| less than
 
|-
 
|-
| >=
+
| style="text-align:center;" | '''>='''
 
| greater than or equal to
 
| greater than or equal to
 
|-
 
|-
| <=
+
| style="text-align:center;" | '''<='''
 
| less than or equal to
 
| less than or equal to
 
|}
 
|}
Line 260: Line 456:
  
 
<!--T:35-->
 
<!--T:35-->
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.
+
Units can be used directly in expressions. The parser connects them to the previous value. So {{incode|2mm}} or {{incode|2 mm}} is valid while {{incode|mm}} is invalid because there is no preceding value.
  
 
<!--T:56-->
 
<!--T:56-->
 
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.<br/>
 
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.<br/>
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.
+
In some cases it works even without a unit, for example if you have e.g. in spreadsheet cell B1 just the number {{incode|1.5}} and refer to it for a pad height. This only works because the pad height predefines the unit {{incode|mm}} that is used if no unit is given. It will nevertheless fail if you use for the pad height e.g. {{incode|Sketch1.Constraints.Width - Spreadsheet.B1}} because {{incode|Sketch1.Constraints.Width}} has a unit and {{incode|Spreadsheet.B1}} has not.
  
 
<!--T:57-->
 
<!--T:57-->
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³.
+
Units with exponents can directly be entered. So e.g. {{incode|mm^3}} will be recognized as mm³ and {{incode|m^3}} will be recognized as m³.
  
 
<!--T:36-->
 
<!--T:36-->
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.<<A>>''''.
+
If you have a variable whose name is that of a unit you must put the variable between {{incode|<< >>}} to prevent it from being recognized as a unit. For example if you have the dimension {{incode|Sketch.Constraints.A}} it would be recognized as the unit ampere. Therefore you must write it in the expression as {{incode|Sketch.Constraints.<<A>>}}.
  
 
<!--T:37-->
 
<!--T:37-->
Line 277: Line 473:
 
<!--T:38-->
 
<!--T:38-->
 
Amount of substance:
 
Amount of substance:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 287: Line 483:
 
<!--T:39-->
 
<!--T:39-->
 
Angle:
 
Angle:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
 
|-
 
|-
 
| °
 
| °
| [https://en.wikipedia.org/wiki/Degree_(angle) Degree]; alternative to the unit ''deg''
+
| [https://en.wikipedia.org/wiki/Degree_(angle) Degree]; alternative to the unit deg
 
|-
 
|-
 
| deg
 
| deg
| [https://en.wikipedia.org/wiki/Degree_(angle) Degree]; alternative to the unit ''°''
+
| [https://en.wikipedia.org/wiki/Degree_(angle) Degree]; alternative to the unit °
 
|-
 
|-
 
| rad
 
| rad
Line 304: Line 500:
 
|-
 
|-
 
| S
 
| S
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Second of arc]
+
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Second of arc]; alternative to the unit ″
 
|-
 
|-
 
| ″
 
| ″
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Second of arc]; alternative to the unit ''S''
+
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Second of arc]; alternative to the unit S
 
|-
 
|-
 
| M
 
| M
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]
+
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]; alternative to the unit ′
 
|-
 
|-
 
| ′
 
| ′
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]; alternative to the unit ''M''
+
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]; alternative to the unit M
 
|}
 
|}
  
 
<!--T:40-->
 
<!--T:40-->
 
Current:
 
Current:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 336: Line 532:
  
 
<!--T:41-->
 
<!--T:41-->
Energy / Work:
+
Energy/work:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 345: Line 541:
 
|-
 
|-
 
| Ws
 
| Ws
| [https://en.wikipedia.org/wiki/Joule#Watt_second Watt second]; alternative to the unit ''Joule''
+
| [https://en.wikipedia.org/wiki/Joule#Watt_second Watt second]; alternative to the unit Joule
 
|-
 
|-
 
| VAs
 
| VAs
| [https://en.wikipedia.org/wiki/Joule Volt-ampere-second]; alternative to the unit ''Joule''
+
| [https://en.wikipedia.org/wiki/Joule Volt-ampere-second]; alternative to the unit Joule
 
|-
 
|-
 
| CV
 
| CV
| [https://en.wikipedia.org/wiki/Joule Coulomb·Volt]; alternative to the unit ''Joule''
+
| [https://en.wikipedia.org/wiki/Joule Coulomb-volt]; alternative to the unit Joule
 
|}
 
|}
  
 
<!--T:42-->
 
<!--T:42-->
 
Force:
 
Force:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 378: Line 574:
 
<!--T:43-->
 
<!--T:43-->
 
Length:
 
Length:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 386: Line 582:
 
|-
 
|-
 
| um
 
| um
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit ''µm''
+
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit µm
 
|-
 
|-
 
| µm
 
| µm
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit ''mu''
+
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit um
 
|-
 
|-
 
| mm
 
| mm
Line 396: Line 592:
 
| cm
 
| cm
 
| Centi[https://en.wikipedia.org/wiki/Metre meter]
 
| Centi[https://en.wikipedia.org/wiki/Metre meter]
|-
 
| mm
 
| Milli[https://en.wikipedia.org/wiki/Metre meter]
 
 
|-
 
|-
 
| dm
 
| dm
Line 410: Line 603:
 
|-
 
|-
 
| mil
 
| mil
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit ''thou''
+
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit thou
 
|-
 
|-
 
| thou
 
| thou
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit ''mil''
+
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit mil
 
|-
 
|-
 
| in
 
| in
| [https://en.wikipedia.org/wiki/Inch Inch]
+
| [https://en.wikipedia.org/wiki/Inch Inch]; alternative to the unit "
 +
|-
 +
| "
 +
| [https://en.wikipedia.org/wiki/Inch Inch]; alternative to the unit in
 
|-
 
|-
 
| ft
 
| ft
Line 422: Line 618:
 
|-
 
|-
 
| '
 
| '
| [https://en.wikipedia.org/wiki/Foot_(unit) Foot]; alternative to the unit ''ft''
+
| [https://en.wikipedia.org/wiki/Foot_(unit) Foot]; alternative to the unit ft
 
|-
 
|-
 
| yd
 
| yd
Line 433: Line 629:
 
<!--T:44-->
 
<!--T:44-->
 
Luminous intensity:
 
Luminous intensity:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 443: Line 639:
 
<!--T:45-->
 
<!--T:45-->
 
Mass:
 
Mass:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
 
|-
 
|-
 
| ug
 
| ug
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit ''µg''
+
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit µg
 
|-
 
|-
 
| µg
 
| µg
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit ''ug''
+
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit ug
 
|-
 
|-
 
| mg
 
| mg
Line 469: Line 665:
 
|-
 
|-
 
| lb
 
| lb
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit ''lbm''
+
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit lbm
 
|-
 
|-
 
| lbm
 
| lbm
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit ''lb''
+
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit lb
 
|-
 
|-
 
| st
 
| st
Line 483: Line 679:
 
<!--T:61-->
 
<!--T:61-->
 
Power:
 
Power:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 496: Line 692:
 
<!--T:46-->
 
<!--T:46-->
 
Pressure:
 
Pressure:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 513: Line 709:
 
|-
 
|-
 
| uTorr
 
| uTorr
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit ''µTorr''
+
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit µTorr
 
|-
 
|-
 
| µTorr
 
| µTorr
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit ''uTorr''
+
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit uTorr
 
|-
 
|-
 
| mTorr
 
| mTorr
Line 522: Line 718:
 
|-
 
|-
 
| Torr
 
| Torr
| [https://en.wikipedia.org/wiki/Torr Torr]
+
| [https://en.wikipedia.org/wiki/Torr Torr]; 1 Torr = 133.32 Pa
 
|-
 
|-
 
| psi
 
| psi
| [https://en.wikipedia.org/wiki/Pounds_per_square_inch Pound-force per square inch]
+
| [https://en.wikipedia.org/wiki/Pounds_per_square_inch Pound-force per square inch]; 1 psi = 6.895 kPa
 
|-
 
|-
 
| ksi
 
| ksi
Line 533: Line 729:
 
<!--T:47-->
 
<!--T:47-->
 
Temperature:
 
Temperature:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
 
|-
 
|-
 
| uK
 
| uK
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit ''µK''
+
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit µK
 
|-
 
|-
 
| µK
 
| µK
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit ''uK''
+
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit uK
 
|-
 
|-
 
| mK
 
| mK
Line 552: Line 748:
 
<!--T:48-->
 
<!--T:48-->
 
Time:
 
Time:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 564: Line 760:
 
| h
 
| h
 
| [https://en.wikipedia.org/wiki/Hour Hour]
 
| [https://en.wikipedia.org/wiki/Hour Hour]
|}
 
 
<!--T:49-->
 
Torque:
 
{| class="wikitable float-right mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
|-
 
| Nm
 
| [https://en.wikipedia.org/wiki/Newton_metre Newton metre]
 
 
|}
 
|}
  
 
<!--T:50-->
 
<!--T:50-->
 
Volume:
 
Volume:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 33%;"|Unit
 
!style="width: 33%;"|Unit
 
!style="width: 66%;"|Description
 
!style="width: 66%;"|Description
Line 588: Line 774:
 
<!--T:51-->
 
<!--T:51-->
 
The following commonly used units are not yet supported:
 
The following commonly used units are not yet supported:
{| class="wikitable float-right mw-collapsible mw-collapsed"
+
{| class="wikitable mw-collapsible mw-collapsed"
 
!style="width: 25%;"|Unit
 
!style="width: 25%;"|Unit
 
!style="width: 50%;"|Description
 
!style="width: 50%;"|Description
 
!style="width: 25%;"|Alternative
 
!style="width: 25%;"|Alternative
 
|-
 
|-
| C
+
| °C
| [https://en.wikipedia.org/wiki/Coulomb Coulomb]
+
| [https://en.wikipedia.org/wiki/Celsius Celsius ]
| 1 A*s
+
| [°C] + 273.15 K
|-
 
| Hz
 
| [https://en.wikipedia.org/wiki/Hertz Hertz]
 
| 1 /s
 
|-
 
| V
 
| [https://en.wikipedia.org/wiki/Volt Volt]
 
| 1 W/A
 
|-
 
| eV
 
| [https://en.wikipedia.org/wiki/Electronvolt Electronvolt]
 
| 1.602176634e-19 J
 
|-
 
| kWh
 
| [https://en.wikipedia.org/wiki/Kilowatt_hour Kilowatt hour]
 
| 3.6e6 J
 
|-
 
| bar
 
| [https://en.wikipedia.org/wiki/Bar_(unit) Bar]
 
| 100 kPa
 
|-
 
| T
 
| [https://en.wikipedia.org/wiki/Tesla_(unit) Tesla]
 
| 1 kg/s^2/A
 
|-
 
| F
 
| [https://en.wikipedia.org/wiki/Farad Farad]
 
| 1 s^4*A^2/m^2/kg
 
 
|-
 
|-
| H
+
| °F
| [https://en.wikipedia.org/wiki/Henry_(unit) Henry]
+
| [https://en.wikipedia.org/wiki/Fahrenheit Fahrenheit];
| 1 kg*m^2/s^2/A^2
+
| ([°F] + 459.67) × ​5/9
 
|-
 
|-
 
| u
 
| u
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Atomic mass unit]; alternative to the unit 'Da'
+
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Atomic mass unit]; alternative to the unit Da
 
| 1.66053906660e-27 kg
 
| 1.66053906660e-27 kg
 
|-
 
|-
 
| Da
 
| Da
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Dalton]; alternative to the unit 'u'
+
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Dalton]; alternative to the unit u
 
| 1.66053906660e-27 kg
 
| 1.66053906660e-27 kg
|-
 
| cal
 
| [https://en.wikipedia.org/wiki/Calorie Calorie]
 
| 4.184 J
 
 
|-
 
|-
 
| sr
 
| sr
Line 653: Line 807:
 
| not directly
 
| not directly
 
|-
 
|-
| Mpsi
+
| px
| Mega[https://en.wikipedia.org/wiki/Pounds_per_square_inch pound-force per square inch]
+
| [https://en.wikipedia.org/wiki/Pixel Pixel]
| 1000 ksi
+
| not directly
 
|}
 
|}
  
== Reference To CAD-Data == <!--T:12-->
+
==Invalid characters and names== <!--T:85-->
 +
 
 +
<!--T:86-->
 +
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.
 +
 
 +
<!--T:87-->
 +
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=== <!--T:88-->
 +
 
 +
<!--T:89-->
 +
For [[Object_name#Label|labels]] there are no invalid characters, however some characters need to be escaped:
 +
{| class="wikitable"
 +
!style="width: 33%;"|Characters
 +
!style="width: 66%;"|Description
 +
|-
 +
| {{incode|'}}, {{incode|\}}, {{incode|"}}
 +
| Need to be escaped by adding {{incode|\}} in front of them.
 +
|}
 +
 
 +
<!--T:90-->
 +
For example, the label {{incode|Sketch\002}} must be referenced as {{incode|<<Sketch\\002>>}}.
 +
 
 +
===Names=== <!--T:91-->
 +
 
 +
<!--T:92-->
 +
[[Object_name#Name|Names]] of objects like dimensions, sketches, etc. may not have the characters or character sequences listed below, otherwise the name is invalid:
 +
 
 +
<!--T:93-->
 +
{| class="wikitable"
 +
!style="width: 33%;"|Characters / Character sequences
 +
!style="width: 66%;"|Description
 +
|-
 +
| '''+''', '''-''', '''*''', '''/''', '''^''', '''_''', '''<''', '''>''', '''(''', ''')''', '''{''', '''}''', '''[''', ''']''', '''.''', ''',''',  '''='''
 +
| Characters that are math operators or part of mathematical constructs
 +
|-
 +
| '''A''', '''kA''', '''mA''', '''MA''', '''C''', '''G''', '''F''', '''uF''', '''µF''', '''J''', '''K''', ''' ' ''', ''' ft ''', '''°''', and many more!
 +
| Characters and character sequences that are [[Expressions#Units|units]]
 +
|-
 +
| '''#''', '''!''', '''?''', '''§''', '''$''', '''%''', '''&''', ''':''', ''';''', '''\''', '''<nowiki>|</nowiki>''', '''~''', '''∆''', '''¿''', 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
 +
|}
 +
 
 +
<!--T:95-->
 +
For example, the following name is valid: {{incode|<<Sketch>>.Constraints.T2üßµ@}}. While these are invalid names: {{incode|<<Sketch>>.Constraints.test\result_2}} (\r means "carriage return") or {{incode|<<Sketch>>.Constraints.mol}} (mol is a unit).
 +
 
 +
<!--T:94-->
 +
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=== <!--T:114-->
 +
 
 +
<!--T:115-->
 +
For [[Spreadsheet_SetAlias|spreadsheet cell aliases]] only alphanumeric characters and underscores ({{incode|A}} to {{incode|Z}}, {{incode|a}} to {{incode|z}}, {{incode|0}} to {{incode|9}} and {{incode|_}}) are allowed.
 +
 
 +
== Reference to CAD data == <!--T:12-->
  
 
<!--T:13-->
 
<!--T:13-->
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".  
+
It is possible to use data from the model itself in an expression. To reference a property use{{incode|object.property}}. If the property is a compound of fields, the individual fields can be accessed as {{incode|object.property.field}}.  
  
 
<!--T:14-->
 
<!--T:14-->
 
The following table shows some examples:
 
The following table shows some examples:
{|{{Prettytable}}
+
{| class="wikitable"
  !CAD-Data
+
  !CAD data
 
  !Call in expression
 
  !Call in expression
 
  !Result
 
  !Result
 
  |-
 
  |-
 
  |Parametric Length of a Part-Workbench Cube
 
  |Parametric Length of a Part-Workbench Cube
  |Cube.Length
+
  |{{incode|Cube.Length}}
 
  |Length with units mm
 
  |Length with units mm
 
  |-
 
  |-
 
  |Volume of the Cube
 
  |Volume of the Cube
  |Cube.Shape.Volume
+
  |{{incode|Cube.Shape.Volume}}
  |Volume in mm&sup3; without units
+
  |Volume in mm&sup3; without units
 
  |-
 
  |-
 
  |Type of the Cube-shape
 
  |Type of the Cube-shape
  |Cube.Shape.ShapeType
+
  |{{incode|Cube.Shape.ShapeType}}
 
  |String: Solid
 
  |String: Solid
 
  |-
 
  |-
 
  |Label of the Cube
 
  |Label of the Cube
  |Cube.Label
+
  |{{incode|Cube.Label}}
 
  |String: Label
 
  |String: Label
 
  |-
 
  |-
 
  |x-coordinate of center of mass of the Cube
 
  |x-coordinate of center of mass of the Cube
  |Cube.Shape.CenterOfMass.x
+
  |{{incode|Cube.Shape.CenterOfMass.x}}
 
  |x-coordinate in mm without units
 
  |x-coordinate in mm without units
 
  |-
 
  |-
 
  |Value of constraint in a sketch
 
  |Value of constraint in a sketch
  |Constraints.Width
+
  |{{incode|Constraints.Width}}
  |Numeric value of the named constraint 'Width' in the sketch, if the expression is used in the sketch itself.
+
  |Numeric value of the named constraint {{incode|Width}} in the sketch, if the expression is used in the sketch itself.
 
  |-
 
  |-
 
  |Value of constraint in a sketch
 
  |Value of constraint in a sketch
  |MySketch.Constraints.Width
+
  |{{incode|MySketch.Constraints.Width}}
  |Numeric value of the named constraint 'Width' in the sketch, if the expression is used outside of the sketch.
+
  |Numeric value of the named constraint {{incode|Width}} in the sketch, if the expression is used outside of the sketch.
 
  |-
 
  |-
 
  |Value of a spreadsheet alias
 
  |Value of a spreadsheet alias
  |Spreadsheet.Depth
+
  |{{incode|Spreadsheet.Depth}}
  |Value of the alias "Depth" in the spreadsheet "Spreadsheet"
+
  |Value of the alias {{incode|Depth}} in the spreadsheet {{incode|Spreadsheet}}
 
  |-
 
  |-
 
  |Value of a local property
 
  |Value of a local property
  |Length
+
  |{{incode|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.
+
  |Value of the {{PropertyData|Length}} property in e.g a Pad object, if the expression is used in e.g {{PropertyData|Length2}} in the same object.
 
  |}
 
  |}
  
Line 715: Line 932:
  
 
<!--T:21-->
 
<!--T:21-->
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.
+
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 {{PropertyData|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.
  
 
<!--T:22-->
 
<!--T:22-->
Line 721: Line 938:
  
 
<!--T:23-->
 
<!--T:23-->
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:
+
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 {{incode|master}}, the spreadsheet {{incode|modelConstants}}, and give a cell an alias-name {{incode|Length}}, you can then access the value as:
  
    <!--T:65-->
+
<!--T:65-->
master#modelConstants.Length
+
{{incode|master#modelConstants.Length}}
  
 
<!--T:66-->
 
<!--T:66-->
Note that the master document must be loaded for the values in the master to be available to the dependent document.
+
'''Note:''' that the master document must be loaded for the values in the master to be available to the dependent document.
  
 
<!--T:24-->
 
<!--T:24-->
Line 738: Line 955:
  
 
<!--T:18-->
 
<!--T:18-->
* 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 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.
+
* The expression parser does not handle parentheses well, and is unable to properly parse some expressions.  For example: {{incode|<nowiki>=</nowiki> (A1 > A2) ? 1 : 0}} results in an error, while {{incode|<nowiki>=</nowiki> A1 > A2 ? 1 : 0}} is accepted.  The expression {{incode|<nowiki>=</nowiki> 5 + ((A1>A2) ? 1 : 0)}} cannot be entered in any form.
* There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc.
+
* 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|OK}} button will become active.
* The names of Sketcher constraints must not contain any blanks when the value is calculated by an expression, see [https://forum.freecadweb.org/viewtopic.php?p=302500#p302381; forum discussion].
+
* 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: [https://github.com/gbroques/fcxref fcxref expression manager].
 
* Open bugs/tickets for Expressions can be found in the [https://freecadweb.org/tracker/set_project.php?project_id=4;20 FreeCAD Bugtracker Expressions category]
 
* Open bugs/tickets for Expressions can be found in the [https://freecadweb.org/tracker/set_project.php?project_id=4;20 FreeCAD Bugtracker Expressions category]
  
<!--T:19-->
 
{{Userdocnavi}}
 
[[Category:User Documentation]]
 
[[Category:API]]
 
  
 
</translate>
 
</translate>
{{clear}}
+
{{Powerdocnavi{{#translation:}}}}
 +
[[Category:Spreadsheet{{#translation:}}]]

Latest revision as of 16:21, 28 October 2021

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎italiano • ‎polski • ‎português do Brasil • ‎русский

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 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 notation for the standard mathematical operators 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.

Numbers may use either a comma , or a decimal point . separating 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 (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). These units are currently recognized.

You can use predefined constants and functions.

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 numerical 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 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 constraint 17 has the index 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 mathematical functions listed below are available.

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.
These trigonometric functions are supported:

Function Description Value range
acos(x) Arc cosine -1 <= x <= 1
asin(x) Arc sine -1 <= x <= 1
atan(x) Arc tangent all
atan2(x; y) Arc tangent of x/y all, except y = 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 = uneven 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 and y > 0, x >= y

These functions for exponentiation and logarithmization are supported:

Function Description Value 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

These functions for rounding, truncation and remainder are supported:

Function Description Value 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 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).

These aggregate functions are supported:

Function Description Value 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 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--, following expression <<Cube length : %s>> % Box.Length will expand to "Cube length : 10.0 mm"

A limitation is that only one %-specifier is allowed in string, thus you have to use string concatenation if more than one is needed. With same above situation, expression <<Cube length is %s>> % Box.Length + << and width is %s>> % Box.Width 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

Create function

The following objects may be created in expressions via the create function:

  • Vector
  • Matrix
  • Rotation
  • Placement

The create function passes subsequent arguments to the underlying Python constructor when creating the object.

Various mathematical operations such as multiplication, addition, and subtraction are supported via standard mathematical operators (e.g. *, +, -).

Vector

When create is passed <<vector>> as the 1st argument, the next 3 arguments are the X, Y, and Z coordinates for the Vector respectively.

Example:

create(<<vector>>; 2; 1; 2)

Matrix

When create is passed <<matrix>> as the 1st argument, the next 16 arguments are the elements for the Matrix in row-major order.

Example:

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

Rotation

When create is passed <<rotation>> as the 1st argument, there are two ways to create a Rotation:

1. Specify an axis vector and a rotation angle.

Example:

create(<<rotation>>; create(<<vector>>; 0; 1; 0); 45)

2. Specify 3 rotations about the X, Y, and Z axes as Euler angles.

Example:

create(<<rotation>>; 30; 30; 30)

Placement

When create is passed <<placement>> as the 1st argument, there are five ways to create a Placement.

These possible combinations are documented in the below table and are based on the Placement API page.

Number of arguments Description
2 create(<<placement>>; Placement)
2 create(<<placement>>; Matrix)
3 create(<<placement>>; Base; Rotation)
4 create(<<placement>>; Base; Rotation; Center)
4 create(<<placement>>; Base; Axis; Angle)

The following example shows the syntax for creating a Placement from a Base (vector) and a Rotation:

create(<<placement>>; create(<<vector>>; 2; 1; 2); create(<<rotation>>; create(<<vector>>; 0; 1; 0); 45))

For readability, you can define vectors and rotations in separate cells, and then reference the cells in your expression.

Matrix functions

mscale

Scale a Matrix with a given Vector.

mscale(Matrix; Vector)

mscale(Matrix; x; y; z)

minvert

Invert the given Matrix, Rotation, or Placement.

minvert(Matrix)

minvert(Rotation)

minvert(Placement)

Tuple & list

You can create Python tuple or list objects via their respective functions.

tuple(2; 1; 2)

list(2; 1; 2)

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

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

Energy/work:

Unit Description
J Joule
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

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

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
VA Volt-ampere

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

Volume:

Unit Description
l Liter

The following commonly used units are not yet supported:

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

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, C, G, F, uF, µF, J, K, ' , ft , °, and many more! Characters and character sequences that are units
#, !, ?, §, $, %, &, :, ;, \, |, ~, , ¿, 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

For spreadsheet cell aliases only alphanumeric characters and underscores (A to Z, a to z, 0 to 9 and _) are allowed.

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
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: Label
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, 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.

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

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