netviz layout

Store the diagram's arrangement in the inventory, so a diagram that has been arranged stays arranged.

Everywhere else in netviz, the picture is derived: you describe the network and Graphviz decides where things go. That is the right default and it is what render still does. But it means the diagram cannot be edited — drag a switch to where it belongs and the next render puts it back, because nothing in the tree remembers that you moved it. netviz layout is what makes the arrangement part of the model: a kind: layout document holding a position per node — and, when asked, the route each link takes and the style it is drawn in — scoped by view, loaded, validated and edited like everything else.

Once a view is arranged, render reproduces it exactly — the same coordinates in the SVG, the same coordinates in the HTML, the same coordinates in the JSON export.

docs/schema.md §18 is the document format. docs/rendering.md is how the renderers honour it. This page is the reference for the command.

Synopsis

netviz [GLOBAL OPTIONS] layout [OPTIONS]

The four things it does

With no flags it reports. One row per view: how much of the drawing the stored arrangement decides, how many nodes are placed, and how many stored keys name nothing the diagram has.

$ netviz layout --layer l1 --layer l2
layout documents: layout
VIEW  MODE     NODES  EDGES  GROUPS  STALE
----  -------  -----  -----  ------  -----
l1    fixed    8/8    0/7    0/0     -
l2    partial  6/8    0/7    0/0     1

MODE is the decision a render makes from what is stored:

--write seeds and completes. On a view with no arrangement it runs the automatic layout once and persists the result, which is what makes the diagram editable from then on. On a view that is already arranged it places only what is not yet placed — adding a switch and re-seeding must not throw away an afternoon of arranging. --replace is how you ask for the whole view to be laid out afresh.

netviz layout --write                       # place what is not placed yet
netviz layout --write --replace             # lay every node out afresh
netviz layout --write --engine circo        # ... with a different engine
netviz layout --write --layer l1 --layer l3 # arrange two views
netviz layout --write --dry-run             # print the diff, write nothing

What is written is a fixed point: the coordinates stored are the coordinates the next render produces, not the ones the seeding engine happened to report. (The two differ — a no-op render normalises the drawing to the origin — and an arrangement that only settled on the second render would be a poor thing to promise.)

--prune drops what is gone. Deleting a switch leaves its coordinates behind. They draw nothing, but they accumulate, and W138 reports them until this clears them. A prune on a clean tree writes no files.

--clear goes back to automatic. The arrangement for the selected views is dropped; a layout document left holding nothing is removed, and so is its file if it held nothing else.

The display options are inputs, not decoration

--show-ips, --show-vlans, --group-by-namespace, --icons, --rankdir and the rest are on this command for a reason that is easy to miss: a label decides how big a node is, and how big the nodes are decides where the layout puts them. An arrangement seeded with --no-show-ips and rendered with addresses on is an arrangement of boxes that are now too small for their contents.

So seed with the options you render with. Better, put them in netviz.toml — this command reads [render] and --profile exactly as render does, which is the only way to be sure the two cannot drift apart.

The filter options are deliberately absent. An arrangement covers a view; one seeded from three of a hundred devices would leave the other ninety-seven unplaced and the diagram permanently half-arranged.

What it stores, and what it does not

Positions, in points, y upwards, a position being the centre of the node — Graphviz's coordinate system, unchanged, because the whole point is to be able to hand it straight back.

Group boxes too, when the render groups by namespace: the no-op layout engine does not draw clusters, so netviz draws them itself from the stored box, which means the frame is where you put it rather than wherever a layout happened to land. Its caption sits centred above the frame rather than inside it — docs/follow-ups.md §17 explains why that is not a matter of taste.

--waypoints also stores the routes, as the interior bends of each link — the two ends of a route are always the nodes themselves, so a stored route survives either device being dragged. It is off by default because a seeded route is a handful of points per link that the render recomputes identically, and that is a lot of noise for no decision; a hand-placed bend is a decision, and the flag is how you get a starting point to drag one from. It brings the sizes of the nodes those routes leave from with it, which is the one case where a stored size is worth having: a route netviz computes has to stop at the shape it runs into, and netviz cannot measure a label. Every other node is left sized by its label, because Graphviz derives the same box from the same label on every run and a stored size would go stale the moment a device grew an interface (docs/follow-ups.md §16).

--routing records how this view's links are drawn — spline, orthogonal or straight — as views.<view>.routing. The same flag every other command takes, doing both jobs at once here: the seeding run draws in that style, and --write then records it, so what is stored is what was on screen. It is a default: a link that pins a style of its own keeps it. To take the setting back out, delete the one line it wrote — a generated file that has to be hand-edited to be undone is a poor thing, but a --routing "" that meant "remove" would be one keystroke away from --routing meaning "leave alone", and that is worse.

A style pinned on one link, and where a link's label sits, are decisions a person takes rather than ones a layout run can seed, so they are written by the canvas editor of netviz web instead; docs/rendering.md is what all three draw as.

Writes go through the edit layer

Every change is a netviz edit operation (set-geometry), which means it inherits the whole write path: comments and formatting in a hand-arranged file survive, --dry-run shows the exact hunk, the tree is loaded and validated as it would be before anything is written, and a file that changed on disk since it was read is refused rather than overwritten.

It also means re-seeding an unchanged diagram writes nothing at all — a stored position: [240, 396] and a computed {x: 240, y: 396} are recognised as the same position, so a generated file does not churn on spelling. A position is written on one line for the same reason: a diff of an arrangement should read as a list of what moved.

Arguments and flags

Takes no positional arguments.

Exit codes

See also

• docs/schema.md §18 — the kind: layout document, field by field.
• docs/rendering.md — how svg, html and json honour an arrangement, and what each publishes; Links are geometry too is the same for bends, routing styles and label positions.
• netviz edit — the write path this command goes through, and its two gates.
• docs/follow-ups.md §16 — why the geometry is a sidecar and not a field on each element.
• W138 — the warning --prune clears.