Programmieren von Gimp-Plugins mittels des Koblenzer Plugin-Frameworks

Transkript

1 Programmieren von Gimp-Plugins mittels des Koblenzer Plugin-Frameworks Patrick Sturm, Frank Schmitt 9. November Einleitung Das Koblenzer Plugin-Framework stellt ein generelles Plugin-Konzept dar. Plugins sind kleine Programme, die in Grafikprogramme eingestöpselt werden können, und gemäß ihrem Programm Eingabedaten (Parameter und Eingabebilder) in Ausgabedaten umwandeln. Das Koblenzer Plugin-Framework lässt sich an beliebige Grafikprogramme, die selbst eine Pluginschnittstelle bereitstellen, anpassen. Bisher ist das Koblenzer Plugin-Framework nur an das freie Grafikprogramm GIMP angepasst worden. 2 Installationshinweise Um das Koblenzer Plugin-Framework zu installieren führen Sie folgende Schritte durch: Laden Sie die Datei herunter und entpacken Sie sie. Übersetzen Sie das Framework. Unter Linux: Stellen Sie sicher, das Gimp 2.x und die Gimp- Entwicklerpakete (gimp-devel) installiert sind. Gehen Sie in den Ordner plugin root/plugin-adapter-gimp und geben sie make ein. Wenn keine Fehler auftreten geben Sie dann make install ein. Unter Windows: Installieren Sie gtk von und dann Gimp 2 von Öffnen Sie dann die Datei plugin root/lecture plugin8.sln in Visual Studio 2005 (erhältlich im Rechenzentrum oder als Express Version bei Microsoft) und erstellen Sie das Projekt. Starten Sie Gimp und fügen Sie das Verzeichnis plugin root/plugin-adapter-gimp/release/ in Einstellungen, Verzeichnisse, Plugins hinzu. Abbildung 1 zeigt den Verzeichnisbaum wie er nach einer erfolgreichen Installation des Plugin-Frameworks aussieht. Das Unterverzeichnis win32libs2 ist dabei nur für die Plugin-Entwicklung unter Windows notwendig. Es enthält Portierungen von einigen Linux-Entwicklungsbibliotheken wie GTK und GLIB auf Windows. 3 Hinzufügen eigener Plugins Eigene Plugins müssen im Verzeichnis plugin root/plugin-pool/local plugins abgespeichert werden. 1

2 Abbildung 1: Verzeichnisbaum des Plugin-Frameworks Linuxnutzer müssen jetzt in das Verzeichnis plugin-root/plugin-adapter-gimp wechseln make und anschließend bei fehlerfreien Übersetzung make install aufrufen, um das neue Plugin in Gimp zu integrieren. Windowsnutzer müssen die Plugindatei zusätzlich im Projektbaum (Solution Explorer unter Visual C , siehe Abbildung 2) des Plugin-Frameworks unter lecture pluginpoollib/local plugins einfügen und das Gesamtprojekt neu übersetzen. 4 Programmieren von Plugins für GIMP mit dem Koblenzer Plugin-Framework Die Programmierung von Plugins im Koblenzer Plugin-Framework ist im Allgemeinen etwas umständlich. Um den Prozess der Plugin-Programmierung im Speziellen für die Bildverarbeitung zu vereinfachen, enthält das Koblenzer Plugin-Framework die vorgefertigte Klasse CPluginSimple. Diese stellt eine vereinfachte Programmierschnittstelle bereit. Jedes Plugin sollte von CPluginSimple abgeleitet werden. Im Folgenden wird die Plugin-Programmierung an einem Beispiel (Plugin ROI) erläutert. 4.1 Das Plugin ROI (Region-Of-Interest) Die Aufgabe des Plugins ROI besteht darin, aus einem Farbbild ein beliebiges rechteckiges Teilbild herauszuschneiden und auszugeben (siehe Abbildung 3). Das Teilbild, das aus dem Originalbild herausgeschnitten werden soll, wird durch ein Rechteck beschrieben. Das Rechteck ist dabei durch die Koordinate der linken oberen Ecke (minx, miny) und der rechten unteren Ecke (maxx, maxy) beschrieben. 2

3 Abbildung 2: Projektbaum des Plugin-Frameworks. Die Plugindatei plugin roi.cpp ist korrekt im Projektbaum eingetragen. Beide Koordinaten sollen vom Benutzer verändert werden dürfen. Basierend auf den Koordinaten bestimmt sich die Breite b bzw. die Höhe des Teilbildes durch b := maxx minx + 1 bzw. h := maxy miny Das Grundgerüst des Plugin ROI Jedes Plugin, das von der Klasse CPluginSimple erbt, hat einen einheitlichen Grundaufbau, welcher für das Plugin ROI im Folgenden dargestellt ist: #include <precompiled.h> // INSBESONDERE FÜR WINDOWS NUTZER EXTREM WICHTIG #include <plugin_simple.h> class CPluginROI: public CPluginSimple public: // Konstruktor mit einem Boolschen-Parameter CPluginROI(bool registration=false): CPluginSimple(...) CPlugin* Clone() return new CPluginROI(); protected: 3

4 Abbildung 3: ROI und Lenna void processimages() PluginROI(true); Der Name einer jeden Plugin-Klasse muss aus technischen Gründen mit CPlugin beginnen. Für jedes Plugin, so auch für das Plugin ROI, sind drei Funktionen zu implementieren: 1. Der Konstruktor dient der Initialisierung des Plugins. Hier wird u.a. festgelegt, unter welchem Namen das Plugin im GIMP-Menu erscheinen soll, über wie viele und welche Parameter das Plugin verfügt u.ä. 2. Die Funktion Clone erzeugt eine weitere Instanz des Plugins. 3. Die Funktion processimages enthält den Programmcode zur Verarbeitung der Eingabedaten (Bilder+Parameterwerte) zu Ausgabedaten Der Konstruktor Jeder Konstruktor hat einen Boolschen-Parameter mit dem Namen registration, dessen Standardparameter immer false sein muss. Als nächstes wird der Konstruktor der Basisklasse CPluginSimple aufgerufen. Diesem Konstruktor sind eine Reihe von wichtigen Informationen zu übergeben: CPluginROI(bool registration=false): CPluginSimple( registration, "ROI", // Plugin-Name "Das Plugin schneidet ein rechteckiges \ Teilbild aus einem Farbbild aus", // Hilfe "Patrick Sturm", // Autor 1, // Anzahl der Eingabebilder 1, // Anzahl der Ausgabebilder 4

5 pitrgb) // Nur RGB-Bilder werden verarbeitet. // Mögliche Werte sind: pitrgb, pitgray oder pitany Die meisten Plugins verfügen über eine Reihe von Eingabeparameter. Im Beispiel des Plugins ROI sind dies 4 Integerwerte minx, miny, maxx, maxy. (minx, miny) ist die linke obere Koordinaten und (maxx, maxy) ist die rechte untere Koordinate eine Rechtecks. Diese Parameter sind zunächst in der Klasse CPluginROI zu deklarieren: CPluginROI(bool registration=false): CPluginSimple(...)... private: int minx,miny,maxx,maxy; // Deklaration der beiden Koordinaten (minx,miny) // und (maxx,maxy)... Danach sind die Parameter GIMP mitzuteilen damit dieser sie automatisch im Dialog des Plugins anzeigen kann: CPluginROI(bool registration=false): CPluginSimple(...) addinteger("min-x", // Name des Parameters "X-Koordinate der linken oberen Ecke", // Beschreibung minx); // In welcher Variable soll der Wert gespeichert werden addinteger("min-y", // Name des Parameters "Y-Koordinate der linken oberen Ecke", // Beschreibung miny); // In welcher Variable soll der Wert gespeichert werden addinteger("max-x", // Name des Parameters "X-Koordinate der rechten unteren Ecke", // Beschreibung maxx); // In welcher Variable soll der Wert gespeichert werden addinteger("max-y", // Name des Parameters "Y-Koordinate der rechten unteren Ecke", // Beschreibung maxy); // In welcher Variable soll der Wert gespeichert werden Der vom Plugin-Framework automatisch generierte Dialog für das Plugin ROI sieht dann in GIMP wie folgt aus: 5

6 Änderungen an der Parametern im Dialog werden nach dem Betätigen des Set- Buttons an das Plugin weitergeleitet. 4.2 Weitere Initialisierungsfunktionen Es gibt neben der oben erwähnten addinteger-methode eine weitere Variante, die zudem die Angabe einer unteren und oberen Schranke erlaubt: void addinteger(const std::string& name, // Parametername int min, // untere Schranke des Parameters int max, // obere Schranke des Parameters int defaultval, // Defaultwert const std::string& description, // Beschreibungstext int& val // Referenz auf die eigentliche Parametervariable ) Analog zu addinteger existiert auch die Methoden adddouble jeweils mit und ohne Schranken. Die Funktion addboolean erlaubt die Verwendung eines Boolschen- Parameters: void addboolean(const std::string& name, // Parametername bool defaultval, // Defaultwert const std::string& description, // Beschreibungstext bool& val // Referenz auf die eigentliche Parametervariable ) In einigen Fällen möchte man eine Auswahl von Alternativen im Dialog in Form einer Combobox anzeigen. Dies wird durch die Funktion void addselection(const std::string& name, // Parametername const std::vector<std::string>& list, // Alternativen in einem Vektor const std::string& description, // Beschreibungstext int& val // Referenz auf die eigentliche Parametervariable ) realisiert. Die Variable list ist ein Vektor, der eine Reihe von Alternativen enthalten kann. Welche der Alternativen ausgewählt wird, wird in der Variablen val abgespeichert. Diese Variable ist ein Index und besagt, dass list[val] in der Combobox ausgewählt wurde. 4.3 Die Methode processimages des Plugins ROI In der Funktion processimages findet die eigentliche Arbeit des Plugins statt. Das Beispiel Plugin ROI muss zunächst das Eingabebild abfragen, ein Ausgabebild an- 6

7 legen und schließlich das angeforderte Teilbild aus dem Eingabebild in das Ausgabebild kopieren. Bevor die Implementation der Funktion erklärt wird, zunächst ein Exkurs zur Repräsentation von Bildern in C++: Repräsentation von Bildern in C++ Ein Farbbild I : [0, M 1] [0, N 1] [0, 255] 3 mit M Spalten und N Zeilen (M N) lässt sich in C++ durch das Array image repräsentieren: unsigned char image[m][n][3]; Dabei gibt image[x][y][0] die Rotkomponente, image[x][y][1] die Grünkomponente, und image[x][y][2] die Blaukomponente des Bildpunktes an der Stelle (x, y) im Bild an. Das Bild I wird also wie folgt im Array image kodiert: (image[x][y][0], image[x][y][1], image[x][y][2]) = I(x, y). Das Problem mit mehrdimensionalen Arrays in C++ ist, dass sie nur umständlich dynamisch erzeugt werden können. Normalerweise kennt man die Bildgröße eines Bildes erst zur Laufzeit des Programmes. Deshalb kann das Array nicht vorher schon statisch deklariert werden, sondern muss dynamisch erzeugt werden. Eine mögliche Realisation sieht wie folgt aus: unsigned char*** image; image=new unsigned char[m]; // Allokiere M Zeiger auf Spalten for (int spalte=0; spalte<m; spalte++) image[spalte]=new unsigned char[n]; // Allokiere N Zeiger auf // RGB-Werte für jede Spalte for (int zeile=0; zeile<n; zeile++) image[spalte][zeile]=new unsigned char[3]; // Erzeuge für jedes // Pixel einen RGB-Vektor Wie zu sehen ist diese Art der Bildrepräsentation in C++ recht kompliziert. Deshalb werden Bilder in der Regel in einem 1-dimensionales Array repräsentiert. Dabei geht man davon aus, dass jeder Pixel in einem Farbbild 3 Byte (1 Byte pro Farbkanal) benötigt. Es existieren M N verschiedene Pixel im Bild I. Daher muss ein 1-dimensionales Array, das das I enthalten kann über M N 3 Einträge verfügen: unsigned char* image = new unsigned char[m*n*3]; Sei folgendes Bild I : [0, M 1][ [0, N 1] [0, 255] 3 mit I(x, y) = (R x,y, G x,y, B x,y ) in graphischer Repräsentation gegeben: (R 0,0, G 0,0, B 0,0 ) (R 1,0, G 1,0, B 1,0 )... (R M 1,0, G M 1,0, B M 1,0 ) (R 0,1, G 0,1, B 0,1 ) (R 1,1, G 1,1, B 1,1 )... (R M 1,1, G M 1,1, B M 1,1 ) (R 0,N 1, G 0,N 1, B 0,N 1 ) (R 1,N 1, G 1,N 1, B 1,N 1 )... (R M 1,N 1, G M 1,N 1, B M 1,N 1 ) Die Farbwerte der Pixel des Bildes I werden nun Zeile für Zeile, von links oben nach rechts unten, in das Array image übertragen: R 0,0 G 0,0 B 0,0 R 1,0... R 0,1 G 0,1... R M 1,N 1 G M 1,N 1 B M 1,N 1 I: Dabei gilt folgender Zusammenhang zwischen dem Array image und dem Bild 1. image[0 + 3 (x + M y)] = R x,y 7

8 2. image[1 + 3 (x + M y)] = G x,y 3. image[2 + 3 (x + M y)] = B x,y 4.4 Die processimages des Plugins ROI Die erste Aufgabe des Plugins ROI besteht darin die Eingabeparameter auf Konsistenz zu überprüfen. In diese speziellen Beispiel muss gelten, dass minx maxx miny maxy gilt. Ist dies nicht der Fall, muss eine Fehlermeldung ausgegeben werden: void processimages() if (minx<=maxx && miny<=maxy)... else pluginoutput << "Parameter sind fasch gewählt..." << endl << "minx>maxx oder miny>maxy"; Zur Fehlerausgabe dient der in CPluginSimple definierter Stream pluginoutput. Nach der Kontrolle der Parameter, muss das Plugin sich Zugriff auf das Eingabebild bzw. auf die Eingabebilder beschaffen. Dies geschieht mittels der Funktion getinputimage: void processimages() if (minx<=maxx && miny<=maxy) unsigned int breite,hoehe; unsigned char* eingabe; if (getinputimage(0,&breite,&hoehe,&eingabe)==pitrgb)... else pluginoutput << "Falscher Bildtyp"; else pluginoutput << "Parameter sind fasch gewählt..." << endl << "minx>maxx oder miny>maxy"; Der erste Parameter der Funktion getinputimage gibt den Index des Eingabebildes an. 0 steht dabei für das erste Eingabebild, 1 für das zweite Eingabebild usw. Danach sind die Variablen (unsigned int), die die Breite und Höhe des Eingabebildes aufnehmen sollen, als Zeigerreferenz zu übergeben. Die eigentlichen Pixeldaten des Eingabebildes werden in einem 1-dimensionalen Array gespeichert. Da die dynamische Speicherverwaltung von der Funktion getinputimage selbst übernommen, wird ist hier nur eine Zeigerreferenz (eingabe) auf einen unsigned-char-zeiger zu übergeben. Nach dem Aufruf der Funktion zeigt eingabe auf die Pixeldaten des Eingabebildes. Die Funktion liefert als Rückgabewert, um welchen Bildtyp es sich beim Eingabebild handelt: pitrgb steht für RGB-Bild und pitgray für ein Grauwertbild. 8

9 Im nächsten Schritt ist das Ausgabebild zu erzeugen. Dies wird durch den Aufruf von createoutputimagergb erreicht. Die ersten beiden Parameter der Funktion geben die Breite und Höhe des Ausgabebildes an. Der dritte (optionale) Parameter ist ein Titel für das Ausgabefenster. Rückgabewert ist ein Zeiger auf ein 1-dimensionales Array, das die Ausgabebilddaten enthalten soll. void processimages() if (minx<=maxx && miny<=maxy) unsigned int breite,hoehe; unsigned char* eingabe; if (getinputimage(0,&breite,&hoehe,&eingabe)==pitrgb) unsigned int neuebreite = maxx-minx; unsigned int neuehoehe = maxy-miny; unsigned char* neuesbild = createoutputimagergb(neuebreite,neuehoehe,"roi");... else pluginoutput << "Falscher Bildtyp"; else pluginoutput << "Parameter sind fasch gewählt..." << endl << "minx>maxx oder miny>maxy"; Letztendlich sind nun die Pixel aus dem Eingabebild in das Ausgabebild zu kopieren: void processimages() if (minx<=maxx && miny<=maxy) unsigned int breite,hoehe; unsigned char* eingabe; if (getinputimage(0,&breite,&hoehe,&eingabe)==pitrgb) unsigned int neuebreite = maxx-minx+1; unsigned int neuehoehe = maxy-miny+1; unsigned char* neuesbild = createoutputimagergb(neuebreite,neuehoehe,"roi"); int x,y; for (y=miny; y<=maxy; ++y) for (x=minx; x<=maxx; ++x) int i = 3*(y*breite+x); int k = 3*((y-miny)*neueBreite+(x-minx)); neuesbild[k]=eingabe[i]; neuesbild[k+1]=eingabe[i+1]; neuesbild[k+2]=eingabe[i+2]; else pluginoutput << "Falscher Bildtyp"; 9

10 else pluginoutput << "Parameter sind fasch gewählt..." << endl << "minx>maxx oder miny>maxy"; 5 Das komplette Plugin ROI Der nachfolgende Quelltext ist in einer CPP-Datei im Verzeichnis plugin-pool abzuspeichern. Unter Visual C++ ist diese Datei, dann ins Projekt lecture pluginpoollib unter local plugins aufzunehmen und zu übersetzen. Unter Linux genügt es nach dem Speichern der Datei im Verzeichnis plugin-pool/local plugins den Befehl make oder gmake im Verzeichnis plugin-pool/plugin adpater gimp auszuführen. Nach dem Start von Gimp steht das Plugin dann unter MyBV im Menu zur Verfügung. #include <precompiled.h> // Diese Zeile muss am Anfang der Datei stehen!!! #include <plugin_simple.h> using namespace std; class CPluginExample: public CPluginSimple private: int minx,maxx,miny,maxy; public: CPluginExample(bool registration = false): CPluginSimple( registration, "ROI", // Plugin-Name "Das Plugin schneidet ein rechteckiges \ Teilbild aus einem Farbbild aus", // Hilfe "Patrick Sturm", // Autor 1, // Anzahl der Eingabebilder 1, // Anzahl der Ausgabebilder pitrgb) // Nur RGB-Bilder werden verarbeitet. // Mögliche Werte sind: pitrgb, pitgray oder pitany addinteger("min-x", // Name des Parameters "X-Koordinate der linken oberen Ecke", // Beschreibung minx); // In welcher Variable soll der Wert gespeichert werden addinteger("min-y", // Name des Parameters "Y-Koordinate der linken oberen Ecke", // Beschreibung miny); // In welcher Variable soll der Wert gespeichert werden addinteger("max-x", // Name des Parameters "X-Koordinate der rechten unteren Ecke", // Beschreibung maxx); // In welcher Variable soll der Wert gespeichert werden addinteger("max-y", // Name des Parameters "Y-Koordinate der rechten unteren Ecke", // Beschreibung 10

11 maxy); // In welcher Variable soll der Wert gespeichert werden CPlugin* Clone() return new CPluginExample(); protected: void processimages() if (minx<=maxx && miny<=maxy) unsigned int breite,hoehe; unsigned char* eingabe; if (getinputimage(0,&breite,&hoehe,&eingabe)==pitrgb) unsigned int neuebreite = maxx-minx+1; unsigned int neuehoehe = maxy-miny+1; unsigned char* neuesbild = createoutputimagergb(neuebreite,neuehoehe,"roi"); int x,y; for (y=miny; y<=maxy; ++y) for (x=minx; x<=maxx; ++x) int i = 3*(y*breite+x); int k = 3*((y-miny)*neueBreite+(x-minx)); neuesbild[k]=eingabe[i]; neuesbild[k+1]=eingabe[i+1]; neuesbild[k+2]=eingabe[i+2]; else pluginoutput << "Falscher Bildtyp"; else pluginoutput << "Parameter sind fasch gewaehlt..." << endl << "minx>maxx oder miny>maxy"; PluginExample(true); 11