Source: A beginner’s guide to visual scripting with Grasshopper   by Paul Jeffries

In this tutorial, I will provide a very simple demonstration of the use of Grasshopper, a visual scripting environment embedded into the 3D modelling package Rhinoceros and a very useful computational design tool.  This example is intended to give a brief overview of how the software works to people with no prior exposure to it and explain the core theoretical principles.  Some basic prior knowledge of Rhino itself is assumed, however (i.e. you need to at least be familiar with the general interface – this video will cover most of what you need).

The example should take under 30 minutes to run through but will teach you everything you need to know in order to start using the software by yourself.  Each step is accompanied by an animation showing exactly what you need to do.

We’re focusing on Grasshopper in this case, but most of the concepts shown here are also transferable to other similar node-based visual programming environments (for example, Dynamo).

Grasshopper is a free plugin for Rhino and can be obtained from its official website:  In Rhino 6+, Grasshopper will be incorporated into the main Rhino install and will no longer need to be downloaded separately.  Rhino itself can be downloaded here and will run as a free evaluation version for a full 90 days.

1. Setup

In this example, we will create a very straightforward parametric definition which will draw a line between two points.  These two points will be our inputs; create these in Rhino by using the ‘Point’ command twice.

Once Grasshopper is installed, you can run it from inside Rhino by typing the command ‘Grasshopper’ at the command prompt.

2. Interface

Grasshopper’s subwindow will appear, and should look something like this:

  1. The title bar.  This shows the name of the currently opened file (if any).  It can also be double-clicked to collapse Grasshopper to just this title bar – useful if you are working on a single screen and want to get Grasshopper out of the way quickly.
  2. The menu bar.  We’ll talk more about this in a minute…
  3. The component library.  This is categorised into several different tabs for different kinds of functionality.  (You probably won’t have as many as are shown in the images – many of these are optional plugins.)
  4. The component library is further sub-categorised into different groups.  You can click on the title bar at the bottom of each group to expand it and see all of the components in that group with their names.
  5. The canvas toolbar.  Contains several quick-tools to save the file, scribble on the canvas and change the way that things are being displayed.
  6. The main canvas.  This is where the magic happens.
  7. The recent files grid.  You probably won’t see this if it is your first time opening Grasshopper as you won’t have any recent files!  This will disappear as soon as you start adding things to the canvas.
  8. The status bar – occasionally displays useful information.

Let’s go back to the menu bar to make a couple of important points:

  • Grasshopper files can be opened, saved, etc. via the File menu.  Grasshopper definitions are saved separately from Rhino files, so make sure you save both if you don’t want to lose any data!
  • In the ‘View’ menu you can turn on an ‘Obscure Components’ option which will show more components in the library ribbon than you get by default.  This option is presumably there to stop people getting scared by lots of component icons when they start out, but also makes it harder to find things.
  • In the display menu, turn on ‘Draw Icons’.  This changes the way components are displayed on the canvas.  This is a matter of personal taste and some people prefer the default (which just shows text), but these people are wrong.
  • You should also make sure ‘Draw Fancy Wires’ option is on (which it should be by default).  This is not even a matter of personal taste; having this turned on will make certain definitions much, much easier to understand.

3. Grasshopper Basics

3.1 Adding Components

Now onto the creation of our actual definition.

The first step is to get the points we created in Rhino and put them into Grasshopper in a form that we can use.  To do this we’ll need a couple of Point Parameter Components which you can find on the ‘Params’ tab in the ‘Geometry’ group on the component library ribbon.  Left click on the icon and then left click again somewhere on the canvas to create one of those components.

This is one way of adding components to the definition.  The other way is to search for them by name.  To do this, double-click somewhere on the canvas (not on a component).  In the text box that appears, type in ‘Point’.  It will then show a range of suggestions – click on the component just called ‘Point’.

3.2 Referencing Rhino Geometry

These components are intended to store point data, but at the moment no data has been assigned to them.  This is why they are showing up in orange – this indicates a warning, typically that the component does not have all of the inputs it needs to do whatever it is meant to be doing.

We’ll need to set up these components to refer to the two points we created earlier in Rhino.  Right-click on the first component to bring up its context menu.  Select the option ‘Set one Point’ and then in Rhino pick the first point.

This will assign the point to the parameter and the component should turn grey to indicate that everything is working as planned.

Repeat this for the second component and the second point.

You may notice that little red ‘x’s have appeared over the points in Rhino – these indicate that the geometry is also present in the Grasshopper model.  If you left-click on one of the Grasshopper components it will become selected and will turn green.  The ‘x’ in Rhino related to that component should also turn green.  You can use this to remind yourself which Grasshopper component refers to which bit of Rhino geometry.

3.3 Creating Data Flows

Now that we have our input points in Grasshopper we can generate the line between them.  Navigate to the ‘Primitive’ group on the ‘Curve’ tab and find the component called ‘Line’.  Left click on the icon and left click again on the canvas to create a Line component.

This component has a few more features than the Point parameter components.  Whereas the Point components simply store a bit of data, this Line component represents a process which will consume input data and generate an output from it.  The process inputs are shown on the left hand side of the component (called ‘A’ and ‘B’) and the outputs are shown on the right hand side (called ‘L’).  Hover your mouse over these letters and you should see tooltips that provide more information about them.

A and B are the start and end points of the line, respectively.  We can populate these inputs using the data stored in our Point parameter components.  To do this, hover your mouse over the small nodule on the right hand side of one of the point components.  You should see a small arrow icon below your cursor.  Click and hold the left mouse button and drag the mouse away to see a snaking arrow follow your mouse.  Move your mouse over the first input of the line component and release.

This will create a connection between the output of the Point parameter component and the input of the Line component.

Repeat this for the second point and you should see the Line component turn grey and a red line appear between the two points in Rhino.

Congratulations!  You now know how to use Grasshopper!

Grasshopper allows you to describe parametric models by essentially drawing a flow diagram of the process you want to follow to create that model.  If you can diagram a process, you can use Grasshopper.

All components essentially work the same way; inputs on the left and outputs on the right.  Click and drag to create connections between inputs and outputs and choose the way that data will flow between different operations.  Simple!

So far we’ve just used this to draw a line, which isn’t enormously useful – we could have done the same thing in Rhino just by using the ‘Line’ command.  But the power of Grasshopper comes from the fact that several different processes can be daisy-chained together, with the output of one operation feeding the input of another.

To demonstrate this, we’ll take the curve output from the Line component and we’ll create a tubular surface around it using the ‘Pipe’ component from under ‘Surface’/’Freeform’.  Drop one of these onto the canvas and connect the ‘L’ output from the Line component to it’s ‘C’ input.

The ‘C’ input is the centreline curve around which the pipe surface will be created.  You should be able to see this surface in the Rhino view.  Click and drag one of the two initial points to move it and you should see the pipe geometry automatically update.

This is the power of Grasshopper.  Changing an input (in this case a point) will prompt an update of any geometry which is linked to it.  The process you have set out will be run again automatically and the model regenerated, without you having to go through all the pain of manually remodelling everything.

Complex chains of hundreds of different operations can be built up and whole buildings can be defined and controlled by just a few simple inputs, with changes automatically propagating throughout the model.

3.4 Number Sliders

The Pipe component is already working even though we haven’t put anything into the ‘R’ and ‘E’ inputs.  This is because these inputs have default values – hover your mouse over these letters to see what those default values are.  ‘R’ is the radius of the pipe, which we might want to be able to adjust.  (We won’t bother looking at ‘E’ in any detail, but this can be used to control what the ends of the pipe look like).

We’ll control the radius with a Number Slider component from ‘Params’/’Input’.  Drop one onto the canvas and connect the output to ‘R’ to override the default value.

This is a little input widget that we can use to control a numeric input just by dragging the slider left and right.  If you want to change the maximum and minimum values right click on the slider and click on ‘Edit’ to access a form which will let you set up the properties of the slider, including the numeric domain it covers.

Grasshopper features many different input widgets that allow you to enter and modify different types of data easily.

We’ve now finished creating our definition for this example, but we will use the model that we’ve made to explore a few other aspects of the program.

4. Geometry Preview

You may already have noticed that the red transparent geometry that you can see in Rhino has some peculiar properties – you can’t select it, it won’t be saved in the Rhino file if you try to save it, if you hit the render button then it won’t show up, etc.  This is because none of this geometry actually exists in Rhino yet – it is merely a ‘preview’ that Grasshopper is drawing in the Rhino viewport to show you what is going on.

If you want to turn this preview off – now that we have our pipe you might no longer care about seeing the centreline geometry, for example – you can turn it off by right-clicking on the middle part of the relevant component (not over one of the inputs or outputs) and toggling on or off the ‘Preview’ option.

The preview geometry associated with that component should disappear and the component should turn a darker shade of grey to indicate that its preview is turned off.

You can also change how everything is displayed using the first three buttons on the right-hand side of the toolbar just above the canvas, to ‘off’, ‘wireframe’ and ‘shaded’ modes respectively.

5. Baking

To add this previewed geometry to Rhino, so that we can manually modify it, export it, render it, etc. we need to ‘bake’ it.  This will add a copy of that geometry into the current Rhino document.

To bake some Grasshopper geometry, right-click on the component whose geometry you wish to add to Rhino (again, this needs to be on the centre part of the component, not over any of the input or output components) and click on the ‘Bake’ option.  This will throw up a small form which allows you to select certain properties of the new object in Rhino (for example, the layer it will be placed on).  Click ‘OK’ to bake the geometry.

You can now modify, delete, move, export etc. this geometry the same way you would any other Rhino object.  Note that there is no link between this baked object and the Grasshopper definition that created it – if you change the model in Grasshopper these changes will not be reflected in the Rhino model and likewise changes made to the geometry in Rhino will not matter a jot to Grasshopper.  If you wish to later update the Rhino geometry from the Grasshopper model you will need to delete it and re-bake; for this reason it is a very good idea to keep baked geometry on its own set of layers in Rhino so that it can be easily selected and deleted in one go.

6. Data Matching

One advantage of Grasshopper is that, as we have already seen, (non-baked) geometry can be parametrically linked and automatically updated.  Another advantage is that once we have a process defined, we can apply that process over and over and over again on multiple inputs, which is what we will do now.  We do not have to modify our actual model definition at all for this; we simply need to change the inputs.

Rather than creating a single pipe between two points, we will now use our definition to create multiple pipes between multiple pairs of points.  Add four more point objects to your Rhino model (using the ‘Point’ or ‘Points’ command) for a total of six.

Right-click on the first Point parameter component.  Just below the option to ‘Set one Point’ is another which allows you to ‘Set multiple Points’.  Click on this option and select in Rhino the three points you want to use as pipe start points.  Press return or right-click once you have finished.

Note that this will override the data previously stored in this component, so you’ll need to include the original start point in this selection if you want to include it.

This component now contains multiple bits of data.  Those multiple points are being passed along to the Line component and it is now generating three different lines from each of those three points to the single end point we currently have selected.  Those three lines are being passed in turn to the Pipe component to create three different pipes.  You can tell at a glance that multiple pieces of data are being passed between components by looking at the wires between them – provided you have the ‘Draw Fancy Wires’ option turned on these should now appear as double-lines rather than one.  This indicates that a list of data is being passed along that connection instead of just one individual piece of data (which will be a single line).

Repeat this operation to set the three end points.

We now have three start points and three end points going into our Line component, and as an output we are getting three lines (and consequently, pipes).  You might have expected that we would get nine lines connecting every start point to every end point, but instead Grasshopper is ‘pairing up’ start and end points and just creating one line for each pair – this behaviour is known as ‘Data Matching’ and it is a very important concept to understand when using Grasshopper.

Whenever a component has multiple pieces of input data plugged in Grasshopper will first determine which sets of inputs to use together and then will run the process once for each set.  To figure out which inputs belong together, Grasshopper follows two simple rules:

RULE 1: When matching two or more lists of objects, items at equivalent positions in those lists will be matched together.

So, the first item in the first list will be matched with the first item in the second list, the second item in the first list will be matched to the second item in the second list, third with third, fourth with fourth and so on.

Imagine we have two lists of letters – in the first list we have ABCD and E, while in the second we have FGHI and J.  Data matching these two lists together would give us the pairings A-FB-GC-HD-I and E-J.

So, the order that things are stored in is important – in this case the order that the points were selected will be the order that they are matched up in.

This all works great when we have lists which are all the same length, but what if one is shorter than the others?  This is where the second rule comes in.

RULE 2: When one list is shorter than the others, the last item in the list will be matched with subsequent items in the others.

Grasshopper will ‘re-use’ the last item in a list when there aren’t any further pieces of data to match up.  If we dispose of the last two letters in our second list (so list 2 is now just FG and H) the resultant pairings will be A-FB-GC-HD-HE-H.  H will be used in three different pairings!

We can see this effect in action by setting our ‘end points’ input to only contain two points (or just one, as we originally had it) while the start points have three:

Now, the last end point will be connected to the last two start points.

This behaviour applies to any component and any type of data, not just lines and points.  This means that we can take advantage of this to give us individual control over the diameter of each of the pipes we are creating.

Create a second Number Slider (you can press Ctrl-CCtrl-V to copy and paste the one we already made) and connect it to the Pipe component ‘R’ input.  If you try and do this normally it will automatically replace the connection to our original slider, but if we hold down the shift key as we’re making the connection we can connect multiple outputs to one input.

Our ‘R’ input will now be a list of numbers comprising the values of the sliders that we’ve plugged in (in the order that you plugged them in) and these will be data-matched with the list of curves going into ‘C’.  As a consequence, the first slider will control the radius of the first pipe and the second will control the radius of the others.  If we wanted, we could add more sliders to give us total control over each pipe.

7. Finally

You now know everything you need to get started using Grasshopper.  There is certainly a lot more to learn – there are thousands of different components available and as well as flat lists data can also be passed around in the form of multidimensional ‘Data Trees’ (essentially, lists of lists), which can make data matching a lot more confusing, but these all follow the basic principles we have covered here.

Becoming more proficient is largely just a matter of learning what tools are available to you and of getting used to manipulating the data flows between components to achieve the effect that you want.  The best way to start is simply to choose something that you want to model, think about the basic geometric steps you would take to create it manually and then try to express that process in Grasshopper.

The official Grasshopper forums feature a very active and helpful community and are a useful resource to get help.  For a little more structured learning, the ‘Parametric Engineering’ course that I co-teach at Imperial College London is available to view on YouTube.  You can also discover how to use Grasshopper to create parametric structural analysis models via RCD’s Salamander plugin in the video below: