th-koeln / wordcloudjs

WordCloudJS: Javascript framework for generating wordclouds. Includes Sample applications.

WordCloudJS

WordCloudJS ist ein JavaScript Framework zur Generierung von Wortwolken.

Inhaltsverzeichnis

1. Verwendung des Frameworks WordCloudJS in Webanwendungen

2. Installation der Beispielanwendung

3. API

Verwendung des Frameworks WordCloudJS in Webanwendungen

Die Einbindung der Dateien im Webprojekt erfolgt über den -Bereich des HTML:

<script src="WordcloudJS/webfontloader.js" type="text/javascript"></script>
<script src="WordcloudJS/WordcloudJS.js" type="text/javascript"></script>

Falls weitere Schriftarten verwendet werden sollen, müssen diese in einer zusätzlichen CSS-Datei definiert werden.

Installation der Beispielanwendung

Für die Installation der Beispielanwendung müssen alle Projektdateien, die sich im Repository befinden heruntergeladen werden. Zum Ausführen der Anwendung muss lediglich die index.html Datei ausgeführt werden. Hierfür ist ein Browser notwendig. Da die Anwendung bei der Entwicklung ausschließlich mit dem Google Chrome Browser getestet wurde, empfiehlt es sich auch für die Verwen-dung der Beispielanwendung den neuesten Google Chrome Browser zu verwen-den.

Die Anwendung selbst bietet zwei Modi zur Generierung von Wortwolken:

Wortwolken generieren aus Texten

In diesem Modus werden Wortwolken aus einem Text generiert, der in einem Ein-gabefeld eingefügt werden kann. Dabei werden die Stoppwörter aus dem Text erkannt und bei Generierung der Wortwolke nicht berücksichtigt. Alle anderen Wörter werden nach der Häufigkeit des Vorkommens im Text gewichtet, wodurch die Schriftgröße bestimmt wird.

Wortwolken generieren aus Wörtern

In diesem Modus wird eine Wortwolke aus einzelnen Wörtern generiert. Die Schriftgröße wird hierbei zufällig gewählt und es werden keine Stoppwörter gefil-tert. Die Wortwolke wird dabei aus allen Wörter gebildet, die sich in dem Einga-befeld eingefügt werden. Die Anzahl der Wörter ist in diesem Modus festgesetzt auf 600 Wörtern.

API

WordCloudJS.core

Die Kernklasse des WordCloudJS Frameworks. Erzeugt eine Instanz der Klasse WordCloudJS.word.

 

new WordcloudJS();

 

Ausgabe

object :WordCloudJS.core

 

loadFonts(webFontConfig, ready)

Lädt Schriftarten mithilfe des Web Font Loader.

 

Parameter	Typ	Beschreibung
webFontConfig	object	Konfigurationsobjekt des Web Font Loaders. (Siehe https://github.com/typekit/webfontloader)   Beispiel: WebFontConfig = {     custom: {         families: [             'My Font',             'My Other Font'         ],         urls: ['/fonts.css']     } };
ready	event	Wird ausgeführt, wenn alle Schriftarten geladen wurden.

 

getWordTableFromText(text, language)

Extrahiert Wörter aus einem Text mit Berücksichtigung der Sprache und der jeweiligen Stoppwörter der Sprache und ermittelt die Gewichtung der Wörter anhand der Anzahl der Vorkommnisse jedes Worts in Relation zur Gesamtanzahl der Wörter.

 

Parameter	Typ	Beschreibung
text	string	Eingabetext
language	string	Sprache des eingegebenen Texts. Es werden die Sprachen "german" und "english" unterstützt

 

Ausgabe

object   Gibt ein Objekt zurück mit einer Liste der extrahierten Wörter und ihrer Gewichtung   Beispiel: {    wordCount: 100,    minWordCount: 1,    maxWordCount: 16,    wordTable: {                  text: "Wortwolke",                  count: 14               } }

 

createWord(options)

Erzeugt eine Instanz der Klasse WordCloudJS.word. Für weitere Informationen siehe WordCloudJS.word.

 

Parameter	Typ	Beschreibung
options	object	Siehe WordCloudJS.word

 

Ausgabe

object :WordCloudJS.word

 

getSpiralPath(distPoints, distCoils, maxRadius, startX, startY)

Generiert einen Pfad einer Spirale.

 

Parameter	Typ	Beschreibung
distPoints	number	Abstand zwischen den Punkten in Pixeln
distCoils	number	Abstand zwischen den Windungen in Pixeln
maxRadius	number	Maximaler Radius in Pixeln. Wenn die Distanz eines Punktes zum Ursprung der Spirale überschreitet, werden keine weiteren Punkte mehr berechnet.
startX	number	X-Koordinate des Ursprungs der Spirale in Pixeln
startY	number	Y-Koordinate des Ursprungs der Spirale in Pixeln

 

Ausgabe

array   Gibt ein Array mit allen ermittelten Punkten beginnend vom Ursprung der Spirale zurück.   Beispiel: [ {x: 0, y: 0}, … ]

 

getRectSpiralPath(distPoints, distCoils, maxRadius, startX, startY)

Generiert einen Pfad einer rechteckigen Spirale.

 

Parameter	Typ	Beschreibung
distPoints	number	Abstand zwischen den Punkten in Pixeln
distCoils	number	Abstand zwischen den Windungen in Pixeln
maxRadius	number	Maximaler Radius in Pixeln. Wenn die Distanz eines Punktes zum Ursprung der Spirale überschreitet, werden keine weiteren Punkte mehr berechnet.
startX	number	X-Koordinate des Ursprungs der Spirale in Pixeln
startY	number	Y-Koordinate des Ursprungs der Spirale in Pixeln

 

Ausgabe

array   Gibt ein Array mit allen ermittelten Punkten beginnend vom Ursprung der Spirale zurück.   Beispiel: [ {x: 0, y: 0}, … ]

 

createScene(path)

Erzeugt eine Instanz der Klasse WordCloudJS.scene. Für weitere Informationen siehe WordCloudJS.scene.

 

Parameter	Typ	Beschreibung
path	object	Siehe WordCloudJS.scene

 

Ausgabe

object :WordCloudJS.scene

 

downloadSVG(svg)

Generiert einen Pfad einer rechteckigen Spirale.

 

Parameter	Typ	Beschreibung
svg	object	Javascript SVG Element

 

Ausgabe

.svg-Datei Löst einen Download des SVGs im Browser aus.

 

drawPath(ctx, path, drawLines, lineColor, drawPoints, pointColor, pointRadius)

Zeichnet einen Pfad auf einen Canvas. Diese Methode kann zum Debugging verwendet werden.

 

Parameter	Typ	Beschreibung
ctx	object	HTML Canvas-2D-Kontext
path	object	Generierter Pfad. Siehe Ausgabe von WordCloudJS.core.getSpiralPath
drawLines	boolean	Sollen die Punkte mit einer Linie verbunden werden?
lineColor	string	Farbe der Linien im Hex-Format
drawPoints	boolean	Sollen die Punkte gezeichnet werden?
pointColor	string	Farbe der Punkte im Hex-Format
pointRadius	number	Radius der Punkte

WordCloudJS.scene

Die Klasse WordCloudJS.scene beinhaltet Methoden zur Generierung und Zeichnung einer Szene. Erzeugt eine Instanz der Klasse WordCloudJS.scene.

 

new WordcloudJS.scene(path);

 

Parameter	Typ	Beschreibung
path	array	Siehe WordCloudJS.core.getSpiralPath

 

Attribut	Typ	Beschreibung
path	array	Siehe WordCloudJS.core.getSpiralPath
words	array	Eine Liste aller Wörter, die zur Szene hinzugefügt und bereits positioniert wurden.

 

Ausgabe

object :WordCloudJS.scene

 

addWord (word, position, minMargin)

Ermittelt eine Position für ein Wort und fügt es zur Szene hinzu.

 

Parameter	Typ	Beschreibung
word	object	Siehe WordCloudJS.word
position	string	Die horizontale Ausrichtung des Wortes zum Einfügepunkt: “center“, “left“, “right“
minMargin	number	Minimaler Abstand, der zwischen Worten bei der Positionierung eingehalten werden soll.

 

getSvg(id)

Zeichnet die Szene als SVG.

 

Parameter	Typ	Beschreibung
id	string	CSS-ID des SVG

 

Ausgabe

object   Liefert ein Javascript SVG-Element zurück.

 

getCanvas(id)

Zeichnet die Szene in ein Canvas und gibt den Canvas zurück.

 

Parameter	Typ	Beschreibung
id	string	CSS-ID des

 

Ausgabe

object   Liefert ein Javascript Canvas-Objekt zurück.

 

boundingVolumeCollision(boundingVolume1, boundingVolume2, minMargin)

Prüft zwei Bounding-Volumes auf Kollision.

Wird von WordCloudJS.scene.boundingVolumeHierarchyCollision verwendet.

 

Parameter	Typ	Beschreibung
boundingVolume1	object	Siehe WordcloudJS.boundingVolume
boundingVolume2	object	Siehe WordcloudJS.boundingVolume
minMargin	number	Minimaler Abstand zwischen den Bounding-Volumes

 

Ausgabe

boolean   Überschneiden sich die Bounding-Volumes?

 

boundingVolumeHierarchyCollision(boundingVolume1, boundingVolume2, minMargin, result)

Prüft zwei Bounding-Volume-Hierarchien rekursiv auf Kollision.

 

Parameter	Typ	Beschreibung
boundingVolume1	object	Siehe WordcloudJS.boundingVolume
boundingVolume2	object	Siehe WordcloudJS.boundingVolume
minMargin	number	Minimaler Abstand zwischen den Bounding-Volumes

 

Ausgabe

boolean   Überschneiden sich die Bounding-Volumes-Hierarchien?

WordCloudJS.word

Die Klasse WordCloudJS.word erzeugt ein Wort. Erzeugt eine Instanz von der Klasse WordCloudJS.word.

 

new WordcloudJS.word();

 

Parameter	Typ	Beschreibung
options	objekt	Optionen für das Generieren eines Worts.   Beispiel: options = {     text: 'text',     id: 'cssId',     class: 'cssClass',     boundingVolumeMinSize: 8,     style: {         'fontStyle': 'italic',         'fontVariant': 'normal',         'fontWeight': 'bold',         'fontSize': 14,         'fontFamily': 'Arial',         'fontColor': '#000000'     } }

 

Attribut	Typ	Beschreibung
text	string	Siehe WordCloudJS.core.getSpiralPath
id	string	CSS-ID des Worts, wenn das Wort als SVG auf eine Szene gezeichnet wird.
class	string	CSS-Klasse des Worts, wenn das Wort als SVG auf eine Szene gezeichnet wird.
boundingVolumeMinSize	number	Minimale Größe, die die Höhe oder Breite eines Bounding-Volumes der Bounding-Volume-Hierarchie des Worts haben soll.
style	object	Stil des Worts. Beispiel: Siehe Konstruktor.
position	object	Position des Worts.   Beispiel: {x:0, y:0}
width	number	Breite des Worts in Pixeln.
height	number	Höhe des Worts in Pixeln.
angle	number	Winkelgrad des Worts.
anchorOffsetX	number	Abstand zwischen Ankerpunkt, wenn das Wort auf ein Canvas gezeichnet wird, und erstem gefüllten Pixel in X-Richtung.
anchorOffsetY	number	Abstand zwischen Ankerpunkt, wenn das Wort auf ein Canvas gezeichnet wird, und erstem gefüllten Pixel in Y-Richtung.
rotationAnchorX	number	X-Koordinate des Rotationspunkts.
rotationAnchorY	number	Y-Koordinate des Rotationspunkts.
imageData	array	Pixeldaten des Worts im Uint8Array-Format
imageData32	array	Pixeldaten des Worts im Uint32Array-Format
boundingVolume	object	Siehe WordCloudJS.boundingVolume

 

Ausgabe

object :WordCloudJS.word

 

hasPixelsInBox (sx, sy, width, height)

Prüft, ob sich Pixel in einem bestimmten rechteckigen Bereich des Worts befinden.

 

Parameter	Typ	Beschreibung
sx	number	X-Koordinate in Pixeln
sy	number	Y-Koordinate in Pixeln
width	number	Breite in Pixeln
height	number	Höhe in Pixeln

 

Ausgabe

Boolean   Sind Pixel in diesem Bereich des Worts vorhanden?

 

move (x, y)

Verschiebt das Wort auf eine Position.

 

Parameter	Typ	Beschreibung
x	number	X-Koordinate in Pixeln
y	number	Y-Koordinate in Pixeln

 

getMinMax()

Ermittelt die minimalsten und maximalsten X- und Y-Werte des Worts.

 

Ausgabe

object   Beispiel: {     minX: 0,     maxX: 150,     minY: 0,     maxY: 100, }

 

drawWordOnCanvas (drawBoundingVolume)

Zeichnet das Wort und die Bounding-Volume-Hierarchie auf einen Canvas und gibt den Canvas zurück. Diese Methode kann zum Debugging verwendet werden.

 

Parameter	Typ	Beschreibung
drawBoundingVolume	object	Optionen für das zusätzliche Zeichnen der Bounding-Volume-Hierarchie des Worts. Wenn dieser Parameter nicht mitgegeben wird, wird nur das Wort, ohne die Bounding-Volume-Hierarchie gezeichnet.   drawOption:   'all' Zeichnet alle Bounding-Volumes   'filled' Zeichnet nur Bounding-Volumes, die gefüllte Pixel enthalten.   'empty' Zeichnet nur Bounding-Volumes, die keine Pixel enthalten   fill: Sollen die Bounding-Volumes mit Farbe gefüllt werden?   Beispiel: {     color: '#ff0000',     fill: false,     drawOption: 'filled' }

 

Ausgabe

object   Liefert Javascript Canvas-Objekt zurück.

WordCloudJS.boundingVolume

Die Klasse WordCloudJS.boundingVolume definiert ein Bounding-Volume eines Worts und generiert eine Bounding-Hierarchie. Erzeugt eine Instanz der Klasse WordCloudJS.boundingVolume.

 

new WordcloudJS.boundingVolume(option);

 

Parameter	Typ	Beschreibung
option	object	Optionen, die das Bounding-Volume definieren. Ein Bounding-Volume wird durch eine Position (linke obere Ecke) mit den Koordinaten x und y sowie eine Höhe und eine Breite definiert. Jedes Bounding-Volume ist immer einem Wort zugeordnet.   Beispiel: {     word: word,     x: 0,     y: 0,     width: 100,     height: 100 }

 

Attribut	Typ	Beschreibung
word	object	Siehe WordCloudJS.word
x	number	X-Koordinate der Position des Bounding-Volumes
y	number	Y-Koordinate der Position des Bounding-Volumes
width	number	Breite des Bounding-Volumes
height	number	Höhe des Bounding-Volumes
children	array	Bounding-Volumes, die sich innerhalb von diesen Bounding-Volume befinden. Das Array enthält immer zwei oder keine Elemente, da ein Bounding-Volume immer in der hälfte geteilt wird oder garnicht.
isFilled	boolean	Enthält das Bounding-Volume gefüllte Pixel?

 

Ausgabe

object :WordCloudJS.boundingVolume

 

hasChildren ()

Ermittelt, ob sich weitere Bounding-Volumes innerhalb des Bounding-Volumes befinden.

 

Ausgabe

boolean

 

traverse(func, param)

Durchläuft rekursiv ein Bounding-Volume und alle Bounding-Volumes, die sich innerhalb des Bounding-Volumes befinden, und führt eine Operation aus.

 

Parameter	Typ	Beschreibung
func	function	Operation, die für jedes Bounding-Volume ausgeführt werden soll. Die Funktion muss zwei Parameter besitzen: -       Instanz des Bounding-Volumes -       Javascript-Objekt mit individuellen Parametern Diese werden beim Ausführen der Rekursion von traverse() der Funktion func übergeben.
param	object	Objekt mit individuellen Parametern, die der Funktion func übergeben werden.

 

drawBoundingVolume(ctx, color, fill, drawOption)

Zeichnet ein Bounding-Volume auf ein Canvas. Diese Methode kann zum Debugging verwendet werden.

 

Parameter	Typ	Beschreibung
ctx	object	Canvas 2D-Kontext
color	string	Farbe im Hex-Format
fill	boolean	Soll das Bounding-Volume gefüllt werden?
drawOption	string	Option, die angibt, welche Eigenschaft das Bounding-Volume haben muss, damit es gezeichnet wird.    'all' Zeichnet alle Bounding-Volumes   'filled' Zeichnet nur Bounding-Volumes, die gefüllte Pixel enthalten.   'empty' Zeichnet nur Bounding-Volumes, die keine Pixel enthalten

WordCloudJS.stopwords

Dieses Objekt beinhaltet Stoppwörter für die Sprachen deutsch und englisch. Die Stoppwörter werden für das Extrahieren von Wörtern aus Texten verwendet.

 

Deutsche Stoppwörter:

WordcloudJS.stopwords.german = [“ab“, “aber“, … ];

 

Englische Stoppwörter:

WordcloudJS.stopwords.english = [“a“, “able“, … ];