Appearance

  2. API
  3. Ogma

Ogma.layouts ​

Layout API: algorithms to calculate graph layouts.

ogma.layouts.concentric(params) ​

Concentric layout. This layout takes a base node as parameter and organizes the graph so the nodes close to the selected node are close to it spatially.

Arguments

  • params object See LayoutOptions for common layout options.
    • allowOverlap(optional) boolean[=false] Specifies if nodes are allowed to overlap.
    • centerX(optional) number X coordinate where the central node must be moved, if different from the central node X
    • centerY(optional) number Y coordinate where the central node must be moved, if different from the central node Y
    • centralNode NodeId|Node Id of the central node
    • circleHopRatio(optional) number[=5] If allowOverlap is false, specified the space between each ring, relative to the highest node size.
    • clockwise(optional) boolean[=true] Specifies if the nodes must be ordered clockwise.
    • duration(optional) number[=300] Duration of the animation when the graph is updated
    • easing(optional) Easing[='cubicOut'] Easing function used during the animation
    • edges(optional) EdgeId[]|EdgeList List of affected edges. If nothing provided, the adjacent edges to the node list is used.
    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.
    • nodes(optional) NodeId[]|NodeList List of affected nodes. If nothing provided, the whole graph will be used. If edges are provided too, then this list will be augmented with reached nodes from the passed edge list.
    • onEnd(optional) function(): void Function called after the last graph update
    • onSync(optional) function(): void Function called every time the graph is updated
    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout. Improves performance and user experience.
    • sortBy(optional) string Indicates the property from which the nodes must be sorted, or 'random'. You can use 'radius', 'degree' or custom data attributes.
    • useWebWorker(optional) boolean[=true] Indicates if the layout should be computed inside a web worker.

Returns

  • Promise<void>

ogma.layouts.force(params) ​

Force-directed layout.

Arguments

  • params object See LayoutOptions for common layout options.

    • alignSiblings(optional) boolean[=false] Align nodes that are linked to the same two nodes only. It enhances readability. This operation is performed once the main layout is finished.

    • autoStop(optional) autoStop[=false] Stop layout earlier if the algorithm decides that it has converged to a stable configuration. It can make the algorithm run much faster and would require fewer iterations if you are restarting the layout after it has already converged.

    • charge(optional) number[=10] Distance factor between nodes. A greater value increases the distance.

    • cx(optional) number X coordinate of the layout mass center.

    • cy(optional) number Y coordinate of the layout mass center.

    • duration(optional) number[=300] Duration of the animation when the graph is updated

    • easing(optional) Easing[='cubicOut'] Easing function used during the animation

    • edgeLength(optional) number[=30] Desired length of an edge connecting 2 nodes.

    • edgeStrength(optional) number[=0.75] Attraction strength. Higher values make edges' attractive force stronger.

    • edgeWeight(optional) function(Edge):number Use this getter to modify individual weight. 0 means that the edge will be ignored.

    • edges(optional) EdgeId[]|EdgeList List of affected edges. If nothing provided, the adjacent edges to the node list is used.

    • elasticity(optional) number[=0.9] Node collision elasticity. Smaller values may result in incomplete node overlap removal. Passing 0 will skip that algorithm pass altogether.

    • gpu(optional) boolean[=false] Enable GPU acceleration using WebGL. It makes the algoritm run faster and produce higher quality layouts. You cannot use Web Workers together with gpu accelearation, so useWebWorker is ignored if gpu: true.

    • gravity(optional) number[=0.015] Force that attracts nodes to the center of the graph. Center is either the mass center of the graph or the value defined by cx and cy. Greater value makes the layout more compact.

    • incremental(optional) boolean | object[=false] Enable the incremental layout using Force layout. When true is uses the default options.

      • margin (optional) number[=5] Will apply Force layout to the group and place the resulting configuration in the closest available position, maintaining a margin.
      • referenceNodes(optional) NodeId[]|NodeList

    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.

    • nodeMass(optional) function(Node):number Use this getter to assign individual node masses. Avoid very small masses, as it can lead to numerical instability.

    • nodes(optional) NodeId[]|NodeList List of affected nodes. If nothing provided, the whole graph will be used. If edges are provided too, then this list will be augmented with reached nodes from the passed edge list.

    • onEnd(optional) function(): void Function called after the last graph update

    • onSync(optional) function(): void Function called every time the graph is updated

    • radiusRatio(optional) number[=1.25] Radius ratio is used to allow for small gaps between the nodes while avoiding the overlapping.

    • siblingsOffset(optional) number[=0.0] Additional offset between the node siblings, so that the distance to the next node in the row would be r * (1 + siblingsOffset), where r is the previous node's radius.

    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout.

    • steps(optional) number[=300] Iteration steps limit and cooling ratio.

    • theta(optional) number[=0.62] Theta parameter of the Barnes-Hut optimization. Plays the role of the precision in repulsive forces approximation.

    • useWebWorker(optional) boolean[=true] Indicates if the layout should be computed inside a web worker

Returns

  • Promise<void>

Force link layout.

Arguments

  • params object See LayoutOptions for common layout options.

    • alignNodeSiblings(optional) boolean[=true] Align nodes that are linked to the same two nodes only. It enhances readability. This operation is performed once the main layout is finished.

    • autoStop(optional) boolean[=true] The layout stops automatically if true.

    • avgDistanceThreshold(optional) number[=0.01] This is the normal stopping condition of autoStop: true. When the average displacements of nodes is below this threshold, the layout stops.

    • barnesHutOptimize(optional) boolean[=false] Should we use the algorithm's Barnes-Hut to improve repulsion's scalability (O(n²) to O(nlog(n)))? This is useful for large graphs (5000+ nodes) but harmful to small ones.

    • barnesHutTheta(optional) number[=0.5] Theta parameter of the Barnes-Hut optimization.

    • duration(optional) number[=300] Duration of the animation when the graph is updated

    • easing(optional) Easing[='cubicOut'] Easing function used during the animation

    • edgeWeight(optional) function(edge:Edge):number Use this getter to modify edge weight. 0 means that the edge will be ignored

    • edgeWeightInfluence(optional) number[=0] Increase attraction force between nodes connected with edges of positive weights. Disabled by default.

    • edges(optional) EdgeId[]|EdgeList List of affected edges. If nothing provided, the adjacent edges to the node list is used.

    • gravity(optional) number[=1] Force which attracts nodes to the center of the graph. A greater value makes the graph more compact.

    • incremental(optional) boolean | object[=false] Enable the incremental layout using Force layout. When true is uses the default options.

      • margin (optional) number[=5] Will apply Force layout to the group and place the resulting configuration in the closest available position, maintaining a margin.
      • referenceNodes(optional) NodeId[]|NodeList

    • iterationsPerRender(optional) number[=10] Number of iterations to be run before each update of the graph visualization.

    • linLogMode(optional) boolean[=false] Alternative energy model with linear repulsion force and logarithmic attraction force.

    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.

    • maxIterations(optional) number[=1000] Set a limit to the number of iterations if autoStop: true.

    • nodeMass(optional) function(node:Node):number Use this getter to assign node masses. Node degree is passed in for convenience.

    • nodeSiblingsAngleMin(optional) number[=0] Force a minimal angle between aligned nodes (from 0 to PI / 2). Node labels may indeed overlap on horizontally aligned nodes.

    • nodeSiblingsScale(optional) number[=5] Distance multiplier between the aligned nodes.

    • nodes(optional) NodeId[]|NodeList List of affected nodes. If nothing provided, the whole graph will be used. If edges are provided too, then this list will be augmented with reached nodes from the passed edge list.

    • onEnd(optional) function(): void Function called after the last graph update

    • onSync(optional) function(): void Function called every time the graph is updated

    • outboundAttractionDistribution(optional) boolean[=false] Attract super-nodes (with many edges) to the outside.

    • scalingRatio(optional) number[=100] Distance factor between nodes. A greater value increases the distance.

    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout. Improves performance and user experience.

    • slowDown(optional) number[=1] Reduces the speed of node displacements as the number of iterations increases.

    • startingIterations(optional) number[=10] Number of iterations to be run before the first update of the graph visualization.

    • strongGravityMode(optional) boolean[=true] Enable a gravity formula to have a strong effect.

    • useWebWorker(optional) boolean[=true] Indicates if the layout should be computed inside a web worker.

  • randomize(optional) string Whether to randomize the node positions before running the layout. Possible values are locally and globally. Locally means that the node coordinate will be shuffled around its current position, whereas with globally it will be assigned a new random value.

  • randomizeFactor(optional) number[=1] [1] Randomization scaling factor.

Returns

  • Promise<void>

ogma.layouts.grid(params) ​

Arrange the nodes in a grid.

Arguments

  • params object See LayoutOptions for common layout options.
    • colDistance(optional) number Desired distance between the columns of nodes. It should be a positive number and it will be uniformly applied to the whole layout.
    • cols(optional) number Indicates the desired number of cols. If neither rows or cols are specified, the layout will attempt to make a square.
    • duration(optional) number[=300] Duration of the animation when the graph is updated
    • easing(optional) Easing[='cubicOut'] Easing function used during the animation
    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.
    • nodes(optional) NodeId[]|NodeList List of affected nodes. If nothing provided, the whole graph will be used
    • onEnd(optional) function(): void Function called after the last graph update
    • onSync(optional) function(): void Function called every time the graph is updated
    • reverse(optional) boolean [false] If true, the nodes will be sorted in reverse order.
    • rowDistance(optional) number Desired distance between the rows of nodes. It should be a positive number and it will be uniformly applied to the whole layout.
    • rows(optional) number Indicates the desired number of rows. If neither rows or cols are specified, the layout will attempt to make a square.
    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout. Improves performance and user experience.
    • sortBy(optional) PropertyPath Indicates the property from which the nodes must be sorted. Can also be 'random', in which case the node order is randomized. 'degree' is a possible value, too.
    • sortFallbackValue(optional) any Use this value for the nodes, for which the sorting attribute is undefined.
    • useWebWorker(optional) boolean[=true] Indicates if the layout should be computed inside a web worker.

Returns

  • Promise<void>

ogma.layouts.hierarchical(params) ​

The hierarchical layout positions nodes starting from a root nodes downwards generating a visual hierarchy based on connectivity.

When the user provides the root nodes then the algorithm positions the cascading nodes based on their graph-theoretical distance. When root nodes are not provided then the algorithm works out the best top node in order to reduce the number of layers (depth) of the hierarchy. It is possibile to impose constraints to the layout in order to set specific layers (depth) for each node using a numeric layer data attribute.
If you want to force a node to be at the top or the bottom of the layering, look at the roots and sinks parameters.

If there are subgraphs or nodes not reachable from the central node, they will be layouted separately. It is possibile to control how these subgraphs are positioned.

Arguments

  • params object See LayoutOptions for common layout options.
    • arrangeComponents(optional) "fit"|"grid"|"singleLine"[='fit'] Desired fit for multiple disconnected components: "fit" attempt to optimize the screen space; "grid" adds a special behaviour for isolated nodes, arranging them together in a grid, then fit on the screen; "singleLine" arrange all disconnected components alongside.
    • componentDistance(optional) number[=25] Desired distance between disconnected components
    • direction(optional) "TB"|"BT"|"LR"|"RL"[='TB'] Layout direction: Top-bottom/bottom-top/left-right/right-left.
    • duration(optional) number[=300] Duration of the animation when the graph is updated
    • easing(optional) Easing[='cubicOut'] Easing function used during the animation
    • edges(optional) EdgeId[]|EdgeList List of affected edges. If nothing provided, the adjacent edges to the node list is used.
    • gapWidth(optional) number[=1] Desidered width of gap spaces between nodes not sequentially next to each other (siblings). This is an advanced parameter, often not required to change, it is similar to the previous "edgeDistance" parameter in Dagre. Expressed in percentage (%) from 1 to 100.
    • gridDistance(optional) number[=50] Desidered distance between isolated nodes when arranged in grid. Used only when "grid" arrangeComponent is enabled.
    • layer(optional) string Data field defining the layer of the node in the hierarchy
    • levelDistance(optional) number[=50] Desired distance between the layers of layout
    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.
    • nodeDistance(optional) number[=5] Desired distance between the nodes on one layer
    • nodes(optional) NodeId[]|NodeList List of affected nodes. If nothing provided, the whole graph will be used. If edges are provided too, then this list will be augmented with reached nodes from the passed edge list.
    • onEnd(optional) function(): void Function called after the last graph update
    • onSync(optional) function(): void Function called every time the graph is updated
    • roots(optional) NodeId[]|NodeList[=[]] List of nodes to put at the top of the hierarchy
    • sinks(optional) NodeId[]|NodeList[=[]] List of nodes to put at the bottom of the hierarchy
    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout. Improves performance and user experience.

Returns

  • Promise<void>

ogma.layouts.radial(params) ​

Radial (concentric) layout positions nodes around the selected one based on their graph-theoretical distance (shortest path in the graph, connecting them). If there are subgraphs or nodes not reachable from the central node, they will be pushed outwards, but still placed around the layout in a readable way.

Arguments

  • params object See LayoutOptions for common layout options.
    • allowOverlap(optional) boolean[=false] Specifies if nodes are allowed to overlap.
    • centerX(optional) number X coordinate where the central node must be moved, if different from the central node X
    • centerY(optional) number Y coordinate where the central node must be moved, if different from the central node Y
    • centralNode Node|NodeId Id of the central node
    • duration(optional) number[=300] Duration of the animation when the graph is updated
    • easing(optional) Easing[='cubicOut'] Easing function used during the animation
    • epsilon(optional) number[=0.001] Layout precision. Smaller number means better precision but longer computation time
    • iterationsPerRender(optional) number[=20] Layout iterations per update.
    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.
    • maxIterations(optional) number[=100] Maximum number of layout sweeps
    • nodeGap(optional) number[=10] Additional gap between the nodes that belong to one layer
    • nodes(optional) Array<NodeId>|NodeList List of affected nodes. If nothing provided, the whole graph will be used.
    • onEnd(optional) function(): void Function called after the last graph update
    • onSync(optional) function(): void Function called every time the graph is updated
    • radiusDelta(optional) number[=0] You can specify a constant distance between the layout layers, in this case radiusRatio will be ignored
    • radiusRatio(optional) number[=Math.SQRT2] Ratio between the radii of adjacent concentric layers: R[n+1] = R[n] × ratio
    • renderSteps(optional) boolean[=false] Render intermediate results, before the algorithm converges. That means sending the calculated positions every iterationsPerRender iterations.
    • repulsion(optional) number[=1] Increase or decrease the repulsion force between the nodes on the same levels. Values smaller than 1 will result in more compact placement along the layers.
    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout. Improves performance and user experience.
    • useWebWorker(optional) boolean[=true] Indicates if the layout should be computed inside a web worker.

Returns

  • Promise<void>

ogma.layouts.sequential(params) ​

The sequential layout positions nodes starting from a root nodes downwards generating a visual hierarchy based on connectivity with a costant width.

When the user provides the root nodes then the algorithm positions the cascading nodes based on their graph-theoretical distance. When root nodes are not provided then the algorithm works out the best top node in order to reduce the number of layers (depth) of the hierarchy. It is possibile to impose constraints to the layout in order to set specific layers (depth) for each node using a numeric layer data attribute.
If you want to force a node to be at the top or the bottom of the layering, look at the roots and sinks parameters.

If there are subgraphs or nodes not reachable from the central node, they will be layouted separately. It is possibile to control how these subgraphs are positioned.

Arguments

  • params object See LayoutOptions for common layout options.
    • arrangeComponents(optional) "fit"|"grid"|"singleLine"[='fit'] Desired fit for multiple disconnected components: "fit" attempt to optimize the screen space; "grid" adds a special behaviour for isolated nodes, arranging them together in a grid, then fit on the screen; "singleLine" arrange all disconnected components alongside.
    • componentDistance(optional) number[=50] Desired distance between the components in the layout
    • direction(optional) "TB"|"BT"|"LR"|"RL"[='TB'] Layout direction: Top-bottom/bottom-top/left-right/right-left.
    • duration(optional) number[=300] Duration of the animation when the graph is updated
    • easing(optional) Easing[='cubicOut'] Easing function used during the animation
    • edges(optional) EdgeId[]|EdgeList List of affected edges. If nothing provided, the adjacent edges to the node list is used.
    • gridDistance(optional) number[=50] Desidered distance between isolated nodes when arranged in grid. Used only when "grid" arrangeComponent is enabled.
    • levelDistance(optional) number[=50] Desired distance between the layers of layout
    • locate(optional) boolean|LocateOptions[=false] Center on the graph bounding box when the layout is complete. You can also provide padding.
    • nodeDistance(optional) number[=50] Desired distance between the nodes on one layer
    • nodes(optional) NodeId[]|NodeList List of affected nodes. If nothing provided, the whole graph will be used. If edges are provided too, then this list will be augmented with reached nodes from the passed edge list.
    • onEnd(optional) function(): void Function called after the last graph update
    • onSync(optional) function(): void Function called every time the graph is updated
    • roots(optional) NodeId[]|NodeList[=[]] List of nodes to put at the top of the hierarchy
    • sinks(optional) NodeId[]|NodeList[=[]] List of nodes to put at the bottom of the hierarchy
    • skipTextDrawing(optional) boolean[=true] Skip drawing labels during the layout. Improves performance and user experience.

Returns

  • Promise<void>

ogma.layouts.stop() ​

Stops currently running layout