Graphty

Appearance

@graphty/graphty-element / index / LayoutEngine

Abstract Class: LayoutEngine ​

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

The base every layout engine extends: how the element adds, places, steps and removes.

Constructors ​

Constructor ​

new LayoutEngine(): LayoutEngine

Returns ​

LayoutEngine

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.

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.

maxDimensions ​

static maxDimensions: number

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

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.

type ​

static type: string

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

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.

Accessors ​

edges ​

Get Signature ​

get abstract edges(): Iterable<Edge>

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

Returns ​

Iterable<Edge>

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.

isSettled ​

Get Signature ​

get abstract isSettled(): boolean

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

Returns ​

boolean

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

nodes ​

Get Signature ​

get abstract nodes(): Iterable<Node>

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

Returns ​

Iterable<Node>

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

Methods ​

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

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

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

getEdgePosition() ​

abstract getEdgePosition(e): EdgePosition

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

Parameters ​

e ​

Edge

Returns ​

EdgePosition

getNodePosition() ​

abstract getNodePosition(n): Position

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

Parameters ​

n ​

Node

Returns ​

Position

getOptionsForDimension() ​

static getOptionsForDimension(dimension): object | null

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

Get dimension-specific options for this layout

Parameters ​

dimension ​

2 | 3

The desired dimension (2 or 3)

Returns ​

object | null

Options object for the dimension or null if unsupported

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

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

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

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

init() ​

abstract init(): Promise<void>

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

Returns ​

Promise<void>

loadArrangement() ​

loadArrangement(): void

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

Take the coordinates in the position array as this engine's own, and stay at rest.

Undo and redo write where the nodes were into the array and then call this, so the next drag, add or setRunning(true) starts from the restored arrangement instead of the one the engine was holding. The default hands every placed node back through setNodePosition, which is right for any engine that keeps coordinates of its own; an engine that can adopt the array in one pass overrides it.

Returns ​

void

publishPositions() ​

publishPositions(): void

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

Copy every node's current coordinates out of the engine and into the position array.

Engines call this at the end of a step, so that by the time anything draws, the array is the answer rather than a copy of it. The default walks the engine's own nodes through LayoutEngine.getNodePosition, which is correct for any engine but allocates one object per node; an engine that can read its own state without allocating overrides it, and an engine that already writes straight into the array overrides it to do nothing.

Returns ​

void

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

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.

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

step() ​

abstract step(): void

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

Returns ​

void

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