Grasshopper lists

List basics

In the previous section, we have addressed the different types of data that you can encounter in Grasshopper. Now, instead of considering singular data elements, we will see how to handle lists of data with Grasshopper. But first, what is a list? To put it short, a list is an ordered collection of data. The elements of a list are called items and the position of each item in the list is given by its index.

Typically, in the example below, the first output of the component “Divide Curve” is a list of points. The length of the list is equal to the input parameter N+1 (with N=6, the line is divided in 6 pieces, so 7 points). Using panels is the best way to display the content of a list. Small tip: to add a panel, you can double-click on the canvas and type a quotation mark (“) in the search bar.

Now, what happens when we set a list as input for a Grasshopper component? Well, the operation will simply be repeated for each item in the list. In the example below, Grasshopper will therefore draw 11 lines, one for each item in the list A. Similarly, if the input B of the line component was another list of 11 points, the “line” component would have simply drawn 11 lines between each pair of points.

Where it gets more complicated is when several inputs of a component have lists of different lengths. In the example below, the line component has an input A with a list of 7 items and an input B with a list of 9 items. We see that the output is a list of 9 items… What happened? Per default, Grasshopper will always match the exceeding items of the longest list with the latest item of the shortest list. As a result, the length of the output is equal to the length of the longest list.

However, it is possible to get different list matching behavior by playing with the components “Shortest list” and “Longest list” as in the three examples below. As you can imagine, list matching is often the source of scripting errors. Therefore, when possible, try to always pass lists of the same length to a component!

Creating lists

Here are two simple ways of manually creating lists. First, by adding a parameter component on the canvas and selecting “Manage […] Collection” (right-click on the component). Second, by using a text panel and enabling “Multiline data” (right-click on the panel).

Often, large list of numbers need to be created. Instead of manually typing the values, the “Range”, “Series”, and “Random” components allow you to generate lists of numbers in different manners.

List management and patterns

Grasshopper has a lot of components to perform operations on lists. This becomes handy when you need to rearrange long lists of data, or when you need to delete or select certain values in a list. Here we introduce and illustrate the behavior of some of those components:

Some of these components require a pattern as input. A pattern is a list of Boolean values (True, False) which you can use as a mask to delete (“Cull Component”) or sort items (“Dispatch component”) in a list.

It is also possible to sort the items of a list either by numeric or alphabetical values using the “Sort List” or “Sort Text” components.

Furthermore, two lists can be sorted synchronously like in the example below where breps are sorted according to their volume. The list that is sorted is the list with the different volumes of the breps. This list is called the “sorting key”. The other list (the list of breps) is then rearranged to match the sorted key.