At the heart of any Grasshopper definition is the data. Grasshopper components process and create data, while wires transport the data between different components. In the last exercise, you may have already noticed that some wires look different from each other. This is because the visualization of the wire changes based on the structure of the data flowing through it. There are three types of data that can flow through a wire in Grasshopper:
- Item — one data element, for example one curve object
- List — an ordered set of elements, for example 10 points
- DataTree — a more complex data structure composed of two or more Lists
DataTrees are the subject of the <next lesson>. For now, let’s focus on Lists, and how to work with them in Grasshopper.
Many components generate Lists of items as a result of their operation. For example, the
Divide Curve component we saw in the first exercise uses one curve and a value specifying the number of divisions to create a List of Points along the Curve.
To create your own List from scratch, you can input multiple values into a
Panel component. A shortcut for creating a
Panel is to double-click on the canvas to bring up the search bar, then type ‘//’. This will create a new
Panel, and place any text you type after the two slashes into the
Panel can be used to input text or numerical data. To create a List of values, put them on separate lines in the
Panel. Make sure to right-click on the
Panel and select the option for ‘Multiline Data’ to separate the lines into different items in a list. Otherwise, the text will be output as one big chunk.
You can find many useful components for creating and manipulating Lists in the ‘Sets’ tab in Grasshopper’s component toolbar.
In the ‘Sequence’ section of the ‘Sets’ tab, you will find several components for generating sets of numbers, which can be very useful for driving your computational models. In the previous exercise we used the
Series component to generate a set of numbers given a starting value, a step value between each number, and a total number of values to generate.
Range component also generates a set of evenly spaced numbers, but it does so based on a Domain that defines the minimum and maximum value, and the total number of values to generate within that range.
Random component will also generate a set of values within a given Domain, but it will choose the values randomly. To create different sets of random values, you can input different numbers into the Seed (S) input, which controls how the random algorithm is run. While the numbers created by the
Random component will always appear random, inputting the same Seed will always produce the same set of numbers. This is important for making sure that the numbers don’t change each time you re-run the script.
Seeing the data
A quick way to see the data stored inside a component is to hover over any of the component’s input or output ports. A tooltip will pop up with a preview of the data stored inside the port. You can also pass the data into the input port of a
Panel component, which will display the data in a scrollable table. This is a great way to monitor the data being produced by your definition and keep it visible on the canvas.
In the table generated within the
Panel, you will notice that each value in the List has a corresponding number to the left of it. This is the index of the item, and it represents the item’s position in the list. You will also notice that the first item’s index is 0, not 1 as you might expect. This is because in Grasshopper, as in most programming languages, elements are numbered starting with 0. This can take some getting used to but you will get the hang of it over time.
Working with Lists
In the ‘List’ section of the ‘Sets’ tab, you will find many useful components for manipulating Lists, including:
<List Length>component which returns the length of a list
<List Item>component which returns a List item at a specified index
Sort Listcomponent which sorts the items in a List
Reverse Listcomponent which reverses the order of a List
Spend some time exploring these components on your own, we will see some of them again in later exercises.
Working with Domains
A Domain is a special data type in Grasshopper that represents a numerical range based on a start and end value. Domains are used by many components that operate over a range of values. We’ve already seen how Domains are used by the
Random components to generate sets of numbers.
The easiest way to create a Domain is to type it into a
Panel component with the starting and ending value separated by “ to ” — for example: “0 to 100”. If you pass this text into an input that expects a Domain, Grasshopper will automatically convert it for you. If you want more control over how the Domain is defined, or want to control the start and end values using data in your definition, you can use the
Construct Domain component which creates a Domain from two input values.
Construct Domain component can be found in the ‘Domain’ section of the ‘Maths’ tab in the component toolbar. Here you will find several other useful tools for working with Domains.
Remap Numbers component maps a set of numbers from one Domain to another. For example, you can use the
Remap Numbers component to take data in the range of [0, 100] and map it to a range of [0.0, 1.0]. The Remap component has three inputs — the data (D) you want to map, the starting domain (S) representing the range of the current data, and the target domain (T) representing the range you want to map the data to.
A very common application of the
Remap Numbers component is mapping a List of values to a Domain of 0.0 — 1.0 so that the lowest value in the List becomes 0.0 and the highest value becomes 1.0. To find the starting Domain of the data we can use the
Bounds component which returns a Domain defined by the smallest and largest values in a List. We can use the output of the Bounds component as the starting Domain (S) of the
Remap Numbers component to map the values to the default target Domain of 0.0–1.0.
How Lists affect the data flow
Each component in Grasshopper defines a process for taking in a set of inputs and producing a set of outputs. Most components are built to work with single items as inputs. For example, the
Line component creates a line using one start point (A) and one end point (B) as inputs.
When we pass a List of values into a component’s input port instead of a single item, the component will actually run multiple times, as many times as it needs to process each item in the List in order. For example, if we pass ten points into the
Line component’s (B) input, the component will actually run ten times and produce ten lines as a result, with each resulting line using one of the ten provided end points. Since we only supplied one start point, the same point is used for each line.
Now, what happens when we pass multiple points into the other input as well? In this case, Grasshopper will go down both lists at once, using one point from each list in order to create each line. You can see that the component stills runs ten times to produce ten lines, but this time each line has a unique start point.
If you input Lists of different lengths into the same component, the component will still run as many times as it needs to in order to process all the items in the longest List. For the shorter List(s), the component will use as many unique items as possible until it runs out of items, and then reuse the last item until all values in the longest List are used up. For example, if we only pass six points into the
Line component’s (A) input, the component will still run ten times, but the last five lines will share the same start point.
In this lesson, we have seen how Grasshopper uses Lists to store data containing multiple items. Working with Lists and predicting how the structure of your data will impact the way a component will run can be challenging when you’re first learning Grasshopper. It can even be challenging for those used to programming with a text-based programming language, where processes for creating and working with data can be described much more explicitly.
What you need to remember is that everything in Grasshopper is defined by individual components that execute specific functions and generate new data based on the data given to them. Thus, unlike traditional code, a Grasshopper definition is not so much a set of instructions as a complex system for developing formal solutions based on a set of interrelated parts. Learning to control the data in our definitions and getting an intuition for how the data structure will impact various components is a critical part of becoming an expert in Grasshopper, and like everything else, it is best learned through practice.
In the <next lesson> we will take these concepts further by describing DataTrees, which define more complex data structures composed of two or more individual Lists. We will then get hands-on practice with Lists and DataTrees in the following <exercise>.