Docs @mythoskop/graph-engine v0.1.2

Inhalt

1. Öffentliche Schnittstelle des Pakets

  1.1 Die Klasse `DirectedGraph`
    1.1.1  constructor(source:string)
    1.1.2  public readonly vertices: DirectedVertex[]
    1.1.2  public readonly edges: DirectedEdge[]

  1.2 Die Klasse `DirectedEdge`
    1.2.1  constructor(from: DirectedVertex, to: DirectedVertex, data?: object = {})
    1.2.2  public readonly from: DirectedVertex
    1.2.3  public readonly to: DirectedVertex
    1.2.4  assignData(data: object): void
    1.2.5  getData(): any
    1.2.6  setColor(colorCode: string): void
    1.2.7  getColor(): string
    1.2.8  setWeight(weight: number): void
    1.2.9  getWeight(): number
    1.2.10 setStrokeDasharray(strokeDasharray: string): void
    1.2.11 getStrokeDasharray(): string
    1.2.12 remove(): void

  1.3 Die Klasse `DirectedVertex`
    1.3.1  constructor(data?: object = {})
    1.3.2  public readonly in: DirectedEdge[]
    1.3.3  public readonly out: DirectedEdge[]
    1.3.4  public readonly graph: DirectedGraph
    1.3.5  assignData(data: object): void
    1.3.6  getData(): any
    1.3.7  setPosition(x: number, y: number): void
    1.3.8  getX(): number
    1.3.9  getY(): number
    1.3.10  setDisplayLevel(level: number): void
    1.3.11 getDisplayLevel(): number
    1.3.12 setColor(colorCode: string): void
    1.3.13 getColor(): string
    1.3.14 remove(): void

  1.4 Die Klasse `RenderParams`
    1.4.1  constructor(graph: DirectedGraph, data: { [key: string]: any })
    1.4.2  public readonly graph: DirectedGraph
    1.4.3  public readonly data: { [key: string]: any }

  1.5 Die abstrakte Klasse `AbstractRenderingAlgorithm`
    1.5.1  public abstract run(params: RenderParams): DirectedVertex[]

  1.6 Die Komponente `GraphEngine`
    1.6.1  export let graph: DirectedGraph
    1.6.2  export let algorithm?: AbstractRenderingAlgorithm
    1.6.3  export let params?: { [key: string]: any }
    1.6.4  export let vertexRenderer?: typeof VertexRenderer
    1.6.5  export let edgeRenderer?: typeof EdgeRenderer
    1.6.6  <slot name="background" />

2. User Guides
    2.1 Graphen aus einem JSON-String parsen

1. Öffentliche Schnittstelle

In diesem Kapitel werden die öffentlichen Klassen, Attribute, Komponenten und Methoden aufgezählt und erläutert sowie Vor- und Nachbedingungen definiert.

1.1 Die Klasse DirectedGraph

Diese Klasse repräsentiert den Graphen als Ganzes und bietet Schnittstellen zum Parsing des Graphen und zum Zugriff auf die Ecken und Kanten.

1.1.1 constructor(source:string | TransportGraph)

Ein DirectedGraph wird aus einem JSON-String konstruiert, oder aus einem bereits geparstem JSON-Objekt vom Typ TransportGraph. Der String beschreibt den Graphen durch Knoten und Kanten.

const jsonString: string = "...";
const graph: DirectedGraph = new DirectedGraph(jsonString);

Der geparste JSON-String bzw. das gepraste JSON-Objekt muss den folgenden Typescript-Typ haben:

type TransportGraph = {
  vertices: object[];
  edges: { from: number; to: number; data?: object }[];
};

Ist dieser Typ nicht eingehalten, werden vom Konstruktor Ausnahmen mit den folgenden Fehlermeldungen ausgelöst.

Der zu parsende JSON-String enthält kein Array mit den Namen vertices:

DirectedGraph must have attribute 'vertices' of type 'array'.

Der zu parsende JSON-String enthält kein Array mit den Namen edges:

DirectedGraph must have attribute 'edges' of type 'array'.

Das edges-Array enthält Kanten, die null oder undefined sind, was nicht zulässig ist:

Edge does not exist.

Eine Kante muss durch das Attribut from vom Typ number beschrieben werden:

Edges on DirectedGraph must have attribute 'from' of type 'number'

Eine Kante muss durch das Attribut to vom Typ number beschrieben werden:

Edges on DirectedGraph must have attribute 'to' of type 'number'

Der Index des Start- und/oder Endknoten ist nicht in der Knotenmenge vertreten:

Edge tried to connect vertices '<number>' and '<number>' on DirectedGraph with only <number> vertices (index out of bounds).

1.1.2 public readonly vertices: DirectedVertex[]

Dieses Attribut enthält alle Ecken des Graphen.

1.1.2 public readonly edges: DirectedEdge[]

Dieses Attribut enthält alle Kanten des Graphen.

1.2 Die Klasse DirectedEdge

Diese Klasse repräsentiert eine Kante im Graphen und bietet Funktionalität zur Datenverwaltung und Darstellung.

1.2.1 constructor(from: DirectedVertex, to: DirectedVertex, data?: object = {})

Erstellt aus den übergebenen Knoten und Daten eine Kante.

Pre: `from` und `to` sind Knoten im selben Graphen.
Post: this.from === from && this.to === to && data.key != undefined => data.key === getData().key

1.2.2 public readonly from: DirectedVertex

Dieses Attribut enthält den Ausgangsknoten der Ecke.

1.2.3 public readonly to: DirectedVertex

Dieses Attribut enthält den Zielknoten der Ecke.

1.2.4 assignData(data: object): void

Hiermit können beliebige Daten in der Kante gespeichert werden.

Pre: true
Post: data.key != undefined => data.key === getData().key

1.2.5 getData(): any

Pre: true

1.2.6 setColor(colorCode: string): void

Hiermit kann festgelegt werden, wie die Kante eingefärbt ist.

Siehe: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

Pre: true
Post: this.getColor() === colorCode

1.2.7 getColor(): string

Siehe: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

Pre: true

1.2.8 setWeight(weight: number): void

Hiermit kann festgelegt werden, wie betont die Kante ist.

Siehe: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-width

Pre: true
Post: this.getWeight() === weight

1.2.9 getWeight(): number

Siehe: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-width

Pre: true

1.2.10 setStrokeDasharray(strokeDasharray: string): void

Hiermit kann festgelegt werden, ob und inwiefern die Kante gestrichelt ist.

Siehe: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray

Pre: true
Post: this.getStrokeDasharray() === strokeDasharray

1.2.11 getStrokeDasharray(): string

Siehe: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray

Pre: true

1.2.12 remove(): void

Diese Methode entfernt die Kante aus dem Graphen.

Pre: true
Post: alle Referenzen im Graphen auf diese Kante wurden entfernt

1.3 Die Klasse DirectedVertex

1.3.1 constructor(data?: object = {})

Erstellt einen Knoten mit den angegebenen Daten.

Pre: true
Post: data.key != undefined => data.key === getData().key && this.in.length === 0 && this.out.length === 0

1.3.2 public readonly in: DirectedEdge[]

Dieses Attribut enthält die Adjazenzliste der eingehenden Kanten.

1.3.3 public readonly out: DirectedEdge[]

Dieses Attribut enthält die Adjazenzliste der ausgehenden Kanten.

1.3.4 public readonly graph: DirectedGraph

Dieses Attribut enthält einen Verweis auf den Graphen, zu dem der Knoten gehört.

1.3.5 assignData(data: object): void

Hiermit können beliebige Daten in der Kante gespeichert werden.

Pre: true
Post: data.key != undefined => data.key === getData().key

1.3.6 getData(): any

Pre: true

1.3.7 setPosition(x: number, y: number): void

Hiermit kann der Ecke eine beliebige Koordinate zugewiesen werden.

Pre: true
Post: this.getX() === x && this.getY() === y

1.3.8 getX(): number

Pre: true

1.3.9 getY(): number

Pre: true

1.3.10 setDisplayLevel(level: number): void

Hiermit kann der Ecke eine Zahl zugewiesen werden, die den Detailgrad der Darstellung bzw. ihre Relevanz beschreibt. In den Standardeinstellungen zeigt ein DisplayLevel <= 0 an, dass die Kante im Graphen nicht dargestellt werden soll und verbordgen bleibt.

Pre: true
Post: this.getX() === x && this.getY() === y

1.3.11 getDisplayLevel(): number

Pre: true

1.3.12 setColor(colorCode: string): void

Hiermit kann festgelegt werden, wie die Kante eingefärbt sein soll.

Siehe: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

Pre: true
Post: this.getColor() === colorCode

1.3.13 getColor(): string

Siehe: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

Pre: true

1.3.14 remove(): void

Diese Methode entfernt den Knoten aus dem Graphen.

Pre: true
Post: alle Referenzen im Graphen auf diesen Knoten wurden entfernt. Zudem wurden inzidente Kanten entfernt.

1.4 Die Klasse RenderParams

Diese Klasse enthält die Argumente, die der run-Methode eines AbstractRenderingAlgorithm zur Berechnung der neuen Darstellung übergeben werden.

1.4.1 constructor(graph: DirectedGraph, data: { [key: string]: any })

Pre: true
Post: this.graph === graph && this.data === data

1.4.2 public readonly graph: DirectedGraph

Dieses Attribut verweist auf den darzustellenden Graphen.

1.4.3 public readonly data: { [key: string]: any }

Dieses Attribut enthält die Argumente, mit denen die Darstellung angepasst werden soll.

1.5 Die abstrakte Klasse AbstractRenderingAlgorithm

Diese abstrakte Klasse definiert die Signatur eines Rendering-Algorithmus nach dem Design-Pattern Strategy. Siehe https://en.wikipedia.org/wiki/Strategy_pattern.

1.5.1 public abstract run(params: RenderParams): DirectedVertex[]

Man beachte, dass diese Methode auf dem übergebenen Algorithmus durch die Komponente GraphEngine aufgerufen wird. Die zurückgegebenen Objekte vom Typ DirectedVertex werden dann von der GraphEngine dargestellt. Ein Aufrufen aus dem übrigen Programm sorgt nicht für eine Neuberechnung der Grafik.

Pre: true

1.6 Die Komponente GraphEngine

Diese Svelte-Komponente ist das Herzstück dieses Pakets und stellt den übergebenen Graphen anhand der übergebenen Argumente als SVG-Grafik dar. Diese hat folgende Properties:

1.6.1 export let graph: DirectedGraph

Dieses Property enthält den darzustellenden Graphen.

1.6.2 export let algorithm?: AbstractRenderingAlgorithm

Hiermit kann optional ein Algorithmus angegeben werden, der die Darstellung des Graphen berechnet.

1.6.3 export let params?: { [key: string]: any }

Dies sind die optionalen Parameter, die dem Algorithmus übergeben werden. Eine Änderung hier sorgt für eine Neuberechnung der Darstellung.

1.6.4 export let vertexRenderer?: typeof VertexRenderer

Hier kann eine Svelte-Komponente übergeben werden, die statt des eingebauten VertexRenderer die Darstellung einer Ecke übernimmt.

1.6.5 export let edgeRenderer?: typeof EdgeRenderer

Hier kann eine Svelte-Komponente übergeben werden, die statt des eingebauten EdgeRenderer die Darstellung einer Kante übernimmt.

1.6.6 <slot name="background" />

Diesem Slot können SVG-Elemente übergeben werden, die im Hintergrund der dargestellten Grafik eingefügt werden.

Siehe: https://developer.mozilla.org/en-US/docs/Web/SVG/Element

2. User Guides

2.1 Graphen aus einem JSON-String parsen

Ein navigierbarer Graph (siehe 2.2) wird aus einem JSON-String oder einem bereits geparstem JSON-Objekt vom Typ TransportGraph konstruiert. Der String beschreibt den Graphen durch seine Knoten und Kanten.

Der geparste JSON-String bzw. das gepraste JSON-Objekt muss den folgenden Typescript-Typ haben:

type TransportGraph = {
  vertices: object[];
  edges: { from: number; to: number; data?: object }[];
};

Es ist möglich, Knoten ohne zusätzliche Daten zu definieren:

{
  vertices:[{}, {}, {}],
  edges: [...]
}

Eine Kante wird durch die Attribute from, to und data beschrieben. Die Attribute from und to beschreiben den Startknoten und Endknoten der Kante. Diese Attribute müssen gültige Indizes auf dem vertices-Array enthalten. Andernfalls treten Fehler auf.

Das Attribut data darf undefined sein.

Beim aufruf des Konstruktor einer DirectedGraph-Komponente wird eine entsprechende Prüfung der korrekten Beschreibung getestet. Nur korrekt beschriebene Graphen werden konstruiert.