Installation der kompilierten Binärdateien
Das auf dieser CD befindliche Verzeichnis picana/
kann ohne weitere Änderungen in jedes beliebige Verzeichnis auf dem
Zielrechner kopiert werden. In dem Zielverzeichnis picana/
sollten sich nach dem Kopiervorgang folgende Unterverzeichnisse befinden:
bin/ - MS-DOS/Windows Batch-Dateien zum Starten
von Picana
etc/ - Templates für
Beispielkonfigurationen und Durchläufe
data/ - Beispielbilder zum Clustern
lib/ - Alle benötigten Java-Bibliotheken
log/ - Verzeichnis, das zum Loggen benutzt
werden kann
Die Anwendung wurde bisher unter dem Betriebssystem Microsoft
Windows XP Professional getestet. Für die Ausführung unter
Linux sind die MS-DOS/Windows Batch-Dateien im bin/ -Verzeichnis
in entsprechende Shell-Skripte umzuwandeln.
Installation der Quelldateien und Kompilierung
Voraussetzungen:
Das auf der CD befindliche Verzeichnis picsrc/
kann ohne weitere Änderungen in jedes beliebige Verzeichnis auf dem
Zielrechner kopiert werden.
In dem Verzeichnis befinden sich folgende Unterverzeichnisse:
src/ - Quelldateien für Java, C++, LaTeX
und HTML. Die Java-Klassendateien unter java/ sind in
Paketen organisiert. Das Verzeichnis html/ enthält
diese Anleitung. Die Verzeichnisse cpp/ und latex/
sind für spätere Erweiterungen reserviert und werden zur Zeit
nicht verwendet.
res/ - Ressourcen, die unabhängig von der
verwendeten Programmiersprache sind. Darunter befinden sich
Velocity-Templates, Batch-Dateien und Beispielbilder im PNG-Format.
thirdparty/ - Bibliotheken von Drittanbietern.
Das Verzeichnis picsrc/ enthält eine build.xml -Datei,
die alle für den Vorgang der Kompilierung nötigen
Informationen enthält. Sofern das Build-Werkzeug Ant erfolgreich
installiert wurde, lässt sich die Kompilierung einfach durch Aufruf
von ant build.xml starten. In der integrierten
Entwicklungsumgebung NetBeans ist Ant bereits integriert. Der Vorgang
wird in der IDE nach dem Mounten des Verzeichnisses picsrc/
durch Anklicken der Datei build.xml gestartet.
Es werden die Unterverzeichnisse dist/ und build/
erzeugt. Das Verzeichnis build/ enthält nur
Zwischenergebnisse und wird nicht weiter benötigt. Das Verzeichnis dist/
entspricht dem Verzeichnis picana/ auf der CD und
enthält die vollständige Anwendung Picana mit allen für
die Ausführung benötigten Dateien.
Mit Hilfe des Werkzeugs Doxygen lässt sich aus den
Quelldateien eine Dokumentation im Unterverzeichnis apidoc/
erzeugen. Doxygen wird als Ersatz für javadoc
verwendet, da sich bei späterer Einbindung von C++-Code die
Dokumentation insgesamt einheitlicher gestalten lässt. Zur Zeit
wird jedoch kein C++-Code verwendet.
Schnellstart
Im Verzeichnis etc/ der Anwendung Picana befindet
sich die Datei diplom.vm . Sie realisiert Durchläufe
von Picana mit unterschiedlichen Clusteringverfahren im
Anwendungsbereich der Erosionserkennung auf Luftaufnahmen. Mit Hilfe
dieser Datei wurden auch die Clusterungen in der Diplomarbeit erzeugt.
Für ein tieferes Verständnis der Datei werden Kenntnisse
über die Struktur von Ant-Build-Dateien benötigt. Darüber
hinaus ist ein Verständnis der Velocity-Bibliothek nötig.
Für einfache Durchläufe sollte das Studium der Beispieldatei
jedoch bereits genügen. Die Daten über das zu clusternde Bild
werden zu Beginn der Datei über sog. Properties bestimmt.
Die Eigenschaft source gibt den Namen der
Bilddatei im Verzeichnis data/ an. In dem Datenverzeichnis
befinden sich bereits einige Beispieldateien, eigene Dateien sollten in
das Verzeichnis kopiert werden. Über die Eigenschaft description
lässt sich die Datei weiter beschreiben. Die Beschreibung erscheint
später in den für jede Clusterung erzeugten
HTML-Ergebnis-Dateien. Zudem ist es nötig, über width
und height die Anzahl der Pixel in Breite und Höhe des
Bildes zu spezifizieren.
Alle weiteren (eher variablen) Properties lassen sich nun beim
Aufruf von Picana über die Kommandozeile angeben. Auf diese Weise
ist es möglich, für ein Bild Durchläufe mit
unterschiedlichen Parameter zu starten. Für den Aufruf der
Batchdatei picanaAnt ist ein MS-DOS-Fenster zu öffnen
und in das Verzeichnis bin/ der Anwendung zu wechseln.
Die Pfade und Umgebungsvariablen m?ssen so gesetzt sein, dass sich Java
starten l?sst (wird bei der Windows-Installation eigentlich automatisch
bei der Installation des JRE/SDK erledigt). Das Format der Kommandozeile ist
picanaAnt template -Dproperty=X ... Clusteringverfahren
Soll z. B. ein Durchlauf mit FastAML gestartet werden, so
lautet der Aufruf
picanaAnt ..\etc\diplom -Dclusters=24 -Drho=0.25 FastAML
Beispiele für die Kommandozeilen anderer Verfahren finden
sich in der Datei realrun.bat im bin/ -Verzeichnis.
Ein Durchlauf erzeugt im data/ -Verzeichnis
verschiedene Unterverzeichnisse in Abhängigkeit vom gewählten
Verfahren, der gewählten Clusterzahl und den Parametern. Die so
erzeugte Verzeichnishierarchie lässt sich dann z. B. auf einen
Web-Server kopieren. Die Ergebnisse eines Durchlaufs befinden sich auf
der untersten Ebene der Hierarchie in der Datei result.html .
Diese lässt sich mit einem Web-Browser der neueren Generation
anzeigen.
Grundlagen
Für ein tieferes Verständnis der Datei diplom.vm
werden Kenntnisse über die Struktur von Ant-Build-Dateien
benötigt. Der Quellcode der Anwendung Picana ist in mehrere Pakete
aufgeteilt, die unterschiedliche Bereiche des in der Diplomarbeit
beschriebenen Clustering-Prozesses abdecken. Die einzelnen Schritte des
Clustering-Prozesses entsprechen dabei sog. Tasks. Ein Task
verfügt über Methoden für die Initialisierung und den
Start und gleicht somit sehr stark herkömmlichen Java-Applets. Alle
Tasks der Anwendung sind von der Oberklasse Task
abgeleitet. Für die Integration in Ant wurde ein neuer Ant-Task
entwickelt, der den Aufruf aller von Task abgeleiteten
Tasks in Ant-Build-Dateien erlaubt. Die Struktur für den Aufruf
eines solchen Tasks gestaltet sich wie folgt:
<picana task="clusterer.FastAML"> <parameter name="training_set" value="${basedir}/../data/${source}.arff"/> <parameter name="model" value="${dstpath}/${source}.model"/> <parameter name="num_clusters" value="${clusters}"/> <parameter name="rho" value="${rho}"/> <parameter name="pruning" value="${pruning}"/> <parameter name="statistics" value="${dstpath}/${source}.stat"/> </picana>
Der Name des Tasks setzt sich aus dem Paketnamen (ohne de.picana )
und dem Namen der Klassendatei zusammen (für die Namen und
Parameter siehe die Beschreibung weiter unten). Danach lassen sich
verschiedene Parameter mit Namen und Wert übergeben. Die Namen und
Werte werden alle als Strings behandelt, die Interpretation des Typs
durch die Anwendung ergibt sich aus dem Zusammenhang. Für die
Spezifikation von Dateinamen oder auch anderen Parametern lassen sich
wie in dem Beispiel gezeigt Ant-Properties einsetzen, die später z.
B. über die Kommandozeile näher spezifiziert werden. Die Werte
der Parameter können natürlich auch direkt angegeben werden.
Einige wenige Tasks benötigen nicht nur einzelne
Parameter, sondern ganze Sammlungen von Parametern. Eine solche Sammlung
wird durch den Tag paramset eingeschlossen. Eine Sammlung
hat ähnlich wie ein Parameter einen Namen, jedoch keinen Wert
(d.h. der Wert ist die Sammlung nachfolgend spezifizierter Parameter).
Mit Hilfe von Sammlungen von Parametern lassen sich hierarchisch
organisierte Parameterstrukturen an Tasks übergeben. Für ein
Beispiel siehe den Aufruf des Tasks converter.Stats2File
in der Datei diplom.vm .
Durch die Batch-Datei picanaAnt werden zwei
Schritte realisiert. Zuerst wird die Datei diplom.vm
mittels dem Makro-Prozessor Velocity in die eigentliche Build-Datei
für Ant umgewandelt. Die Datei ist in diesem Sinn ein
Velocity-Template für eine Ant-Build-Datei. Danach wird Ant auf der
umgewandelten Build-Datei aufgerufen. Im Template können
können daher auch alle Velocity-Befehle wie #set oder #foreach
eingesetzt werden. Die Konstruktion des Zielpfades für einen
Durchlauf ist in diesem Zusammenhang nicht über Properties, sondern
über Variablen realisiert worden, denen über #set
dynamisch ein Wert zugewiesen wird. Der Name des umzuwandelnden
Templates ist dabei ohne die Endung .vm anzugeben.
Es bietet sich an, einzelne Durchläufe in Form von
Ant-Targets zu organisieren. Ein Target umfasst dabei mehrere Aufrufe
von Tasks oder in Ant eingebauten Befehlen (z. B. zum Erzeugen von
Verzeichnissen, Löschen von Dateien, usw.). Die Tasks und Befehle
innerhalb eines Targets werden nacheinander ausgeführt. Ein Target
kann von anderen Targets abhängen, die gegebenenfalls automatisch
vorher ausgeführt werden.
Logging
In den Templates f?r die Ant-Build-Dateien lassen sich ?ber Properties
(gleichzeitig) zwei unterschiedliche Ziele f?r Log-Ausgaben angeben: die Konsole
und eine Datei. F?r das Logging zur Konsole lassen sich ?ber die Eigenschaft
logger.console.level unterschiedliche Log-Level setzen (die
Schl?sselw?rter sind im value -Attribut durch Komma getrennt
anzugeben und addieren sich in ihrer Wirkung):
info - grundlegende Informationen ?ber die Aktivit?ten eines Tasks.
verbose - ausf?hrliche Informationen ?ber die Aktivit?ten eines Tasks.
warn - Warnungen, die nicht zum Abbruch des Programms f?hren, aber anzeigen,
dass ein Problem aufgetreten ist.
error - Fehlermeldung, die zum Abbruch des Programms f?hrt.
debug - Ausgaben f?r Entwickler.
default - zur Vereinfachung ist die Kombination "info,warn,error" unter diesem
Schl?ssel zusammengefasst.
all - zur Vereinfachung ist die Kombination aller Schl?ssel unter diesem
Schl?ssel zusammengefasst.
Der Log-Level f?r Ausgaben in eine Datei l?sst sich ?ber die Eigenschaft
logger.file.level ebenso setzen. Zus?tzlich muss mittels logger.file.name
der Pfad zu der Log-Datei angegeben werden. F?r ein Beispiel siehe die Datei diplom.vm .
Tasks der Anwendung Picana
Im Folgenden werden die verfügbaren Pakete, Tasks und
ihre Parameter vorgestellt.
converter
Alle im Paket converter zusammengefassten Tasks
wandeln eine Datei von einem Format in ein anderes um. So müssen z.
B. PNG-Bilddateien über den Task PNG2ARFF erst in das
ARFF-Format umgewandelt werden, um von anderen Tasks verarbeitet werden
zu können.
PNG2ARFF
Wandelt eine Bilddatei im PNG-Format in eine Textdatei im
ARFF-Format um. Dateien im ARFF-Format werden für andere Tasks
benötigt.
Parameter:
in - Pfad und Name der Bilddatei im PNG-Format.
out - Pfad und Name der Ausgabedatei im
ARFF-Format.
upperLeftX - X-Koordinate der oberen linken
Ecke des Bildausschnittes, der in die ARFF-Datei eingehen soll.
upperLeftY - Y-Koordinate der oberen linken
Ecke des Bildausschnittes, der in die ARFF-Datei eingehen soll.
width - Breite des PNG-Bildes.
height - Höhe des PNG-Bildes.
ARFF2PNG
Wandelt eine Textdatei im ARFF-Format in eine Bilddatei im
PNG-Format um.
Parameter:
in - Pfad und Name der Textdatei im ARFF-Format.
out - Pfad und Name der Bilddatei im PNG-Format.
width - Breite des PNG-Bildes.
height - Höhe des PNG-Bildes.
SVG2PNG
Wandelt eine Datei im SVG-Format in das PNG-Format um.
Parameter:
src - Pfad und Name der Quelldatei im
SVG-Format.
dest - Pfad und Name der Zieldatei im
PNG-Format.
FreqConverter
Transformiert die Häufigkeiten der Instanzen aus einer
ARFF-Datei und schreibt die Instanzen zufällig mit dieser
Häufigkeit in eine neue ARFF-Datei.
Parameter:
src - Pfad und Name der zu transformierenden
Textdatei im ARFF-Format.
dest - Pfad und Name der Zieldatei im
ARFF-Format.
transformation - Art der Umwandlung.
picana : Umwandlung gemäß der von
Zerbst/Tschiersch entwickelten Formel.
unique : alle Häufigkeiten werden auf 1
gesetzt.
Stats2File
Während einer Clusterung werden Statistiken, evtl. ein
Modell und Clusterzentren erzeugt. Der Task wandelt diese Daten
benutzerdefiniert anhand eines Velocity-Templates in eine durch das
Template definierte Textdatei um. Auf diese Weise lassen sich etwa die
SVG-Dateien und HTML-Dateien der Beispielanwendung erzeugen. Welche
Variablen/Methoden im Velocity-Context zur Verfügung stehen, soll
hier nicht weiter dargestellt werden. Für nähere Informationen
sei auf die beiden Beispiel-Templates svg.vm und html.vm
im etc/ -Verzeichnis verwiesen.
Parameter:
statistics - Pfad und Name der Datei, welche
die zu verwendenden Statistiken enthält.
model - Pfad und Name der Modell-Datei
(optional).
centroids - Pfad und Name der Datei, welche die
Clusterzentren enthält.
template - Template-Datei für Velocity.
Über den Kontext kann auf die Statistiken, die Modell-Daten (falls
vorhanden) und die Clusterzentren zugegriffen werden.
out - Pfad und Name der Zieldatei im
Text-Format.
context - Bezeichnung für ein paramset ,
das eine Liste von Name/Wert-Paaren enthält, die in den
Velocity-Context eingefügt werden und bei der Umwandlung zur
Verfügung stehen sollen.
generator
Die Tasks des Pakets generator erzeugen
automatisch Instanzen anhand verschiedener
Wahrscheinlichkeits-Verteilungen.
Random2ARFF
Erzeugt eine ARFF-Datei mit zufälligen Instanzen. Die
Werte der Attribute können gleichverteilt gezogen werden, aus
N(0.5,sigma) oder aus einer Mischung von N(0,sigma) und N(1,sigma).
Parameter:
out - Pfad und Name der Zieldatei im
ARFF-Format.
relation - Name der Relation.
num_instances - Anzahl der zufällig zu
erzeugenden Instanzen.
normal - Sollen die Attributwerte
gleichverteilt (false ) oder normalverteilt (true )
erzeugt werden?
invert - Falls die Attributwerte normalverteilt
werden, sollen sie aus N(0.5,sigma) (false ) oder aus einer
Mischung von N(0,sigma) und N(1,sigma) (true ) stammen?
attributes - Bezeichnung für ein paramset ,
das weitere paramset -Tags enthält, die jeweils
Angaben (Parameter) zu den zu verwendenden Attributen enthalten. Der
Name der jeweiligen Sammlung von Parametern für ein Attribut
entspricht dem Namen des Attributes. Danach folgen Angaben zum Attribut
im Name/Wert-Format:
min : untere Grenze des Intervalls, aus dem die
Attributwerte erzeugt werden sollen.
max : obere Grenze des Intervalls, aus dem die
Attributwerte erzeugt werden sollen.
sigma : Standardabweichung für das Attribut.
Beispiel:
<picana task="generator.Random2ARFF"> <parameter name="out" value="random.arff"/> <parameter name="relation" value="colour"/> <parameter name="num_instances" value="1000"/> <parameter name="normal" value="true"/> <parameter name="invert" value="false"/> <paramset name="attributes"> <paramset name="red"> <parameter name="min" value="0.0"/> <parameter name="max" value="1.0"/> <parameter name="sigma" value="0.1"/> </paramset> <paramset name="green"> <parameter name="min" value="0.0"/> <parameter name="max" value="1.0"/> <parameter name="sigma" value="0.1"/> </paramset> <paramset name="blue"> <parameter name="min" value="0.0"/> <parameter name="max" value="1.0"/> <parameter name="sigma" value="0.1"/> </paramset> </paramset> </picana>
clusterer
Das Paket clusterer beinhaltet alle Tasks, die
Instanzen aus einer Datei im ARFF-Format in eine vorgegebene Anzahl von
Kategorien einteilen.
AML
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem AML-Algorithmus.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
rho - Parameter rho des AML-Algorithmus.
FastAML
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem FastAML-Algorithmus.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
rho - Parameter rho des FastAML-Algorithmus.
pruning - Methode für das Pruning
gemäß Diplomarbeit: rand , lexi , comp ,mid .
EM
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem EM-Algorithmus.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
max_iterations - Max. Anz. der Iterationen des
EM-Algorithmus.
SimpleKMeans
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem k-Mittelwert-Verfahren.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
SON
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit einer selbstorganisierenden Karte.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
cycles - Anz. der Lernzyklen für die
selbstorganisierende Karte.
radius - Radius (euklidischer Abstand) um die
Trainings-Instanzen, aus dem die initialen Clusterzentren der Karte
gewählt werden sollen.
preset - Bestimmt die Parameter und die
Arbeitsweise der selbstorganisierenden Karte wie folgt:
WTAN : verwendet ein Alles-dem-Gewinner-Netz
SOM_SQUARE : herkömmliche Self-Organizing
Map, rechteckige Topologie
SOM_HEXA : herkömmliche Self-Organizing Map,
hexagonale Topologie
QSOM_SQUARE : QuickSOM (siehe Zerbst
2001, Tschiersch 2002), rechteckige Topologie
QSOM_HEXA : QuickSOM (siehe Zerbst
2001, Tschiersch 2002), hexagonale Topologie
classifier
Das Paket classifier beinhaltet Tasks, die
Instanzen aus einer Datei im ARFF-Format anhand eines zuvor erstellten
Modells klassifizieren. Die klassifizierten Instanzen werden durch die
Zentren der Cluster ersetzt, denen sie angehören und in einer neuen
Datei im ARFF-Format gespeichert.
Centroid
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
rho - Parameter rho des AML-Algorithmus.
FastAML
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem FastAML-Algorithmus.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
rho - Parameter rho des FastAML-Algorithmus.
pruning - Methode für das Pruning
gemäß Diplomarbeit: rand , lexi , comp ,mid .
EM
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem EM-Algorithmus.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
max_iterations - Max. Anz. der Iterationen des
EM-Algorithmus.
SimpleKMeans
Clustert die Instanzen aus der angegebenen Datei im
ARFF-Format mit dem k-Mittelwert-Verfahren.
Parameter:
training_set - Pfad und Name der zu clusternden
Instanzendatei im ARFF-Format.
model - Pfad und Name der Datei, die das durch
den Clustering-Schritt gebildete Modell enthält.
statistics - Pfad und Name der Datei, die
statistische Informationen über die Clusterung enthält.
|