Expressions: Difference between revisions
(→Names: Give examples for units explicitly) |
(V0.22 -> V1.0) |
||
(252 intermediate revisions by 17 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:Bound-expression.svg|24px]]. Clicking on the icon or typing the equal sign {{KEY|=}} brings up the expression editor for that particular property. |
||
<!--T:3--> |
<!--T:3--> |
||
A FreeCAD expression is a mathematical expression |
A FreeCAD expression is a mathematical expression using the standard mathematical [[#Supported_operators|operators]], [[#Supported_functions|functions]] and [[#Supported_constants|predefined constants]] as described below. In addition, the expression may reference object properties, and also use [[#Conditional_expressions|conditionals]]. Numbers in an expression may have an optional [[#Units|unit]] attached to them. |
||
<!--T:54--> |
<!--T:54--> |
||
Numbers may use either a comma |
Numbers may use either a comma {{incode|,}} or a decimal point {{incode|.}} to separate whole digits from decimals. When the decimal marker is used, it ''must'' be followed by at least one digit. 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. |
||
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. |
|||
<!--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. This also applies to references to object properties that have units, such as Length properties. Thus {{incode|Pad001.Length + 1}} is invalid since it adds a pure number to a property with length units, it requires {{incode|Pad001.Length + 1mm}}. |
||
<!--T: |
<!--T:199--> |
||
Some unit related errors can seem unintuitive, with expressions either being rejected or producing results that do not match the units of the property being set. Here are some examples: |
|||
You can use [[#Supported Constants|predefined constants]] and [[#Supported Functions|functions]]. |
|||
<!--T:200--> |
|||
{{incode|1/2mm}} is not interpreted as half a millimeter but as {{incode|1/(2mm)}}, resulting in: {{incode|0.5 mm^-1}}. |
|||
<!--T:201--> |
|||
{{incode|sqrt(2)mm}} is not valid because the function call is not a number. This has to be entered as {{incode|sqrt(2) * 1mm}}. |
|||
===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--> |
||
As already shown above, you can reference an object by its {{PropertyData|Name}}. But you can also use 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 |
You can reference any property of an object. For example, to reference a Cylinder's height, you may use {{incode|Cylinder.Height}} or {{incode|<<Label_of_cylinder>>.Height}}. |
||
<!--T:71--> |
|||
To reference list objects, the syntax is {{incode|<<object_label>>.list[list_index]}} or {{incode|object_name.list[list_index]}}. If you want for example reference a constraint in a sketch, do it this way '''<<MySketch>>.Constraints[16]'''. If you are in the same sketch you can omit its name and just use '''Constraints[16]'''.<br/> |
|||
'''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]]. |
||
</translate>{{Top}}<translate> |
|||
<!--T: |
== Supported constants == <!--T:58--> |
||
<!--T:157--> |
|||
The following constants are supported: |
|||
<!--T:59--> |
|||
{| 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] |
|||
|} |
|||
</translate>{{Top}}<translate> |
|||
== Supported operators == <!--T:96--> |
|||
<!--T:158--> |
|||
The following operators are supported: |
The following operators are supported: |
||
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
|||
<!--T:53--> |
|||
{| class="wikitable" |
|||
!style="width: 33%;"|Operator |
!style="width: 33%;"|Operator |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 63: | Line 95: | ||
|} |
|} |
||
</translate>{{Top}}<translate> |
|||
==Supported Constants== <!--T:58--> |
|||
<!--T: |
== Supported functions == <!--T:5--> |
||
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] |
|||
|} |
|||
== |
=== General mathematical functions === <!--T:55--> |
||
<!--T:159--> |
|||
=== General Mathematical Functions === <!--T:55--> |
|||
The following mathematical functions are supported: |
|||
==== Trigonometric functions ==== <!--T:160--> |
|||
<!--T:7--> |
|||
The mathematical functions listed below are available. |
|||
<!--T: |
<!--T:161--> |
||
[https://en.wikipedia.org/wiki/Trigonometric_functions Trigonometric functions] use degree as their default unit. For radians 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|1deg}}, {{incode|1°}} or {{incode|1rad}} as appropriate, e.g. {{incode|(360 - X) * 1deg}}; {{incode|(360 - X) * 1°}}; {{incode|(0.5 + pi / 2) * 1rad}}. |
|||
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--> |
||
{| class="wikitable" |
|||
[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)'''. 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'''. <br/> |
|||
!style="width: 15%;"|Function |
|||
These trigonometric functions are supported: |
|||
!style="width: 55%;"|Description |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: |
!style="width: 30%;"|Input range |
||
!style="width: 33%;"|Description |
|||
!style="width: 33%;"|Value range |
|||
|- |
|- |
||
| acos(x) |
| {{incode|acos(x)}} |
||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc cosine] |
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc cosine] |
||
| -1 <= x <= 1 |
| -1 <= x <= 1 |
||
|- |
|- |
||
| asin(x) |
| {{incode|asin(x)}} |
||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc sine] |
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc sine] |
||
| -1 <= x <= 1 |
| -1 <= x <= 1 |
||
|- |
|- |
||
| atan(x) |
| {{incode|atan(x)}} |
||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] |
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent], return value in the range -90° < value < 90° |
||
| all |
| all |
||
|- |
|- |
||
| atan2( |
| {{incode|atan2(y; x)}} |
||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] of '' |
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] of ''y/x'' accounting for quadrant, return value in the range -180° < value <= 180° |
||
| all, |
| all, the invalid input x = y = 0 returns 0 |
||
|- |
|- |
||
| cos(x) |
| {{incode|cos(x)}} |
||
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Cosine] |
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Cosine] |
||
| all |
| all |
||
|- |
|- |
||
| cosh(x) |
| {{incode|cosh(x)}} |
||
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic cosine] |
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic cosine] |
||
| all |
| all |
||
|- |
|- |
||
| sin(x) |
| {{incode|sin(x)}} |
||
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Sine] |
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Sine] |
||
| all |
| all |
||
|- |
|- |
||
| sinh(x) |
| {{incode|sinh(x)}} |
||
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic sine] |
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic sine] |
||
| all |
| all |
||
|- |
|- |
||
| tan(x) |
| {{incode|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 |
| all, except x = n*90 with n = odd integer |
||
|- |
|- |
||
| tanh(x) |
| {{incode|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 |
||
|- |
|||
| {{incode|hypot(x; y)}} |
|||
| [https://en.wikipedia.org/wiki/Pythagorean_addition Pythagorean addition] ('''hypot'''enuse), e.g. hypot(4; 3) = 5 |
|||
| x and y >= 0 |
|||
|- |
|||
| {{incode|cath(x; y)}} |
|||
| Given hypotenuse, and one side, returns other side of triangle, e.g. cath(5; 3) = 4 |
|||
| x >= y >= 0 |
|||
|} |
|} |
||
==== Exponential and logarithmic functions ==== <!--T:162--> |
|||
<!--T:30--> |
<!--T:30--> |
||
{| class="wikitable" |
|||
These functions for exponentiation and logarithmization are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Function |
!style="width: 33%;"|Function |
||
!style="width: 33%;"|Description |
!style="width: 33%;"|Description |
||
!style="width: 33%;"| |
!style="width: 33%;"|Input range |
||
|- |
|- |
||
| exp(x) |
| {{incode|exp(x)}} |
||
| [https://en.wikipedia.org/wiki/Exponential_function#Formal_definition Exponential function] |
| [https://en.wikipedia.org/wiki/Exponential_function#Formal_definition Exponential function] |
||
| all |
| all |
||
|- |
|- |
||
| log(x) |
| {{incode|log(x)}} |
||
| [https://en.wikipedia.org/wiki/Natural_logarithm Natural logarithm] |
| [https://en.wikipedia.org/wiki/Natural_logarithm Natural logarithm] |
||
| x > 0 |
| x > 0 |
||
|- |
|- |
||
| log10(x) |
| {{incode|log10(x)}} |
||
| [https://en.wikipedia.org/wiki/Common_logarithm Common logarithm] |
| [https://en.wikipedia.org/wiki/Common_logarithm Common logarithm] |
||
| x > 0 |
| x > 0 |
||
|- |
|- |
||
| pow(x |
| {{incode|pow(x; y)}} |
||
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation] |
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation] |
||
| all |
| all |
||
|- |
|- |
||
| sqrt(x) |
| {{incode|sqrt(x)}} |
||
| [https://en.wikipedia.org/wiki/Square_root Square root] |
| [https://en.wikipedia.org/wiki/Square_root Square root] |
||
| x >= 0 |
| x >= 0 |
||
|- |
|||
| {{incode|cbrt(x)}} {{Version|0.21}} |
|||
| [https://en.wikipedia.org/wiki/Cube_root Cubic root] |
|||
| all |
|||
|} |
|} |
||
==== Rounding, truncation and remainder functions ==== <!--T:163--> |
|||
<!--T:31--> |
<!--T:31--> |
||
{| class="wikitable" |
|||
These functions for rounding, truncation and remainder are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 20%;"|Function |
!style="width: 20%;"|Function |
||
!style="width: 55%;"|Description |
!style="width: 55%;"|Description |
||
!style="width: 25%;"| |
!style="width: 25%;"|Input range |
||
|- |
|- |
||
| abs(x) |
| {{incode|abs(x)}} |
||
| [https://en.wikipedia.org/wiki/Absolute_value Absolute value] |
| [https://en.wikipedia.org/wiki/Absolute_value Absolute value] |
||
| all |
| all |
||
|- |
|- |
||
| ceil(x) |
| {{incode|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 |
||
|- |
|- |
||
| floor(x) |
| {{incode|floor(x)}} |
||
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Floor function], largest integer value less than or equal to x |
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Floor function], largest integer value less than or equal to x |
||
| all |
| all |
||
|- |
|- |
||
| mod(x |
| {{incode|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'', sign of result is that of the dividend. |
||
| all, except y = 0 |
| all, except y = 0 |
||
|- |
|- |
||
| round(x) |
| {{incode|round(x)}} |
||
| [https://en.wikipedia.org/wiki/Rounding Rounding] to the nearest integer |
| [https://en.wikipedia.org/wiki/Rounding Rounding] to the nearest integer |
||
| all |
| all |
||
|- |
|- |
||
| trunc(x) |
| {{incode|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 |
||
|} |
|} |
||
</translate>{{Top}}<translate> |
|||
=== Statistical / Aggregate Functions === <!--T:8--> |
|||
[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/> |
|||
=== Statistical / aggregate functions === <!--T:99--> |
|||
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.<br/> |
|||
Arguments may include ranges of cells (two cell references separated by a colon), for example '''average(B1:B8)'''. |
|||
<!--T:8--> |
|||
[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:164--> |
|||
The following aggregate functions are supported: |
|||
<!--T:60--> |
<!--T:60--> |
||
{| class="wikitable" |
|||
These aggregate functions are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 20%;"|Function |
!style="width: 20%;"|Function |
||
!style="width: 55%;"|Description |
!style="width: 55%;"|Description |
||
!style="width: 25%;"| |
!style="width: 25%;"|Input range |
||
|- |
|- |
||
| average( |
| {{incode|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( |
| {{incode|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( |
| {{incode|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( |
| {{incode|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( |
| {{incode|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( |
| {{incode|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 |
||
|} |
|} |
||
</translate>{{Top}}<translate> |
|||
== 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 conversion ==== <!--T:180--> |
|||
<!--T:181--> |
|||
Numerical values can be converted to strings with the {{incode|str}} function: |
|||
</translate> |
|||
{{incode|str(Box.Length.Value)}} |
|||
<translate> |
|||
==== 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), the following expression {{incode|<<Cube length : %s>> % Box.Length}} will expand to "Cube length : 10.0 mm" |
|||
<!--T:112--> |
|||
For more than one %-specifier use the following syntax: {{incode|<<Cube length is %s and width is %s>> % tuple(Box.Length; Box.Width)}}. Or use concatenation: {{incode|<<Cube length is %s>> % Box.Length + << and width is %s>> % Box.Width}}. Both will expand to "Cube length is 10.0 mm and width is 10.0 mm". |
|||
<!--T:113--> |
|||
A FreeCAD sample file using string formatting is available [https://forum.freecadweb.org/viewtopic.php?f=8&t=58657 in the forum] |
|||
</translate>{{Top}}<translate> |
|||
=== Object creation functions === <!--T:116--> |
|||
<!--T:117--> |
|||
The following objects may be created in expressions using the following functions: |
|||
<!--T:193--> |
|||
{| class="wikitable" |
|||
! Type |
|||
! Function |
|||
! Description |
|||
|- |
|||
| {{incode|Tuple}} |
|||
| {{incode|tuple(a; b; ...)}} |
|||
| Example: {{incode|tuple(2; 1; 2)}} |
|||
|- |
|||
| {{incode|List}} |
|||
| {{incode|list(a; b; ...)}} |
|||
| Example: {{incode|list(2; 1; 2)}} |
|||
|- |
|||
| rowspan="2" | [[Vector API|{{incode|Vector}}]] |
|||
| {{incode|vector(x; y; z)}} |
|||
| rowspan="2" | Create a vector using three unit-less or {{incode|Length}} unit values. |
|||
Example: {{incode|vector(2; 1; 3)}} |
|||
|- |
|||
| {{incode|create(<<vector>>; x; y; z)}} |
|||
|- |
|||
| rowspan="2" | [[Matrix API|{{incode|Matrix}}]] |
|||
| |
|||
matrix( |
|||
a<sub>11</sub>; a<sub>12</sub>; a<sub>13</sub>; a<sub>14</sub>; |
|||
a<sub>21</sub>; a<sub>22</sub>; a<sub>23</sub>; a<sub>24</sub>; |
|||
a<sub>31</sub>; a<sub>32</sub>; a<sub>33</sub>; a<sub>34</sub>; |
|||
a<sub>41</sub>; a<sub>42</sub>; a<sub>43</sub>; a<sub>44</sub> |
|||
) |
|||
| rowspan="2" | Create a 4x4 matrix in [https://en.wikipedia.org/wiki/Row-_and_column-major_order row-major order]: |
|||
<math> |
|||
\begin{bmatrix} |
|||
a_{11} & a_{12} & a_{13} & a_{14} \\ |
|||
a_{21} & a_{22} & a_{23} & a_{24} \\ |
|||
a_{31} & a_{32} & a_{33} & a_{34} \\ |
|||
a_{41} & a_{42} & a_{43} & a_{44} \\ |
|||
\end{bmatrix} |
|||
</math> |
|||
<!--T:194--> |
|||
A minimum of 1 argument can be supplied such as {{incode|matrix(1)}} which creates an identity matrix. |
|||
<!--T:195--> |
|||
Example: {{incode|matrix(1; 2; 3; 4; 5; 6; 7; 8; 9; 10; 11; 12; 13; 14; 15; 16)}} |
|||
|- |
|||
| {{incode|create(<<matrix>>; a<sub>11</sub>; a<sub>12</sub>; ...; a<sub>44</sub>)}} |
|||
|- |
|||
| rowspan="4" | {{incode|Rotation}} |
|||
| {{incode|rotation(axis; angle)}} |
|||
| rowspan="4" | Create a {{incode|Rotation}} by specifying its {{incode|axis}} ({{incode|Vector}}) and {{incode|angle}} ({{incode|Angle}} unit or unit-less), or three Euler angles {{incode|α}}, {{incode|β}}, {{incode|γ}}. |
|||
Examples: |
|||
* {{incode|rotation(vector(0; 1; 0); 45)}} |
|||
* {{incode|create(<<rotation>>; 30; 30; 30)}} |
|||
|- |
|||
| {{incode|rotation(α; β; γ)}} |
|||
|- |
|||
| {{incode|create(<<rotation>>; axis; angle)}} |
|||
|- |
|||
| {{incode|create(<<rotation>>; α; β; γ)}} |
|||
|- |
|||
| rowspan="5" | [[Placement_API|{{incode|Placement}}]] |
|||
| {{incode|placement(base; rotation)}} |
|||
| rowspan="5" | Create a {{incode|Placement}} with various parameters, including: |
|||
* {{incode|base}}: base location ({{incode|Vector}}) |
|||
* {{incode|center}}: center location ({{incode|Vector}}) |
|||
* {{incode|rotation}}: {{incode|Rotation}} |
|||
* {{incode|axis}}: Rotation axis ({{incode|Vector}}) |
|||
* {{incode|angle}}: Rotation angle (unit-less or {{incode|Angle}} unit value) |
|||
* {{incode|matrix}}: {{incode|Matrix}} |
|||
<!--T:196--> |
|||
Examples: |
|||
* {{incode|placement(vector(2; 1; 3); rotation(vector(0; 0; 1); 45))}} |
|||
* {{incode|create(<<placement>>; create(<<vector>>; 2; 1; 2); create(<<rotation>>; create(<<vector>>; 0; 1; 0); 45))}} |
|||
|- |
|||
| {{incode|placement(base; rotation; center)}} |
|||
|- |
|||
| {{incode|placement(base; axis; angle)}} |
|||
|- |
|||
| {{incode|placement(matrix)}} |
|||
|- |
|||
| {{incode|create(<<placement>>; ...)}} |
|||
|} |
|||
</translate>{{Top}}<translate> |
|||
=== Vector functions === <!--T:202--> |
|||
<!--T:204--> |
|||
Functions: {{Version|1.0}}. |
|||
<!--T:203--> |
|||
{| class="wikitable" |
|||
! Function / Operator |
|||
! Description |
|||
|- |
|||
| {{incode|v1 + v2}} |
|||
| Add two vectors. |
|||
|- |
|||
| {{incode|v1 - v2}} |
|||
| Subtract two vectors. |
|||
|- |
|||
| {{incode|v * s}} |
|||
| Uniformly scale a vector by {{incode|s}}. |
|||
|- |
|||
| {{incode|vangle(v1; v2)}} |
|||
| Angle between two vectors in degrees. |
|||
|- |
|||
| {{incode|vcross(v1; v2)}} |
|||
| Cross product of two vectors <math>v_1 \times v_2</math>. |
|||
|- |
|||
| {{incode|v1 * v2}} |
|||
| rowspan="2" | Dot product of two vectors <math>v_1 \cdot v_2</math>. |
|||
|- |
|||
| {{incode|vdot(v1; v2)}} |
|||
|- |
|||
| {{incode|vlinedist(v1; v2; v3)}} |
|||
| Distance between vector {{incode|v1}} and a line through {{incode|v2}} in direction {{incode|v3}}. |
|||
|- |
|||
| {{incode|vlinesegdist(v1; v2; v3)}} |
|||
| Distance between vector {{incode|v1}} and the closest point on a line segment from {{incode|v2}} to {{incode|v3}}. |
|||
|- |
|||
| {{incode|vlineproj(v1; v2; v3)}} |
|||
| Project vector {{incode|v1}} on a line through {{incode|v2}} in direction {{incode|v3}}. |
|||
|- |
|||
| {{incode|vnormalize(v)}} |
|||
| Normalize a vector to a unit vector. |
|||
|- |
|||
| {{incode|vplanedist(v1)}} |
|||
| Distance between vector {{incode|v1}} and a plane defined by a point {{incode|v2}} and a normal {{incode|v3}}. |
|||
|- |
|||
| {{incode|vplaneproj(v1)}} |
|||
| Project vector {{incode|v1}} on a plane defined by a point {{incode|v2}} and a normal {{incode|v3}}. |
|||
|- |
|||
| {{incode|vscale(v; sx; sy; sz)}} |
|||
| rowspan="4" | Non-uniformly scale a vector by {{incode|sx}} in the X direction, {{incode|sy}} in the Y direction, and {{incode|sz}} in the Z direction. |
|||
|- |
|||
| {{incode|vscalex(v; sx)}} |
|||
|- |
|||
| {{incode|vscaley(v; sy)}} |
|||
|- |
|||
| {{incode|vscalez(v; sz)}} |
|||
|} |
|||
</translate>{{Top}}<translate> |
|||
=== Matrix functions === <!--T:143--> |
|||
<!--T:197--> |
|||
{{incode|Rotation}} and {{incode|Placement}} can each be represented by a {{incode|Matrix}}. The following functions all take in a {{incode|Matrix}}, {{incode|Rotation}}, or {{incode|Placement}} as their first parameter denoted in the table below by {{incode|m}}. The type of the returned object is the same as the object supplied in the first argument except when using {{incode|mtranslate}} on a {{incode|Rotation}}, in which case a {{incode|Placement}} will be returned. |
|||
<!--T:198--> |
|||
{| class="wikitable" |
|||
! Function |
|||
! Description |
|||
|- |
|||
| {{incode|minvert(m)}} |
|||
| Calculate the [https://en.wikipedia.org/wiki/Invertible_matrix Inverse matrix]. |
|||
|- |
|||
| {{incode|mrotate(m; rotation)}} |
|||
| rowspan="3" | [https://en.wikipedia.org/wiki/Transformation_matrix#Rotation_2 Rotate] by either: |
|||
* a {{incode|Rotation}} |
|||
* an axis ({{incode|Vector}}) and an angle ({{incode|Angle}} unit or unit-less) |
|||
* three Euler angles {{incode|α}}, {{incode|β}}, {{incode|γ}} |
|||
|- |
|||
| {{incode|mrotate(m; axis; angle)}} |
|||
|- |
|||
| {{incode|mrotate(m; α; β; γ)}} |
|||
|- |
|||
| {{incode|mrotatex(m; angle)}} |
|||
| [https://en.wikipedia.org/wiki/Transformation_matrix#Rotation_2 Rotate] around the X axis. |
|||
|- |
|||
| {{incode|mrotatey(m; angle)}} |
|||
| [https://en.wikipedia.org/wiki/Transformation_matrix#Rotation_2 Rotate] around the Y axis. |
|||
|- |
|||
| {{incode|mrotatez(m; angle)}} |
|||
| [https://en.wikipedia.org/wiki/Transformation_matrix#Rotation_2 Rotate] around the Z axis. |
|||
|- |
|||
| {{incode|mtranslate(m; vector)}} |
|||
| rowspan="2" | [https://en.wikipedia.org/wiki/Translation_(geometry)#Matrix_representation Translate] by a {{incode|vector}} ({{incode|Vector}}) or X, Y, Z values. If a {{incode|Rotation}} is translated, the returned object is a {{incode|Placement}}. |
|||
|- |
|||
| {{incode|mtranslate(m; x; y; z)}} |
|||
|- |
|||
| {{incode|mscale(m; vector)}} |
|||
| rowspan="2" | [https://en.wikipedia.org/wiki/Scaling_(geometry)#Matrix_representation Scale] by a {{incode|vector}} ({{incode|Vector}}) or X, Y, Z values. |
|||
|- |
|||
| {{incode|mscale(m; x; y; z)}} |
|||
|} |
|||
</translate>{{Top}}<translate> |
|||
== 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}} |
|||
<!--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 |
{| class="wikitable" |
||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 264: | Line 548: | ||
| less than or equal to |
| less than or equal to |
||
|} |
|} |
||
</translate>{{Top}}<translate> |
|||
== Units == <!--T:34--> |
== Units == <!--T:34--> |
||
<!--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--> |
||
The following units are recognized by the expression parser: |
The following units are recognized by the expression parser: |
||
=== Amount of substance === <!--T:165--> |
|||
<!--T:38--> |
<!--T:38--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Amount of substance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 295: | Line 582: | ||
| [https://en.wikipedia.org/wiki/Mole_(unit) Mole] |
| [https://en.wikipedia.org/wiki/Mole_(unit) Mole] |
||
|} |
|} |
||
=== Angle === <!--T:166--> |
|||
<!--T:39--> |
<!--T:39--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Angle: |
|||
{| class="wikitable float-right 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 |
| [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 315: | Line 603: | ||
|- |
|- |
||
| 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 |
| [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 |
| [https://en.wikipedia.org/wiki/Minute_and_second_of_arc Minute of arc]; alternative to the unit M |
||
|} |
|} |
||
=== Current === <!--T:167--> |
|||
<!--T:40--> |
<!--T:40--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Current: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 345: | Line 634: | ||
| Mega[https://en.wikipedia.org/wiki/Ampere ampere] |
| Mega[https://en.wikipedia.org/wiki/Ampere ampere] |
||
|} |
|} |
||
=== Electric capacitance === <!--T:183--> |
|||
<!--T:75--> |
<!--T:75--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Electrical Capacitance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| pF |
| pF |
||
| Pico[https://en.wikipedia.org/wiki/Farad farad] |
| Pico[https://en.wikipedia.org/wiki/Farad farad] |
||
|- |
|- |
||
| nF |
| nF |
||
| Nano[https://en.wikipedia.org/wiki/Farad farad] |
| Nano[https://en.wikipedia.org/wiki/Farad farad] |
||
|- |
|- |
||
| uF |
| uF |
||
| Micro[https://en.wikipedia.org/wiki/Farad farad]; alternative to the unit |
| Micro[https://en.wikipedia.org/wiki/Farad farad]; alternative to the unit µF |
||
|- |
|- |
||
| µF |
| µF |
||
| Micro[https://en.wikipedia.org/wiki/Farad farad]; alternative to the unit |
| Micro[https://en.wikipedia.org/wiki/Farad farad]; alternative to the unit uF |
||
|- |
|- |
||
| mF |
| mF |
||
| Milli[https://en.wikipedia.org/wiki/Farad farad] |
| Milli[https://en.wikipedia.org/wiki/Farad farad] |
||
|- |
|- |
||
| F |
| F |
||
| [https://en.wikipedia.org/wiki/Farad Farad]; 1 F = 1 s^4·A^2/m^2/kg |
| [https://en.wikipedia.org/wiki/Farad Farad]; 1 F = 1 s^4·A^2/m^2/kg |
||
|} |
|} |
||
<!--T: |
=== Electric charge === <!--T:184--> |
||
Electrical Conductance: |
|||
<!--T:73--> |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| C |
|||
| [https://en.wikipedia.org/wiki/Coulomb Coulomb]; 1 C = 1 A*s |
|||
|} |
|||
=== Electric conductivity === <!--T:185--> |
|||
<!--T:186--> |
|||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| uS |
| uS |
||
| Micro[https://en.wikipedia.org/wiki/Siemens_(unit) siemens]; alternative to the unit |
| Micro[https://en.wikipedia.org/wiki/Siemens_(unit) siemens]; alternative to the unit µS |
||
|- |
|- |
||
| µS |
| µS |
||
| Micro[https://en.wikipedia.org/wiki/Siemens_(unit) siemens]; alternative to the unit |
| Micro[https://en.wikipedia.org/wiki/Siemens_(unit) siemens]; alternative to the unit uS |
||
|- |
|- |
||
| mS |
| mS |
||
| Milli[https://en.wikipedia.org/wiki/Siemens_(unit) siemens] |
| Milli[https://en.wikipedia.org/wiki/Siemens_(unit) siemens] |
||
|- |
|- |
||
| S |
| S |
||
| [https://en.wikipedia.org/wiki/Siemens_(unit) Siemens]; 1 S = 1 s^3·A^2/kg/m^2 |
| [https://en.wikipedia.org/wiki/Siemens_(unit) Siemens]; 1 S = 1 s^3·A^2/kg/m^2 |
||
|- |
|||
| kS |
|||
| Kilo[https://en.wikipedia.org/wiki/Siemens_(unit) Siemens] |
|||
|- |
|||
| MS |
|||
| Mega[https://en.wikipedia.org/wiki/Siemens_(unit) Siemens] |
|||
|} |
|} |
||
=== Electric inductance === <!--T:187--> |
|||
<!--T:76--> |
<!--T:76--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Electrical Inductance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| nH |
| nH |
||
| Nano[https://en.wikipedia.org/wiki/Henry_(unit) henry] |
| Nano[https://en.wikipedia.org/wiki/Henry_(unit) henry] |
||
|- |
|- |
||
| uH |
| uH |
||
| Micro[https://en.wikipedia.org/wiki/Henry_(unit) henry]; alternative to the unit |
| Micro[https://en.wikipedia.org/wiki/Henry_(unit) henry]; alternative to the unit µH |
||
|- |
|- |
||
| µH |
| µH |
||
| Micro[https://en.wikipedia.org/wiki/Henry_(unit) henry]; alternative to the unit |
| Micro[https://en.wikipedia.org/wiki/Henry_(unit) henry]; alternative to the unit uH |
||
|- |
|- |
||
| mH |
| mH |
||
| Milli[https://en.wikipedia.org/wiki/Henry_(unit) henry] |
| Milli[https://en.wikipedia.org/wiki/Henry_(unit) henry] |
||
|- |
|- |
||
| H |
| H |
||
| [https://en.wikipedia.org/wiki/Henry_(unit) Henry]; 1 H = 1 kg·m^2/s^2/A^2 |
| [https://en.wikipedia.org/wiki/Henry_(unit) Henry]; 1 H = 1 kg·m^2/s^2/A^2 |
||
|} |
|} |
||
<!--T: |
=== Electric potential === <!--T:188--> |
||
Electrical Resistance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| Ohm |
|||
| [https://en.wikipedia.org/wiki/Ohm Ohm]; 1 Ohm = 1 kg·m^2/s^3/A^2, {{Version|0.19}} |
|||
|- |
|||
| kOhm |
|||
| Kilo[https://en.wikipedia.org/wiki/Ohm ohm], {{Version|0.19}} |
|||
|- |
|||
| MOhm |
|||
| Mega[https://en.wikipedia.org/wiki/Ohm ohm], {{Version|0.19}} |
|||
|} |
|||
<!--T:73--> |
|||
Electric Charge: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| C |
|||
| [https://en.wikipedia.org/wiki/Coulomb Coulomb]; 1 C = 1 A·s, {{Version|0.19}} |
|||
|} |
|||
<!--T:74--> |
<!--T:74--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Electric Potential: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 453: | Line 737: | ||
| Kilo[https://en.wikipedia.org/wiki/Volt volt] |
| Kilo[https://en.wikipedia.org/wiki/Volt volt] |
||
|} |
|} |
||
=== Electric resistance === <!--T:189--> |
|||
<!--T:80--> |
|||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| Ohm |
|||
| [https://en.wikipedia.org/wiki/Ohm Ohm]; 1 Ohm = 1 kg·m^2/s^3/A^2 |
|||
|- |
|||
| kOhm |
|||
| Kilo[https://en.wikipedia.org/wiki/Ohm ohm] |
|||
|- |
|||
| MOhm |
|||
| Mega[https://en.wikipedia.org/wiki/Ohm ohm] |
|||
|} |
|||
=== Energy/work === <!--T:168--> |
|||
<!--T:41--> |
<!--T:41--> |
||
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 467: | Line 769: | ||
|- |
|- |
||
| kJ |
| kJ |
||
| Kilo[https://en.wikipedia.org/wiki/Joule joule] |
| Kilo[https://en.wikipedia.org/wiki/Joule joule] |
||
|- |
|- |
||
| eV |
| eV |
||
| [https://en.wikipedia.org/wiki/Electronvolt Electronvolt]; 1 |
| [https://en.wikipedia.org/wiki/Electronvolt Electronvolt]; 1 eV = 1.602176634e-19 J |
||
|- |
|- |
||
| keV |
| keV |
||
| Kilo[https://en.wikipedia.org/wiki/Electronvolt electronvolt] |
| Kilo[https://en.wikipedia.org/wiki/Electronvolt electronvolt] |
||
|- |
|- |
||
| MeV |
| MeV |
||
| Mega[https://en.wikipedia.org/wiki/Electronvolt electronvolt] |
| Mega[https://en.wikipedia.org/wiki/Electronvolt electronvolt] |
||
|- |
|- |
||
| kWh |
| kWh |
||
| [https://en.wikipedia.org/wiki/Kilowatt_hour Kilowatt hour]; 1 kWh = 3.6e6 J |
| [https://en.wikipedia.org/wiki/Kilowatt_hour Kilowatt hour]; 1 kWh = 3.6e6 J |
||
|- |
|- |
||
| Ws |
| Ws |
||
| [https://en.wikipedia.org/wiki/Joule#Watt_second Watt second]; alternative to the unit |
| [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 |
| [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 |
| [https://en.wikipedia.org/wiki/Joule Coulomb-volt]; alternative to the unit Joule |
||
|- |
|- |
||
| cal |
| cal |
||
| [https://en.wikipedia.org/wiki/Calorie Calorie]; 1 cal = 4.184 J |
| [https://en.wikipedia.org/wiki/Calorie Calorie]; 1 cal = 4.184 J |
||
|- |
|- |
||
| kcal |
| kcal |
||
| Kilo[https://en.wikipedia.org/wiki/Calorie calorie] |
| Kilo[https://en.wikipedia.org/wiki/Calorie calorie] |
||
|} |
|} |
||
=== Force === <!--T:169--> |
|||
<!--T:42--> |
<!--T:42--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Force: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 518: | Line 821: | ||
| [https://en.wikipedia.org/wiki/Pound_(force) Pound of force] |
| [https://en.wikipedia.org/wiki/Pound_(force) Pound of force] |
||
|} |
|} |
||
=== Length === <!--T:170--> |
|||
<!--T:43--> |
<!--T:43--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Length: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 529: | Line 833: | ||
|- |
|- |
||
| um |
| um |
||
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit |
| 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 |
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit um |
||
|- |
|- |
||
| mm |
| mm |
||
Line 539: | Line 843: | ||
| 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 553: | Line 854: | ||
|- |
|- |
||
| mil |
| mil |
||
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit |
| [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 |
| [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 565: | Line 869: | ||
|- |
|- |
||
| ' |
| ' |
||
| [https://en.wikipedia.org/wiki/Foot_(unit) Foot]; alternative to the unit |
| [https://en.wikipedia.org/wiki/Foot_(unit) Foot]; alternative to the unit ft |
||
|- |
|- |
||
| yd |
| yd |
||
Line 573: | Line 877: | ||
| [https://en.wikipedia.org/wiki/Mile Mile] |
| [https://en.wikipedia.org/wiki/Mile Mile] |
||
|} |
|} |
||
=== Luminous intensity === <!--T:171--> |
|||
<!--T:44--> |
<!--T:44--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Luminous Intensity: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 584: | Line 889: | ||
|} |
|} |
||
<!--T: |
=== Magnetic flux === <!--T:190--> |
||
Magnetic Field Strength: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| Oe |
|||
| [https://en.wikipedia.org/wiki/Oersted Oersted]; 1 Oe = 79.57747 A/m, {{Version|0.19}} |
|||
|} |
|||
<!--T:82--> |
<!--T:82--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Magnetic Flux: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| Wb |
| Wb |
||
| [https://en.wikipedia.org/wiki/Weber_(unit) Weber]; 1 Wb = 1 kg*m^2/s^2/A |
| [https://en.wikipedia.org/wiki/Weber_(unit) Weber]; 1 Wb = 1 kg*m^2/s^2/A |
||
|} |
|} |
||
=== Magnetic flux density === <!--T:191--> |
|||
<!--T:77--> |
<!--T:77--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Magnetic Flux Density: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| G |
| G |
||
| [https://en.wikipedia.org/wiki/Gauss_(unit) Gauss]; 1 G = 1 e-4 T |
| [https://en.wikipedia.org/wiki/Gauss_(unit) Gauss]; 1 G = 1 e-4 T |
||
|- |
|- |
||
| T |
| T |
||
| [https://en.wikipedia.org/wiki/Tesla_(unit) Tesla]; 1 T = 1 kg/s^2/A |
| [https://en.wikipedia.org/wiki/Tesla_(unit) Tesla]; 1 T = 1 kg/s^2/A |
||
|} |
|} |
||
=== Mass === <!--T:172--> |
|||
<!--T:45--> |
<!--T:45--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Mass: |
|||
{| class="wikitable float-right 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 |
| 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 |
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit ug |
||
|- |
|- |
||
| mg |
| mg |
||
Line 645: | Line 943: | ||
|- |
|- |
||
| lb |
| lb |
||
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit |
| [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 |
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit lb |
||
|- |
|- |
||
| st |
| st |
||
Line 656: | Line 954: | ||
| [https://en.wikipedia.org/wiki/Hundredweight Hundredweight] |
| [https://en.wikipedia.org/wiki/Hundredweight Hundredweight] |
||
|} |
|} |
||
=== Power === <!--T:173--> |
|||
<!--T:61--> |
<!--T:61--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Power: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 667: | Line 966: | ||
|- |
|- |
||
| kW |
| kW |
||
| Kilo[https://en.wikipedia.org/wiki/Watt watt] |
| Kilo[https://en.wikipedia.org/wiki/Watt watt] |
||
|- |
|||
| VA |
|||
| [https://en.wikipedia.org/wiki/Volt-ampere Volt-ampere] |
|||
|} |
|} |
||
=== Pressure === <!--T:174--> |
|||
<!--T:46--> |
<!--T:46--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Pressure: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 690: | Line 987: | ||
| GPa |
| GPa |
||
| Giga[https://en.wikipedia.org/wiki/Pascal_(unit) pascal] |
| Giga[https://en.wikipedia.org/wiki/Pascal_(unit) pascal] |
||
|- |
|||
| mbar |
|||
| Milli[https://en.wikipedia.org/wiki/Bar_(unit) Bar], {{Version|0.19}} |
|||
|- |
|||
| bar |
|||
| [https://en.wikipedia.org/wiki/Bar_(unit) Bar], {{Version|0.19}} |
|||
|- |
|- |
||
| uTorr |
| uTorr |
||
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit |
| 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 |
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit uTorr |
||
|- |
|- |
||
| mTorr |
| mTorr |
||
Line 714: | Line 1,005: | ||
| ksi |
| ksi |
||
| Kilo[https://en.wikipedia.org/wiki/Pounds_per_square_inch pound-force per square inch] |
| Kilo[https://en.wikipedia.org/wiki/Pounds_per_square_inch pound-force per square inch] |
||
|- |
|||
| Mpsi |
|||
| Mega[https://en.wikipedia.org/wiki/Pounds_per_square_inch pound-force per square inch], {{Version|0.19}} |
|||
|} |
|} |
||
=== Temperature === <!--T:175--> |
|||
<!--T:47--> |
<!--T:47--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Temperature: |
|||
{| class="wikitable float-right 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 |
| 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 |
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit uK |
||
|- |
|- |
||
| mK |
| mK |
||
Line 737: | Line 1,026: | ||
| [https://en.wikipedia.org/wiki/Kelvin Kelvin] |
| [https://en.wikipedia.org/wiki/Kelvin Kelvin] |
||
|} |
|} |
||
=== Time === <!--T:176--> |
|||
<!--T:48--> |
<!--T:48--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Time: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
Line 754: | Line 1,044: | ||
|- |
|- |
||
| Hz (1/s) |
| Hz (1/s) |
||
| [https://en.wikipedia.org/wiki/Hertz Hertz] |
| [https://en.wikipedia.org/wiki/Hertz Hertz] |
||
|- |
|- |
||
| kHz |
| kHz |
||
| Kilo[https://en.wikipedia.org/wiki/Hertz hertz], |
| Kilo[https://en.wikipedia.org/wiki/Hertz hertz], |
||
|- |
|- |
||
| MHz |
| MHz |
||
| Mega[https://en.wikipedia.org/wiki/Hertz hertz] |
| Mega[https://en.wikipedia.org/wiki/Hertz hertz] |
||
|- |
|- |
||
| GHz |
| GHz |
||
| Giga[https://en.wikipedia.org/wiki/Hertz hertz] |
| Giga[https://en.wikipedia.org/wiki/Hertz hertz] |
||
|- |
|- |
||
| THz |
| THz |
||
| Tera[https://en.wikipedia.org/wiki/Hertz hertz] |
| Tera[https://en.wikipedia.org/wiki/Hertz hertz] |
||
|} |
|} |
||
<!--T: |
=== Volume === <!--T:177--> |
||
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--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Volume: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| ml |
| ml |
||
| Milli[https://en.wikipedia.org/wiki/Litre liter] |
| Milli[https://en.wikipedia.org/wiki/Litre liter] |
||
|- |
|- |
||
| l |
| l |
||
Line 792: | Line 1,073: | ||
|- |
|- |
||
| cft |
| cft |
||
| Cubic[https://en.wikipedia.org/wiki/Foot_(unit) foot] |
| Cubic[https://en.wikipedia.org/wiki/Foot_(unit) foot] |
||
|} |
|} |
||
=== Special imperial units === <!--T:192--> |
|||
<!--T:78--> |
<!--T:78--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
Special imperial units: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
!style="width: 33%;"|Unit |
||
!style="width: 66%;"|Description |
!style="width: 66%;"|Description |
||
|- |
|- |
||
| mph |
| mph |
||
| [https://en.wikipedia.org/wiki/Miles_per_hour Miles per hour] |
| [https://en.wikipedia.org/wiki/Miles_per_hour Miles per hour] |
||
|- |
|- |
||
| sqft |
| sqft |
||
| [https://en.wikipedia.org/wiki/Square_foot Square foot] |
| [https://en.wikipedia.org/wiki/Square_foot Square foot] |
||
|} |
|} |
||
=== Unsupported units === <!--T:178--> |
|||
<!--T:179--> |
|||
The following commonly used units are not yet supported, for some an alternative is provided: |
|||
<!--T:51--> |
<!--T:51--> |
||
{| class="wikitable mw-collapsible mw-collapsed" |
|||
The following commonly used units are not yet supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 25%;"|Unit |
!style="width: 25%;"|Unit |
||
!style="width: 50%;"|Description |
!style="width: 50%;"|Description |
||
Line 824: | Line 1,110: | ||
|- |
|- |
||
| u |
| u |
||
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Atomic mass unit]; alternative to the unit |
| [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 |
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Dalton]; alternative to the unit u |
||
| 1.66053906660e-27 kg |
| 1.66053906660e-27 kg |
||
|- |
|- |
||
Line 848: | Line 1,134: | ||
|} |
|} |
||
</translate>{{Top}}<translate> |
|||
==Invalid Characters and Names== |
|||
==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 |
{| class="wikitable" |
||
!style="width: 33%;"|Characters |
!style="width: 33%;"|Characters |
||
!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--> |
|||
===Names=== |
|||
For example, the label {{incode|Sketch\002}} must be referenced as {{incode|<<Sketch\\002>>}}. |
|||
===Names=== <!--T:91--> |
|||
[[Object_name#Name|Names]] of objects like dimensions, sketches etc. may not have the characters listed below. They may also not be equal to a unit. |
|||
<!--T:92--> |
|||
For example this is possible: '''<<Sketch>>.Constraints.T2üßµ@'''</br>while this 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: |
|||
'''<<Sketch>>.Constraints.test\result_2''' or '''<<Sketch>>.Constraints.mol''' |
|||
<!--T:93--> |
|||
The following characters in names are invalid: |
|||
{| class="wikitable |
{| class="wikitable" |
||
!style="width: 33%;"|Characters |
!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''', '''J''', '''K''', ''' ' ''', ''' ft ''', '''°''', and many more! |
|||
| Characters that are [[ |
| Characters and character sequences that are units (see the [[#Units|Units]] paragraph) |
||
|- |
|- |
||
| '''#''', '''!''', '''?''', '''§''', '''$''', '''%''', '''&''', ''':''', ''';''', '''\''', '''<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--> |
|||
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:182--> |
|||
See [[Spreadsheet_SetAlias#Usage|Spreadsheet SetAlias]]. |
|||
</translate>{{Top}}<translate> |
|||
== 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_name.property}} or {{incode|<<object_label>>.property}}, labels must be enclosed in {{incode|<<}} and {{incode|>>}}. If you want to use labels they must be unique. |
||
<!--T:205--> |
|||
All next examples reference the object by its name, but in all cases the object label can also be used. |
|||
<!--T:206--> |
|||
If the property is a compound of fields, the individual fields can be accessed as {{incode|object_name.property.field}}. |
|||
<!--T:71--> |
|||
To reference list objects use {{incode|object_name.list[list_index]}}. If you want to reference a constraint in a sketch, use {{incode|Sketch.Constraints[16]}}. If you are in the same sketch you may omit its name and just use {{incode|Constraints[16]}}. Note that the index starts with 0, therefore Constraint17 has to be referenced as {{incode|Constraints[16]}}. |
|||
<!--T:207--> |
|||
To reference the object itself use the {{incode|_self}} pseudo property: {{incode|object_name._self}}. |
|||
<!--T:14--> |
<!--T:14--> |
||
The following table shows some examples: |
The following table shows some more examples: |
||
{| class="wikitable" |
|||
{|{{Prettytable}} |
|||
!CAD |
!CAD data |
||
!Call in expression |
!Call in expression |
||
!Result |
!Result |
||
|- |
|- |
||
| |
|Length of a [[Part_Box|Part Box]] |
||
|{{incode| |
|{{incode|Box.Length}} |
||
|Length with units (mm) |
|||
|- |
|- |
||
|Volume of the |
|Volume of the Box |
||
|{{incode| |
|{{incode|Box.Shape.Volume}} |
||
|Volume in mm³ without units |
|||
|- |
|- |
||
| |
|Shape type of the Box |
||
|{{incode| |
|{{incode|Box.Shape.ShapeType}} |
||
|String: Solid |
|String: Solid |
||
|- |
|- |
||
|Label of the |
|Label of the Box |
||
|{{incode| |
|{{incode|Box.Label}} |
||
|String: Label |
|String: Label |
||
|- |
|- |
||
| |
|X-coordinate of center of mass of the Box |
||
|{{incode| |
|{{incode|Box.Shape.CenterOfMass.x}} |
||
| |
|X-coordinate in mm without units |
||
|- |
|||
|X-coordinate of the Box placement |
|||
|{{incode|Box.Placement.Base.x}} |
|||
|X-coordinate with units (mm) |
|||
|- |
|||
|X-component of the rotation axis of the Box placement |
|||
|{{incode|Box.Placement.Rotation.Axis.x}} |
|||
|X-component of the unit vector in mm without units |
|||
|- |
|||
|Rotation angle of the Box placement |
|||
|{{incode|Box.Placement.Rotation.Angle}} |
|||
|Rotation angle with units (deg) |
|||
|- |
|||
|Full Box object |
|||
|{{incode|Box._self}} |
|||
|Object of type <Part::PartFeature> |
|||
|- |
|- |
||
|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. |
||
|} |
|} |
||
=== Cyclic dependencies === <!--T:208--> |
|||
<!--T:209--> |
|||
FreeCAD checks dependencies based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. You have to use two spreadsheets, one to drive your model and the other for reporting. |
|||
<!--T:210--> |
|||
As a workaround it is possible to display a cell range from the second spreadsheet in the first (or vice versa) by creating a [[Spreadsheet_Workbench#Cell_binding|cell binding]] with the {{MenuCommand|Hide dependency of binding}} option. |
|||
<!--T:211--> |
|||
Another way to workaround cyclic dependencies is to hide the reference by using the {{incode|href}} or {{incode|hiddenref}} function for individual expressions, for example: {{incode|href(Box.Length)}}. |
|||
<!--T:212--> |
|||
Please note that both mentioned workarounds should be used with caution, and that they do not work if the properties that are reported depend on dimensions that are driven from the same spreadsheet. |
|||
</translate>{{Top}}<translate> |
|||
== Document-wide global variables == <!--T:15--> |
== Document-wide global variables == <!--T:15--> |
||
Line 946: | Line 1,298: | ||
<!--T:16--> |
<!--T:16--> |
||
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|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. |
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|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. |
||
</translate>{{Top}}<translate> |
|||
== Cross-document linking == <!--T:20--> |
== Cross-document linking == <!--T:20--> |
||
<!--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--> |
||
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). |
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. |
||
<!--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: |
||
</translate> |
|||
<!--T:65--> |
|||
{{incode|master#modelConstants.Length}} |
|||
<translate> |
|||
<!--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. |
|||
<!--T:24--> |
|||
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. |
|||
<!--T:25--> |
<!--T:25--> |
||
Of course, it's up to you to load the corresponding documents later when you want to change anything. |
Of course, it's up to you to load the corresponding documents later when you want to change anything. |
||
</translate>{{Top}}<translate> |
|||
== Known issues / remaining tasks == <!--T:17--> |
== Known issues / remaining tasks == <!--T:17--> |
||
<!--T:18--> |
<!--T:18--> |
||
* 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]. |
|||
* 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. |
|||
* Open bugs/tickets for Expressions can be found on [https://github.com/FreeCAD/FreeCAD/issues?q=is%3Aissue+is%3Aopen+label%3AExpressions GitHub]. |
|||
* The expression parser does not handle parentheses well, and is unable to properly parse some expressions. For example: "'''= (A1 > A2) ? 1 : 0'''" results in an error, while "'''= A1 > A2 ? 1 : 0'''" is accepted. The expression "'''= 5 + ((A1>A2) ? 1 : 0)'''" cannot be entered in any form. |
|||
* As stated above, unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the {{Button|OK}} button will become active. |
|||
</translate>{{Top}}<translate> |
|||
* 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] |
|||
</translate> |
</translate> |
||
{{Powerdocnavi{{#translation:}}}} |
{{Powerdocnavi{{#translation:}}}} |
||
[[Category:Spreadsheet{{#translation:}}]] |
[[Category:Spreadsheet{{#translation:}}]] |
||
{{clear}} |
Latest revision as of 10:00, 21 April 2024
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 . 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 using the standard mathematical operators, functions and predefined constants as described below. In addition, the expression may reference object 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 .
to separate 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. This also applies to references to object properties that have units, such as Length properties. Thus Pad001.Length + 1
is invalid since it adds a pure number to a property with length units, it requires Pad001.Length + 1mm
.
Some unit related errors can seem unintuitive, with expressions either being rejected or producing results that do not match the units of the property being set. Here are some examples:
1/2mm
is not interpreted as half a millimeter but as 1/(2mm)
, resulting in: 0.5 mm^-1
.
sqrt(2)mm
is not valid because the function call is not a number. This has to be entered as sqrt(2) * 1mm
.
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
As already shown above, you can reference an object by its DataName. But you can also use its DataLabel. In the case of a DataLabel, it must be enclosed in double <<
and >>
symbols, such as <<Label>>
.
You can reference any property of an object. For example, to reference a Cylinder's height, you may use Cylinder.Height
or <<Label_of_cylinder>>.Height
.
For more information about referencing objects, see Reference to CAD data.
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 following mathematical functions are supported:
Trigonometric functions
Trigonometric functions use degree as their default unit. For radians add rad
following the first value in an expression. So e.g. cos(45)
is the same as cos(pi rad / 4)
. Expressions in degrees can use either deg
or °
, e.g. 360deg - atan2(3; 4)
or 360° - atan2(3; 4)
. If an expression is without units and needs to be converted to degrees or radians for compatibility, multiply by 1deg
, 1°
or 1rad
as appropriate, e.g. (360 - X) * 1deg
; (360 - X) * 1°
; (0.5 + pi / 2) * 1rad
.
Function | Description | Input range |
---|---|---|
acos(x)
|
Arc cosine | -1 <= x <= 1 |
asin(x)
|
Arc sine | -1 <= x <= 1 |
atan(x)
|
Arc tangent, return value in the range -90° < value < 90° | all |
atan2(y; x)
|
Arc tangent of y/x accounting for quadrant, return value in the range -180° < value <= 180° | all, the invalid input x = y = 0 returns 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 = odd 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 >= y >= 0 |
Exponential and logarithmic functions
Function | Description | Input 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 |
cbrt(x) introduced in version 0.21
|
Cubic root | all |
Rounding, truncation and remainder functions
Function | Description | Input 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, sign of result is that of the dividend. | 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)
.
The following aggregate functions are supported:
Function | Description | Input 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 conversion
Numerical values can be converted to strings with the str
function:
str(Box.Length.Value)
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), the following expression <<Cube length : %s>> % Box.Length
will expand to "Cube length : 10.0 mm"
For more than one %-specifier use the following syntax: <<Cube length is %s and width is %s>> % tuple(Box.Length; Box.Width)
. Or use concatenation: <<Cube length is %s>> % Box.Length + << and width is %s>> % Box.Width
. Both will expand to "Cube length is 10.0 mm and width is 10.0 mm".
A FreeCAD sample file using string formatting is available in the forum
Object creation functions
The following objects may be created in expressions using the following functions:
Type | Function | Description |
---|---|---|
Tuple
|
tuple(a; b; ...)
|
Example: tuple(2; 1; 2)
|
List
|
list(a; b; ...)
|
Example: list(2; 1; 2)
|
Vector
|
vector(x; y; z)
|
Create a vector using three unit-less or Length unit values.
Example: |
create(<<vector>>; x; y; z)
| ||
Matrix
|
matrix( a11; a12; a13; a14; a21; a22; a23; a24; a31; a32; a33; a34; a41; a42; a43; a44 ) |
Create a 4x4 matrix in row-major order:
A minimum of 1 argument can be supplied such as Example: |
create(<<matrix>>; a11; a12; ...; a44)
| ||
Rotation
|
rotation(axis; angle)
|
Create a Rotation by specifying its axis (Vector ) and angle (Angle unit or unit-less), or three Euler angles α , β , γ .
Examples:
|
rotation(α; β; γ)
| ||
create(<<rotation>>; axis; angle)
| ||
create(<<rotation>>; α; β; γ)
| ||
Placement
|
placement(base; rotation)
|
Create a Placement with various parameters, including:
Examples:
|
placement(base; rotation; center)
| ||
placement(base; axis; angle)
| ||
placement(matrix)
| ||
create(<<placement>>; ...)
|
Vector functions
Functions: introduced in version 1.0.
Function / Operator | Description |
---|---|
v1 + v2
|
Add two vectors. |
v1 - v2
|
Subtract two vectors. |
v * s
|
Uniformly scale a vector by s .
|
vangle(v1; v2)
|
Angle between two vectors in degrees. |
vcross(v1; v2)
|
Cross product of two vectors . |
v1 * v2
|
Dot product of two vectors . |
vdot(v1; v2)
| |
vlinedist(v1; v2; v3)
|
Distance between vector v1 and a line through v2 in direction v3 .
|
vlinesegdist(v1; v2; v3)
|
Distance between vector v1 and the closest point on a line segment from v2 to v3 .
|
vlineproj(v1; v2; v3)
|
Project vector v1 on a line through v2 in direction v3 .
|
vnormalize(v)
|
Normalize a vector to a unit vector. |
vplanedist(v1)
|
Distance between vector v1 and a plane defined by a point v2 and a normal v3 .
|
vplaneproj(v1)
|
Project vector v1 on a plane defined by a point v2 and a normal v3 .
|
vscale(v; sx; sy; sz)
|
Non-uniformly scale a vector by sx in the X direction, sy in the Y direction, and sz in the Z direction.
|
vscalex(v; sx)
| |
vscaley(v; sy)
| |
vscalez(v; sz)
|
Matrix functions
Rotation
and Placement
can each be represented by a Matrix
. The following functions all take in a Matrix
, Rotation
, or Placement
as their first parameter denoted in the table below by m
. The type of the returned object is the same as the object supplied in the first argument except when using mtranslate
on a Rotation
, in which case a Placement
will be returned.
Function | Description |
---|---|
minvert(m)
|
Calculate the Inverse matrix. |
mrotate(m; rotation)
|
Rotate by either:
|
mrotate(m; axis; angle)
| |
mrotate(m; α; β; γ)
| |
mrotatex(m; angle)
|
Rotate around the X axis. |
mrotatey(m; angle)
|
Rotate around the Y axis. |
mrotatez(m; angle)
|
Rotate around the Z axis. |
mtranslate(m; vector)
|
Translate by a vector (Vector ) or X, Y, Z values. If a Rotation is translated, the returned object is a Placement .
|
mtranslate(m; x; y; z)
| |
mscale(m; vector)
|
Scale by a vector (Vector ) or X, Y, Z values.
|
mscale(m; x; y; z)
|
Conditional expressions
Conditional expressions are of the form condition ? resultTrue : resultFalse
. The condition is defined as an expression that evaluates to either 0
(false) or non-zero (true).
The following 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; 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 |
Electric capacitance
Unit | Description |
---|---|
pF | Picofarad |
nF | Nanofarad |
uF | Microfarad; alternative to the unit µF |
µF | Microfarad; alternative to the unit uF |
mF | Millifarad |
F | Farad; 1 F = 1 s^4·A^2/m^2/kg |
Electric charge
Unit | Description |
---|---|
C | Coulomb; 1 C = 1 A*s |
Electric conductivity
Unit | Description |
---|---|
uS | Microsiemens; alternative to the unit µS |
µS | Microsiemens; alternative to the unit uS |
mS | Millisiemens |
S | Siemens; 1 S = 1 s^3·A^2/kg/m^2 |
kS | KiloSiemens |
MS | MegaSiemens |
Electric inductance
Unit | Description |
---|---|
nH | Nanohenry |
uH | Microhenry; alternative to the unit µH |
µH | Microhenry; alternative to the unit uH |
mH | Millihenry |
H | Henry; 1 H = 1 kg·m^2/s^2/A^2 |
Electric potential
Unit | Description |
---|---|
mV | Millivolt |
V | Volt |
kV | Kilovolt |
Electric resistance
Unit | Description |
---|---|
Ohm | Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2 |
kOhm | Kiloohm |
MOhm | Megaohm |
Energy/work
Unit | Description |
---|---|
mJ | Millijoule |
J | Joule |
kJ | Kilojoule |
eV | Electronvolt; 1 eV = 1.602176634e-19 J |
keV | Kiloelectronvolt |
MeV | Megaelectronvolt |
kWh | Kilowatt hour; 1 kWh = 3.6e6 J |
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 |
kcal | Kilocalorie |
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 |
Magnetic flux
Unit | Description |
---|---|
Wb | Weber; 1 Wb = 1 kg*m^2/s^2/A |
Magnetic flux density
Unit | Description |
---|---|
G | Gauss; 1 G = 1 e-4 T |
T | Tesla; 1 T = 1 kg/s^2/A |
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 |
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 |
Hz (1/s) | Hertz |
kHz | Kilohertz, |
MHz | Megahertz |
GHz | Gigahertz |
THz | Terahertz |
Volume
Unit | Description |
---|---|
ml | Milliliter |
l | Liter |
cft | Cubicfoot |
Special imperial units
Unit | Description |
---|---|
mph | Miles per hour |
sqft | Square foot |
Unsupported units
The following commonly used units are not yet supported, for some an alternative is provided:
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, J, K, ' , ft , °, and many more! | Characters and character sequences that are units (see the Units paragraph) |
#, !, ?, §, $, %, &, :, ;, \, |, ~, ∆, ¿, 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
See Spreadsheet SetAlias.
Reference to CAD data
It is possible to use data from the model itself in an expression. To reference a property use object_name.property
or <<object_label>>.property
, labels must be enclosed in <<
and >>
. If you want to use labels they must be unique.
All next examples reference the object by its name, but in all cases the object label can also be used.
If the property is a compound of fields, the individual fields can be accessed as object_name.property.field
.
To reference list objects use object_name.list[list_index]
. If you want to reference a constraint in a sketch, use Sketch.Constraints[16]
. If you are in the same sketch you may omit its name and just use Constraints[16]
. Note that the index starts with 0, therefore Constraint17 has to be referenced as Constraints[16]
.
To reference the object itself use the _self
pseudo property: object_name._self
.
The following table shows some more examples:
CAD data | Call in expression | Result |
---|---|---|
Length of a Part Box | Box.Length
|
Length with units (mm) |
Volume of the Box | Box.Shape.Volume
|
Volume in mm³ without units |
Shape type of the Box | Box.Shape.ShapeType
|
String: Solid |
Label of the Box | Box.Label
|
String: Label |
X-coordinate of center of mass of the Box | Box.Shape.CenterOfMass.x
|
X-coordinate in mm without units |
X-coordinate of the Box placement | Box.Placement.Base.x
|
X-coordinate with units (mm) |
X-component of the rotation axis of the Box placement | Box.Placement.Rotation.Axis.x
|
X-component of the unit vector in mm without units |
Rotation angle of the Box placement | Box.Placement.Rotation.Angle
|
Rotation angle with units (deg) |
Full Box object | Box._self
|
Object of type <Part::PartFeature> |
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. |
Cyclic dependencies
FreeCAD checks dependencies based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. You have to use two spreadsheets, one to drive your model and the other for reporting.
As a workaround it is possible to display a cell range from the second spreadsheet in the first (or vice versa) by creating a cell binding with the Hide dependency of binding option.
Another way to workaround cyclic dependencies is to hide the reference by using the href
or hiddenref
function for individual expressions, for example: href(Box.Length)
.
Please note that both mentioned workarounds should be used with caution, and that they do not work if the properties that are reported depend on dimensions that are driven from the same spreadsheet.
Document-wide global variables
There is no concept of global variables in FreeCAD at the moment. Instead, arbitrary variables can be defined as cells in a spreadsheet using the Spreadsheet workbench, and then be given a name using the alias property for the cell (right-click on cell). Then they can be accessed from any expression just as any other object property.
Cross-document linking
It is possible (with limitations) to define a Property of an object in your current document (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the 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.
Of course, it's up to you to load the corresponding documents later when you want to change anything.
Known issues / remaining tasks
- FreeCAD does not yet have a built-in expression manager where all expressions in a document are listed, and can be created, deleted, queried, etc. But an addon is available: fcxref expression manager.
- Open bugs/tickets for Expressions can be found on GitHub.
- 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