Grasshopper Data Tree Editing

From TOI-Pedia


Data Tree

Grasshopper uses, in contrast to a programming environment, no object names to define an object. This may sound trivial but it one of the most fundamental differences from a traditional modelling environment. In Grasshopper the object or objects are placed in a list. The different lists of data are organized in a data tree structure where every branch and data content of the branch have an index number. Accessing the object is therefore more problematic then in a scripting environment. Grasshopper has various tools to remedy this problem. These tools supports the editing and selecting the content of the lists and editing the data tree structure. Knowledge of these techniques are essential for the effective use of Grasshopper.

Data tree structure

Data Tree

Multiple data will be stored in a data tree. The data tree is the hierarchical organization of the data. Each branch of the tree can contain data. This can be a variety of data , surfaces, curves, points etc. To effectively use Grasshopper a sound understanding of this structure and how to manipulate it is paramount.

This structure and handling of data is fundamentally different then when we use an environment where the name of the object can be used to define a selection. In the case of Grasshopper the data can't be accessed by its name but only as a part of a list of data. Although the lists have an index number for every data element the separate data elements can't be defined or recognized by any kind of reference other than the index number. The data list is stored on a branch of the data tree. Each branch can hold data. The interaction of data will only take place if the data lists are at the same level of the data tree or trees. This means that to effectively access the data in a data tree structure you will have to know how the data has to accessed and the tree structure can be manipulated.

Space frame

Data from the same level , say {0;0;1} , {0,0,2} or {0;1;3} can interact with each other when the correct component is used. Like the Line component which needs more than 1 input stream. However the data of different level branches can't interact. If we have a data structure where one set of data is placed on the {0;0;1} branch and the other on the {0;1} branch they can't be used for a line for example because the data is not on the same branch level. The problem with this system is therefore the need to be able to manipulate where the data is stored in the data tree structure so that the data from different data trees can interact ( in essence the data is stored at the same level)

How Tree data is handled in components

There are 2 main ways how trees are being used by components. Components can either work on sets of items (called branches), or combine items from multiple inputs. Of course combinations in more advanced components are also possible, but for clarity, we'll start with these two main options.

Components working on branches from a single input


The first is the component will work only on the data on the same branch within the same tree. For example a Polyline uses the data of serie of points on a single branch to define the polyline. So from the content of a branch a polyline is generated and therefore for each branch 1 polyline. There is only 1 input channel for the points needed to define the polyline. Another example is the Loft component. It also uses only 1 channel for curve input.


The same functional combination of data can be obtained with two or more data trees by connect the different data trees to the same input channel. The trees are merged and the data is placed on similar branches. In the example two data trees with each 100 branches containing each 1 curve of data are merged into a single tree with 100 branches and 2 curves on each branch. Because there are now two curves on a branch the loft will be based on these two curves. This will repeat itself over the rest of the 99 branches.

If however the data structure is not similar because there are additional branches in one list, the data won't be combined and handled as separate lists. So getting the data on the right level of branches can be one prerequisite of a successful merger of data.

Components using multiple inputs


The second option is the use of a component which needs multiple inputs. An example is the line.The line needs 2 points. If a data tree structure is offered as data input for 1 of the two points the content of each point on the branch is seen as a separate input. This point will interact with a point of the same branch in the other data tree. The fundamental difference with the first option is that you always need two inputs and therefore two data structures which will interact on the same branch level.


In the example we can see a difference of the amount of points on the branch of one input and the amount of the other branch of input. In one tree structure the amount of points defined on a branch is 4 in the other tree structure 1. Grasshopper will generate in this case a line from one point of the four from one list to the 1 of the other list. It will then generate a line from the second point of the four to again the 1 in the other list, and so on. If all the four points are calculated , Grasshopper switches to a new branch and start calculating the lines between the four point and the single point of the other list. The lines therefore have a similar end point per branch. The way the lists are combined is depending on which option is selected in the option menu of the component.

Tree Editing


For an effective use of multiple data lists it is necessary to make sure that the data is at the same branch level at the different trees. If this is not the case you will have to edit the tree structure. There are a wide range of options for editing the data tree. This already indicates that there are a wide range of problems you can encounter with the data structures. Understanding how to edit them is crucial for effective use of Grasshopper.

To access the options for tree editing go to Sets - Tree . Here we can find a wide range of options to edit the data tree.

In the Tree tab we can find a wide variety of options. We will discuss them in context of some examples.

Flatten Tree

Flatten Tree

The Sets-Tree-Flatten Tree option is one which is often used to restructure the data tree structure by deleting the branch information and put all the data together in the root of data tree. It a drastic option and often forms the basis for restructuring the Data Tree from scratch.

Sets » Tree » Flatten

Graft Tree

Graft Tree

The Sets-Tree-Graft Tree option is also one which is used to restructure the data tree structure by adding a branch to each data item. Grafting is often used in combination with the Flatten Tree option. First the original data branch structure is deleted and then the data items in the root of the tree will each be placed onto a new branch. This can be useful for creating a branch structure which is similar to another data tree.

Example: We have a surface and two points. We want to "hang" the surface from the two points by a set of lines. If we generate a surface couple it to a Params-Geometry-Brep component and then extract a set of points from the surface with the Surface-Util-Divide Surface option. Connect a slider to the U and V input. For the points we use the Params-Geometry-Point option. We draw two points. If you have to move them use a Transform-Euclidian-Move component. If we connect the points of the surface with the two points we generated we can see that the amount of connections with one point is not similar to the other. The two point will interact with 14 points because the surface point list contains multiple points on a branch. If the list is grafted each point will be placed on a separate branch. If then the line is drawn with the list of the point an evenly distributed set of lines is generated.

Sets » Tree » Graft Tree

Simplify Tree

Simplify Tree

The Sets-Tree-Simplify Tree option to get rid of any overlapping by shared branches . The result is a simplified data tree structure.

Sets » Tree » Simplify Tree

Flip Matrix

Flip Matrix

The Sets-Tree-Flip Matrix option can be very useful when we have a grid of points divided in an equal set of branches and items on each branch. For example there are 10 branches {0;0;0} etc and on each branch there are 10 data items (n10). A polyline through each 10 items of each branch will generate 10 polylines. However when we flip the matrix a plyline is generated between each first item on each branch and then the second on each branch resulting in a set of crosswise angled lines with the first set.

Sets » Tree » Flip Matrix

Shift Path

Shift Paths

The Sets-Tree-Shift Path option looks a bit like a controlled Flatten option. It gives you the possibility to move the data one or more branches lower or to collapse the data into a single branch similar like the Flatten option however now placed on a single branch

Sets » Tree » Shift Path

Clean Tree

Clean Tree

The Sets-Tree-Clean Tree option is ideal for cleaning up complex data structures. When invalid or non information is entered in a list it might lead to instability or failure of the network. In the example several sources with their own lists are used as input for a point parameter. These lists are in this case combined in a single list of the point. One of the inputs is a point where the z axis is defined by the formula 2/X. If the x input is defined as zero the formula will fail resulting in Null output ( no output). The Sets-Tree-Clean Tree option will remove that data from the list.

Sets » Tree » Clean Tree

Path mapper

Path Mapper

The Sets-Tree-Path Mapper option lets you reorganize the branch structure by renaming the original path of the branches and indexed data to a new target path. There are various options available for generating a new path. The input is defined by the branch location and the item index. The syntax for this input is branch = { 0;0;0} for example and item = (10) combined {0;0;0}(10). Item 10 on branch 0;0;0.

  • If we want to place all the data of various branches , say 10 branches {0;0;0},{0;0;1} etc with on each branch 10 data items, at the same level onto 1 branch which is defined by the user we can for example place at the source {0;0;0} and at the target { 0;0;0;0} . The result is that all the data items are placed on the {0;0;0;0} branch.
  • If we however we want only the branch names to be changed and the data items remain on the branches we can use an option called Path_index this will give you the option of extracting the amount of branches from the source and translate the same amount to the target branches. In this case the whole structure with items and branches is moved to the target branches.
  • This manipulation of the items of the branch is also possible when we want to have all the first items of all the branches on a single branch. Say you want to generate a line between all the first items of a branch. In this case we can use the Path_index on the source {0;0;0}(path_index) and target {0;0;0;path_index}. The path_index generates the numbers from 0 to 9 The items are selected with index 0 on all the branches and placed on a target branch {0;0;0;0}
  • Path_count There is also an option to make a link between the number of items or branches and the index number of the target branch. For example when the source branch is defined as {0;0;0} and the target branch as {0;0;0;path_count} the final branch name will be in our case {0;0;0;10} because there are ten branches in our example.
  • A similar option is available with the Item_count option. This will define a number based on the amount of items in a branch.

Sets » Tree » Path Mapper

Tree Editing continued

An overview of more advanced tree editing options.

Explode Tree

Explode Tree

The Sets-Tree-Explode Tree works similar to the Flatten Tree option however it will create a list of every branch instead of putting all the information of all the branches in 1 list. This however also means that you will have to define how many lists you want to generate. If you have 10 branches with each 10 data items you will have to use the Output Manager of the Explode Tree component. Right click on the Explode Tree component and select the option of Output manager. In this menu you can add additional output lists.

Sets » Tree » Explode Tree



The Sets-Tree-Merge is like the Merge 3 and Merge Multiple option a method of merging the data of similar branches of different trees into the same branches in a single tree. This can be done for not only two but also for multiple trees.

Sets » Tree » Merge

Relative Item

Relative Item

Relative Item - The Sets-Tree-Relative Item enables you to extract 2 lists from a single list. The output of the component is dictated by the Relative Offset input. The offset has two components . The branch offset and the item offset. When the branch offset is defined as {0;0;0} in the example list where we have 10 branches and 10 items on the branches nothing happens. The output of A and B are the same and contain the same information as the original list. There is no offset , because the input list also starts with {0,0,0}. If however we define the offset as {0;0;5} the Lists of A and B are still the same however they are limited to the first 5 branches of the input list. The rest is ignored. If we however also offset the items of the branches the lists will change from each other.

  • With a setting of {0;0;9}(6) representing the branch offset and the item offset the lists of A and B will consist of 1 branch with in the A List the first 4 items of the first branch and in the B list the last 4 items of the last original branch.
  • With a setting of {0;0;8}(6) the list of the A output will contain the first 4 items of the first branch and the first 4 items of the second branch. The B output consists of the last two branches with on the each branch the last 4 items of each of the last branches.

Sets » Tree » Relative Item

Stream Filter

Stream filter

The Sets-Tree-Stream filter is a simple method of switching between two or more lists by simply selecting the wanted list by its input number. This input number can be defined within the network and thereby can change depending on a variety of settings influencing which list is passed through the filter.

Sets » Tree » Stream filter

Stream Gate

Stream Gate

The Sets-Tree-Stream Gate works similar to the Stream Filter option. The difference however is that we have only one input list. An index number defines to which output channel the list is gated. The selection if therefore focussed on which channel the list is gated.

Sets » Tree » Stream Gate

Tree Branch

Tree Branch

The Sets-Tree-Tree Branch looks a lot like the List Item option in the Lists part of the Sets Tab. It enables you to extract the data of one or more branches. When 1 branch is defined the output list will contain only the data of that input branch. If however you define multiple branches, the list will generate new branches where the selected data items are placed on.

Sets » Tree » Tree Branch

Tree Item

Tree Item

The Sets-Tree-Tree Item differs from Tree Branch because there is an extra input option for selecting specific items on the branch of the data tree.

Sets » Tree » Tree Item

Working with Tree Branches

When you're working on datatree branches, the following options are available.

Branch Compare

Branch compare

The Sets-Tree-Branch compare option enables you to filter the item data of a tree structure. If for example you have a list of light strength measurements of your scene, it is possible to filter the data based on a selection mask. This mask is a string and can be defined in the Branch compare option or with the help of an expression component. The input of the string itself doesn't support expressions so they have to be made with an expression component and this output then can be connected to the mask input. Examples of syntax supported by the mask string

  • 10
  • <10
  • >10
  • <=10
  • >=10
  • [10-20]

Sets » Tree » Branch compare

Create Branch

Create branch

The Sets-Tree-Create branch is a option which does what it says. You can create a branch or multiple branches with an index which is defined by the input. If the numbers 0 0 and 9 are input the branch will have the index of {0;0;9}

Sets » Tree » Create branch

Decompose Branch

Decompose branch

The Sets-Tree-Decompose branch is the reverse of the Create branch option. It will de-construct the index of the branch into a set of numbers.

Sets » Tree » Decompose branch

Prune Tree

Prune Tree

The Sets-Tree-Prune Tree enables you to filter the branches based on the amount of data items they have on their branches. Branches with to much or few data items will filtered and deleted from the list. The

Sets » Tree » Prune Tree

Replace Branch

Replace Branch

The Sets-Tree-Replace Branch enables you to select branches of the tree and replace them with a new index for the branch. For this option you can use the Param Viewer to extract the indices of the branches of the list which has to be replaced. To make sure the mask works you need a similar amount of replacement addresses as the branches which have to be replaced. For the Path replacement data you can select the Path parameter in the parameter tab.

Sets » Tree » Replace Branch

Split Tree

Split Tree

The Sets-Tree-Split Tree enables you to select branches of the tree and place them in a separate Tree. The remaining branches form a new list.

Sets » Tree » Split Tree

Personal tools