initAvoidRouter

initAvoidRouter(graph: dia.Graph, options?: InitAvoidOptions): Promise<RouterService>;

Loads the libavoid WebAssembly module (via loadAvoidRouter(), if it is not loaded yet) and creates a RouterService for graph. The returned promise resolves once the module is loaded and the graph's current content has been registered with libavoid; the routes themselves are computed asynchronously and applied as they come in.

The returned service is not started. Call start() to keep the graph continuously routed, or routeAll() / routeSubgraph() for a one-shot routing pass.

import { dia, shapes } from '@joint/core';
import { initAvoidRouter } from '@joint/router-avoid';

const graph = new dia.Graph({}, { cellNamespace: shapes });

const avoidRouter = await initAvoidRouter(graph, {
    shapeBufferDistance: 20,
    idealNudgingDistance: 10
});

avoidRouter.start();

Options

The options argument is an InitAvoidOptions object.

Option	Type	Description
shapeBufferDistance	number	Spacing added to the sides of each shape when determining obstacle sizes for routing. Also used as the margin around elements when computing a fallback route. Defaults to 10.
idealNudgingDistance	number	Spacing used for nudging apart overlapping corners and line segments of connectors. Affects the libavoid engine only, never the fallback route. Defaults to 5.
worker	boolean | WorkerOptions	Runs libavoid inside a Worker thread instead of the main thread. Pass true for the defaults, or a WorkerOptions object to configure it. Defaults to false.
libavoidFilePath	string	Path to the libavoid.wasm binary, for when it is not served from its default location. Forwarded to loadAvoidRouter().
trackLink	TrackLinkCallback	Determines which links to route. Defaults to tracking every link.
trackElement	TrackElementCallback	Determines which elements to treat as obstacles. Defaults to tracking every element.
interceptUnroutableLink	UnroutableLinkCallback	Gives you first refusal on links libavoid cannot route. Defaults to always applying the built-in rightAngle fallback route.
setRouteAttributes	SetRouteAttributesCallback	Overrides how computed route attributes are applied to a link. Defaults to calling link.set() directly.
changeFlag	string	Name of the opt flag set on the link.set() calls this instance makes, so its own changes can be told apart from yours. Defaults to 'avoidRouter'.

Multiple services on one graph

By default a service tracks every cell, so two of them on one graph both route the same links and fight over them - whether they are started or running one-shot passes. When replacing a service, destroy() the previous one first.

Several services can share a graph if their trackElement and trackLink sets are disjoint, and every link a service tracks connects elements that same service tracks - otherwise the link is 'untracked' and takes the fallback route.

Each service drives its own libavoid engine, so they know nothing of each other's obstacles: links routed by one pass straight through elements tracked by another. Give them distinct changeFlag values so their writes stay distinguishable.

Types

InitAvoidOptions

interface InitAvoidOptions {
    trackLink?: TrackLinkCallback;
    trackElement?: TrackElementCallback;
    interceptUnroutableLink?: UnroutableLinkCallback;
    setRouteAttributes?: SetRouteAttributesCallback;
    changeFlag?: string;
    shapeBufferDistance?: number;
    idealNudgingDistance?: number;
    worker?: boolean | WorkerOptions;
    libavoidFilePath?: string;
}

Configuration for initAvoidRouter(). See Options for the defaults and a description of each field.

SetRouteAttributesCallback

type SetRouteAttributesCallback = (params: {
    link: dia.Link;
    attributes: RouteAttributes;
    origin: RouteOrigin;
    routing?: boolean;
    unroutableReason?: UnroutableReason;
}) => void;

Applies computed route attributes to a link, overriding the default behavior of calling link.set() directly. Useful for routing the update through a command manager or another change-tracking layer.

routing is true when the route is provisional - libavoid is still computing and another call for the same link follows. unroutableReason is set only when the fallback route is applied because the link is unroutable and interceptUnroutableLink did not claim it.

When this callback is provided, the router never calls link.set() itself. See RouteAttributes for the shape it receives.

TrackElementCallback

type TrackElementCallback = (params: { element: dia.Element }) => boolean;

Determines whether an element should be tracked as an obstacle. Return false to exclude it entirely - links are routed straight through it, and links connected to it become 'untracked'.

TrackLinkCallback

type TrackLinkCallback = (params: { link: dia.Link }) => boolean;

Determines whether a link should be routed by this service. Return false to leave the link's own router and connector attributes untouched.

UnroutableLinkCallback

type UnroutableLinkCallback = (params: {
    link: dia.Link;
    reason: UnroutableReason;
}) => boolean;

Gives you first refusal on a link libavoid cannot route. Return true to claim the link, skipping the built-in rightAngle fallback route entirely and leaving that link's routing to your application. See UnroutableReason for the possible reasons.

WorkerOptions

interface WorkerOptions {
    debounceTime?: number;
}

Options for the Worker-based provider, passed as worker to initAvoidRouter().

debounceTime is the number of milliseconds the Worker waits after the last received graph change before applying the queued changes and recomputing routes. Changes arriving within this window are batched into a single routing pass. Set to 0 to apply every change immediately. Defaults to 100.