npm package: @mythoskop/graph-engine
Description: ## Inhalt
Latest version: 0.2.4

# 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.

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

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

```ts
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:

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

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

```ts
{
  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.