Expressions: Difference between revisions
(→Names) |
|||
(38 intermediate revisions by 6 users not shown) | |||
Line 6: | Line 6: | ||
<!--T:2--> |
<!--T:2--> |
||
It is possible to define properties using mathematical expressions. |
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|=}} brings up the expression editor for that particular property. |
||
<!--T:3--> |
<!--T:3--> |
||
Line 12: | Line 12: | ||
<!--T:54--> |
<!--T:54--> |
||
Numbers may use either a comma |
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 |
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, |
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 [[# |
You can use [[#Supported_constants|predefined constants]] and [[#Supported_functions|functions]]. |
||
===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--> |
===Referencing objects=== <!--T:69--> |
||
<!--T:67--> |
<!--T:67--> |
||
You can reference |
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>>}}. |
||
<!--T:70--> |
<!--T:70--> |
||
You can reference any numerical property of |
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}}. |
||
<!--T:71--> |
<!--T:71--> |
||
To reference list objects, |
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. |
'''Note:''' The index starts with 0, therefore constraint 17 has the index 16. |
||
<!--T:72--> |
<!--T:72--> |
||
For more |
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 float-right mw-collapsible mw-uncollapsed" |
|||
!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:96--> |
|||
<!--T:53--> |
<!--T:53--> |
||
Line 63: | Line 87: | ||
|} |
|} |
||
==Supported |
== Supported functions == <!--T:5--> |
||
=== General mathematical functions === <!--T:55--> |
|||
<!--T:59--> |
|||
The following constants are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
|||
!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 Functions == <!--T:5--> |
|||
=== 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 |
[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° - atan2(3; 4)}}. If an expression is without units and needs to be converted to degrees or radians for compatibility, multiply by {{incode|1 deg}}, {{incode|1 °}} or {{incode|1 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 float-right mw-collapsible mw-collapsed" |
||
Line 177: | Line 183: | ||
|- |
|- |
||
| 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 193: | Line 199: | ||
|- |
|- |
||
| 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 / |
=== 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/> |
|||
<!--T:8--> |
|||
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.<br/> |
|||
[https://en.wikipedia.org/wiki/Aggregate_function Aggregate functions] take one or more arguments.<br> |
|||
Arguments may include ranges of cells (two cell references separated by a colon), for example '''average(B1:B8)'''. |
|||
<!--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)}} {{Version|0.19}}. |
|||
<!--T:60--> |
<!--T:60--> |
||
Line 209: | Line 219: | ||
!style="width: 25%;"|Value range |
!style="width: 25%;"|Value range |
||
|- |
|- |
||
| average( |
| average(a; b; c; ...) |
||
| [https://en.wikipedia.org/wiki/Arithmetic_mean |
| [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( |
| count(a; b; c; ...) |
||
| [https://en.wikipedia.org/wiki/Counting |
| [https://en.wikipedia.org/wiki/Counting Count] of the arguments; typically used for cell ranges |
||
| all |
| all |
||
|- |
|- |
||
| max( |
| max(a; b; c; ...) |
||
| [https://en.wikipedia.org/wiki/Maxima_and_minima Maximum] value |
| [https://en.wikipedia.org/wiki/Maxima_and_minima Maximum] value of the arguments |
||
| all |
| all |
||
|- |
|- |
||
| min( |
| min(a; b; c; ...) |
||
| [https://en.wikipedia.org/wiki/Maxima_and_minima Minimum] value |
| [https://en.wikipedia.org/wiki/Maxima_and_minima Minimum] value of the arguments |
||
| all |
| all |
||
|- |
|- |
||
| stddev( |
| stddev(a; b; c; ...) |
||
| [https://en.wikipedia.org/wiki/ |
| [https://en.wikipedia.org/wiki/standard_deviation Standard deviation] of the values of the arguments |
||
| all |
| all |
||
|- |
|- |
||
| sum( |
| sum(a; b; c; ...) |
||
| [https://en.wikipedia.org/wiki/Summation Sum] of values |
| [https://en.wikipedia.org/wiki/Summation Sum] of the values of the arguments; typically used for cell ranges |
||
| all |
| all |
||
|} |
|} |
||
=== String manipulation === |
|||
== Conditional Expressions == <!--T:32--> |
|||
==== 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 : {{incode|<<TEXT>>}} |
|||
==== String concatenation ==== |
|||
Strings can be concatenated using the '+' sign. |
|||
Following example {{incode|<<MY>> + <<TEXT>>}} will be concatenated to "MYTEXT". |
|||
==== String formatting ==== |
|||
String formatting is supported using the (old) %-style Python way. |
|||
All %-specifiers as defined in [https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting Python documentation]. |
|||
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" |
|||
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". |
|||
A FreeCAD sample file using string formatting is available [https://forum.freecadweb.org/viewtopic.php?f=8&t=58657 in the forum] |
|||
== Conditional expressions == <!--T:32--> |
|||
<!--T:10--> |
<!--T:10--> |
||
Conditional expressions are of the form |
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. {{VersionMinus|0.19}} |
Note that enclosing the conditional expression in parentheses is currently considered an error. {{VersionMinus|0.19}} |
||
Line 268: | Line 304: | ||
<!--T:35--> |
<!--T:35--> |
||
Units can |
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 |
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. |
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 |
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 347: | Line 383: | ||
<!--T:75--> |
<!--T:75--> |
||
Electrical |
Electrical capacitance: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 372: | Line 408: | ||
<!--T:79--> |
<!--T:79--> |
||
Electrical |
Electrical conductance: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 388: | Line 424: | ||
| S |
| S |
||
| [https://en.wikipedia.org/wiki/Siemens_(unit) Siemens]; 1 S = 1 s^3·A^2/kg/m^2, {{Version|0.19}} |
| [https://en.wikipedia.org/wiki/Siemens_(unit) Siemens]; 1 S = 1 s^3·A^2/kg/m^2, {{Version|0.19}} |
||
|- |
|||
| kS |
|||
| Kilo[https://en.wikipedia.org/wiki/Siemens_(unit) siemens], {{Version|0.20}} |
|||
|- |
|||
| MS |
|||
| Mega[https://en.wikipedia.org/wiki/Siemens_(unit) siemens], {{Version|0.20}} |
|||
|} |
|} |
||
<!--T:76--> |
<!--T:76--> |
||
Electrical |
Electrical inductance: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 413: | Line 455: | ||
<!--T:80--> |
<!--T:80--> |
||
Electrical |
Electrical resistance: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 429: | Line 471: | ||
<!--T:73--> |
<!--T:73--> |
||
Electric |
Electric charge: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 439: | Line 481: | ||
<!--T:74--> |
<!--T:74--> |
||
Electric |
Electric potential: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 455: | Line 497: | ||
<!--T:41--> |
<!--T:41--> |
||
Energy / |
Energy / work: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 528: | Line 570: | ||
| Nano[https://en.wikipedia.org/wiki/Metre meter] |
| Nano[https://en.wikipedia.org/wiki/Metre meter] |
||
|- |
|- |
||
| |
| mu |
||
| 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'' |
||
|- |
|- |
||
Line 539: | Line 581: | ||
| 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 575: | Line 614: | ||
<!--T:44--> |
<!--T:44--> |
||
Luminous |
Luminous intensity: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 585: | Line 624: | ||
<!--T:81--> |
<!--T:81--> |
||
Magnetic |
Magnetic field strength: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 595: | Line 634: | ||
<!--T:82--> |
<!--T:82--> |
||
Magnetic |
Magnetic flux: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 605: | Line 644: | ||
<!--T:77--> |
<!--T:77--> |
||
Magnetic |
Magnetic flux density: |
||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
{| class="wikitable float-right mw-collapsible mw-collapsed" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
Line 767: | Line 806: | ||
| THz |
| THz |
||
| Tera[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}} |
| Tera[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}} |
||
|} |
|||
<!--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] |
|||
|} |
|} |
||
Line 848: | Line 877: | ||
|} |
|} |
||
==Invalid |
==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. |
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, like for example the name of a sketch constraints, you must be aware what characters are not allowed. |
|||
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=== |
===Labels=== <!--T:88--> |
||
<!--T:89--> |
|||
For [[Object_name#Label|labels]] there are no invalid characters, however some characters need to be escaped: |
For [[Object_name#Label|labels]] there are no invalid characters, however some characters need to be escaped: |
||
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
||
Line 861: | Line 893: | ||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| {{incode|'}}, {{incode|\}}, {{incode|"}} |
|||
| style="text-align:center;" | ''' ' ''', '''\''' , '''"''' |
|||
| |
| Need to be escaped by adding {{incode|\}} in front of them. |
||
|} |
|} |
||
<!--T:90--> |
|||
For example, the label ''Sketch\002'' must be referenced as ''<<Sketch\\002>>'' |
|||
For example, the label {{incode|Sketch\002}} must be referenced as {{incode|<<Sketch\\002>>}}. |
|||
===Names=== |
===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: |
[[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 float-right mw-collapsible mw-uncollapsed" |
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
||
!style="width: 33%;"|Characters / Character sequences |
!style="width: 33%;"|Characters / Character sequences |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| '''+''', '''-''', '''*''', '''/''', '''^''', '''_''', '''<''', '''>''', '''(''', ''')''', '''{''', '''}''', '''[''', ''']''', '''.''', ''',''', '''=''' |
|||
| Characters that are math operators or part of mathematical constructs |
| 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]] |
| Characters and character sequences that are [[Expressions#Units|units]] |
||
|- |
|- |
||
| '''#''', '''!''', '''?''', '''§''', '''$''', '''%''', '''&''', ''':''', ''';''', '''\''', '''<nowiki>|</nowiki>''', '''~''', '''∆''', '''¿''', and many more! |
|||
| Characters used as placeholder or to trigger special operations |
| Characters used as placeholder or to trigger special operations |
||
|- |
|- |
||
| '''pi''', '''e''' |
|||
| Mathematical constants |
|||
|- |
|||
| '''´''', '''`''', ''' ' ''', '''"''' |
|||
| Characters used for accents |
| Characters used for accents |
||
|- |
|- |
||
| space |
|||
| style="text-align:center;" | space |
|||
| A space defines the end of a name and can therefore not be used |
| A space defines the end of a name and can therefore not be used |
||
|} |
|} |
||
<!--T:95--> |
|||
'''Note:''' Since shorter names (especially if they have only one or two characters) can easily result in invalid names, consider to use longer names and/or to establish a suitable naming convention. |
|||
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--> |
|||
For example, the following is legal: '''<<Sketch>>.Constraints.T2üßµ@'''</br>while these are invalid names: |
|||
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. |
|||
'''<<Sketch>>.Constraints.test\result_2''' (\r means "carriage return") or '''<<Sketch>>.Constraints.mol''' (mol is a unit) |
|||
== Reference |
== 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 |
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}} |
{|{{Prettytable}} |
||
!CAD |
!CAD data |
||
!Call in expression |
!Call in expression |
||
!Result |
!Result |
||
Line 910: | Line 949: | ||
|Parametric Length of a Part-Workbench Cube |
|Parametric Length of a Part-Workbench Cube |
||
|{{incode|Cube.Length}} |
|{{incode|Cube.Length}} |
||
|Length with units mm |
|||
|- |
|- |
||
|Volume of the Cube |
|Volume of the Cube |
||
|{{incode|Cube.Shape.Volume}} |
|{{incode|Cube.Shape.Volume}} |
||
|Volume in mm³ without units |
|||
|- |
|- |
||
|Type of the Cube-shape |
|Type of the Cube-shape |
||
Line 930: | Line 969: | ||
|Value of constraint in a sketch |
|Value of constraint in a sketch |
||
|{{incode|Constraints.Width}} |
|{{incode|Constraints.Width}} |
||
|Numeric value of the named constraint |
|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 |
||
|{{incode|MySketch.Constraints.Width}} |
|{{incode|MySketch.Constraints.Width}} |
||
|Numeric value of the named constraint |
|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 |
||
|{{incode|Spreadsheet.Depth}} |
|{{incode|Spreadsheet.Depth}} |
||
|Value of the alias |
|Value of the alias {{incode|Depth}} in the spreadsheet {{incode|Spreadsheet}} |
||
|- |
|- |
||
|Value of a local property |
|Value of a local property |
||
|{{incode|Length}} |
|{{incode|Length}} |
||
|Value of the {{ |
|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 953: | Line 992: | ||
<!--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 959: | Line 998: | ||
<!--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 |
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--> |
||
Line 976: | Line 1,015: | ||
<!--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 |
* 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: |
* 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. |
||
* 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. |
* 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. |
||
* There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc. |
* 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 [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] |
||
</translate> |
</translate> |
Revision as of 12:44, 3 June 2021
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 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 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 of x = n·90 with n = integer |
tanh(x) | Hyperbolic tangent | all |
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)
introduced in version 0.19.
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
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. version 0.19 and below
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 |
---|---|
mmol | Millimole |
mol | Mole |
Angle:
Unit | Description |
---|---|
° | Degree; alternative to the unit deg |
deg | Degree; alternative to the unit ° |
rad | Radian |
gon | Gradian |
S | Second of arc |
″ | Second of arc; alternative to the unit S |
M | Minute of arc |
′ | Minute of arc; alternative to the unit M |
Current:
Unit | Description |
---|---|
mA | Milliampere |
A | Ampere |
kA | Kiloampere |
MA | Megaampere |
Electrical capacitance:
Unit | Description |
---|---|
pF | Picofarad, introduced in version 0.19 |
nF | Nanofarad, introduced in version 0.19 |
uF | Microfarad; alternative to the unit µF, introduced in version 0.19 |
µF | Microfarad; alternative to the unit uF, introduced in version 0.19 |
mF | Millifarad, introduced in version 0.19 |
F | Farad; 1 F = 1 s^4·A^2/m^2/kg, introduced in version 0.19 |
Electrical conductance:
Unit | Description |
---|---|
uS | Microsiemens; alternative to the unit µS, introduced in version 0.19 |
µS | Microsiemens; alternative to the unit uS, introduced in version 0.19 |
mS | Millisiemens, introduced in version 0.19 |
S | Siemens; 1 S = 1 s^3·A^2/kg/m^2, introduced in version 0.19 |
kS | Kilosiemens, introduced in version 0.20 |
MS | Megasiemens, introduced in version 0.20 |
Electrical inductance:
Unit | Description |
---|---|
nH | Nanohenry, introduced in version 0.19 |
uH | Microhenry; alternative to the unit µH, introduced in version 0.19 |
µH | Microhenry; alternative to the unit uH, introduced in version 0.19 |
mH | Millihenry, introduced in version 0.19 |
H | Henry; 1 H = 1 kg·m^2/s^2/A^2, introduced in version 0.19 |
Electrical resistance:
Unit | Description |
---|---|
Ohm | Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2, introduced in version 0.19 |
kOhm | Kiloohm, introduced in version 0.19 |
MOhm | Megaohm, introduced in version 0.19 |
Electric charge:
Unit | Description |
---|---|
C | Coulomb; 1 C = 1 A·s, introduced in version 0.19 |
Electric potential:
Unit | Description |
---|---|
mV | Millivolt |
V | Volt |
kV | Kilovolt |
Energy / work:
Unit | Description |
---|---|
mJ | Millijoule |
J | Joule |
kJ | Kilojoule, introduced in version 0.19 |
eV | Electronvolt; 1 ev = 1.602176634e-19 J, introduced in version 0.19 |
keV | Kiloelectronvolt, introduced in version 0.19 |
MeV | Megaelectronvolt, introduced in version 0.19 |
kWh | Kilowatt hour; 1 kWh = 3.6e6 J, introduced in version 0.19 |
Ws | Watt second; alternative to the unit Joule |
VAs | Volt-ampere-second; alternative to the unit Joule |
CV | Coulomb-volt; alternative to the unit Joule |
cal | Calorie; 1 cal = 4.184 J, introduced in version 0.19 |
kcal | Kilocalorie, introduced in version 0.19 |
Force:
Unit | Description |
---|---|
mN | Millinewton |
N | Newton |
kN | Kilonewton |
MN | Meganewton |
lbf | Pound of force |
Length:
Unit | Description |
---|---|
nm | Nanometer |
mu | Micrometer; alternative to the unit µm |
µm | Micrometer; alternative to the unit mu |
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 |
ft | Foot; alternative to the unit ' |
' | Foot; alternative to the unit ft |
yd | Yard |
mi | Mile |
Luminous intensity:
Unit | Description |
---|---|
cd | Candela |
Magnetic field strength:
Unit | Description |
---|---|
Oe | Oersted; 1 Oe = 79.57747 A/m, introduced in version 0.19 |
Magnetic flux:
Unit | Description |
---|---|
Wb | Weber; 1 Wb = 1 kg*m^2/s^2/A, introduced in version 0.19 |
Magnetic flux density:
Unit | Description |
---|---|
G | Gauss; 1 G = 1 e-4 T, introduced in version 0.19 |
T | Tesla; 1 T = 1 kg/s^2/A, introduced in version 0.19 |
Mass:
Unit | Description |
---|---|
ug | Microgram; alternative to the unit µg |
µg | Microgram; alternative to the unit ug |
mg | Milligram |
g | Gram |
kg | Kilogram |
t | Tonne |
oz | Ounce |
lb | Pound; alternative to the unit lbm |
lbm | Pound; alternative to the unit lb |
st | Stone |
cwt | Hundredweight |
Power:
Unit | Description |
---|---|
W | Watt |
kW | Kilowatt, introduced in version 0.19 |
VA | Volt-ampere |
Pressure:
Unit | Description |
---|---|
Pa | Pascal |
kPa | Kilopascal |
MPa | Megapascal |
GPa | Gigapascal |
mbar | MilliBar, introduced in version 0.19 |
bar | Bar, introduced in version 0.19 |
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 |
Mpsi | Megapound-force per square inch, introduced in version 0.19 |
Temperature:
Unit | Description |
---|---|
uK | Microkelvin; alternative to the unit µK |
µK | Microkelvin; alternative to the unit uK |
mK | Millikelvin |
K | Kelvin |
Time:
Unit | Description |
---|---|
s | Second |
min | Minute |
h | Hour |
Hz (1/s) | Hertz, introduced in version 0.19 |
kHz | Kilohertz, introduced in version 0.19 |
MHz | Megahertz, introduced in version 0.19 |
GHz | Gigahertz, introduced in version 0.19 |
THz | Terahertz, introduced in version 0.19 |
Volume:
Unit | Description |
---|---|
ml | Milliliter, introduced in version 0.19 |
l | Liter |
cft | Cubicfoot, introduced in version 0.19 |
Special imperial units:
Unit | Description |
---|---|
mph | Miles per hour, introduced in version 0.19 |
sqft | Square foot, introduced in version 0.19 |
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.
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.
- 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
- FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics
- Modules: Builtin modules, Units, Quantity
- Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
- Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC
- Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
- Scenegraph: Coin (Inventor) scenegraph, Pivy
- Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Embedding: Embedding FreeCAD, Embedding FreeCADGui
- Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)
- Hubs: User hub, Power users hub, Developer hub