ktsu.ImGui.NodeEditor 3.26.0

ktsu.ImGui.NodeEditor

ImGui.NodeEditor is a visual node editor built on ImNodes, with the graph itself kept away from the drawing. NodeEditorEngine owns nodes, links and the physics that lays them out and knows nothing about ImGui; NodeEditorRenderer draws whatever the engine holds; NodeEditorInputHandler turns a frame's interactions into requests the engine can accept or refuse. Nodes can be declared as ordinary types decorated with ktsu.NodeGraph attributes and instantiated by reflection.

Features

• Separation of concerns: business logic (NodeEditorEngine), rendering (NodeEditorRenderer), and input (NodeEditorInputHandler) are separate objects, so the graph can be built and tested without a renderer
• Tuning panel: PhysicsSettingsPanel draws every layout setting, grouped and captioned, so a graph can be tuned while it is on screen
• Attribute-based nodes: AttributeBasedNodeFactory reads ktsu.NodeGraph attributes off a type — or every decorated type in an assembly — and creates nodes with the right pins
• Physics is opt-in: the simulation does nothing until PhysicsSettings.Enabled is set, so a host that positions nodes itself pays nothing for it
• Type-aware connections: TryCreateLink returns a result with a message rather than throwing, and pin compatibility comes from the same rules the metadata declares
• Physics-based layout: nodes repel, links pull, and the graph settles; powered by ktsu.ForceDirectedLayout, with per-frame stability and energy readings for debug overlays
• Drag-aware: nodes being dragged are excluded from the simulation, and the renderer reports position and size changes back to the engine

Installation

Package Manager Console

Install-Package ktsu.ImGui.NodeEditor

.NET CLI

dotnet add package ktsu.ImGui.NodeEditor

Package Reference

<PackageReference Include="ktsu.ImGui.NodeEditor" Version="x.y.z" />

ImNodes must be initialized before the editor draws. ktsu.ImGui.App detects and sets up the extension automatically; in a host that does not, initialize ImNodes yourself as its bindings document.

Usage Examples

Basic Example

using System.Numerics;

using Hexa.NET.ImGui;

using ktsu.ImGui.NodeEditor;

private readonly NodeEditorEngine engine = new();
private readonly NodeEditorRenderer renderer = new();
private readonly NodeEditorInputHandler input = new();

// Build a graph
Node source = engine.CreateNode(new Vector2(200, 200), "Source", [], ["Value"]);
Node target = engine.CreateNode(new Vector2(500, 200), "Target", ["Source.Value"], []);
engine.TryCreateLink(source.OutputPins[0].Id, target.InputPins[0].Id);

// Draw it, once per frame
void DrawGraph(float deltaTime)
{
    renderer.Render(engine, ImGui.GetContentRegionAvail());

    // The renderer measures what ImNodes actually laid out; hand that back to the engine
    foreach ((int id, Vector2 position) in renderer.GetNodePositionUpdates(engine))
    {
        engine.UpdateNodePosition(id, position);
    }

    foreach ((int id, Vector2 dimensions) in renderer.GetNodeDimensionUpdates(engine))
    {
        engine.UpdateNodeDimensions(id, dimensions);
    }

    // Apply what the user did this frame
    InputEvents events = input.ProcessInput();
    foreach (LinkCreationRequest request in events.LinkCreationRequests)
    {
        engine.TryCreateLink(request.FromPinId, request.ToPinId);
    }

    foreach (int linkId in events.LinkDeletionRequests)
    {
        engine.RemoveLink(linkId);
    }

    engine.SetDraggedNodes(renderer.CurrentlyDraggedNodes);
    engine.UpdatePhysics(deltaTime);
}

Nodes from decorated types

using ktsu.NodeGraph;

[Node("Add")]
public class AddNode
{
    [InputPin("A")] public double A { get; set; }
    [InputPin("B")] public double B { get; set; }
    [OutputPin("Sum")] public double Sum { get; private set; }

    [NodeExecute]
    public void Execute() => Sum = A + B;
}

AttributeBasedNodeFactory factory = new(engine);
factory.RegisterNodeType<AddNode>();
factory.RegisterNodeTypesFromAssembly(typeof(AddNode).Assembly);

Node node = factory.CreateNode<AddNode>(new Vector2(100, 100));

GetAllNodeDefinitions() returns the registered definitions, which is what a "add node" menu is built from: each one carries the display name, category, tags, execution mode, deprecation state and pin list read off the attributes.

Two things to know about registration. A class node also gets an Instance output pin (and input pins for its constructor's parameters), so it can be chained onward. And RegisterNodeTypesFromAssembly skips abstract types — which in IL includes every static class — so a [Node] method parked on a static holder class has to be registered by naming that holder: factory.RegisterNodeType(typeof(MathNodes)).

Tuning the layout

engine.UpdatePhysicsSettings(new PhysicsSettings
{
    Enabled = true,
    RepulsionStrength = 1_200_000.0,
    LinkSpringStrength = 0.5,
    RestLinkLength = 225.0,
});

// Readings worth putting behind a debug toggle
float energy = engine.TotalSystemEnergy;
(int substeps, float substepDelta) = engine.LastPhysicsStepInfo;
renderer.RenderDebugOverlays(engine, editorPosition, editorSize, showDebug: true);

API Reference

NodeEditorEngine

The graph and its physics. No ImGui calls.

NodeEditorRenderer

PhysicsSettingsPanel

The forces interact, so none can be judged alone: raising repulsion changes what the spring's rest length means, and levelling links only works in the room repulsion made. The panel therefore exposes the whole of PhysicsSettings rather than a chosen subset — a setting that is not on it is one nobody can reach without recompiling. Every control marks itself with ktsu.ImGui.Probes, so a UI test can address it by the label the user sees.

PhysicsSettings settings = engine.PhysicsSettings;
if (PhysicsSettingsPanel.Draw(ref settings))
{
    engine.UpdatePhysicsSettings(settings);
}

PhysicsSettingsPanel.DrawDiagnostics(engine);

NodeEditorInputHandler

ProcessInput() returns InputEvents, holding LinkCreationRequests (LinkCreationRequest(FromPinId, ToPinId)) and LinkDeletionRequests.

AttributeBasedNodeFactory

Domain models

Node(Id, Position, Name, InputPins, OutputPins, Dimensions, Velocity, Force, IsPinned), Link(Id, OutputPinId, InputPinId) and Pin(Id, Direction, Name, DisplayName) are records; PinDirection is Input or Output.

Acknowledgments

• Dear ImGui - The immediate mode GUI library the editor draws into
• Hexa.NET.ImGui - The .NET bindings for Dear ImGui, and for Hexa.NET.ImNodes, the node editor extension this renders through
• ktsu.Semantics - ktsu.Semantics.Quantities for typed quantities in the physics settings

ktsu.NodeGraph supplies the node metadata and ktsu.ForceDirectedLayout the physics; both ship from this repository.

Contributing

Contributions are welcome! For feature requests, bug reports, or questions, please open an issue on the GitHub repository. If you would like to contribute code, please open a pull request with your changes.

License

ImGui.NodeEditor is licensed under the MIT License. See LICENSE.md for more information.