elk

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2026 License: EPL-2.0 Imports: 7 Imported by: 0

README

elk-go

elk-go is a native Go port of the Eclipse Layout Kernel behavior used by D2. Its compatibility target is D2's ELK integration running against the exact official ELK.js 0.12.0 release; it is not a general drop-in replacement for every ELK option combination.

The port is based on:

ELK.js compiles ELK's Java algorithms to JavaScript with GWT. This repository translates the provider registry used by D2 to Go while preserving the ordering, option-default, and floating-point behavior observable on that path. It registers D2's 11 selectable 0.12 algorithms: Fixed, Box, Random, Layered, Stress, MR Tree, Radial, Force, SPOrE Overlap, SPOrE Compaction, and Rectangle Packing. ELK.js removed DisCo from its bundled algorithm surface after 0.8.2, so it is not registered by this version.

D2's default and documented engine is Layered. Its complete D2 option profile, including compounds, ports, self loops, labels, model order, and orthogonal routing, is the primary end-to-end compatibility contract. Exact, deterministic oracle fixtures cover all eleven registered providers. D2 also smoke-tests its literal provider defaults; unseeded Random and the two SPOrE providers use finite-output checks because those default calls are nondeterministic.

The contract tests vary algorithm selection, all four directions, nodeNodeBetweenLayers, padding, edgeNodeBetweenLayers, and nodeSelfLoop, and include compound graphs, ports, inline edge labels, and self loops. Each scalar option pair is also required to change official-oracle geometry, which guards against a silently ignored option.

The option metadata exposed by the Go registry matches the official 0.12 bundle so D2 can resolve its option IDs consistently. Metadata presence is not an execution guarantee for expert ELK configurations outside D2's profile. Known out-of-scope Layered values include SCC_CONNECTIVITY and BFS_NODE_ORDER cycle breaking; LONGEST_PATH_SOURCE, BF_MODEL_ORDER, and DF_MODEL_ORDER layering; and MEDIAN_LAYER_SWEEP crossing minimization.

API

The public graph types mirror ELK JSON. Layout can be requested either with a typed graph or with JSON:

graph := &elk.Graph{
    ID: elk.StringID("root"),
    LayoutOptions: elk.LayoutOptions{
        "elk.algorithm": "layered",
        "elk.direction": "DOWN",
    },
    Children: []*elk.Node{
        {ID: elk.StringID("a"), Width: elk.Float64(80), Height: elk.Float64(40)},
        {ID: elk.StringID("b"), Width: elk.Float64(80), Height: elk.Float64(40)},
    },
    Edges: []*elk.Edge{
        {ID: elk.StringID("e"), Sources: []elk.ID{elk.StringID("a")}, Targets: []elk.ID{elk.StringID("b")}},
    },
}

if err := elk.Layout(graph); err != nil {
    // handle the layout error
}

Compatibility testing

Normal tests are pure Go:

go test ./...
go test -race ./...
go vet ./...

Development differentials compare ordered ELK JSON output with the official ELK.js 0.12.0 oracle. IDs, element order, topology, edge-section structure, field presence, and coordinates are exact for the provider matrix, curated D2 fixtures, D2-profile random cases, codec behavior used by D2, and the complete captured D2 corpus. Broader provider and expert-option probes are development diagnostics, not part of the supported D2 contract. See internal/oracle for the opt-in oracle setup.

License

This program is available under the Eclipse Public License 2.0. Two attributed GWT runtime adaptations retain the Apache License 2.0; the V8/fdlibm math adaptation retains its BSD-3-Clause and SunPro terms. See LICENSE, LICENSE.apache-2.0, LICENSE.v8-bsd, NOTICE.md, the preserved NOTICE.eclipse-elk.md, and PROVENANCE.md.

Documentation

Overview

Package elk provides a native Go implementation of the Eclipse Layout Kernel JSON behavior used by D2, pinned to official ELK.js 0.12.0. It does not promise compatibility with expert option combinations outside D2's documented profile.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Float64 

func Float64(value float64) *float64

Float64 returns a pointer suitable for optional numeric graph fields.

func Layout 

func Layout(input *Graph) error

Layout computes layout in place. Like elkjs, it preserves the input graph's element and slice order and adds computed shape and edge-route fields.

func LayoutJSON 

func LayoutJSON(input []byte) ([]byte, error)

LayoutJSON is the byte-oriented equivalent of Layout.

func Number 

func Number(value *float64) float64

Number returns value, or zero when value is nil.

func String 

func String(value string) *string

String returns a pointer suitable for optional text fields.

Types

type Edge 

type Edge = graphjson.Edge

Edge is an ELK JSON edge.

type EdgeSection 

type EdgeSection = graphjson.EdgeSection

EdgeSection is a routed section of an ELK JSON edge.

type Graph 

type Graph = graphjson.Graph

Graph is the root ELK JSON graph type.

type ID 

type ID = graphjson.ID

ID is a string- or integer-valued ELK graph identifier.

func IDPtr 

func IDPtr(id ID) *ID

IDPtr returns a pointer to a copy of id.

func IntID 

func IntID(value int64) ID

IntID constructs an integer-valued graph identifier.

func StringID 

func StringID(value string) ID

StringID constructs a string-valued graph identifier.

type Label 

type Label = graphjson.Label

Label is an ELK JSON label.

type LayoutOptions 

type LayoutOptions = graphjson.LayoutOptions

LayoutOptions maps ELK option identifiers to their JSON values.

type Node 

type Node = graphjson.Node

Node is an ELK JSON node.

type Point 

type Point = graphjson.Point

Point is an ELK JSON bend or junction point.

type Port 

type Port = graphjson.Port

Port is an ELK JSON port.

Source Files

View all Source files

Directories

Path Synopsis
cmd
elk-go command
Package graphjson defines ELK's JSON graph interchange model.
 Package graphjson defines ELK's JSON graph interchange model.
internal
basic
Package basic registers ELK's three core utility layout providers.
 Package basic registers ELK's three core utility layout providers.
basicoptions
Package basicoptions contains the core options whose defaults are specialized by ELK's fixed, box, and random utility algorithms.
 Package basicoptions contains the core options whose defaults are specialized by ELK's fixed, box, and random utility algorithms.
box
Package box implements org.eclipse.elk.box from ELK 0.12.0.
 Package box implements org.eclipse.elk.box from ELK 0.12.0.
builtins
Package builtins registers the layout providers compiled into ELK.js 0.12.0.
 Package builtins registers the layout providers compiled into ELK.js 0.12.0.
common/elkutil
Package elkutil ports the core ElkUtil operations shared by native layout providers.
 Package elkutil ports the core ElkUtil operations shared by native layout providers.
common/networksimplex
Package networksimplex implements ELK's deterministic network-simplex layering primitive.
 Package networksimplex implements ELK's deterministic network-simplex layering primitive.
common/nodespacing
core
Package core implements ELK metadata, JSON conversion, and recursive layout.
 Package core implements ELK metadata, JSON conversion, and recursive layout.
fixed
Package fixed implements org.eclipse.elk.fixed from ELK 0.8.1.
 Package fixed implements org.eclipse.elk.fixed from ELK 0.8.1.
force
Package force is a native Go port of org.eclipse.elk.force targeting ELK.js 0.12.0.
 Package force is a native Go port of org.eclipse.elk.force targeting ELK.js 0.12.0.
geometry
Package geometry implements ELK's core two-dimensional data types.
 Package geometry implements ELK's core two-dimensional data types.
graph
Package graph implements ELK's mutable graph as deterministic typed arenas.
 Package graph implements ELK's mutable graph as deterministic typed arenas.
javacompat
Package javacompat contains the small parts of the Java runtime whose exact behavior is observable in ELK layouts.
 Package javacompat contains the small parts of the Java runtime whose exact behavior is observable in ELK layouts.
layered
Package layered implements ELK Layered's internal graph and five-phase layout pipeline.
 Package layered implements ELK Layered's internal graph and five-phase layout pipeline.
layered/components
Package components ports ELK Layered 0.8.1's connected-components split and packing stage.
 Package components ports ELK Layered 0.8.1's connected-components split and packing stage.
layered/intermediate
Package intermediate contains the processors run between ELK Layered's five main phases.
 Package intermediate contains the processors run between ELK Layered's five main phases.
layered/intermediate/loops
Package loops contains ELK Layered 0.8.1's temporary self-loop model.
 Package loops contains ELK Layered 0.8.1's temporary self-loop model.
layered/intermediate/loops/ordering
layered/intermediate/loops/routing
layered/intermediate/preserveorder
Package preserveorder ports ELK Layered's stateful model-order comparators.
 Package preserveorder ports ELK Layered's stateful model-order comparators.
layered/intermediate/unzipping
Package unzipping ports ELK Layered's post-crossing-minimization layer splitting processors.
 Package unzipping ports ELK Layered's post-crossing-minimization layer splitting processors.
layered/intermediate/wrapping
layered/p1cycles
Package p1cycles implements ELK Layered phase 1.
 Package p1cycles implements ELK Layered phase 1.
layered/p2layers
Package p2layers implements ELK Layered phase 2.
 Package p2layers implements ELK Layered phase 2.
layered/p3order
layered/p4nodes
layered/p5edges
Package p5edges implements the fifth phase of ELK Layered 0.8.1.
 Package p5edges implements the fifth phase of ELK Layered 0.8.1.
layered/p5edges/orthogonal
layeredlayout
Package layeredlayout connects ELK Layered's internal five-phase pipeline to the core graph engine.
 Package layeredlayout connects ELK Layered's internal five-phase pipeline to the core graph engine.
mrtree
Package mrtree is a native Go port of ELK Mr.
 Package mrtree is a native Go port of ELK Mr.
oracle
Package oracle provides the pinned elkjs 0.12.0 differential oracle used while porting ELK to Go.
 Package oracle provides the pinned elkjs 0.12.0 differential oracle used while porting ELK to Go.
radial
Package radial is a native Go port of ELK Radial targeting ELK.js 0.12.0.
 Package radial is a native Go port of ELK Radial targeting ELK.js 0.12.0.
random
Package random implements org.eclipse.elk.random from ELK 0.12.0.
 Package random implements org.eclipse.elk.random from ELK 0.12.0.
rectpacking
Package rectpacking ports org.eclipse.elk.alg.rectpacking from ELK 0.12.0.
 Package rectpacking ports org.eclipse.elk.alg.rectpacking from ELK 0.12.0.
spore
Package spore is a native Go port of the SPOrE overlap-removal and compaction providers targeting ELK.js 0.12.0 behavior.
 Package spore is a native Go port of the SPOrE overlap-removal and compaction providers targeting ELK.js 0.12.0 behavior.
stress
Package stress ports org.eclipse.elk.stress targeting ELK.js 0.12.0 while retaining the historical ELK 0.8.1 source mapping for unchanged routines.
 Package stress ports org.eclipse.elk.stress targeting ELK.js 0.12.0 while retaining the historical ELK 0.8.1 source mapping for unchanged routines.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.