Node Graph Basics

Learn how to build pipelines by connecting nodes in the graph editor.

How Nodes Work

Every node in Magerie has input ports and output ports. Data flows from outputs to inputs, forming a directed acyclic graph (DAG). When you change a node's parameters or paint on a canvas, the pipeline re-evaluates downstream nodes automatically.

Port Types

Ports are typed. The system prevents invalid connections and auto-coerces compatible numeric types:

Port Type Color Description
image Blue Raster image data
number Gray Single numeric value
vector2 Green 2D coordinate (x, y)
vector3 Yellow 3D coordinate (x, y, z)
vector4 Orange 4D value (x, y, z, w)
color Red RGBA color (maps to vector4)
text White String data

Numeric Coercion

The numeric family (number, vector2, vector3, vector4, color) is fully interconvertible:

  • Upcasting pads with zeros (w defaults to 1)
  • Downcasting trims extra components
  • Color ↔ Vector4 maps r=x, g=y, b=z, a=w
// These connections are all valid:
connect(numberNode.output, colorNode.input)    // number → color: (n, 0, 0, 1)
connect(colorNode.output, numberNode.input)    // color → number: r component only
connect(vector2Node.output, vector4Node.input)  // vec2 → vec4: (x, y, 0, 1)

Building a Pipeline

Step 1: Add Nodes

Right-click on the graph background to open the node menu. Nodes are organized by category. You can also search by name.

Step 2: Connect Ports

Click and drag from an output port (right side of a node) to an input port (left side). A wire appears showing the connection.

  • Input ports accept one connection — connecting a new wire auto-disconnects the previous one
  • Output ports accept unlimited connections — one output can feed many inputs

Step 3: Adjust Parameters

Select a node to see its parameters in the inspector panel. Changes propagate downstream in real time.

Selection and Navigation

Selecting Nodes

  • Click a node to select it
  • Cmd/Ctrl + Click to add to selection
  • Click + Drag on the background for box selection
  • Cmd/Ctrl + A to select all

Navigating the Graph

  • Scroll to zoom in/out
  • Middle-click + Drag or Space + Drag to pan
  • F to frame selected nodes (zoom to fit)

Tips

Performance: Magerie evaluates nodes lazily. Only nodes whose outputs are visible or connected to a viewed canvas are computed. Disconnected branches are skipped entirely.

  1. Name your nodes — Double-click a node's title to rename it
  2. Use groups — Select multiple nodes and press Cmd/Ctrl+G to group them
  3. Collapse nodes — Press H to hide parameters and minimize visual clutter