Skip to content

Latest commit

 

History

History
4780 lines (4585 loc) · 306 KB

README.md

File metadata and controls

4780 lines (4585 loc) · 306 KB
Raw

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“, … ];