Expressions/es: Difference between revisions
Renatorivo (talk | contribs) (Created page with "Category:User Documentation/es") |
(Updating to match new version of source page) |
||
(29 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
<languages/> |
<languages/> |
||
{{ |
{{TOCright}} |
||
==Overview== |
|||
It is now possible to drive properties using mathematical expressions. From the GUI, spin boxes or input fields, that are bound to properties contain a blue icon [[Image:Sketcher_Expressions.png|24px]]. Clicking on the icon, or typing the equal sign (=), brings up the expression editor for that particular property. |
|||
It is possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon [[Image:Sketcher_Expressions.png|32px]]. Clicking on the icon or typing the equal sign {{KEY|=}} brings up the expression editor for that particular property. |
|||
A FreeCAD expression is a mathematical expression, following normal notation for the standard mathematical operators (+, -, * and /) and functions as described below. In addition, the expression may reference other properties, and also use conditionals. Numbers in an expression may have an optional unit attached to it. |
|||
A FreeCAD expression is a mathematical expression following notation for the standard mathematical operators and functions as described below. In addition, the expression may reference other properties, and also use conditionals. Numbers in an expression may have an optional unit attached to them. |
|||
Operators and functions are unit-aware, and require valid combinations of units, if supplied. For example, 2mm+4mm is a valid expression, while 2mm+4 is not (the reason for this is that an expression like 1in + 4 will most likely be interpreted as 1in + 4in by humans, but all units are converted to the SI system internally, and the system is not able to guess this). |
|||
Numbers may use either a comma ',' or a decimal point '.' separating whole digits from decimals. |
|||
When the decimal marker is used, it ''must'' be followed by at least one digit. |
|||
Thus, the expressions '''1.+2.''' and '''1,+2,''' are invalid, but '''1.0 + 2.0''' and '''1,0 + 2,0''' are valid. |
|||
Operators and functions are unit-aware, and require valid combinations of units, if supplied. For example, '''2mm + 4mm''' is a valid expression, while '''2mm + 4''' is not (the reason for this is that an expression like '''1in + 4''' will most likely be interpreted as '''1in + 4in''' by humans, but all units are converted to the SI system internally, and the system is not able to guess this). These [[#Units|units]] are currently recognized. |
|||
You can use [[#Supported Constants|predefined constants]] and [[#Supported Functions|functions]]. |
|||
===Referencing objects=== |
|||
You can reference to an object by its {{incode|Name}} or by its {{incode|Label}}. In the case of a {{incode|Label}}, it must be enclosed in double {{incode|<<}} and {{incode|>>}} symbols, such as {{incode|<<Label>>}}. |
|||
You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use {{incode|Cylinder.Height}} or {{incode|<<Long_name_of_cylinder>>.Height}}. |
|||
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. |
|||
For more info about referencing objects, see [[#Reference To CAD-Data|this section]]. |
|||
The following operators are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
|||
!style="width: 33%;"|Operator |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| style="text-align:center;" |'''+''' |
|||
| [https://en.wikipedia.org/wiki/Addition Addition] |
|||
|- |
|||
| style="text-align:center;" |'''-''' |
|||
| [https://en.wikipedia.org/wiki/Subtraction Subtraction] |
|||
|- |
|||
| style="text-align:center;" | '''*''' |
|||
| [https://en.wikipedia.org/wiki/Multiplication Multiplication] |
|||
|- |
|||
| style="text-align:center;" | '''/''' |
|||
| Floating point [https://en.wikipedia.org/wiki/Division_(mathematics) Division] |
|||
|- |
|||
| style="text-align:center;" | '''%''' |
|||
| [https://en.wikipedia.org/wiki/Remainder Remainder] |
|||
|- |
|||
| style="text-align:center;" | '''^''' |
|||
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation] |
|||
|} |
|||
==Supported Constants== |
|||
The following constants are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
|||
!style="width: 33%;"|Constant |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| style="text-align:center;" | '''e''' |
|||
| [https://en.wikipedia.org/wiki/E_(mathematical_constant) Euler's number] |
|||
|- |
|||
| style="text-align:center;" | '''pi''' |
|||
| [https://en.wikipedia.org/wiki/Pi Pi] |
|||
|} |
|||
== Supported Functions == |
== Supported Functions == |
||
=== General Mathematical Functions === |
|||
In expressions, the following functions are supported, taking one or two arguments: abs, acos, asin, atan, atan2, cos, cosh, exp, log, log10, mod, pow, sin, sinh, sqrt, tan, tanh, ceil, floor, trunc, and round. |
|||
The mathematical functions listed below are available. |
|||
Aggregate functions can take one or more arguments, separated by comma or semicolon. Arguments may include ranges (two cells separated by a colon), e.g =average(B1:B8). These are interpreted as the properties B1, B2, ... B8. |
|||
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. |
|||
Trigonometric functions use degrees as its default unit; supply "rad" if you want them to use radians. |
|||
[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/> |
|||
The constants pi and e are predefined. |
|||
These trigonometric functions are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Function |
|||
!style="width: 33%;"|Description |
|||
!style="width: 33%;"|Value range |
|||
|- |
|||
| acos(x) |
|||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc cosine] |
|||
| -1 <= x <= 1 |
|||
|- |
|||
| asin(x) |
|||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc sine] |
|||
| -1 <= x <= 1 |
|||
|- |
|||
| atan(x) |
|||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] |
|||
| all |
|||
|- |
|||
| atan2(x, y) |
|||
| [https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties Arc tangent] of ''x/y'' |
|||
| all, except y = 0 |
|||
|- |
|||
| cos(x) |
|||
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Cosine] |
|||
| all |
|||
|- |
|||
| cosh(x) |
|||
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic cosine] |
|||
| all |
|||
|- |
|||
| sin(x) |
|||
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Sine] |
|||
| all |
|||
|- |
|||
| sinh(x) |
|||
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic sine] |
|||
| all |
|||
|- |
|||
| tan(x) |
|||
| [https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions Tangent] |
|||
| all, except of x = n·90 with n = integer |
|||
|- |
|||
| tanh(x) |
|||
| [https://en.wikipedia.org/wiki/Hyperbolic_function#Trigonometric_definitions Hyperbolic tangent] |
|||
| all |
|||
|} |
|||
These functions for exponentiation and logarithmization are supported: |
|||
The conditional statement works like this: = condition ? resultTrue : resultFalse |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Function |
|||
!style="width: 33%;"|Description |
|||
!style="width: 33%;"|Value range |
|||
|- |
|||
| exp(x) |
|||
| [https://en.wikipedia.org/wiki/Exponential_function#Formal_definition Exponential function] |
|||
| all |
|||
|- |
|||
| log(x) |
|||
| [https://en.wikipedia.org/wiki/Natural_logarithm Natural logarithm] |
|||
| x > 0 |
|||
|- |
|||
| log10(x) |
|||
| [https://en.wikipedia.org/wiki/Common_logarithm Common logarithm] |
|||
| x > 0 |
|||
|- |
|||
| pow(x, y) |
|||
| [https://en.wikipedia.org/wiki/Exponentiation Exponentiation] |
|||
| all |
|||
|- |
|||
| sqrt(x) |
|||
| [https://en.wikipedia.org/wiki/Square_root Square root] |
|||
| x >= 0 |
|||
|} |
|||
These functions for rounding, truncation and remainder are supported: |
|||
The condition is defined as an expression that evaluates to either 0 (for false) or non-zero for true. The following comparison operators are defined: ==, !=, >, <, >=, and <=. |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 20%;"|Function |
|||
!style="width: 55%;"|Description |
|||
!style="width: 25%;"|Value range |
|||
|- |
|||
| abs(x) |
|||
| [https://en.wikipedia.org/wiki/Absolute_value Absolute value] |
|||
| all |
|||
|- |
|||
| ceil(x) |
|||
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Ceiling function] smallest integer value greater than or equal to x |
|||
| all |
|||
|- |
|||
| floor(x) |
|||
| [https://en.wikipedia.org/wiki/Floor_and_ceiling_functions Floor function], largest integer value less than or equal to x |
|||
| all |
|||
|- |
|||
| mod(x, y) |
|||
| [https://en.wikipedia.org/wiki/Remainder Remainder] after dividing ''x'' by ''y'' |
|||
| all, except y = 0 |
|||
|- |
|||
| round(x) |
|||
| [https://en.wikipedia.org/wiki/Rounding Rounding] to the nearest integer |
|||
| all |
|||
|- |
|||
| trunc(x) |
|||
| [https://en.wikipedia.org/wiki/Truncation Truncation] to the nearest integer |
|||
| all |
|||
|} |
|||
=== Statistical / Aggregate Functions === |
|||
Formulas are written as e.g follows: 2 * Length, where Length is a property in the object holding the expression. |
|||
[https://en.wikipedia.org/wiki/Aggregate_function Aggregate functions] take one or more arguments, separated by a semicolon ';' or a comma ''and'' a space ', '.<br/> |
|||
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.<br/> |
|||
Arguments may include ranges of cells (two cell references separated by a colon), for example '''average(B1:B8)'''. |
|||
These aggregate functions are supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 20%;"|Function |
|||
!style="width: 55%;"|Description |
|||
!style="width: 25%;"|Value range |
|||
|- |
|||
| average(x:y) |
|||
| [https://en.wikipedia.org/wiki/Arithmetic_mean Arithmetic mean] of values in cells x through y; sum(x:y) / count(x:y) |
|||
| all |
|||
|- |
|||
| count(x:y) |
|||
| [https://en.wikipedia.org/wiki/Counting Counting] of cells from x through y |
|||
| all |
|||
|- |
|||
| max(x:y) |
|||
| [https://en.wikipedia.org/wiki/Maxima_and_minima Maximum] value in cells x through y |
|||
| all |
|||
|- |
|||
| min(x:y) |
|||
| [https://en.wikipedia.org/wiki/Maxima_and_minima Minimum] value in cells x through y |
|||
| all |
|||
|- |
|||
| stddev(x:y) |
|||
| [https://en.wikipedia.org/wiki/Standard_deviation Standard deviation] of values in cells x through y |
|||
| all |
|||
|- |
|||
| sum(x: y) |
|||
| [https://en.wikipedia.org/wiki/Summation Sum] of values in cells x through y |
|||
| all |
|||
|} |
|||
== Conditional Expressions == |
|||
Conditional expressions are of the form '''condition ? resultTrue : resultFalse'''. The condition is defined as an expression that evaluates to either '0' (false) or non-zero (true). |
|||
Note that enclosing the conditional expression in parentheses is currently considered an error. {{VersionMinus|0.19}} |
|||
The following [https://en.wikipedia.org/wiki/Relational_operator#Standard_relational_operators relational operators] are defined: |
|||
{| class="wikitable float-right mw-collapsible mw-uncollapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| style="text-align:center;" | '''==''' |
|||
| equal to |
|||
|- |
|||
| style="text-align:center;" | '''!=''' |
|||
| not equal to |
|||
|- |
|||
| style="text-align:center;" | '''>''' |
|||
| greater than |
|||
|- |
|||
| style="text-align:center;" | '''<''' |
|||
| less than |
|||
|- |
|||
| style="text-align:center;" | '''>=''' |
|||
| greater than or equal to |
|||
|- |
|||
| style="text-align:center;" | '''<=''' |
|||
| less than or equal to |
|||
|} |
|||
== Units == |
|||
Units can directly be used in expressions. The parser connects them to the previous value. So ''''2mm'''' or ''''2 mm'''' is valid while '''' mm'''' is invalid because there is no preceding value. |
|||
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.<br/> |
|||
In some cases it works even without a unit, for example if you have e.g. in spreadsheet cell B1 just the number ''1.5'' and refer to it for a pad height. This only works because the pad height predefines the unit ''mm'' that is used if no unit is given. It will nevertheless fail if you use for the pad height e.g. '''Sketch1.Constraints.Width - Spreadsheet.B1''' because ''Sketch1.Constraints.Width'' has a unit and ''Spreadsheet.B1'' has not. |
|||
Units with exponents can directly be entered. So e.g. '''mm^3''' will be recognized as mm³ and '''m^3''' will be recognized as m³. |
|||
If you have a variable with a name of a unit you must put the variable into '''<< >>''' to prevent that it will be recognized as unit. For example if you have the dimension ''''Sketch.Constraints.A'''' it would be recognized as unit ampere. Therefore you must write it in the expression as ''''Sketch.Constraints.<<A>>''''. |
|||
The following units are recognized by the expression parser: |
|||
Amount of substance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| mmol |
|||
| Milli[https://en.wikipedia.org/wiki/Mole_(unit) mole] |
|||
|- |
|||
| mol |
|||
| [https://en.wikipedia.org/wiki/Mole_(unit) Mole] |
|||
|} |
|||
Angle: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| ° |
|||
| [https://en.wikipedia.org/wiki/Degree_(angle) Degree]; alternative to the unit ''deg'' |
|||
|- |
|||
| deg |
|||
| [https://en.wikipedia.org/wiki/Degree_(angle) Degree]; alternative to the unit ''°'' |
|||
|- |
|||
| rad |
|||
| [https://en.wikipedia.org/wiki/Radian Radian] |
|||
|- |
|||
| gon |
|||
| [https://en.wikipedia.org/wiki/Gon_(unit) Gradian] |
|||
|- |
|||
| 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 ''S'' |
|||
|- |
|||
| 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 ''M'' |
|||
|} |
|||
Current: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| mA |
|||
| Milli[https://en.wikipedia.org/wiki/Ampere ampere] |
|||
|- |
|||
| A |
|||
| [https://en.wikipedia.org/wiki/Ampere Ampere] |
|||
|- |
|||
| kA |
|||
| Kilo[https://en.wikipedia.org/wiki/Ampere ampere] |
|||
|- |
|||
| MA |
|||
| Mega[https://en.wikipedia.org/wiki/Ampere ampere] |
|||
|} |
|||
Electrical Capacitance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| pF |
|||
| Pico[https://en.wikipedia.org/wiki/Farad farad], {{Version|0.19}} |
|||
|- |
|||
| nF |
|||
| Nano[https://en.wikipedia.org/wiki/Farad farad], {{Version|0.19}} |
|||
|- |
|||
| uF |
|||
| Micro[https://en.wikipedia.org/wiki/Farad farad]; alternative to the unit ''µF'', {{Version|0.19}} |
|||
|- |
|||
| µF |
|||
| Micro[https://en.wikipedia.org/wiki/Farad farad]; alternative to the unit ''uF'', {{Version|0.19}} |
|||
|- |
|||
| mF |
|||
| Milli[https://en.wikipedia.org/wiki/Farad farad], {{Version|0.19}} |
|||
|- |
|||
| F |
|||
| [https://en.wikipedia.org/wiki/Farad Farad]; 1 F = 1 s^4·A^2/m^2/kg, {{Version|0.19}} |
|||
|} |
|||
Electrical Conductance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| uS |
|||
| Micro[https://en.wikipedia.org/wiki/Siemens_(unit) siemens]; alternative to the unit ''µS'', {{Version|0.19}} |
|||
|- |
|||
| µS |
|||
| Micro[https://en.wikipedia.org/wiki/Siemens_(unit) siemens]; alternative to the unit ''uS'', {{Version|0.19}} |
|||
|- |
|||
| mS |
|||
| Milli[https://en.wikipedia.org/wiki/Siemens_(unit) siemens], {{Version|0.19}} |
|||
|- |
|||
| S |
|||
| [https://en.wikipedia.org/wiki/Siemens_(unit) Siemens]; 1 S = 1 s^3·A^2/kg/m^2, {{Version|0.19}} |
|||
|} |
|||
Electrical Inductance: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| nH |
|||
| Nano[https://en.wikipedia.org/wiki/Henry_(unit) henry], {{Version|0.19}} |
|||
|- |
|||
| uH |
|||
| Micro[https://en.wikipedia.org/wiki/Henry_(unit) henry]; alternative to the unit ''µH'', {{Version|0.19}} |
|||
|- |
|||
| µH |
|||
| Micro[https://en.wikipedia.org/wiki/Henry_(unit) henry]; alternative to the unit ''uH'', {{Version|0.19}} |
|||
|- |
|||
| mH |
|||
| Milli[https://en.wikipedia.org/wiki/Henry_(unit) henry], {{Version|0.19}} |
|||
|- |
|||
| H |
|||
| [https://en.wikipedia.org/wiki/Henry_(unit) Henry]; 1 H = 1 kg·m^2/s^2/A^2, {{Version|0.19}} |
|||
|} |
|||
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}} |
|||
|} |
|||
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}} |
|||
|} |
|||
Electric Potential: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| mV |
|||
| Milli[https://en.wikipedia.org/wiki/Volt volt] |
|||
|- |
|||
| V |
|||
| [https://en.wikipedia.org/wiki/Volt Volt] |
|||
|- |
|||
| kV |
|||
| Kilo[https://en.wikipedia.org/wiki/Volt volt] |
|||
|} |
|||
Energy / Work: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| mJ |
|||
| Milli[https://en.wikipedia.org/wiki/Joule joule] |
|||
|- |
|||
| J |
|||
| [https://en.wikipedia.org/wiki/Joule Joule] |
|||
|- |
|||
| kJ |
|||
| Kilo[https://en.wikipedia.org/wiki/Joule joule], {{Version|0.19}} |
|||
|- |
|||
| eV |
|||
| [https://en.wikipedia.org/wiki/Electronvolt Electronvolt]; 1 ev = 1.602176634e-19 J, {{Version|0.19}} |
|||
|- |
|||
| keV |
|||
| Kilo[https://en.wikipedia.org/wiki/Electronvolt electronvolt], {{Version|0.19}} |
|||
|- |
|||
| MeV |
|||
| Mega[https://en.wikipedia.org/wiki/Electronvolt electronvolt], {{Version|0.19}} |
|||
|- |
|||
| kWh |
|||
| [https://en.wikipedia.org/wiki/Kilowatt_hour Kilowatt hour]; 1 kWh = 3.6e6 J, {{Version|0.19}} |
|||
|- |
|||
| Ws |
|||
| [https://en.wikipedia.org/wiki/Joule#Watt_second Watt second]; alternative to the unit ''Joule'' |
|||
|- |
|||
| VAs |
|||
| [https://en.wikipedia.org/wiki/Joule Volt-ampere-second]; alternative to the unit ''Joule'' |
|||
|- |
|||
| CV |
|||
| [https://en.wikipedia.org/wiki/Joule Coulomb-volt]; alternative to the unit ''Joule'' |
|||
|- |
|||
| cal |
|||
| [https://en.wikipedia.org/wiki/Calorie Calorie]; 1 cal = 4.184 J, {{Version|0.19}} |
|||
|- |
|||
| kcal |
|||
| Kilo[https://en.wikipedia.org/wiki/Calorie calorie], {{Version|0.19}} |
|||
|} |
|||
Force: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| mN |
|||
| Milli[https://en.wikipedia.org/wiki/Newton_(unit) newton] |
|||
|- |
|||
| N |
|||
| [https://en.wikipedia.org/wiki/Newton_(unit) Newton] |
|||
|- |
|||
| kN |
|||
| Kilo[https://en.wikipedia.org/wiki/Newton_(unit) newton] |
|||
|- |
|||
| MN |
|||
| Mega[https://en.wikipedia.org/wiki/Newton_(unit) newton] |
|||
|- |
|||
| lbf |
|||
| [https://en.wikipedia.org/wiki/Pound_(force) Pound of force] |
|||
|} |
|||
Length: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| nm |
|||
| Nano[https://en.wikipedia.org/wiki/Metre meter] |
|||
|- |
|||
| um |
|||
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit ''µm'' |
|||
|- |
|||
| µm |
|||
| Micro[https://en.wikipedia.org/wiki/Metre meter]; alternative to the unit ''mu'' |
|||
|- |
|||
| mm |
|||
| Milli[https://en.wikipedia.org/wiki/Metre meter] |
|||
|- |
|||
| cm |
|||
| Centi[https://en.wikipedia.org/wiki/Metre meter] |
|||
|- |
|||
| mm |
|||
| Milli[https://en.wikipedia.org/wiki/Metre meter] |
|||
|- |
|||
| dm |
|||
| Deci[https://en.wikipedia.org/wiki/Metre meter] |
|||
|- |
|||
| m |
|||
| [https://en.wikipedia.org/wiki/Metre Meter] |
|||
|- |
|||
| km |
|||
| Kilo[https://en.wikipedia.org/wiki/Metre meter] |
|||
|- |
|||
| mil |
|||
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit ''thou'' |
|||
|- |
|||
| thou |
|||
| [https://en.wikipedia.org/wiki/Thousandth_of_an_inch Thousandth of an inch]; alternative to the unit ''mil'' |
|||
|- |
|||
| in |
|||
| [https://en.wikipedia.org/wiki/Inch Inch] |
|||
|- |
|||
| ft |
|||
| [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 |
|||
| [https://en.wikipedia.org/wiki/Yard Yard] |
|||
|- |
|||
| mi |
|||
| [https://en.wikipedia.org/wiki/Mile Mile] |
|||
|} |
|||
Luminous Intensity: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| cd |
|||
| [https://en.wikipedia.org/wiki/Candela Candela] |
|||
|} |
|||
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}} |
|||
|} |
|||
Magnetic Flux: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| Wb |
|||
| [https://en.wikipedia.org/wiki/Weber_(unit) Weber]; 1 Wb = 1 kg*m^2/s^2/A, {{Version|0.19}} |
|||
|} |
|||
Magnetic Flux Density: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| G |
|||
| [https://en.wikipedia.org/wiki/Gauss_(unit) Gauss]; 1 G = 1 e-4 T, {{Version|0.19}} |
|||
|- |
|||
| T |
|||
| [https://en.wikipedia.org/wiki/Tesla_(unit) Tesla]; 1 T = 1 kg/s^2/A, {{Version|0.19}} |
|||
|} |
|||
Mass: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| ug |
|||
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit ''µg'' |
|||
|- |
|||
| µg |
|||
| Micro[https://en.wikipedia.org/wiki/Gram gram]; alternative to the unit ''ug'' |
|||
|- |
|||
| mg |
|||
| Milli[https://en.wikipedia.org/wiki/Gram gram] |
|||
|- |
|||
| g |
|||
| [https://en.wikipedia.org/wiki/Gram Gram] |
|||
|- |
|||
| kg |
|||
| Kilo[https://en.wikipedia.org/wiki/Gram gram] |
|||
|- |
|||
| t |
|||
| [https://en.wikipedia.org/wiki/Tonne Tonne] |
|||
|- |
|||
| oz |
|||
| [https://en.wikipedia.org/wiki/Ounce Ounce] |
|||
|- |
|||
| lb |
|||
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit ''lbm'' |
|||
|- |
|||
| lbm |
|||
| [https://en.wikipedia.org/wiki/Pound_(mass) Pound]; alternative to the unit ''lb'' |
|||
|- |
|||
| st |
|||
| [https://en.wikipedia.org/wiki/Stone_(weight) Stone] |
|||
|- |
|||
| cwt |
|||
| [https://en.wikipedia.org/wiki/Hundredweight Hundredweight] |
|||
|} |
|||
Power: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| W |
|||
| [https://en.wikipedia.org/wiki/Watt Watt] |
|||
|- |
|||
| kW |
|||
| Kilo[https://en.wikipedia.org/wiki/Watt watt], {{Version|0.19}} |
|||
|- |
|||
| VA |
|||
| [https://en.wikipedia.org/wiki/Volt-ampere Volt-ampere] |
|||
|} |
|||
Pressure: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| Pa |
|||
| [https://en.wikipedia.org/wiki/Pascal_(unit) Pascal] |
|||
|- |
|||
| kPa |
|||
| Kilo[https://en.wikipedia.org/wiki/Pascal_(unit) pascal] |
|||
|- |
|||
| MPa |
|||
| Mega[https://en.wikipedia.org/wiki/Pascal_(unit) pascal] |
|||
|- |
|||
| GPa |
|||
| 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 |
|||
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit ''µTorr'' |
|||
|- |
|||
| µTorr |
|||
| Micro[https://en.wikipedia.org/wiki/Torr torr]; alternative to the unit ''uTorr'' |
|||
|- |
|||
| mTorr |
|||
| Milli[https://en.wikipedia.org/wiki/Torr torr] |
|||
|- |
|||
| Torr |
|||
| [https://en.wikipedia.org/wiki/Torr Torr]; 1 Torr = 133.32 Pa |
|||
|- |
|||
| psi |
|||
| [https://en.wikipedia.org/wiki/Pounds_per_square_inch Pound-force per square inch]; 1 psi = 6.895 kPa |
|||
|- |
|||
| ksi |
|||
| 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: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| uK |
|||
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit ''µK'' |
|||
|- |
|||
| µK |
|||
| Micro[https://en.wikipedia.org/wiki/Kelvin kelvin]; alternative to the unit ''uK'' |
|||
|- |
|||
| mK |
|||
| Milli[https://en.wikipedia.org/wiki/Kelvin kelvin] |
|||
|- |
|||
| K |
|||
| [https://en.wikipedia.org/wiki/Kelvin Kelvin] |
|||
|} |
|||
Time: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| s |
|||
| [https://en.wikipedia.org/wiki/Second Second] |
|||
|- |
|||
| min |
|||
| [https://en.wikipedia.org/wiki/Minute Minute] |
|||
|- |
|||
| h |
|||
| [https://en.wikipedia.org/wiki/Hour Hour] |
|||
|- |
|||
| Hz (1/s) |
|||
| [https://en.wikipedia.org/wiki/Hertz Hertz], {{Version|0.19}} |
|||
|- |
|||
| kHz |
|||
| Kilo[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}} |
|||
|- |
|||
| MHz |
|||
| Mega[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}} |
|||
|- |
|||
| GHz |
|||
| Giga[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}} |
|||
|- |
|||
| THz |
|||
| Tera[https://en.wikipedia.org/wiki/Hertz hertz], {{Version|0.19}} |
|||
|} |
|||
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] |
|||
|} |
|||
Volume: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| ml |
|||
| Milli[https://en.wikipedia.org/wiki/Litre liter], {{Version|0.19}} |
|||
|- |
|||
| l |
|||
| [https://en.wikipedia.org/wiki/Litre Liter] |
|||
|- |
|||
| cft |
|||
| Cubic[https://en.wikipedia.org/wiki/Foot_(unit) foot], {{Version|0.19}} |
|||
|} |
|||
Special imperial units: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 33%;"|Unit |
|||
!style="width: 66%;"|Description |
|||
|- |
|||
| mph |
|||
| [https://en.wikipedia.org/wiki/Miles_per_hour Miles per hour], {{Version|0.19}} |
|||
|- |
|||
| sqft |
|||
| [https://en.wikipedia.org/wiki/Square_foot Square foot], {{Version|0.19}} |
|||
|} |
|||
The following commonly used units are not yet supported: |
|||
{| class="wikitable float-right mw-collapsible mw-collapsed" |
|||
!style="width: 25%;"|Unit |
|||
!style="width: 50%;"|Description |
|||
!style="width: 25%;"|Alternative |
|||
|- |
|||
| °C |
|||
| [https://en.wikipedia.org/wiki/Celsius Celsius ] |
|||
| [°C] + 273.15 K |
|||
|- |
|||
| °F |
|||
| [https://en.wikipedia.org/wiki/Fahrenheit Fahrenheit]; |
|||
| ([°F] + 459.67) × 5/9 |
|||
|- |
|||
| u |
|||
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Atomic mass unit]; alternative to the unit 'Da' |
|||
| 1.66053906660e-27 kg |
|||
|- |
|||
| Da |
|||
| [https://en.wikipedia.org/wiki/Unified_atomic_mass_unit Dalton]; alternative to the unit 'u' |
|||
| 1.66053906660e-27 kg |
|||
|- |
|||
| sr |
|||
| [https://en.wikipedia.org/wiki/Steradian Steradian] |
|||
| not directly |
|||
|- |
|||
| lm |
|||
| [https://en.wikipedia.org/wiki/Lumen_(unit) Lumen] |
|||
| not directly |
|||
|- |
|||
| lx |
|||
| [https://en.wikipedia.org/wiki/Lux Lux] |
|||
| not directly |
|||
|- |
|||
| px |
|||
| [https://en.wikipedia.org/wiki/Pixel Pixel] |
|||
| not directly |
|||
|} |
|||
== Reference To CAD-Data == |
== Reference To CAD-Data == |
||
It is possible to use data from |
It is possible to use data from the model itself in an expression. To reference a property use "object.property". If the property is a compound of fields, the individual fields can be accessed as "object.property.field". |
||
The following table shows some examples: |
The following table shows some examples: |
||
Line 36: | Line 809: | ||
|- |
|- |
||
|Parametric Length of a Part-Workbench Cube |
|Parametric Length of a Part-Workbench Cube |
||
|Cube.Length |
|{{incode|Cube.Length}} |
||
|Length with units mm |
|{{incode|Length}} with units mm |
||
|- |
|- |
||
|Volume of the Cube |
|Volume of the Cube |
||
|Cube.Shape.Volume |
|{{incode|Cube.Shape.Volume}} |
||
|Volume |
|{{incode|Volume}} in mm³ without units |
||
|- |
|- |
||
|Type of the Cube-shape |
|Type of the Cube-shape |
||
|Cube.Shape.ShapeType |
|{{incode|Cube.Shape.ShapeType}} |
||
|String: Solid |
|String: Solid |
||
|- |
|- |
||
|Label of the Cube |
|Label of the Cube |
||
|Cube.Label |
|{{incode|Cube.Label}} |
||
|String: |
|String: Label |
||
|- |
|- |
||
|x-coordinate of center of mass of the Cube |
|x-coordinate of center of mass of the Cube |
||
|Cube.Shape.CenterOfMass.x |
|{{incode|Cube.Shape.CenterOfMass.x}} |
||
|x-coordinate in mm without units |
|x-coordinate in mm without units |
||
|- |
|- |
||
|Value of constraint in a sketch |
|Value of constraint in a sketch |
||
|Constraints.Width |
|{{incode|Constraints.Width}} |
||
|Numeric value of the named constraint 'Width' in the sketch |
|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 |
|||
|{{incode|MySketch.Constraints.Width}} |
|||
|Numeric value of the named constraint '{{incode|Width}}' in the sketch, if the expression is used outside of the sketch. |
|||
|- |
|- |
||
|Value of a spreadsheet alias |
|Value of a spreadsheet alias |
||
|Spreadsheet.Depth |
|{{incode|Spreadsheet.Depth}} |
||
|Value of the alias "Depth" in the spreadsheet "Spreadsheet" |
|Value of the alias "{{incode|Depth}}" in the spreadsheet "{{incode|Spreadsheet}}" |
||
|- |
|- |
||
|Value of a local property |
|Value of a local property |
||
|Length |
|{{incode|Length}} |
||
|Value of the Length property in e.g a Pad object, if the expression is used in e.g Length2 in the same object. |
|Value of the {{incode|Length}} property in e.g a Pad object, if the expression is used in e.g Length2 in the same object. |
||
|} |
|} |
||
Line 74: | Line 851: | ||
== Cross-document linking == |
== Cross-document linking == |
||
It is possible (with limitations) to define a Property of an object in your current document (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the Length of a Part Cube, etc. in one document can be defined by an Expression that references the X Placement value or another Property of an object contained in a different document. |
|||
It's possible that you have a spreadsheet in one document and reference values from there in other documents. |
|||
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 "{{incode|master}}", the spreadsheet "{{incode|modelConstants}}", and give a cell an alias-name "{{incode|Length}}", you can then access the value as: |
|||
{{Code|code=master#modelConstants.Length}} |
|||
Unfortunately, the integrated checker is more confusing than helping because it always gives parser errors or claims that this or that doesn't exist. So, just continue on typing. When you are finished and the content is correct the OK suddenly becomes active. |
|||
'''Note:''' that the master document must be loaded for the values in the master to be available to the dependent document. |
|||
Unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the {{Button|OK}} button will become active. |
|||
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. |
||
Line 86: | Line 867: | ||
== Known issues / remaining tasks == |
== Known issues / remaining tasks == |
||
* The dependency |
* The dependency graph is based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. As a work-around, use multiple spreadsheets -- one to drive your model, and one for reporting. |
||
* The expression parser does not handle parentheses well, and is unable to properly parse some expressions. For example: "'''= (A1 > A2) ? 1 : 0'''" results in an error, while "'''= A1 > A2 ? 1 : 0'''" is accepted. The expression "'''= 5 + ((A1>A2) ? 1 : 0)'''" cannot be entered in any form. |
|||
* There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queries, etc. |
|||
* As stated above, unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the {{Button|OK}} button will become active. |
|||
* There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc. |
|||
* The names of Sketcher constraints must not contain any blanks when the value is calculated by an expression, see [https://forum.freecadweb.org/viewtopic.php?p=302500#p302381; forum discussion]. |
|||
* Open bugs/tickets for Expressions can be found in the [https://freecadweb.org/tracker/set_project.php?project_id=4;20 FreeCAD Bugtracker Expressions category] |
* Open bugs/tickets for Expressions can be found in the [https://freecadweb.org/tracker/set_project.php?project_id=4;20 FreeCAD Bugtracker Expressions category] |
||
{{Powerdocnavi{{#translation:}}}} |
|||
[[Category:User Documentation/es]] |
|||
[[Category:Spreadsheet{{#translation:}}]] |
|||
{{clear}} |
{{clear}} |
Revision as of 17:03, 25 September 2020
Overview
It is possible to define properties using mathematical expressions. From the GUI, spin boxes or input fields that are bound to properties contain a blue icon File:Sketcher Expressions.png. Clicking on the icon or typing the equal sign = brings up the expression editor for that particular property.
A FreeCAD expression is a mathematical expression following notation for the standard mathematical operators and functions as described below. In addition, the expression may reference other properties, and also use conditionals. Numbers in an expression may have an optional unit attached to them.
Numbers may use either a comma ',' or a decimal point '.' separating whole digits from decimals. When the decimal marker is used, it must be followed by at least one digit. Thus, the expressions 1.+2. and 1,+2, are invalid, but 1.0 + 2.0 and 1,0 + 2,0 are valid.
Operators and functions are unit-aware, and require valid combinations of units, if supplied. For example, 2mm + 4mm is a valid expression, while 2mm + 4 is not (the reason for this is that an expression like 1in + 4 will most likely be interpreted as 1in + 4in by humans, but all units are converted to the SI system internally, and the system is not able to guess this). These units are currently recognized.
You can use predefined constants and functions.
Referencing objects
You can reference to an object by its Name
or by its Label
. In the case of a Label
, it must be enclosed in double <<
and >>
symbols, such as <<Label>>
.
You can reference any numerical property of this object. For example, to refer to a Cylinder's height, you may use Cylinder.Height
or <<Long_name_of_cylinder>>.Height
.
To reference list objects, the syntax is <<object_label>>.list[list_index]
or 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].
Note: The index starts with 0, therefore constraint 17 has the index 16.
For more info about referencing objects, see this section.
The following operators are supported:
Operator | Description |
---|---|
+ | Addition |
- | Subtraction |
* | Multiplication |
/ | Floating point Division |
% | Remainder |
^ | Exponentiation |
Supported Constants
The following constants are supported:
Constant | Description |
---|---|
e | Euler's number |
pi | Pi |
Supported Functions
General Mathematical Functions
The mathematical functions listed below are available.
Multiple arguments to a function may be separated by either a semicolon ';' or a comma followed by a space ', '. In the latter case, the comma is converted to a semicolon after entry. When a semicolon is used, no trailing space is necessary.
Trigonometric functions use degree as their default unit. For radian measure, add rad following the first value in an expression. So e.g. cos(45) is the same as cos(pi rad / 4). Expressions in degrees can use either deg or °, e.g. 360deg - atan2(3; 4) or 360° - atan2(3; 4). If an expression is without units and needs to be converted to degrees or radians for compatibility, multiply by 1 deg, 1 ° or 1 rad as appropriate, e.g. (360 - X) * 1deg; (360 - X) * 1°; (0.5 + pi / 2) * 1rad.
These trigonometric functions are supported:
Function | Description | Value range |
---|---|---|
acos(x) | Arc cosine | -1 <= x <= 1 |
asin(x) | Arc sine | -1 <= x <= 1 |
atan(x) | Arc tangent | all |
atan2(x, y) | Arc tangent of x/y | all, except y = 0 |
cos(x) | Cosine | all |
cosh(x) | Hyperbolic cosine | all |
sin(x) | Sine | all |
sinh(x) | Hyperbolic sine | all |
tan(x) | Tangent | all, except of x = n·90 with n = integer |
tanh(x) | Hyperbolic tangent | all |
These functions for exponentiation and logarithmization are supported:
Function | Description | Value range |
---|---|---|
exp(x) | Exponential function | all |
log(x) | Natural logarithm | x > 0 |
log10(x) | Common logarithm | x > 0 |
pow(x, y) | Exponentiation | all |
sqrt(x) | Square root | x >= 0 |
These functions for rounding, truncation and remainder are supported:
Function | Description | Value range |
---|---|---|
abs(x) | Absolute value | all |
ceil(x) | Ceiling function smallest integer value greater than or equal to x | all |
floor(x) | Floor function, largest integer value less than or equal to x | all |
mod(x, y) | Remainder after dividing x by y | all, except y = 0 |
round(x) | Rounding to the nearest integer | all |
trunc(x) | Truncation to the nearest integer | all |
Statistical / Aggregate Functions
Aggregate functions take one or more arguments, separated by a semicolon ';' or a comma and a space ', '.
Arguments may include references to cells in a spreadsheet. Cell references consist of the (CAPITAL) row letter followed by the column number.
Arguments may include ranges of cells (two cell references separated by a colon), for example average(B1:B8).
These aggregate functions are supported:
Function | Description | Value range |
---|---|---|
average(x:y) | Arithmetic mean of values in cells x through y; sum(x:y) / count(x:y) | all |
count(x:y) | Counting of cells from x through y | all |
max(x:y) | Maximum value in cells x through y | all |
min(x:y) | Minimum value in cells x through y | all |
stddev(x:y) | Standard deviation of values in cells x through y | all |
sum(x: y) | Sum of values in cells x through y | all |
Conditional Expressions
Conditional expressions are of the form condition ? resultTrue : resultFalse. The condition is defined as an expression that evaluates to either '0' (false) or non-zero (true). Note that enclosing the conditional expression in parentheses is currently considered an error. version 0.19 and below
The following relational operators are defined:
Unit | Description |
---|---|
== | equal to |
!= | not equal to |
> | greater than |
< | less than |
>= | greater than or equal to |
<= | less than or equal to |
Units
Units can directly be used in expressions. The parser connects them to the previous value. So '2mm' or '2 mm' is valid while ' mm' is invalid because there is no preceding value.
All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.
In some cases it works even without a unit, for example if you have e.g. in spreadsheet cell B1 just the number 1.5 and refer to it for a pad height. This only works because the pad height predefines the unit mm that is used if no unit is given. It will nevertheless fail if you use for the pad height e.g. Sketch1.Constraints.Width - Spreadsheet.B1 because Sketch1.Constraints.Width has a unit and Spreadsheet.B1 has not.
Units with exponents can directly be entered. So e.g. mm^3 will be recognized as mm³ and m^3 will be recognized as m³.
If you have a variable with a name of a unit you must put the variable into << >> to prevent that it will be recognized as unit. For example if you have the dimension 'Sketch.Constraints.A' it would be recognized as unit ampere. Therefore you must write it in the expression as 'Sketch.Constraints.<<A>>'.
The following units are recognized by the expression parser:
Amount of substance:
Unit | Description |
---|---|
mmol | Millimole |
mol | Mole |
Angle:
Unit | Description |
---|---|
° | Degree; alternative to the unit deg |
deg | Degree; alternative to the unit ° |
rad | Radian |
gon | Gradian |
S | Second of arc |
″ | Second of arc; alternative to the unit S |
M | Minute of arc |
′ | Minute of arc; alternative to the unit M |
Current:
Unit | Description |
---|---|
mA | Milliampere |
A | Ampere |
kA | Kiloampere |
MA | Megaampere |
Electrical Capacitance:
Unit | Description |
---|---|
pF | Picofarad, introduced in version 0.19 |
nF | Nanofarad, introduced in version 0.19 |
uF | Microfarad; alternative to the unit µF, introduced in version 0.19 |
µF | Microfarad; alternative to the unit uF, introduced in version 0.19 |
mF | Millifarad, introduced in version 0.19 |
F | Farad; 1 F = 1 s^4·A^2/m^2/kg, introduced in version 0.19 |
Electrical Conductance:
Unit | Description |
---|---|
uS | Microsiemens; alternative to the unit µS, introduced in version 0.19 |
µS | Microsiemens; alternative to the unit uS, introduced in version 0.19 |
mS | Millisiemens, introduced in version 0.19 |
S | Siemens; 1 S = 1 s^3·A^2/kg/m^2, introduced in version 0.19 |
Electrical Inductance:
Unit | Description |
---|---|
nH | Nanohenry, introduced in version 0.19 |
uH | Microhenry; alternative to the unit µH, introduced in version 0.19 |
µH | Microhenry; alternative to the unit uH, introduced in version 0.19 |
mH | Millihenry, introduced in version 0.19 |
H | Henry; 1 H = 1 kg·m^2/s^2/A^2, introduced in version 0.19 |
Electrical Resistance:
Unit | Description |
---|---|
Ohm | Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2, introduced in version 0.19 |
kOhm | Kiloohm, introduced in version 0.19 |
MOhm | Megaohm, introduced in version 0.19 |
Electric Charge:
Unit | Description |
---|---|
C | Coulomb; 1 C = 1 A·s, introduced in version 0.19 |
Electric Potential:
Unit | Description |
---|---|
mV | Millivolt |
V | Volt |
kV | Kilovolt |
Energy / Work:
Unit | Description |
---|---|
mJ | Millijoule |
J | Joule |
kJ | Kilojoule, introduced in version 0.19 |
eV | Electronvolt; 1 ev = 1.602176634e-19 J, introduced in version 0.19 |
keV | Kiloelectronvolt, introduced in version 0.19 |
MeV | Megaelectronvolt, introduced in version 0.19 |
kWh | Kilowatt hour; 1 kWh = 3.6e6 J, introduced in version 0.19 |
Ws | Watt second; alternative to the unit Joule |
VAs | Volt-ampere-second; alternative to the unit Joule |
CV | Coulomb-volt; alternative to the unit Joule |
cal | Calorie; 1 cal = 4.184 J, introduced in version 0.19 |
kcal | Kilocalorie, introduced in version 0.19 |
Force:
Unit | Description |
---|---|
mN | Millinewton |
N | Newton |
kN | Kilonewton |
MN | Meganewton |
lbf | Pound of force |
Length:
Unit | Description |
---|---|
nm | Nanometer |
um | Micrometer; alternative to the unit µm |
µm | Micrometer; alternative to the unit mu |
mm | Millimeter |
cm | Centimeter |
mm | Millimeter |
dm | Decimeter |
m | Meter |
km | Kilometer |
mil | Thousandth of an inch; alternative to the unit thou |
thou | Thousandth of an inch; alternative to the unit mil |
in | Inch |
ft | Foot; alternative to the unit ' |
' | Foot; alternative to the unit ft |
yd | Yard |
mi | Mile |
Luminous Intensity:
Unit | Description |
---|---|
cd | Candela |
Magnetic Field Strength:
Unit | Description |
---|---|
Oe | Oersted; 1 Oe = 79.57747 A/m, introduced in version 0.19 |
Magnetic Flux:
Unit | Description |
---|---|
Wb | Weber; 1 Wb = 1 kg*m^2/s^2/A, introduced in version 0.19 |
Magnetic Flux Density:
Unit | Description |
---|---|
G | Gauss; 1 G = 1 e-4 T, introduced in version 0.19 |
T | Tesla; 1 T = 1 kg/s^2/A, introduced in version 0.19 |
Mass:
Unit | Description |
---|---|
ug | Microgram; alternative to the unit µg |
µg | Microgram; alternative to the unit ug |
mg | Milligram |
g | Gram |
kg | Kilogram |
t | Tonne |
oz | Ounce |
lb | Pound; alternative to the unit lbm |
lbm | Pound; alternative to the unit lb |
st | Stone |
cwt | Hundredweight |
Power:
Unit | Description |
---|---|
W | Watt |
kW | Kilowatt, introduced in version 0.19 |
VA | Volt-ampere |
Pressure:
Unit | Description |
---|---|
Pa | Pascal |
kPa | Kilopascal |
MPa | Megapascal |
GPa | Gigapascal |
mbar | MilliBar, introduced in version 0.19 |
bar | Bar, introduced in version 0.19 |
uTorr | Microtorr; alternative to the unit µTorr |
µTorr | Microtorr; alternative to the unit uTorr |
mTorr | Millitorr |
Torr | Torr; 1 Torr = 133.32 Pa |
psi | Pound-force per square inch; 1 psi = 6.895 kPa |
ksi | Kilopound-force per square inch |
Mpsi | Megapound-force per square inch, introduced in version 0.19 |
Temperature:
Unit | Description |
---|---|
uK | Microkelvin; alternative to the unit µK |
µK | Microkelvin; alternative to the unit uK |
mK | Millikelvin |
K | Kelvin |
Time:
Unit | Description |
---|---|
s | Second |
min | Minute |
h | Hour |
Hz (1/s) | Hertz, introduced in version 0.19 |
kHz | Kilohertz, introduced in version 0.19 |
MHz | Megahertz, introduced in version 0.19 |
GHz | Gigahertz, introduced in version 0.19 |
THz | Terahertz, introduced in version 0.19 |
Torque:
Unit | Description |
---|---|
Nm | Newton metre |
Volume:
Unit | Description |
---|---|
ml | Milliliter, introduced in version 0.19 |
l | Liter |
cft | Cubicfoot, introduced in version 0.19 |
Special imperial units:
Unit | Description |
---|---|
mph | Miles per hour, introduced in version 0.19 |
sqft | Square foot, introduced in version 0.19 |
The following commonly used units are not yet supported:
Unit | Description | Alternative |
---|---|---|
°C | Celsius | [°C] + 273.15 K |
°F | Fahrenheit; | ([°F] + 459.67) × 5/9 |
u | Atomic mass unit; alternative to the unit 'Da' | 1.66053906660e-27 kg |
Da | Dalton; alternative to the unit 'u' | 1.66053906660e-27 kg |
sr | Steradian | not directly |
lm | Lumen | not directly |
lx | Lux | not directly |
px | Pixel | not directly |
Reference To CAD-Data
It is possible to use data from the model itself in an expression. To reference a property use "object.property". If the property is a compound of fields, the individual fields can be accessed as "object.property.field".
The following table shows some examples:
CAD-Data | Call in expression | Result |
---|---|---|
Parametric Length of a Part-Workbench Cube | Cube.Length
|
Length with units mm
|
Volume of the Cube | Cube.Shape.Volume
|
Volume in mm³ without units
|
Type of the Cube-shape | Cube.Shape.ShapeType
|
String: Solid |
Label of the Cube | Cube.Label
|
String: Label |
x-coordinate of center of mass of the Cube | Cube.Shape.CenterOfMass.x
|
x-coordinate in mm without units |
Value of constraint in a sketch | Constraints.Width
|
Numeric value of the named constraint 'Width ' in the sketch, if the expression is used in the sketch itself.
|
Value of constraint in a sketch | MySketch.Constraints.Width
|
Numeric value of the named constraint 'Width ' in the sketch, if the expression is used outside of the sketch.
|
Value of a spreadsheet alias | Spreadsheet.Depth
|
Value of the alias "Depth " in the spreadsheet "Spreadsheet "
|
Value of a local property | Length
|
Value of the Length property in e.g a Pad object, if the expression is used in e.g Length2 in the same object.
|
Document-wide global variables
There is no concept of global variables in FreeCAD at the moment. Instead, arbitrary variables can be defined as cells in a spreadsheet using the Spreadsheet workbench, and then be given a name using the alias property for the cell (right-click on cell). Then they can be accessed from any expression just as any other object property.
Cross-document linking
It is possible (with limitations) to define a Property of an object in your current document (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the Length of a Part Cube, etc. in one document can be defined by an Expression that references the X Placement value or another Property of an object contained in a different document.
A document's name is used to reference it from other documents. When saving a document the first time, you choose a file name; this is usually different from the initial default "Unnamed1" (or its translated equivalent). To prevent links being lost when the master document is renamed upon saving, it is recommended that you first create the master document, create a spreadsheet inside it, and save it. Subsequently, you can still make changes to the file and its spreadsheet but you should not rename it.
Once the master document with the spreadsheet is created and saved (named), it is safe to create dependent documents. For example, assuming you name the master document "master
", the spreadsheet "modelConstants
", and give a cell an alias-name "Length
", you can then access the value as:
master#modelConstants.Length
Note: that the master document must be loaded for the values in the master to be available to the dependent document.
Unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the OK button will become active.
Of course, it's up to you to load the corresponding documents later when you want to change anything.
Known issues / remaining tasks
- The dependency graph is based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. As a work-around, use multiple spreadsheets -- one to drive your model, and one for reporting.
- The expression parser does not handle parentheses well, and is unable to properly parse some expressions. For example: "= (A1 > A2) ? 1 : 0" results in an error, while "= A1 > A2 ? 1 : 0" is accepted. The expression "= 5 + ((A1>A2) ? 1 : 0)" cannot be entered in any form.
- As stated above, unfortunately, the integrated checker sometimes claims that a valid name doesn't exist. Continue typing anyway. When you have completed the full reference, the OK button will become active.
- There is no expression manager implemented where all expressions in a document are listed, and can be created, deleted, queried, etc.
- The names of Sketcher constraints must not contain any blanks when the value is calculated by an expression, see forum discussion.
- Open bugs/tickets for Expressions can be found in the FreeCAD Bugtracker Expressions category
- FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics
- Modules: Builtin modules, Units, Quantity
- Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
- Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC
- Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
- Scenegraph: Coin (Inventor) scenegraph, Pivy
- Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Embedding: Embedding FreeCAD, Embedding FreeCADGui
- Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)
- Hubs: User hub, Power users hub, Developer hub