Expressions/de

Übersicht

Es ist möglich, Eigenschaften unter Verwendung von mathematischen Ausdrücken festzulegen. In der GUI zeigen Drehfelder oder Eingabefelder, die an Eigenschaften gebunden sind, ein blaues Symbol , wenn aktiviert. Klicken auf das Symbol oder Eingeben des Gleichheitszeichens = öffnet den Ausdruckseditor für diese bestimmte Eigenschaft. Zeigt das Eingabefeld eine Schaltfläche ... anstatt eines Symbols, kann der Ausdruckseditor mit einem Rechtsklick auf die Eigenschaft und Auswählen von Expression... im Kontextmenü geöffnet werden.

Ein FreeCAD-Ausdruck ist ein mathematischer Ausdruck, der die mathematischen Standard- Operatoren, Funktionen und vorgegebene Konstanten verwendet, wie unten beschrieben. Zusätzlich können Ausdrücke auf Objekteigenschaften referenzieren und auch Bedingte Ausdrücke verwenden. Zahlen in Ausdrücken können optionale Einheiten angefügt werden.

Zahlen können entweder ein Komma , oder einen Dezimalpunkt . zur Trennung von Ganzzahlen und Nachkommastellen verwenden. Wenn ein Dezimaltrennzeichen benutzt wird, muss danach mindestens eine Ziffer folgen. Daher sind die Ausdrücke 1.+2. und 1,+2, ungültig, aber 1.0 + 2.0 und 1,0 + 2,0 sind gültig.

Operatoren und Funktionen beachten die Einheiten und erfordern gültige Kombinationen von Einheiten, falls verfügbar. Zum Beispiel ist 2mm + 4mm ein gültiger Ausdruck, während 2mm + 4 kein gültiger Ausdruck ist. Dies gilt auch für Referenzen auf Objekteigenschaften, die Einheiten beinhalten, wie z.B. Längeneigenschaften. Daher ist Pad001.Length + 1 ungültig, da es einer Eigenschaft mit Längeneinheit nur eine Zahl ohne Einheit hinzufügt; gültig wäre Pad001.Length + 1mm.

Einige Fehler im Zusammenhang mit Einheiten können unverständlich erscheinen, wenn Ausdrücke abgelehnt werden oder die Ergebnisse nicht den Einheiten der bearbeiteten Eigenschaft entsprechen. Ein paar Beispiele:

1/2mm wird nicht als halber Millimeter angesehen sondern als 1/(2mm) und ergibt: 0.5 mm^-1.

sqrt(2)mm ist ungültig, da der Funktionsaufruf keine Zahl ist. Dies muss so eingegeben werden: sqrt(2) * 1mm.

Funktionsargumente

Mehrere Argumente zu einer Funktion können entweder durch ein Semikolon ; oder ein Komma gefolgt von einem Leerzeichen , getrennt werden. Im letzteren Fall wird das Komma nach der Eingabe in ein Semikolon umgewandelt. Wenn ein Semikolon verwendet wird, ist kein Leerzeichen am Ende des Semikolons erforderlich.

Die Argumente können Verweise auf Zellen in einer Kalkulationstabelle enthalten. Ein Zellverweis besteht aus dem großen Zeilenbuchstaben der Zelle, gefolgt von ihrer Spaltennummer, zum Beispiel A1. Eine Zelle kann auch durch den Alias der Zelle referenziert werden, zum Beispiel Tabellenblatt.MeineTeilbreite.

Referenzierende Objekte

Wie oben schon gezeigt, kann ein Objekt über seinen Daten-EigenschaftNamen referenziert werden. Es kann aber auch seine Daten-EigenschaftBenennung (Label) verwendet werden. Im Falle einer Daten-EigenschaftBenennung muss sie in doppelten << und >> Symbolen eingeschlossen sein, wie z.B. <<Benennung>>.

Jede Eigenschaft eines Objekts kann referenziert werden. Um sich beispielsweise auf die Höhe eines Zylinders zu beziehen, kann Zylinder.Height oder <<Benennung_des_Zylinders>>.Height verwendet werden.

Für weitere Informationen über das Referenzieren von Objekten siehe Auf CAD-Daten referenzieren.

Anfang

Unterstützte Konstanten

Die folgenden Konstanten werden unterstützt:

Konstante	Beschreibung
e	Eulersche Zahl
pi	Kreiszahl ${\displaystyle \pi }$

Anfang

Unterstützte Operatoren

Die folgenden Operatoren werden untertstützt:

Anfang

Unterstützte Funktionen

Allgemeine mathematische Funktionen

Die folgenden mathematischen Funktionen werden untertstützt:

Trigonometrische Funktionen

Trigonometrische Funktionen verwenden Grad als Standardeinheit. Für die Angabe im Bogenmaß wird rad nach dem ersten Wert in einem Ausdruck hinzugefügt. So ist z.B. cos(45) das gleiche, wie cos(pi rad / 4). Ausdrücke in Grad können entweder deg oder ° verwenden, z.B. 360deg - atan2(3; 4) oder 360° - atan2(3; 4). Ein Ausdruck, der ohne Einheiten angegeben ist und aus Kompatibilitätsgründen in Grad oder Bogenmaß umgewandelt werden muss, wird entsprechend mit 1deg, 1° oder 1rad multipliziert, z.B. (360 - X) * 1deg; (360 - X) * 1°; (0.5 + pi / 2) * 1rad.

Exponential- und Logarithmusfunktionen

Rundung, Trunkierung und Modulo

Anfang

Statistische / Aggregatfunktionen

Aggregatfunktion verwenden ein oder mehrere Argumente.

Einzelne Argumente für Aggregatfunktionen können aus Zellbereichen bestehen. Ein Zellbereich wird durch zwei Zellbezüge ausgedrückt, die durch einen Doppelpunkt : getrennt sind, zum Beispiel Durchschnitt(B1:B8) oder Summe(A1:A4; B1:B4). Die Zellbezüge können auch Zell Aliase verwenden, zum Beispiel Durchschnitt(StartTemp:EndTemp).

Diese Aggregatfunktionen werden unterstützt:

Anfang

Zeichenkettenhandhabung

Zeichenkettenerkennung

Zeichenketten werden in Ausdrücken erkannt, indem sie in doppelte öffnende/schließende Winkel eingeschlossen werden (so wie Beschriftungen).

Im folgenden Beispiel wird "TEXT" als eine Zeichenkette erkannt: <<TEXT>>

Zeichenkettenverkettung

Zeichenketten können durch das '+'-Zeichen aneinandergehängt werden.

Das folgende Beispiel <<MY>>+<<TEXT>> wird verbunden zu "MYTEXT".

Umwandlung in Zeichenketten

Numerische Werte können mit der Funktion str in Zeichenketten gewandelt werden:

str(Box.Length.Value)

Zeichenkettenformatierung

Zeichenkettenformatierung wird unterstützt durch die (alte) %-Form von Python.

Alle %-Spezifizierer wie in der (engl.) Python documentation definiert.

Hat man bspw. einen mit den Vorgabewerten erstellten Würfel namens 'Box' (FreeCAD-Standardbezeichnung) mit 10mm-Kantenlänge, wird der folgende Ausdruck <<Würfellänge: %s>> % Box.Length erweitert zu "Würfellänge: 10.0 mm"

Für mehr als einen %-Spezifizierer verwendet man folgende Syntax: <<Würfellänge ist %s und Würfelbreite ist %s>> % tuple(Box.Length; Box.Width). Oder man verwendet die Verkettung: <<Würfellänge ist %s>> % Box.Length + << und Länge ist %s>> % Box.Width. Beide ergeben zusammen "Würfellänge ist 10.0 mm und Breite ist 10.0 mm".

Eine FreeCAD-Beispieldatei, die Zeichenkettenformatierung zeigt, ist unter im Forum verfügbar (engl.)

Anfang

Funktionen zur Objekterstellung

Die folgenden Objekte können in Ausdrücken durch die folgenden Funktionen erstellt werden:

matrix(
  a11; a12; a13; a14;
  a21; a22; a23; a24;
  a31; a32; a33; a34;
  a41; a42; a43; a44
)

Anfang

Vektorfunktionen

Funktionen: eingeführt mit Version 1.0.

Function / Operator	Description
v1 + v2	Addiert zwei Vektoren.
v1 - v2	Subtrahiert zwei Vektoren.
v * s	Skaliert einen Vektor gleichförmig mit Faktor s.
vangle(v1; v2)	Winkel zwischen zwei Vektoren in Grad.
vcross(v1; v2)	Kreuzprodukt zweier Vektoren ${\displaystyle v_{1}\times v_{2}}$.
v1 * v2	Skalarprodukt zweier Vektoren ${\displaystyle v_{1}\cdot v_{2}}$.
vdot(v1; v2)
vlinedist(v1; v2; v3)	Abstand zwischen Vektor v1 und einer Linie durch v2 in Richtung v3.
vlinesegdist(v1; v2; v3)	Abstand zwischen Vektor v1 und dem dichtesten Punkt auf einem Linienabschnitt (Strecke) von v2 nach v3.
vlineproj(v1; v2; v3)	Projiziert Vektor v1 auf eine Linie durch v2 in Richtung v3.
vnormalize(v)	Normalisiert einen Vektor zu einem Einheitsvektor.
vplanedist(v1)	Abstand zwischen Vektor v1 und einer Ebene, die durch einen Punkt v2 und eine Normale v3 festgelegt wird.
vplaneproj(v1)	Projiziert Vektor v1 auf eine Ebene, die durch einen Punkt v2 und eine Normale v3 festgelegt wird.
vscale(v; sx; sy; sz)	Skaliert einen Vektor ungleichförmig mit den Faktoren sx in X-Richtung, sy in Y-Richtung und sz in Z-Richtung.
vscalex(v; sx)
vscaley(v; sy)
vscalez(v; sz)

Anfang

Matrixfunktionen

Rotation Und Placement können beide durch eine Matrix dargestellt werden. Die folgenden Funktionen akzeptieren alle eine Matrix, eine Rotation oder ein Placement als ihren ersten Parameter, in der folgenden Tabelle mit m gekennzeichnet. Die Art der zurückgegebenen Objekte ist dieselbe, wie die des Objekts, das mit dem ersten Argument übergeben wurde, außer wenn mtranslate auf eine Rotation angewandt wird; in dem Falle wird ein Placement zurückgegeben.

Anfang

Bedingte Ausdrücke

Bedingte Ausdrücke haben die Form Bedingung ? ResultatWahr : ResultatFalsch. Die Bedingung ist definiert als ein Ausdruck, der entweder zu 0 (falsch/false) oder Nicht-Null (wahr/true) ausgewertet wird.

Man beachte, dass, um eine boolesche Eigenschaft für diese Bedingung einzusetzen, folgende Syntax verwendet werden muss: VarSet.MyBool == 1 ? 10 mm : 15 mm.

Die folgenden Vergleichsoperatoren sind definiert:

Anfang

Einheiten

Einheiten können direkt in Ausdrücken verwendet werden. Der Analysator (parser) verbindet sie mit dem vorherigen Wert. So ist 2mm oder 2 mm gültig, während mm ungültig ist, weil es keinen vorhergehenden Wert gibt.

Alle Werte müssen eine Einheit haben. Daher müssen Werte auch in Kalkulationstabellen im allgemeinen eine Einheit haben.
In einigen Fällen funktioniert es auch ohne Einheit, z.B. wenn Sie in Zelle B1 der Kalkulationstabelle z.B. nur die Zahl 1.5 haben und sich für eine Blockhöhe darauf beziehen. Dies funktioniert nur, weil die Blockhöhe die Einheit mm vordefiniert und die verwendet wird, wenn keine Einheit angegeben ist. Es schlägt jedoch fehl, wenn Sie für die Blockhöhe z.B. Sketch1.Constraints.Breite - Kalkulationstabelle.B1 verwenden, weil Sketch1.Constraints.Breite eine Einheit hat und Kalkulationstabelle.B1 keine Einheit.

Einheiten mit Exponenten können direkt eingegeben werden. So wird z.B. mm^3 als mm³ erkannt und m^3 wird als m³ erkannt.

Wenn eine Variable mit dem Namen einer Einheit verwendet wird, muss die Variable in << >> gesetzt werden. Das verhindert, dass die Variable als Einheit erkannt wird. Das Maß Sketch.Constraints.A würde z.B. als Einheit Ampere erkannt werden. Daher muss der Ausdruck als Sketch.Constraints.<<A>> geschrieben werden.

Die folgenden Einheiten werden vom Analysator für Ausdrücke erkannt:

Stoffmenge

Winkel

Strom

Elektrische Kapazität

Elektrische Ladung

Elektrischer Leitwert

Elektrische Induktivität

Elektrische Spannung

Elektrisches Spannung:

Elektrischer Widerstand

Elektrischer Widerstand:

Energie/Arbeit

Kraft

Länge

Lichtstärke

Magnetischer Fluss

Magnetische Flussdichte

Masse

Leistung

Druck

Temperatur

Zeit

Volumen

Spezielle nichtmetrische Einheiten

Nicht unterstützte Einheiten

Die folgenden häufig verwendeten Einheiten werden noch nicht unterstützt, für einige gibt es aber Alternativen:

Anfang

Ungültige Zeichen und Namen

Das Ausdrucks-Feature ist sehr leistungsfähig. Um das zu ermöglichen gibt es ein paar Einschränkungen bei ein paar Zeichen. Als Abhilfe gibt es in FreeCAD die Möglichkeit anstatt der Objektnamen sog. Bezeichner ('labels') zu verwenden und sich auf diese zu beziehen.

In Fällen, in denen du keine Beschriftung verwenden kannst, wie z. B. der Name einer Skizzenbeschränkung, musst du dir bewusst sein, welche Zeichen nicht erlaubt sind.

Bezeichner

Für Bezeichner gibt es keine ungültigen Zeichen, jedoch müssen einige Zeichen maskiert werden:

Zum Beispiel muss der Bezeichner Skizze\002 als <<Skizze\002>> referenziert werden.

Namen

Namen von Objekten wie Maße, Skizzen, usw. dürfen folgende Zeichen oder Zeichenfolgen nicht enthalten. Anderenfalls ist der Namen ungültig.

Beispielsweise ist folgender Name gültig: <<Sketch>>.Constraints.T2üßµ@. Hingegen sind diese ungültige Namen: <<Sketch>>.Constraints.test\result_2 (\r bedeutet "Wagenrücklauf (carriage return)") oder<<Sketch>>.Constraints.mol (mol ist eine Einheit).

Da kürzere Namen (vor allem, wenn sie nur ein oder zwei Zeichen haben) leicht zu ungültigen Namen führen können, sollte die Verwendung längerer Namen in Betracht gezogen und/oder eine geeignete Namenskonvention festgelegt werden.

Zell Aliasse

Siehe Spreadsheet Alias-Namen festlegen.

Anfang

Referenzen auf CAD Daten

Es ist möglich, Daten aus dem Modell selbst in einem Ausdruck zu verwenden. Um auf eine Eigenschaft zu verweisen, wird Objekt-Name.property oder <<Objekt-Benennung>>.property. Benennungen (Label) müssen in << und >> eingeschlossen werden. Sollen Benennungen verwendet werden, müssen sie eindeutig sein.

Alle weiteren Beispiele referenzieren ein Objekt über seinen Namen, aber seine Benennung kann ebenfalls verwendet werden.

Wenn die Eigenschaft aus mehreren Feldern aufgebaut ist, kann auf die einzelnen Felder mit object_name.property.field zugegriffen werden.

Um auf Listenobjekte zu verweisen, wird ObjektName.list[list_index] verwendet. Soll beispielsweise auf eine Randbedingung in einer Skizze verwiesen werden, wird Skizze.Constraints[16] verwendet. Ist eine Skizze im Bearbeitungsmodus geöffnetbefindest, kann man den Namen weglassen und einfach Constraints[16] verwenden. Man beachte, dass der Index mit 0 beginnt, daher muss die 17. Randbedingung als Constraints[16] referenziert werden.

Um auf das Objekt selbst zu referenziertem wird die Pseudo-Eigenschaft _self verwendet: Objekt-Name._self.

Die folgende Tabelle zeigt einige weitere Beispiele:

Zyklische Abhängigkeiten

FreeCAD prüft Abhängigkeiten aufgrund der Beziehungen zwischen Dokumentobjekten, nicht auf Basis ihrer Eigenschaften. Das heißt, dass man einem Objekt nicht Daten zur Verfügung stellen und (gleichzeitig) das Ergebnis desselben Objekts auslesen kann. Z.B. darf es, auch wenn es keine zyklischen Abhängigkeiten zwischen den Eigenschaften selbst gibt, kein Objekt geben, das seine Abmaße aus einer Tabelle erhält, und dessen (gemessenes) Volumen in derselben Tabelle ausgegeben wird. Es müssen zwei Tabellen verwendet werden, eine zum Steuern des Modells und eine für die Ausgabe (von ausgelesenen Ergebnissen).

Als Ungehunglösung kann man einen Zellenbereich der zweiten Tabelle in der ersten anzeigen (oder umgekehrt), indem eine Zellenverbindung mit der Option Hide dependency of binding erstellt wird.

Eine weitere Möglichkeit zyklische Abhängigkeiten zu umgehen, ist das Ausblenden der Referenz, indem die Funktion href oder hiddenref für individuelle Ausdrücke verwendet wird, z.B.: href(Box.Length).

Bitte beachten, dass beide erwähnten Umgehungslösungen mit Vorsicht eingesetzt werden sollten und dass sie nicht funktionieren, wenn die Eigenschaften, die ausgegeben werden, auf Abmaßen beruhen, die aus derselben Tabelle heraus gesteuert werden.

Anfang

Dokumentweit gültige globale Variablen

In FreeCAD gibt es zur Zeit kein Konzept für globale Variablen. Stattdessen können beliebige Variablen mit Hilfe der Arbeitsbereich Kalkulationstabelle als Zellen in einer Kalkulationstabelle definiert werden und dann mit Hilfe der Alias Eigenschaft für die Zelle (Rechtsklick auf die Zelle) einen Namen erhalten. Dann kann von jedem Ausdruck aus auf sie zugegriffen werden, wie auf jede andere Objekteigenschaft auch.

Anfang

Dokumentenübergreifende Verweise

Es ist (mit Begrenzungen) möglich, eine Eigenschaft eines Objekts in deinem aktuellen Dokument (".FCstd" Datei) durch Verwendung eines Ausdrucks zu definieren, um auf eine Eigenschaft eines Objekts in einem anderen Dokument zu verweisen (".FCstd" file). Zum Beispiel kann eine Zelle in einer Kalkulationstabelle oder die Daten-EigenschaftLänge eines Formteil Würfels usw. in einem Dokument durch einen Ausdruck definiert werden, der auf den X Platzierungswert oder eine andere Eigenschaft eines Objekts in einem anderen Dokument verweist.

Der Name des Dokuments wird verwendet, um von einem anderen Dokument aus darauf zu referenzieren. Wenn ein Dokument zum ersten Mal gespeichert wird, muss dem Dokument ein Name gegeben werden. Dies ist normalerweise ein anderer Name als die Vorgabe "Unbenannt1". Um zu verhindern, dass Verknüpfungen beim Speichern des Hauptdokumentes verloren gehen, wenn dieses dabei einen anderen Namen bekommt, sollte das Hauptdokument zuerst mit einer Kalkulationstabelle erstellt werden. Danach kann der Inhalt des Dokuments geändert und das Dokument gespeichert werden, aber es darf nicht umbenannt werden.

Sobald das Mutterdokument mit der Kalkulationstabelle erstellt und gespeichert (benannt) ist, können abhängige Dokumente erstellt werden. Angenommen, du nennst das Mutterdokument master, die Kalkulationstabelle modelConstants und gibst einer Zelle einen Alias-Namen Length, dann kannst du auf den Wert zugreifen als:

master#modelConstants.Length

Man beachte, dass das Hauptdokument geladen sein muss, damit die Werte des Hauptdokuments für das abhängige Dokument verfügbar sind.

Natürlich liegt es bei dir, die zugehörigen Dokumente später zu laden, wenn du etwas ändern willst.

Anfang

Bekannte Probleme / Verbleibende Aufgaben

• FreeCAD hat bisher keinen eingebauten Ausdrucksmanager, der alle Ausdrücke in einem Dokument auflistet und sie erstellt, löscht, abfragt, etc. Aber es ist ein Addon verfügbar: fcxref expression manager.
• Offene Fehler/Tickets für die Ausdrücke (Expressions) können hier gefunden werden: GitHub.

Anfang

Skripten

import FreeCAD as App

doc = App.ActiveDocument
box = doc.addObject("Part::Box", "Box")
cyl = doc.addObject("Part::Cylinder", "Cylinder")
cyl_name = cyl.Name

box.setExpression("Height", f"{cyl_name}.Height / 2")
box.setExpression("Length", f"{cyl_name}.Radius * 2")
box.setExpression("Width", "Length")

doc.recompute()

# Expressions are stored in the ExpressionEngine property:
for prop, exp in box.ExpressionEngine:
    val = getattr(box, prop)
    print(f"Property: '{prop}' -- Expression: '{exp}' -- Current value: {val}")

Anfang

Power user documentation

• 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