Skip to content

Python for Grasshopper

The objective of this section is to introduce basic conventions for setting up python script components in grasshopper and explain how to configure them before editing their code contents.

Default Configuration

To create a new python component switch the component palette to the Maths tab and insert a GHPython Script component in the document. The default component setup contains two input parameters, x and y, as well as two output parameters, out and a.

Standard Operating Procedure

Component Name

The first configuration step is to rename the component from "GhPython Script" to something more appropriate. To achieve this right click over the name of the component and edit the first pop-up menu entry. Note that the name of the component is merely for mnemonic purposes. It does not affect the way python will execute the code provided.

Number of Input Parameters

The number of parameters, zero or more, depends on the objective of the component. To adjust the number of input and output parameter requires zooming in the viewport and using the +/- handles that appear between the parameter names.

Input Parameter Names

Next we need to rename the input parameters. The same operation as before applies where we right click over each parameter's name and change the first entry in the pop-up menu. Unlike renaming the component, changing parameter names affects python.

Common Name Challenges

  1. Parameter names map directly to python variable names. As such it is important to be aware that the letter case used is important. The names "point", "Point", "PoInT" etc, are all different. Python variable names are case sensitive.
  2. Parameter names must not include spaces, white space in general, because python does not allow that for variables. Instead you may use one of the following naming conventions "twoWords", "TwoWords" or "two_words".
  3. Some names are already used by python and Rhino. For instance "if" is a python language construct, so using this as a parameter name will cause errors. The word "Surface" is a class name used by Rhino, so using this as a parameter name will cause naming conflict in the code.
  4. Renaming parameters does not automatically rename the associated variables in the code. Instead the code must be edited and saved before the name change has any effects.

Input Parameter Types

Input parameters may be annotated with data type information before being used in python to avoid programming errors. To adjust an input parameter's type right click over its name and select one of the available types presented by the "Type hint" menu.

Below is a list of the most commonly encountered data type hints and the description for when they should be used. Note that the default object type hint will almost always cause automatic conversion between data types which can result in annoying python errors. It is highly recommended to properly annotate all input parameters with the expected data type.

Type Description
None Used for suppressing data type information and automatic conversions.
Object Used for dynamic values that can take any data type. Default option.
Guid Used for referencing objects contained in the Rhino document.
float Used for real number values such as coordinates and decimal quantities.
bool Used for True / False values such as enable toggles and flags.
int Used for integer number values such as indices and counts.
str Used for string values including single and multiline text.
Geometry Used for grasshopper geometries which are not same as Rhino objects.

Common Type Challenges

Below are some common error messages which hint that the data type information is either missing or incorrectly assigned.

  1. TypeErrorException occurs when the expected and received types of data do not match. For example a numerical-looking value, say "3.1415", is passed from a panel to a python component. The parameter was NOT annotated as float and its was used for performing math eg. computing the cosine. The problem here is that "3.1415" is a str, which cannot be used for regular math. However, if the type hint is set to float then the value will be converted into a number before being received by python.

  2. MissingMemberException occurs when an object with a known attribute is expected but it is not found. For example a point 3D is connected to a python component input and in the code its X-coordinate is used. If the input parameter is not typed as Point3d this error will occur.

  3. Guid object has no attribute identifier is the same as above. It typically happens when some geometric values is passed to an input parameter without a hint. Apply the appropriate type hint and the error will be resolved.

Input Parameter Access

Grasshopper support three access modes for processing data based on their multiplicity, namely Item, List and Tree. To change the access mode, right click over the name of input parameter and select the appropriate item from the pop-up menu. It is highly recommended to use only the Item access mode, when you wish to pass a single value, and the List access mode, for passing multiple items. Avoid all other combinations as they will cause unnecessary complications.

  1. Item: The component will execute as many times as the number of items passed to the input, which may be a single value, a list of values or a tree of values. In the python code, the variable with the same name as the input parameter will contain one element at a time. This is equivalent of asking grasshopper to automatically create the requisite loops for processing items one by one. Use the Item option for only sending single input values. Avoid using the automatic enumeration because it complicates the way the output values are emitted.

  2. List: The component expects a list of items to be passed via the input parameter and the code to receive a python list to be processed manually. If a single value is passed, the component will wrap it into a python list. If a tree is passed, the component will receive multiple python lists one at a time. Use the List option for only sending single or simple list values. Avoid using the automatic tree to list enumeration because it complicates the way the output values are emitted.

  3. Tree: The component expects a tree of items to be passed as-is to the python code. Single values and lists are wrapped automatically. The way multi-dimensional arrays are implemented in grasshopper is highly unusual and does not map to any python programming language concepts. As such it is recommended to avoid using trees.

Common Access Challenges

  1. list object has no attribute identifier is the result of sending a single value while using the list access mode. For example a single point 3D is passed as input parameter named point with list access mode and in the code X-coordinate is used point.X. The problem is that point is a list not a single object. You may either change the access option to item (not recommended) or access the item from the list as point[0].X.

Output Parameters

Next we need to set the number of the output parameters and name them appropriately. The same process as adjusting and renaming the input parameters applies here but there is a catch. The out parameter is special because it is used for capturing messages emitted using python's print( ) method. It is recommended to rename it to messages and to avoid deleting it. If you remove it by accident it is possible to restore by right clicking over the component's name and selecting the "Show output parameter" menu item.

Notice that there is no way to annotate output parameters with either type or access information. This is handled automatically by grasshopper. In most cases this works fine but there are some special scenarios where it is problematic.

Special Output Challenges

  1. Outputting nested lists, or list of lists in python, for example [[1], [2]] produces grasshopper lists containing IronPython.Runtime.List items. Those do not work well with other grasshopper components except other python components. It is possible to convert such nested lists to a Tree data structure but it is not recommended.
  2. Outputting dictionaries such as {'a':1, 'b':2} produces grasshopper lists containing only the keys, that is ['a', 'b'] without the values. The workaround in this case is simple: wrap the dictionary in a list [{'a':1, 'b':2}]. This will retain the data which can be accessed by another python component.
  3. Outputting a Polyline object produces a grasshopper list of points instead of a single polyline. This is because the Polyline object is an enumerable of points and grasshopper automatically unwraps it. To prevent this behavior you may either use the wrap output in list as above, or emit a PolylineCurve object instead.
  4. The data type of the out parameter is str so it is not recommended to use it for emitting any other type of information. For example even through the statement print( 3.1415 ) will output a value that looks like a number, it is in fact as string which may cause problems when used in mathematical expressions.