Graphty

Appearance

@graphty/graphty-element / index / SimpleLayoutEngine

Abstract Class: SimpleLayoutEngine ​

Defined in: graphty-element/src/layout/LayoutEngine.ts:1776

The base class a third party extended to write a layout computed in one pass.

It keeps working through graphty-element 3.x, with everything a subclass reads: _nodes, _edges, positions, result, graph, sourceGraph, scalingFactor and doLayout.

Deprecated ​

Register the layout with registerSnapshotLayout from @graphty/graphty-element/extend instead: a function from the graph snapshot to coordinates, which the element's own one-pass layouts are built on, with pins, cancellation and progress.

Extends ​

  • StaticLayoutEngine

Constructors ​

Constructor ​

new SimpleLayoutEngine(opts?): SimpleLayoutEngine

Defined in: graphty-element/src/layout/LayoutEngine.ts:1248

Create a simple layout engine

Parameters ​

opts? ​

SimpleLayoutOpts = {}

Configuration options including scalingFactor

Returns ​

SimpleLayoutEngine

Inherited from ​

StaticLayoutEngine.constructor

Properties ​

descriptor? ​

static optional descriptor?: AuthoredLayoutDescriptor

Defined in: graphty-element/src/layout/LayoutEngine.ts:341

What a picker reads about this layout. See LayoutEngineStatics.descriptor.

A third party's engine declares one and LayoutEngine.register publishes it to the catalogue; the element's own engines leave it undefined because their arrangements are authored centrally.

Inherited from ​

StaticLayoutEngine.descriptor

honoursWeights ​

static honoursWeights: boolean = false

Defined in: graphty-element/src/layout/LayoutEngine.ts:323

Whether this engine reads edge weights. See LayoutEngineStatics.honoursWeights.

False here because most layouts have no weight channel at all: of the element's own nineteen, only Kamada-Kawai and ForceAtlas2 can read one, and the other seventeen would be advertising a control that changes nothing.

Inherited from ​

StaticLayoutEngine.honoursWeights

maxDimensions ​

static maxDimensions: number

Defined in: graphty-element/src/layout/LayoutEngine.ts:314

Inherited from ​

StaticLayoutEngine.maxDimensions

positions ​

positions: Record<string | number, number[]> = {}

Defined in: graphty-element/src/layout/LayoutEngine.ts:1226

What an engine that does not read the protected graph computed, keyed by node id, in layout units.

Inherited from ​

StaticLayoutEngine.positions

scalingFactor ​

scalingFactor: number = 100

Defined in: graphty-element/src/layout/LayoutEngine.ts:1229

Inherited from ​

StaticLayoutEngine.scalingFactor

scoped ​

static scoped: boolean = false

Defined in: graphty-element/src/layout/LayoutEngine.ts:332

Whether this engine accepts a scope. See LayoutEngineStatics.scoped, which states the contract a scoped engine accepts.

False here because a one-shot arrangement recomputes every coordinate from scratch, and where it would place a subset among nodes it may not move is a question nothing answers yet.

Inherited from ​

StaticLayoutEngine.scoped

stale ​

stale: boolean = true

Defined in: graphty-element/src/layout/LayoutEngine.ts:1224

Inherited from ​

StaticLayoutEngine.stale

type ​

static type: string

Defined in: graphty-element/src/layout/LayoutEngine.ts:1221

Inherited from ​

StaticLayoutEngine.type

zodOptionsSchema? ​

static optional zodOptionsSchema?: OptionsSchema

Defined in: graphty-element/src/layout/LayoutEngine.ts:359

NEW: Zod-based options schema for unified validation and UI metadata

Subclasses should override this to define their configurable options using the new Zod-based schema system.

Inherited from ​

StaticLayoutEngine.zodOptionsSchema

Accessors ​

edges ​

Get Signature ​

get edges(): Iterable<Edge>

Defined in: graphty-element/src/layout/LayoutEngine.ts:1575

Get all edges in the layout

Returns ​

Iterable<Edge>

Iterable of edges

Inherited from ​

StaticLayoutEngine.edges

holdMask ​

Get Signature ​

get holdMask(): U32 | null

Defined in: graphty-element/src/layout/LayoutEngine.ts:598

The hold mask the element last handed this engine, or null when nothing is held.

Returns ​

U32 | null

The mask, which the caller must not change.

Inherited from ​

StaticLayoutEngine.holdMask

isSettled ​

Get Signature ​

get isSettled(): boolean

Defined in: graphty-element/src/layout/LayoutEngine.ts:1584

A static layout is finished the moment it exists, so this is true -- except for an arrangement that is computed asynchronously, which is unsettled until its answer has been published.

Returns ​

boolean

whether the arrangement is final

Inherited from ​

StaticLayoutEngine.isSettled

nodePositions ​

Get Signature ​

get nodePositions(): ReadonlyElementPositions

Defined in: graphty-element/src/layout/LayoutEngine.ts:544

The coordinates this engine publishes, read-only.

Read-only because the array is the element's: a write here would move or pin a node with no undo step. The engine writes through writeNodePosition; a consumer places and pins nodes through session.positions.

Returns ​

ReadonlyElementPositions

the coordinates in use, read-only

Inherited from ​

StaticLayoutEngine.nodePositions

nodes ​

Get Signature ​

get nodes(): Iterable<Node>

Defined in: graphty-element/src/layout/LayoutEngine.ts:1567

Get all nodes in the layout

Returns ​

Iterable<Node>

Iterable of nodes

Inherited from ​

StaticLayoutEngine.nodes

type ​

Get Signature ​

get type(): string

Defined in: graphty-element/src/layout/LayoutEngine.ts:771

Get the type identifier for this layout engine

Returns ​

string

The layout engine type string

Inherited from ​

StaticLayoutEngine.type

Methods ​

addEdge() ​

addEdge(e): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1293

Add an edge to the layout and mark positions as stale

Parameters ​

e ​

Edge

The edge to add

Returns ​

void

Inherited from ​

StaticLayoutEngine.addEdge

addNode() ​

addNode(n): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1284

Add a node to the layout and mark positions as stale

Parameters ​

n ​

Node

The node to add

Returns ​

void

Inherited from ​

StaticLayoutEngine.addNode

dispose() ​

dispose(): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:479

Release whatever this engine holds. The element calls it when the reader switches layouts and when the graph is torn down, and never uses the engine again afterwards.

Declared with a do-nothing default for the same reason as removeNode: it was duck-typed, undeclared and unimplemented by every engine here.

Returns ​

void

Inherited from ​

StaticLayoutEngine.dispose

doLayout() ​

abstract doLayout(): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1589

Compute the layout: assign the protected result from graph, or fill positions.

Returns ​

void

Inherited from ​

StaticLayoutEngine.doLayout

get() ​

static get(type, opts?): LayoutEngine | null

Defined in: graphty-element/src/layout/LayoutEngine.ts:883

Get a layout engine instance by type

Parameters ​

type ​

string

The layout engine type identifier

opts? ​

object = {}

Configuration options for the layout engine

Returns ​

LayoutEngine | null

A new layout engine instance or null if type not found

Inherited from ​

StaticLayoutEngine.get

getClass() ​

static getClass(type): LayoutEngineClass & LayoutEngineStatics | null

Defined in: graphty-element/src/layout/LayoutEngine.ts:952

Get a layout class by type

Parameters ​

type ​

string

The layout engine type identifier

Returns ​

LayoutEngineClass & LayoutEngineStatics | null

The layout engine class or null if not found

Inherited from ​

StaticLayoutEngine.getClass

getEdgePosition() ​

getEdgePosition(e): EdgePosition

Defined in: graphty-element/src/layout/LayoutEngine.ts:1465

Get the position of an edge based on its endpoints

Parameters ​

e ​

Edge

The edge to get position for

Returns ​

EdgePosition

The edge's source and destination positions

Inherited from ​

StaticLayoutEngine.getEdgePosition

getNodePosition() ​

getNodePosition(n): Position

Defined in: graphty-element/src/layout/LayoutEngine.ts:1432

Get the position of a node, computing layout if stale

The coordinates come from the shared position array, rounded to the f32 it stores. A node with no row there falls back to what the engine computed, which is every node in an engine driven by hand.

Parameters ​

n ​

Node

The node to get position for

Returns ​

Position

The node's position coordinates

Inherited from ​

StaticLayoutEngine.getNodePosition

getOptionsForDimension() ​

static getOptionsForDimension(dimension): object | null

Defined in: graphty-element/src/layout/LayoutEngine.ts:1259

Get dimension-specific options for simple layouts

Parameters ​

dimension ​

2 | 3

The desired dimension (2 or 3)

Returns ​

object | null

Options object with dim parameter or null if unsupported

Inherited from ​

StaticLayoutEngine.getOptionsForDimension

getOptionsForDimensionByType() ​

static getOptionsForDimensionByType(type, dimension): object | null

Defined in: graphty-element/src/layout/LayoutEngine.ts:914

Get dimension-specific options for a layout by type

Parameters ​

type ​

string

The layout engine type identifier

dimension ​

2 | 3

The desired dimension (2 or 3)

Returns ​

object | null

Options object for the dimension or null if type not found or unsupported

Inherited from ​

StaticLayoutEngine.getOptionsForDimensionByType

getRegisteredTypes() ​

static getRegisteredTypes(): string[]

Defined in: graphty-element/src/layout/LayoutEngine.ts:943

Get a list of all registered layout types

Returns ​

string[]

Array of registered layout type identifiers

Inherited from ​

StaticLayoutEngine.getRegisteredTypes

getZodOptionsSchema() ​

static getZodOptionsSchema(): OptionsSchema

Defined in: graphty-element/src/layout/LayoutEngine.ts:927

Get the Zod-based options schema for this layout

Returns ​

OptionsSchema

The options schema, or an empty object if no schema defined

Inherited from ​

StaticLayoutEngine.getZodOptionsSchema

hasZodOptions() ​

static hasZodOptions(): boolean

Defined in: graphty-element/src/layout/LayoutEngine.ts:935

Check if this layout has a Zod-based options schema

Returns ​

boolean

true if the layout has options defined

Inherited from ​

StaticLayoutEngine.hasZodOptions

init() ​

init(): Promise<void>

Defined in: graphty-element/src/layout/LayoutEngine.ts:1276

Initialize the layout engine

Simple layouts compute positions synchronously and don't require initialization.

Returns ​

Promise<void>

Inherited from ​

StaticLayoutEngine.init

loadArrangement() ​

loadArrangement(): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1557

Keep the arrangement in the array instead of recomputing one: a static layout that was marked stale by the graph change an undo made would otherwise lay the graph out afresh at the next read and write over what was restored.

Returns ​

void

Inherited from ​

StaticLayoutEngine.loadArrangement

publishPositions() ​

publishPositions(): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1479

Copy the computed layout into the shared position array, recomputing it first if it is stale.

Returns ​

void

Inherited from ​

StaticLayoutEngine.publishPositions

readNodePosition() ​

readNodePosition(n, out): boolean

Defined in: graphty-element/src/layout/LayoutEngine.ts:664

Read a node's published coordinates into an object the CALLER owns.

The point of the out parameter is that a renderer can pass the vector it is about to draw with and allocate nothing per node per frame. A row that no engine has placed answers false and leaves out untouched, so the caller keeps whatever it had rather than being handed a NaN or an origin it cannot tell from a real coordinate.

Parameters ​

n ​

Node

the node to read

out ​

the object to fill; a Babylon Vector3 is one, which is the point

x ​

number

receives the scene-unit x

y ​

number

receives the scene-unit y

z ​

number

receives the scene-unit z

Returns ​

boolean

true when the node has a placed row

Inherited from ​

StaticLayoutEngine.readNodePosition

register() ​

static register<T>(cls, options?): T

Defined in: graphty-element/src/layout/LayoutEngine.ts:796

File a layout engine class under the name it declares, and publish what it says about itself to the catalogue.

WHAT CHANGED AND WHY. This used to read cls.type through a cast and put the class in a map, which meant a class with no static type registered under the string "undefined", a second class under a taken name silently replaced the first, and a registered engine reached no catalogue at all -- so a third party's layout could run but could never be offered by a picker, described in a reader's language, or found by layoutIdForEngine.

A third party's class must declare a static descriptor whose id equals its static type. The element's own nineteen are the one exemption, because their arrangements are authored centrally in the layout catalogue where several engines may sit behind one public name.

Type Parameters ​

T ​

T extends LayoutEngineClass

Parameters ​

cls ​

T

The layout engine class.

options? ​

RegisterOptions

How to register it; strict refuses a different layout under a taken id.

Returns ​

T

The same class, so a declaration can register itself in one expression.

Throws ​

A GraphtyError with E_BAD_COMMAND when the class declares no static type, no static descriptor, or a descriptor whose id disagrees with its static type; or with E_DUPLICATE_PLUGIN when the name or the descriptor id is one the element itself ships.

Inherited from ​

StaticLayoutEngine.register

reload() ​

reload(change, loading): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1409

Hear that the element's graph was frozen again.

The layout is re-run at the next read. When the freeze only added to the graph this engine last arranged, and the data is not still loading, the re-run keeps every existing node where it is (see the class comment). A load is excluded because its chunks are one graph arriving, not a reader adding to a finished one: a circle whose first chunk was held would be drawn as two overlapping circles.

Called by the element's layout manager on every freeze; an engine never calls it itself.

Parameters ​

change ​

SnapshotReplacement

the freeze

loading ​

boolean

whether a load is still streaming records in

Returns ​

void

Inherited from ​

StaticLayoutEngine.reload

removeEdge() ​

removeEdge(e): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1523

The edge half of StaticLayoutEngine.removeNode, with the same reason.

Parameters ​

e ​

Edge

the edge leaving the graph

Returns ​

void

Inherited from ​

StaticLayoutEngine.removeEdge

removeNode() ​

removeNode(n): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1510

Take a node out of the layout.

WITHOUT THIS the engine holds the removed node -- and through it the node's Babylon mesh, its data record and its endpoints -- for as long as the engine lives, and the frame loop keeps walking it, so a node the reader deleted still draws at wherever it last was. The layout is marked stale, so the next read recomputes it without the node.

Parameters ​

n ​

Node

the node leaving the graph

Returns ​

void

Inherited from ​

StaticLayoutEngine.removeNode

setHoldMask() ​

setHoldMask(mask, rows): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:589

Hold the nodes a scoped layout may not move, or release them all with null.

The element calls this on an engine whose class declares static scoped = true, after init() and after every renumbering of the graph. A set bit is a held row. A row at or past rows belongs to a node that arrived after the scope was captured, and is held too: the members of a scoped layout are the ones it started with. An engine that overrides this calls super.setHoldMask first and then fixes held nodes in its own state (see LayoutEngineStatics.scoped).

Parameters ​

mask ​

U32 | null

One bit per row, set for a row to hold; null holds nothing.

rows ​

number

How many rows the mask covers.

Returns ​

void

Inherited from ​

StaticLayoutEngine.setHoldMask

step() ​

step(): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:1497

Step the layout animation

Simple layouts are static and don't animate, so stepping has no effect.

Returns ​

void

Inherited from ​

StaticLayoutEngine.step

updatePositions() ​

updatePositions(_nodes): void

Defined in: graphty-element/src/layout/LayoutEngine.ts:462

Settle nodes that reached the graph after this layout was already running.

THE DEFAULT IS THE ELEMENT'S OWN FALLBACK -- up to ten steps, stopping early if the engine settles -- so a simulation behaves exactly as it did before the hook was declared, and an engine that can place a newcomer without re-running the whole simulation overrides it. It lives on the base class rather than in the manager because the manager cannot tell "did not implement it" from "implemented it as a deliberate no-op", and the difference decides whether ten steps run.

Parameters ​

_nodes ​

readonly Node[]

the nodes that have just arrived

Returns ​

void

Inherited from ​

StaticLayoutEngine.updatePositions