Linienzeichnungsfunktion

From FreeCAD Documentation
Revision as of 12:29, 11 January 2020 by Maker (talk | contribs) (Created page with "Das war's, jetzt müssen wir nur noch FreeCAD neu starten und schon haben wir einen schönen neuen Arbeitsbereich mit unserem brandneuen Linienwerkzeug!")
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Diese Seite zeigt, wie einfach erweiterte Funktionalität in Python gebaut werden kann. In dieser Übung werden wir ein neues Werkzeug bauen, das eine Linie zeichnet. Dieses Werkzeug kann dann mit einem FreeCAD Befehl verknüpft werden, und dieser Befehl kann von jedem Element der Schnittstelle, wie z.B. einem Menüpunkt oder einer Schaltfläche in der Werkzeugleiste, aufgerufen werden.

Das Hauptskript

Zuerst werden wir ein Skript schreiben, das unsere gesamte Funktionalität enthält. Dann werden wir dieses in einer Datei speichern und in FreeCAD importieren, so dass alle von uns geschriebenen Klassen und Funktionen in FreeCAD zur Verfügung stehen. Starte also deinen bevorzugten Texteditor und gib die folgenden Zeilen ein:

import FreeCADGui, Part
from pivy.coin import *
 
class line:
    """This class will create a line after the user clicked 2 points on the screen"""
    def __init__(self):
        self.view = FreeCADGui.ActiveDocument.ActiveView
        self.stack = []
        self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getpoint)  

    def getpoint(self,event_cb):
        event = event_cb.getEvent()
        if event.getState() == SoMouseButtonEvent.DOWN:
            pos = event.getPosition()
            point = self.view.getPoint(pos[0],pos[1])
            self.stack.append(point)
            if len(self.stack) == 2:
                l = Part.Line(self.stack[0],self.stack[1])
                shape = l.toShape()
                Part.show(shape)
                self.view.removeEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.callback)

Detaillierte Erklärung

import Part, FreeCADGui
from pivy.coin import *

Wenn Du in Python Funktionen aus einem anderen Modul verwenden willst, musst Du es importieren. In unserem Fall benötigen wir Funktionen aus dem Part-Modul, um die Linie zu erstellen, und aus dem Gui Modul (FreeCADGui), um auf die 3D Ansicht zuzugreifen. Außerdem benötigen wir den kompletten Inhalt der Coin Bibliothek, damit wir alle Coin Objekte wie SoMouseButtonEvent, etc. direkt verwenden können.

class line:

Hier definieren wir unsere Hauptklasse. Warum verwenden wir eine Klasse und keine Funktion? Der Grund dafür ist, dass wir unser Werkzeug "am Leben" halten müssen, während wir darauf warten, dass der Benutzer auf den Bildschirm klickt. Eine Funktion endet, wenn ihre Aufgabe erledigt ist, aber ein Objekt (eine Klasse definiert ein Objekt) bleibt am Leben, bis es zerstört wird.

"""This class will create a line after the user clicked 2 points on the screen"""

In Python kann jede Klasse oder Funktion einen Dokumentationszeichenkette (docstring) haben. Dies ist besonders in FreeCAD nützlich, denn wenn du diese Klasse im Interpreter aufrufst, wird der Beschreibungszeichenkette als Tooltip angezeigt.

def __init__(self):

Python Klassen können immer eine __init__-Funktion enthalten, die beim Aufruf der Klasse zur Erzeugung eines Objekts ausgeführt wird. Wir werden hier also alles ablegen, was sich ereignen soll, wenn unser Linienwerkzeug beginnt.

self.view = FreeCADGui.ActiveDocument.ActiveView

In einer Klasse möchte man normalerweise self. vor einem Variablennamen anhängen, damit sie für alle Funktionen innerhalb und außerhalb dieser Klasse leicht zugänglich ist. Hier werden wir self.view verwenden, um auf die aktive 3D Ansicht zuzugreifen und sie zu verändern.

self.stack = []

Hier erstellen wir eine leere Liste, die die von der Getpoint Funktion gesendeten 3D Punkte enthält.

self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getpoint)

Das ist der wichtige Teil: Da es sich eigentlich um eine coin3D Szene handelt, verwendet FreeCAD einen Coin Rückruf Mechanismus, der es erlaubt, eine Funktion jedes Mal aufzurufen, wenn ein bestimmtes Szene Ereignis eintritt. In unserem Fall erstellen wir einen Rückruf für SoMouseButtonEvent Ereignisse, und wir binden ihn an die getpoint Funktion. Nun wird jedes Mal, wenn eine Maustaste gedrückt oder losgelassen wird, die getpoint Funktion ausgeführt.

Beachte, dass es auch eine Alternative zu addEventCallbackPivy() namens addEventCallback() gibt, welche die Verwendung von pivy überflüssig macht. Aber da pivy ein sehr effizienter und natürlicher Weg ist, um auf jeden Teil der coin Szene zuzugreifen, ist es viel besser, es so oft wie möglich zu verwenden!

def getpoint(self,event_cb):

Nun definieren wir die Getpoint Funktion, die beim Drücken einer Maustaste in einer 3D Ansicht ausgeführt wird. Diese Funktion erhält ein Argument, das wir event_cb aufrufen. Von diesem Ereignisrückruf aus können wir auf das Ereignisobjekt zugreifen, das verschiedene Informationen enthält (Mode Info Hier).

if event.getState() == SoMouseButtonEvent.DOWN:

The getpoint function will be called when a mouse button is pressed or released. But we want to pick a 3D point only when pressed (otherwise we would get two 3D points very close to each other). So we must check for that here.

pos = event.getPosition()

Here we get the screen coordinates of the mouse cursor

point = self.view.getPoint(pos[0],pos[1])

This function gives us a FreeCAD vector (x,y,z) containing the 3D point that lies on the focal plane, just under our mouse cursor. If you are in camera view, imagine a ray coming from the camera, passing through the mouse cursor, and hitting the focal plane. There is our 3D point. If we are in orthogonal view, the ray is parallel to the view direction.

self.stack.append(point)

We add our new point to the stack

if len(self.stack) == 2:

Do we have enough points already? if yes, then let's draw the line!

l = Part.Line(self.stack[0],self.stack[1])

Here we use the function Line() from the Part Module that creates a line from two FreeCAD vectors. Everything we create and modify inside the Part module, stays in the Part module. So, until now, we created a Line Part. It is not bound to any object of our active document, so nothing appears on the screen.

shape = l.toShape()

The FreeCAD document can only accept shapes from the Part module. Shapes are the most generic type of the Part module. So, we must convert our line to a shape before adding it to the document.

Part.show(shape)

The Part module has a very handy show() function that creates a new object in the document and binds a shape to it. We could also have created a new object in the document first, then bound the shape to it manually.

self.view.removeEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.callback)

Since we are done with our line, let's remove the callback mechanism, that consumes precious CPU cycles.

Testing & Using the script

Now, let's save our script to some place where the FreeCAD python interpreter will find it. When importing modules, the interpreter will look in the following places: the python installation paths, the FreeCAD bin directory, and all FreeCAD modules directories. So, the best solution is to create a new directory in one of the FreeCAD Mod directories, and to save our script in it. For example, let's make a "MyScripts" directory, and save our script as "exercise.py".

Now, everything is ready, let's start FreeCAD, create a new document, and, in the python interpreter, issue:

import exercise

If no error message appear, that means our exercise script has been loaded. We can now check its contents with:

dir(exercise)

The command dir() is a built-in python command that lists the contents of a module. We can see that our line() class is there, waiting for us. Now let's test it:

exercise.line()

Then, click two times in the 3D view, and bingo, here is our line! To do it again, just type exercise.line() again, and again, and again... Feels great, no?

Registering the script in the FreeCAD interface

Now, for our new line tool to be really cool, it should have a button on the interface, so we don't need to type all that stuff everytime. The easiest way is to transform our new MyScripts directory into a full FreeCAD workbench. It is easy, all that is needed is to put a file called InitGui.py inside your MyScripts directory. The InitGui.py will contain the instructions to create a new workbench, and add our new tool to it. Besides that we will also need to transform a bit our exercise code, so the line() tool is recognized as an official FreeCAD command. Let's start by making an InitGui.py file, and write the following code in it:

class MyWorkbench (Workbench): 
   MenuText = "MyScripts"
   def Initialize(self):
       import exercise
       commandslist = ["line"]
       self.appendToolbar("My Scripts",commandslist)
Gui.addWorkbench(MyWorkbench())

By now, you should already understand the above script by yourself, I think: We create a new class that we call MyWorkbench, we give it a title (MenuText), and we define an Initialize() function that will be executed when the workbench is loaded into FreeCAD. In that function, we load in the contents of our exercise file, and append the FreeCAD commands found inside to a command list. Then, we make a toolbar called "My Scripts" and we assign our commands list to it. Currently, of course, we have only one tool, so our command list contains only one element. Then, once our workbench is ready, we add it to the main interface.

But this still won't work, because a FreeCAD command must be formatted in a certain way to work. So we will need to transform a bit our line() tool. Our new exercise.py script will now look like this:

import FreeCADGui, Part
from pivy.coin import *
class line:
    """This class will create a line after the user clicked 2 points on the screen"""

    def Activated(self):
        self.view = FreeCADGui.ActiveDocument.ActiveView
        self.stack = []
        self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getpoint) 
    def getpoint(self,event_cb):
        event = event_cb.getEvent()
        if event.getState() == SoMouseButtonEvent.DOWN:
            pos = event.getPosition()
            point = self.view.getPoint(pos[0],pos[1])
            self.stack.append(point)
            if len(self.stack) == 2:
                l = Part.Line(self.stack[0],self.stack[1])
                shape = l.toShape()
                Part.show(shape)
                self.view.removeEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.callback)
    def GetResources(self): 
        return {'Pixmap' : 'path_to_an_icon/line_icon.png', 'MenuText': 'Line', 'ToolTip': 'Creates a line by clicking 2 points on the screen'} 
FreeCADGui.addCommand('line', line())

What we did here is transform our __init__() function into an Activated() function, because when FreeCAD commands are run, they automatically execute the Activated() function. We also added a GetResources() function, that informs FreeCAD where it can find an icon for the tool, and what will be the name and tooltip of our tool. Any jpg, png or svg image will work as an icon, it can be any size, but it is best to use a size that is close to the final aspect, like 16x16, 24x24 or 32x32. Then, we add the line() class as an official FreeCAD command with the addCommand() method.

Das war's, jetzt müssen wir nur noch FreeCAD neu starten und schon haben wir einen schönen neuen Arbeitsbereich mit unserem brandneuen Linienwerkzeug!

Also willst du mehr?

Wenn Dir diese Übung gefallen hat, warum versuchst Du nicht, dieses kleine Werkzeug zu verbessern? Es gibt viele Dinge, die man tun kann, wie zum Beispiel

  • Benutzer Rückmeldungen hinzufügen: Bis jetzt haben wir ein sehr nacktes Tool gemacht, der Benutzer könnte etwas verloren sein, wenn er es benutzt. Wir könnten also eine Rückmeldung hinzufügen, das ihm sagt, was er als nächstes tun soll. Zum Beispiel könntest Du Meldungen an die FreeCAD Konsole ausgeben. Schaue dir das FreeCAD.Console Modul an
  • Füge die Möglichkeit hinzu, die Koordinaten der 3D Punkte manuell einzugeben. Schaue dir die Python input() Funktion an, zum Beispiel
  • Füge die Möglichkeit hinzu, mehr als 2 Punkte hinzuzufügen
  • Füge Ereignisse für andere Dinge hinzu: Jetzt überprüfen wir nur noch, ob es Ereignisse für die Maustaste gibt, was wäre, wenn wir auch etwas tun würden, wenn die Maus bewegt wird, wie z.B. die aktuellen Koordinaten anzeigen?
  • Gib dem erstellten Objekt einen Namen

Zögere nicht, deine Fragen oder Ideen ins Forum zu schreiben!