Custom Layouts

Guide to creating custom layout algorithms.

Overview

Graphty's layout system is extensible. Create custom layouts for specialized graph structures or unique positioning requirements.

LayoutEngine Interface

All layouts extend the abstract LayoutEngine class:

abstract class LayoutEngine {
    static type: string;

    abstract initialize(nodes: Node[], edges: Edge[]): void;
    abstract step(): boolean; // Returns true when settled
    abstract getPosition(nodeId: string): Vector3;
}

Creating a Custom Layout

Basic Example

import { LayoutEngine, Node, Edge, Vector3 } from "@graphty/graphty-element";

class MyLayout extends LayoutEngine {
    static type = "my-layout";

    private positions: Map<string, Vector3> = new Map();

    initialize(nodes: Node[], edges: Edge[]): void {
        // Set up initial positions
        nodes.forEach((node, index) => {
            this.positions.set(node.id, {
                x: index * 10,
                y: 0,
                z: 0,
            });
        });
    }

    step(): boolean {
        // Perform one iteration of layout algorithm
        // Return true when layout is stable
        return true; // Immediately settled for static layouts
    }

    getPosition(nodeId: string): Vector3 {
        return this.positions.get(nodeId) || { x: 0, y: 0, z: 0 };
    }
}

// Register the layout
LayoutEngine.register(MyLayout);

Using Your Layout

graph.setLayout("my-layout");

Complete Example: Spiral Layout

import { LayoutEngine, Node, Edge, Vector3 } from "@graphty/graphty-element";

class SpiralLayout extends LayoutEngine {
    static type = "spiral";

    private positions: Map<string, Vector3> = new Map();
    private options: SpiralOptions;

    constructor(options: Partial<SpiralOptions> = {}) {
        super();
        this.options = {
            radiusStep: 2,
            angleStep: 0.5,
            heightStep: 1,
            ...options,
        };
    }

    initialize(nodes: Node[], edges: Edge[]): void {
        let angle = 0;
        let radius = 0;
        let height = 0;

        nodes.forEach((node) => {
            this.positions.set(node.id, {
                x: radius * Math.cos(angle),
                y: height,
                z: radius * Math.sin(angle),
            });

            angle += this.options.angleStep;
            radius += this.options.radiusStep;
            height += this.options.heightStep;
        });
    }

    step(): boolean {
        // Static layout - immediately settled
        return true;
    }

    getPosition(nodeId: string): Vector3 {
        return this.positions.get(nodeId) || { x: 0, y: 0, z: 0 };
    }
}

interface SpiralOptions {
    radiusStep: number;
    angleStep: number;
    heightStep: number;
}

LayoutEngine.register(SpiralLayout);

Usage:

graph.setLayout("spiral", {
    radiusStep: 3,
    angleStep: 0.3,
    heightStep: 0.5,
});

Force-Directed Layout Example

For iterative layouts that converge over time:

import { LayoutEngine, Node, Edge, Vector3 } from "@graphty/graphty-element";

class SimpleForceLayout extends LayoutEngine {
    static type = "simple-force";

    private nodes: Node[] = [];
    private edges: Edge[] = [];
    private positions: Map<string, Vector3> = new Map();
    private velocities: Map<string, Vector3> = new Map();

    private repulsion = 100;
    private attraction = 0.01;
    private damping = 0.9;
    private threshold = 0.1;

    initialize(nodes: Node[], edges: Edge[]): void {
        this.nodes = nodes;
        this.edges = edges;

        // Random initial positions
        nodes.forEach((node) => {
            this.positions.set(node.id, {
                x: (Math.random() - 0.5) * 100,
                y: (Math.random() - 0.5) * 100,
                z: (Math.random() - 0.5) * 100,
            });
            this.velocities.set(node.id, { x: 0, y: 0, z: 0 });
        });
    }

    step(): boolean {
        let maxVelocity = 0;

        // Calculate forces
        this.nodes.forEach((node) => {
            const pos = this.positions.get(node.id)!;
            const vel = this.velocities.get(node.id)!;
            const force = { x: 0, y: 0, z: 0 };

            // Repulsion from other nodes
            this.nodes.forEach((other) => {
                if (other.id === node.id) return;
                const otherPos = this.positions.get(other.id)!;

                const dx = pos.x - otherPos.x;
                const dy = pos.y - otherPos.y;
                const dz = pos.z - otherPos.z;
                const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 0.1;

                const f = this.repulsion / (dist * dist);
                force.x += (dx / dist) * f;
                force.y += (dy / dist) * f;
                force.z += (dz / dist) * f;
            });

            // Attraction along edges
            this.edges.forEach((edge) => {
                let otherId: string | null = null;
                if (edge.source === node.id) otherId = edge.target as string;
                if (edge.target === node.id) otherId = edge.source as string;
                if (!otherId) return;

                const otherPos = this.positions.get(otherId);
                if (!otherPos) return;

                const dx = otherPos.x - pos.x;
                const dy = otherPos.y - pos.y;
                const dz = otherPos.z - pos.z;

                force.x += dx * this.attraction;
                force.y += dy * this.attraction;
                force.z += dz * this.attraction;
            });

            // Update velocity
            vel.x = (vel.x + force.x) * this.damping;
            vel.y = (vel.y + force.y) * this.damping;
            vel.z = (vel.z + force.z) * this.damping;

            // Update position
            pos.x += vel.x;
            pos.y += vel.y;
            pos.z += vel.z;

            const speed = Math.sqrt(vel.x * vel.x + vel.y * vel.y + vel.z * vel.z);
            maxVelocity = Math.max(maxVelocity, speed);
        });

        // Return true when settled
        return maxVelocity < this.threshold;
    }

    getPosition(nodeId: string): Vector3 {
        return this.positions.get(nodeId) || { x: 0, y: 0, z: 0 };
    }
}

LayoutEngine.register(SimpleForceLayout);

Layout Configuration

Accept configuration options in the constructor:

class ConfigurableLayout extends LayoutEngine {
    static type = "configurable";

    private config: LayoutConfig;

    constructor(options: Partial<LayoutConfig> = {}) {
        super();
        this.config = {
            spacing: 10,
            direction: "horizontal",
            ...options,
        };
    }

    // ... implementation
}

interface LayoutConfig {
    spacing: number;
    direction: "horizontal" | "vertical";
}

Usage:

graph.setLayout("configurable", {
    spacing: 20,
    direction: "vertical",
});

2D vs 3D Layouts

Check dimensions in your layout:

class FlexibleLayout extends LayoutEngine {
    static type = "flexible";

    private dimensions: 2 | 3 = 3;

    constructor(options: { dimensions?: 2 | 3 } = {}) {
        super();
        this.dimensions = options.dimensions || 3;
    }

    initialize(nodes: Node[], edges: Edge[]): void {
        nodes.forEach((node, i) => {
            if (this.dimensions === 2) {
                this.positions.set(node.id, { x: i * 10, y: 0, z: 0 });
            } else {
                this.positions.set(node.id, {
                    x: i * 10,
                    y: Math.random() * 10,
                    z: Math.random() * 10,
                });
            }
        });
    }
}

Performance Tips

1. Use spatial indexing: For large graphs, use quadtrees (2D) or octrees (3D)
2. Batch updates: Update all positions before returning from step()
3. Early exit: Return true from step() as soon as layout is stable
4. Avoid allocations: Reuse objects instead of creating new ones each step

// Good: reuse force object
private force = { x: 0, y: 0, z: 0 };

step(): boolean {
  this.force.x = 0;
  this.force.y = 0;
  this.force.z = 0;
  // ... calculate forces
}

// Bad: create new object each time
step(): boolean {
  const force = { x: 0, y: 0, z: 0 }; // Allocation every frame!
}

Debugging Layouts

Log layout progress:

step(): boolean {
  this.iterationCount++;

  if (this.iterationCount % 100 === 0) {
    console.log(`Layout iteration ${this.iterationCount}`);
  }

  // ...
}