Data Trees Explained

Here is the exact scene where flat lists fail. You want a grid: 5 columns by 4 rows of points. You could generate 20 points, but the instant they arrive as one list of 20, you have lost the grouping. Which four form a column? Which five form a row? The list can only recite them in a single sequence - it has no way to say 'these belong together, and those belong together'.

You meet the same wall everywhere: divide ten curves and you get points for each, but a flat list of all of them muddles which points came from which curve. Split a floor plate into rooms and you want each room's data kept apart. The problem is always the same shape - you have groups of lists, and a single list is one-dimensional, so it can't hold groups without smearing them together.

You could imagine a 'list of lists', and that is exactly the right instinct. Grasshopper's data tree is that idea made rigorous and, crucially, made addressable - every sub-list gets a name so components can find it, match it, and keep it separate from its neighbours.

A data tree is a collection of lists called branches, and every branch has an address called a path. The path is written in curly braces with semicolons: {0}, {1}, or for nested groups {0;1}, {2;0;3}. Each number is one level of grouping - read it like a folder inside a folder inside a folder, with the actual items (the points, curves, numbers) living as a plain list at the end of that path.

So the full address of any single item has two parts: the path names its branch, and an index names its position within that branch's list. The point at path {0;1}, index 2 is 'the third item on the branch grouped under 0 then 1'. Path plus index is the complete coordinate of a piece of data - and once you can say it out loud, trees stop being mysterious.

Think of it as a filing cabinet. The cabinet is the tree. Each drawer is a branch, labelled with its path. Inside each drawer is an ordinary ordered list - the same list you mastered in the last lesson. Nothing new happens inside a branch; a tree is just many of last lesson's lists, filed under names. That is the whole idea, and it really is that simple once the picture lands.

You rarely build a tree by hand - components create them as a natural by-product of working on many things at once. This is the part that surprises people: the tree appears whether or not you intended it.

The classic case: wire a list of ten curves into Divide Curve. Grasshopper runs the division once per curve, and to keep each curve's points separate it puts them on their own branch - you get a tree with ten branches {0} through {9}, each holding that curve's points. It preserved the grouping for you, automatically. That is the tree doing its job.

Many components deliberately output trees: LunchBox panelling tools hand back a branch per panel row; a surface divided into a UV grid comes back as a tree organised by rows. And some components add a level of nesting whenever they process a list of lists, which is why paths sometimes grow longer than you expected - each pass through a many-in-many-out component can push another number onto the path.

The lesson is not to fear this but to expect it: whenever a component acts once per item of an incoming list, ask yourself whether its output just became a tree. Nine times out of ten it did, and knowing that turns 'why is my data weird?' into 'ah, of course - it branched'.

There's a reassuring corollary. Because branching happens for a reason - to keep separate things separate - the structure a component gives you is usually the structure you'd have wanted anyway. The ten branches from ten curves aren't clutter; they're the software refusing to lose track of which point belongs to which curve. So rather than fighting the tree the instant it appears, read it first and ask whether its grouping already matches your intent. Very often it does, and you can simply carry on.

You cannot manage what you cannot see, so the most important skill in this whole module is reading a tree - and the tool for it is the Param Viewer. Wire any output into it and it draws the tree two ways: a text list of every path with the item count on each branch, and a little diagram of the branching structure. It is the X-ray that turns invisible structure visible.

Learn to read three things off it. First, how many branches - is it one branch (really just a list) or many? Second, the path pattern - do the paths read {0}, {1}, {2} (one level) or {0;0}, {0;1} (nested), and does that match the grouping you intended? Third, the item count per branch - the Param Viewer (in text mode) shows N beside each path, and a stream of, say, four branches of three items each is a very different animal from one branch of twelve.

Pair it with a plain Panel, which shows the actual values grouped by path, and you have full visibility: the Param Viewer tells you the shape of the data, the Panel tells you the contents. When a definition misbehaves - and it will - your first move is never to rewire in a panic. It is to drop a Param Viewer on the suspect wire and simply look. Almost every tree problem announces itself plainly the moment you read the structure.

Before you move on, lock in the picture, because the people who stay comfortable with trees are the ones who carry one clear analogy and refuse to overcomplicate it.

The analogy: a tree is a filing cabinet, a branch is a drawer labelled with its path, and inside each drawer is an ordinary list - the same indexed list from the last lesson, nothing more exotic. Everything you can do to a list, you can do inside a branch; the tree just holds many of them side by side, each addressable by name. When a component 'works on a tree', it usually opens each drawer, does its job on that drawer's list, and puts the results back on a matching branch. Once you believe that, trees stop being a separate mysterious topic and become 'lists, but organised'.

Two working habits make the model pay off. First, always know your data's shape - a single number, a list, or a tree - because most confusion comes from thinking you have one when you have another. A quick Param Viewer answers it instantly. Second, respect the grouping: if the branches mean something (each floor, each room, each curve), keep them until you're truly done with that meaning. Beginners reflexively Flatten everything to 'make it simple', and in doing so throw away the exact structure that was keeping their design organised - then wonder why the next step scrambles floors together.

The emotional truth of this lesson is that trees feel hard for about a week and then feel obvious forever. Almost everyone who gives up on Grasshopper gives up right here; almost everyone who pushes through says the same thing afterwards - oh, that's all it was. Keep the filing-cabinet picture, keep the Param Viewer open, and let it click.