Expressions

Other languages:

Vue d'ensemble

Il est possible de définir des propriétés à l'aide d'expressions mathématiques. Dans l'interface graphique, les zones de sélection numérique ou les champs de saisie liés aux propriétés contiennent une icône bleue File:Sketcher Expressions.png. Cliquez sur l'icône ou tapez le signe égal = pour ouvrir l'éditeur d'expression pour cette propriété particulière.

Une expression FreeCAD est une expression mathématique qui suit la notation pour les opérateurs mathématiques standard et fonctionne comme décrit ci-dessous. En outre, l'expression peut faire référence à d'autres propriétés et également utiliser des conditions. Une unité facultative peut être attachée aux nombres d'une expression.

Les nombres peuvent utiliser une virgule , ou un point décimal . séparer les chiffres entiers des décimales. Lorsque le marqueur décimal est utilisé, il doit obligatoirement être suivi d'au moins un chiffre. Ainsi, les expressions 1.+2. et 1,+2, ne sont pas valides, mais 1.0 + 2.0 et 1,0 + 2,0 sont valables.

Les opérateurs et fonctions reconnaissent les unités de mesure et nécessitent des combinaisons valides si elles sont fournies. Par exemple, 2mm + 4mm est une expression valide, tandis que 2mm + 4 ne l'est pas (la raison est qu'une expression comme 1in + 4 sera très probablement interprété comme 1in + 4in par le dessinateur mais comme toutes les unités en interne sont converties au système international SI, et le système est totalement incapable de deviner de quelle unité il s'agit). Ces unités sont actuellement reconnues.

Vous pouvez utiliser des constantes prédéfinies et des fonctions.

Arguments de la fonction

Lorsqu'une fonction prend plusieurs arguments, ceux-ci peuvent être séparés par un point-virgule ; ou une virgule suivie par un espace , . Dans ce derniers cas, la virgule est convertie en point-virgule après la saisie. Quand on utilise un point-virgule, il n'est pas nécessaire de finir la ligne par un espace.

Les arguments peuvent inclure des références à des cellules dans une feuille de calcul. Une référence de cellule se compose de la lettre en majuscule de la ligne de la cellule suivie de son numéro de colonne, par exemple A1. Une cellule peut également être référencée en utilisant l'alias de la cellule, par exemple Spreadsheet.MyPartWidth.

Référencement d'objets

Vous pouvez faire référence à un objet par sa DonnéesName ou sa DonnéesLabel. Dans le cas d'une DonnéesLabel, vous devez l'entourer de double symboles << et >>, comme ceci <<Label>>.

Vous pouvez référencer n'importe quelle propriété numérique d'un objet. Par exemple, pour référencer la hauteur d'un cylindre, vous pouvez utiliser Cylinder.Height ou <<Long_name_of_cylinder>>. Hauteur.

Pour référencer des objets de liste, utilisez <<object_label>>.list[list_index] ou object_name.list [index_liste]. Si vous souhaitez par exemple référencer une contrainte dans une esquisse, utilisez <<MySketch>>.Constraints[16]. Si vous êtes dans la même esquisse, vous pouvez omettre son nom et utiliser simplement Constraints[16].
Remarque : L'index commence par 0, la contrainte 17 a donc l'index 16.

Pour plus d'informations sur le référencement des objets, voir Référence aux données CAO.

Constantes prises en charge

Les constantes suivantes sont supportées:

Constante	Description
e	nombre d'Euler
pi	Pi

Opérateurs pris en charge

Les opérations suivantes sont supportées:

Opération	Description
+	Addition
-	Soustraction
*	Multiplication
/	Point flottant Division
%	Reste
^	Exponentiation

Fonctions supportées

Fonctions mathématiques générales

Les fonctions mathématiques suivantes sont disponibles.

Les fonctions trigonométriques utilisent le degré comme unité par défaut. Pour la mesure en radian, ajoutez rad après la première valeur dans une expression. Par exemple cos(45) est identique à cos(pi rad / 4). Les expressions en deg ou °, comme 360deg - atan2(3; 4) ou 360° - atan2(3; 4). Si une expression est sans unités et doit être convertie en degrés ou radians pour la compatibilité, multipliez par 1 deg, 1 ° ou 1 rad selon le cas, par ex. (360 - X) * 1deg; (360 - X) * 1°; (0.5 + pi / 2) * 1rad.
Ces fonctions trigonométriques sont supportées :

Fonction	Description	Plage des valeurs
acos(x)	Arc cosinus	-1 <= x <= 1
asin(x)	Arc sinus	-1 <= x <= 1
atan(x)	Arc tangente	tout
atan2(x, y)	atan2 de x/y	tout sauf y = 0
cos(x)	Cosinus	tout
cosh(x)	Cosinus hyperbolique	tout
sin(x)	Sinus	tout
sinh(x)	Sinus hyperbolique	tout
tan(x)	Tangente	tout sauf x = n·90 avec n = entier
tanh(x)	Tangente hyperbolique	tout

Ces fonctions d’exponentiation et de logarithmisation sont prises en charge:

Fonction	Description	Plage des valeurs
exp(x)	Fonction exponentielle	tout
log(x)	Logarithme népérien	x > 0
log10(x)	Logarithme décimal	x > 0
pow(x, y)	Les puissances	tout
sqrt(x)	Racine carrée	x >= 0

Ces fonctions d'arrondi, de troncature et de reste sont supportées:

Fonction	Description	Plage des valeurs
abs(x)	Valeur absolue	tout
ceil(x)	Partie entière par excès, la plus petite valeur entière supérieure ou égale à x	tout
floor(x)	Partie entière, la plus grande valeur entière inférieure ou égale à x	tout
mod(x, y)	Reste après la division de x par y	tout sauf y = 0
round(x)	Arrondi au nombre entier le plus proche	tout
trunc(x)	Troncature au nombre entier le plus proche en direction de zéro	tout

Statistiques et fonctions d'agrégation

Les fonctions d'agrégation prennent un ou plusieurs arguments.

Les arguments individuels pour agréger les fonctions peuvent être constitués de plages de cellules. Une plage de cellules est exprimée sous la forme de deux références de cellule séparées par deux points :, par exemple average(B1:B8) ou sum(A1:A4; B1:B4). Les références de cellule peuvent également utiliser des alias de cellule, par exemple average(StartTemp:EndTemp) introduit dans la version 0.19.

Les fonctions cumulatives supportées sont

Fonction	Description	Plage des valeurs
average(a; b; c; ...)	Valeur Moyenne des arguments; identique à sum(a; b; c; ...) / count(a; b; c; ...)	tout
count(a; b; c; ...)	Comptage des arguments; généralement utilisé pour les plages de cellules	tout
max(a; b; c; ...)	Valeur Maximum des arguments	tout
min(a; b; c; ...)	Valeur Minimum des arguments	tout
stddev(a; b; c; ...)	Écart type des valeurs des arguments	tout
sum(a; b; c; ...)	Somme des valeurs des arguments; généralement utilisé pour les plages de cellules	tout

Manipulation de chaînes de caractères

Identification de la chaîne caractères

Les chaînes de caractères sont identifiées dans les expressions en les entourant de doubles chevrons ouvrants/fermants (comme les étiquettes).

Dans l'exemple suivant, "TEXT" est reconnu comme une chaîne de caractères : <<TEXT>>.

Concaténation de chaînes de caractères

Les chaînes de caractères peuvent être concaténées à l'aide du signe '+'.

L'exemple suivant <<MY>> + <<TEXT>> sera concaténé en "MYTEXT".

Formatage des chaînes de caractères

Le formatage des chaînes de caractères est pris en charge en utilisant le (vieux) style % de Python.

Tous les spécificateurs % tels que définis dans la documentation Python.

Par exemple, supposons que vous ayez un cube par défaut de 10mm de côté nommé 'Box' --nomination par défaut de FreeCAD--, l'expression suivante <<Cube length : %s>> % Box.Length se développera en "Cube length : 10.0 mm"

Une limitation est qu'un seul spécificateur % est autorisé dans une chaîne, vous devez donc utiliser la concaténation de chaînes si plusieurs sont nécessaires. Dans la même situation que ci-dessus, l'expression <<Cube length is %s>> % Box.Length + << and width is %s>> % Box.Width se développera en "Cube length is 10.0 mm and width is 10.0 mm".

Un exemple de fichier FreeCAD utilisant le formatage des chaînes de caractères est disponible dans le forum.

Expressions conditionnelles

Les expressions conditionnelles sont de la forme condition ? resultTrue : resultFalse. (condition ? résultat si VRAI : résultat si FAUX). La condition est définie comme une expression dont le résultat est 0 (faux) ou différent de zéro (vrai). Remarquez que le fait de mettre l'expression conditionnelle entre parenthèses est actuellement considéré comme une erreur. version 0.19 et précédentes

Les opérateurs relationnels suivants sont définis:

Unité	Description
==	égal à
!=	différent de
>	strictement plus grand que
<	strictement plus petit que
>=	plus grand ou égal à
<=	plus petit ou égal à

Unités

Les unités peuvent être directement utilisées dans des expressions. L'analyseur les connecte à la valeur précédente. Donc 2mm ou 2 mm sont valides tandis que mm est invalide car il n'y a pas de valeur.

Toutes les valeurs doivent avoir une unité. Par conséquent, vous devez généralement utiliser une unité pour les valeurs dans les feuilles de calcul.
Dans certains cas, cela fonctionne même sans unité, par exemple si vous avez dans la cellule B1 du calculateur, juste le nombre 1.5 et qu'il se reporte à la hauteur du pavé. Cela ne fonctionne que parce que la hauteur du pad prédéfinit l'unité mm utilisée si aucune unité n'est donnée. Il échouera néanmoins si vous utilisez pour la hauteur du pad, par exemple Sketch1.Constraints.Width - Spreadsheet.B1 car Sketch1.Constraints.Width a une unité et Spreadsheet.B1 n'en a pas.

Les unités avec des exposants peuvent être directement entrées. Donc, par exemple mm^3 sera reconnu comme mm³ et m^3 sera reconnu comme m³.

Si vous avez une variable dont le nom est celui d'une unité, vous devez mettre la variable entre << >> pour éviter qu'elle ne soit reconnue comme une unité. Par exemple, si vous avez la dimension Sketch.Constraints.A, elle serait reconnue comme l'unité Ampère. Par conséquent, vous devez l'écrire dans l'expression sous la forme Sketch.Constraints.<<A>>.

Les unités suivantes sont reconnues par l’analyseur d’expression:

Une quantité de matière:

Unité	Description
mmol	Millimole
mol	Mole

Angle:

Unité	Description
°	Degré; alternative à l'unité deg
deg	Degré; alternative à l'unité °
rad	Radian
gon	Gradian
S	Seconde d'arc
″	Seconde d'arc; alternative à l'unité S
M	Minute d'arc
′	Minute d'arc; à l'unité M

Courant:

Unité	Description
mA	MilliAmpère
A	Ampère
kA	KiloAmpère
MA	MégaAmpère

Capacité électrique:

Unité	Description
pF	Picofarad, introduit dans la version 0.19
nF	Nanofarad, introduit dans la version 0.19
uF	Microfarad; alternative à l'unité µF, introduit dans la version 0.19
µF	Microfarad; alternative à l'unité uF, introduit dans la version 0.19
mF	Millifarad, introduit dans la version 0.19
F	Farad; 1 F = 1 s^4·A^2/m^2/kg, introduit dans la version 0.19

Conductance électrique:

Unité	Description
uS	Microsiemens; alternative à l'unité µS, introduit dans la version 0.19
µS	Microsiemens; alternative à l'unité uS, introduit dans la version 0.19
mS	Millisiemens, introduit dans la version 0.19
S	Siemens; 1 S = 1 s^3·A^2/kg/m^2, introduit dans la version 0.19
kS	Kilosiemens, introduit dans la version 0.20
MS	Megasiemens, introduit dans la version 0.20

Inductance électrique:

Unité	Description
nH	Nanohenry, introduit dans la version 0.19
uH	Microhenry; alternative à l'unité µH, introduit dans la version 0.19
µH	Microhenry; alternative à l'unité uH, introduit dans la version 0.19
mH	Millihenry, introduit dans la version 0.19
H	Henry; 1 H = 1 kg·m^2/s^2/A^2, introduit dans la version 0.19

Résistance électrique:

Unité	Description
Ohm	Ohm; 1 Ohm = 1 kg·m^2/s^3/A^2, introduit dans la version 0.19
kOhm	Kiloohm, introduit dans la version 0.19
MOhm	Megaohm, introduit dans la version 0.19

Charge électrique:

Unité	Description
C	Coulomb; 1 C = 1 A·s, introduit dans la version 0.19

Différence de potentiel électrique:

Unité	Description
mV	Millivolt
V	Volt
kV	Kilovolt

Energie / Travail:

Unité	Description
mJ	Millijoule
J	Joule
kJ	Kilojoule, introduit dans la version 0.19
eV	Electronvolt ; 1 ev = 1.602176634e-19 J, introduit dans la version 0.19
keV	Kiloelectronvolt, introduced in version 0.19
MeV	Megaelectronvolt, introduced in version 0.19
kWh	Kilowatt heure ; 1 kWh = 3.6e6 J, introduit dans la version 0.19
Ws	Watt second ; alternative à l'unité Joule
VAs	Volt ampère seconde ; alternative à l'unité Joule, introduit dans la version 0.19
CV	Coulomb·volt ; alternative à l'unité Joule, introduit dans la version 0.19

Force:

Unité	Description
mN	milliNewton
N	Newton
kN	kiloNewton
MN	mégaNewton
lbf	Livre-force

Longueur:

Unité	Description
nm	nanomètre
mu	micromètre; alternative à l'unité µm
µm	micromètre; alternative à l'unité um
mm	millimètre
cm	centimètre
m	mètre
dm	décimètre
km	kilomètre
mil	millième de pouce; alternative à l'unité thou
thou	millième de pouce; alternative à l'unité mil
in	pouce
ft	pied; alternative à l'unité '
'	pied; alternative à l'unité ft
yd	yard ou verge
mi	mille

Intensité lumineuse :

Unit"	Description
cd	Candela

Intensité du champ magnétique:

Unité	Description
Oe	Oersted; 1 Oe = 79.57747 A/m, introduit dans la version 0.19

Flux d'induction magnétique

Unité	Description
Wb	Weber; 1 Wb = 1 kg*m^2/s^2/A, introduit dans la version 0.19

Densité de flux magnétique :

Unité	Description
G	Gauss; 1 G = 1 e-4 T, introduced in version 0.19\|-	T	Tesla; 1 T = 1 kg/s^2/A, introduit dans la version 0.19

Poids:

Unité	Description
ug	microgramme; alternative à l'unité µg
µg	microgramme; alternative à l'unité ug
mg	milligramme
g	gramme
kg	kilogramme
t	Tonne
oz	Once
lb	livre; alternative à l'unité lbm
lbm	Pound; alternative à l'unité lb
st	Stone
cwt	Hundredweight

Puissance:

Unité	Description
W	Watt
kW	Kilowatt, introduit dans la version 0.19
VA	Voltampère

Pression:

Unité	Description
Pa	pascal
kPa	Kilopascal
MPa	Mégapascal
GPa	Gigapascal
mbar	MilliBar, introduit dans la version 0.19
bar	Bar, introduit dans la version 0.19
uTorr	Microtorr; alternative à l'unité µTorr
µTorr	Microtorr; alternative à l'unité uTorr
mTorr	Millitorr
Torr	Torr; 1 Torr = 133.32 Pa
psi	Livre-force par pouce carré; 1 psi = 6.895 kPa
ksi	Kilolivre-force par pouce carré
Mpsi	Megalivre-force par pouce carré, introduit dans la version 0.19

Température:

Unité	Description
uK	microkelvin; alternative à l'unité µK
µK	microkelvin; alternative à l'unité uK
mK	millikelvin
K	Kelvin

Inductance électrique:

Unité	Description
nH	Nanohenry, introduit dans la version 0.19
uH	Microhenry; alternative à l'unité µH, introduit dans la version 0.19
µH	Microhenry; alternative à l'unité uH, introduit dans la version 0.19
mH	Millihenry, introduit dans la version 0.19
H	Henry; 1 H = 1 kg·m^2/s^2/A^2, introduit dans la version 0.19

Volume:

Unité	Description
ml	MilliLitre, introduit dans la version 0.19
l	Litre
cft	Pied cube, introduit dans la version 0.19

Unités impériales spéciales:

Unité	Description
mph	Mille par heure, introduit dans la version 0.19
sqft	Pied carré, introduit dans la version 0.19

Les unités couramment utilisées suivantes ne sont pas encore prises en charge:

Unité	Description	Alternative
°C	Celsius	[°C] + 273.15 K
°F	Fahrenheit;	([°F] + 459.67) × 5/9
u	Unité de masse atomique unifiée; alternative à l'unité "Da"	1.66053906660e-27 kg
Da	Dalton; alternative à l'unité "u"	1.66053906660e-27 kg
sr	Steradian	Pas directement
lm	Lumen	Pas directement
lx	Lux	Pas directement
px	Pixel	Pas directement

Caractères et noms non valides

La fonction expression est très puissante mais pour atteindre cette puissance, elle présente certaines limitations concernant certains caractères. Pour surmonter cela, FreeCAD propose d'utiliser des étiquettes et de les référencer à la place des noms d'objets. Dans les étiquettes, vous pouvez utiliser presque tous les caractères spéciaux.

Dans les cas où vous ne pouvez pas utiliser une étiquette, telle que le nom des contraintes d'une esquisse, vous devez savoir quels caractères ne sont pas autorisés.

Étiquettes

Pour les étiquettes, il n'y a pas de caractères non valides, cependant certains caractères doivent être évités:

Caractères	Description
`'`, `\`, `"`	Doivent être évités en ajoutant `\` devant eux.

Par exemple, l'étiquette Sketch\002 doit être référencée comme <<Sketch\\002>>.

Noms

Les Noms d'objets tels que des dimensions, des croquis, etc... peuvent ne pas avoir les caractères ou les séquences de caractères répertoriés ci-dessous, auquel cas le nom n'est pas valide:

Caractères / Séquences de caractères	Description
+, -, *, /, ^, _, <, >, (, ), {, }, [, ], ., ,, =	Caractères qui sont des opérateurs mathématiques ou qui font partie de constructions mathématiques
A, kA, mA, MA, C, G, F, uF, µF, J, K, ' , ft , ° et bien d'autres!	Caractères et séquences de caractères qui sont des unités
#, !, ?, §, $, %, &, :, ;, \, \|, ~, ∆, ¿, and many more!	Caractères utilisés comme espace réservé ou pour déclencher des opérations spéciales
pi, e	Constantes mathématiques
´, `, ' , "	Caractères utilisés pour les accents
espace	Un espace définit la fin d'un nom et ne peut donc pas être utilisé

Par exemple, le nom suivant est valide: <<Sketch>>.Constraints.T2üßµ@, alors que ces noms sont non valables: <<Sketch>>.Constraints.test\result_2 (\r signifie "retour chariot") ou <<Sketch>>.Constraints.mol (mol est une unité).

Remarque: puisque des noms plus courts (surtout s'ils n'ont qu'un ou deux caractères) peuvent facilement entraîner des noms invalides, envisagez d'utiliser des noms plus longs et/ou d'établir une convention de dénomination appropriée.

Cell aliases

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

Référence aux données CAO

Il est possible d'utiliser les données du modèle lui-même dans une expression. Pour référencer une propriété, utilisez object.property. Si la propriété est un composé de champs, les champs individuels sont accessibles en tant que object.property.field.

Le tableau suivant montre quelques exemples :

Données CAO	Appel dans l'expression	Résultat
Longueur paramétrique d'un Cube de l'atelier Part	`Cube.Length`	Longueur en mm
Volume du Cube	`Cube.Shape.Volume`	Volume en mm³ sans unité
Type de la forme Cube	`Cube.Shape.ShapeType`	Chaîne de caractère : Solid
Label du Cube	`Cube.Label`	Chaîne de caractère : Label
Coordonnée x du centre de gravité du Cube	`Cube.Shape.CenterOfMass.x`	coordonnée x en mm sans unité
Valeur d'une contrainte dans une esquisse	`Constraints.Width`	Valeur numérique de la contrainte nommée `Width` dans l'esquisse, si l'expression est utilisée dans l'esquisse elle-même.
Valeur d'une contrainte provenant d'une autre esquisse	`MySketch.Constraints.Width`	Valeur numérique de la contrainte nommée `Width` dans l'esquisse, si l'expression est utilisée en dehors de l'esquisse.
Valeur d'un alias de feuille de calcul	`Spreadsheet.Depth`	Valeur de l'alias nommé `Depth` dans la feuille de calcul `Spreadsheet`
Valeur d'une propriété locale	`Length`	Valeur de la propriété DonnéesLength, par exemple dans un objet Pad, on pourrait l'utiliser pour calculer DonnéesLength2, si celle-ci est utilisé.

Variables globales

Pour le moment il n'y a pas de notion de variables globales dans FreeCAD. Mais des variables arbitraires peuvent être définies comme des cellules dans une feuille de calcul en utilisant l'atelier Spreadsheet, auquelles on aura donné un nom en utilisant l'alias de la propriété pour la cellule utilisée (clic-droit dans la cellule). Ainsi, elles peuvent être accessibles à partir de toute expression comme toute autre propriété de l'objet.

Liaison entre documents

Il est possible (avec limitations) de définir une propriété d'un objet dans votre document actuel (fichier ".FCstd") en utilisant une expression pour référencer une propriété d'un objet contenu dans un autre document (fichier ".FCstd"). Par exemple, une cellule dans une feuille de calcul ou la DonnéesLength d'un cube de pièce, etc. dans un document peut être définie par une expression faisant référence à la valeur de placement X ou à une autre propriété d'un objet contenu dans un autre document.

Note importante : Imaginez que vous utilisiez le nom d'un document pour le référencer depuis d'autres documents. Lorsque vous sauverez ce document pour la première fois, vous allez certainement lui choisir un nom différent de "Unnamed1" (ou sa version traduite), et là, quand vous allez le ré-ouvrir, les liens seront perdus. Il est donc recommandé de créer en premier le document "maître", puis d'y créer immédiatement la feuille de calcul, de sauver le document maître avec un nom had-hoc et de le fermer. Après l'avoir ouvert à nouveau, son nom sera fixé en interne dans FreeCAD. Ensuite vous pourrez toujours faire des modification mais il ne faudra pas le renommer.

Une fois que le document maître avec la feuille de calcul est créé et enregistré (nommé), vous pouvez créer des documents dépendants en toute sécurité. Par exemple, si vous nommez le document maître master, la feuille de calcul modelConstants et attribuez à une cellule un nom d'alias Length, vous pouvez ensuite accéder à la valeur comme suit:

master#modelConstants.Length

Remarque: le document maître doit être chargé pour que les valeurs de ce dernier soient disponibles pour le document dépendant.

Malheureusement, le vérificateur intégré suppose parfois qu’aucun nom valide étendu n’existe. Continuez à taper quand même. Lorsque vous avez terminé la référence complète, le bouton OK devient actif.

Bien sûr, vous pouvez charger les documents correspondants à tout moment pour y faire les modifications que vous voudrez.

Problèmes connus / tâches restantes

Le graphe de dépendance est basé sur la relation entre les objets et le document, et non sur les propriétés. Cela signifie que vous ne pouvez pas renseigner et interroger le même objet, par exemple dans une feuille de calcul, même si il n'y a pas de dépendance cyclique si l'on considère seulement les propriétés, vous ne pouvez pas avoir d'objet dont les dimensions proviennent de la feuille de calcul et calculer son volume dans la même feuille de calcul. Pour contourner le problème, utilisez plusieurs feuilles de calcul, l'un pour contrôler votre modèle et l'autre pour faire des rapports.
L'analyseur syntaxique d'expressions ne gère pas bien les parenthèses et n'est pas capable d'analyser correctement certaines expressions. Par exemple : = (A1 > A2) ? 1 : 0 donne une erreur, alors que = A1 > A2 ? 1 : 0 est accepté. L'expression = 5 + ((A1>A2) ? 1 : 0) va contrarier l'analyseur syntaxique dans tous les cas.
Comme indiqué ci-dessus, malheureusement, le vérificateur intégré prétend parfois qu'un nom valide n'existe pas. Continuez à taper quand même. Une fois la référence complète terminée, le bouton OK devient actif.
FreeCAD ne dispose pas encore d'un gestionnaire d'expressions intégré où toutes les expressions d'un document sont listées et peuvent être créées, supprimées, interrogées etc... Un addon est disponible : fcxref expression manager.
les bogues et tickets ouverts pour les expressions sont référencés sur le Bugtracker de Freecad, catégorie Expressions