Python Scripting in Grasshopper
a ni–fty guide
Stephen P. Maher / COL55 Email:
[email protected] Slack: @smaher Twitter: @StepMaher
Python Scripting in Grasshopper a ni–fty guide The Zen of Python by Tim Peters
Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren’t special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one – and preferably only one – obvious way to do it. Although that way may not be obvious at first unless you’re Dutch. Now is better than never. Although never is often better than right now. If the implementation is hard to explain, it’s a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea – let’s do more of those!
Python Scripting in Grasshopper a ni–fty guide
Those are the guiding principles of Python. A sense of humor is required for their proper interpretation. If you’re using a programming language named after a sketch comedy troupe, you better have a sense of humor.
Python Scripting in Grasshopper a ni–fty guide BACKGROUND Rhino and Grasshopper use IronPython, not the general purpose parent language. IronPython is an open-source implementation of the Python programming language which is tightly integrated with the .NET Framework. IronPython can use the .NET Framework and Python libraries, and other .NET languages can use Python code just as easily. – ironpython.net SYNTAX Variables inside the scripting editor should be lower_case with multiple words strung together with underscores.* single_string = "Hello, world!" string_list = ["Hello", ",", "world", "!"] – For GHPython Input and Output variables, the first letter should be capitalized. – You cannot define a variable that starts with a number. – *Note: You may use camelCase, but know it’s not considered Pythonic. It really should only be used to conform to preexisting conditions. Comment Your Code! (remember to be Zen: readability counts) # This is a comment, so it is ignored by the compiler. Note the capitalization and spacing conventions. """ This is a multi-line comment. It’s useful for long comments or temporarily suspending bits of code. """ #This is another multi-line comment. #If you highlight multiple lines #then hit "Ctrl + /", this is what happens.
Python Scripting in Grasshopper a ni–fty guide FUNCTIONS Example short function.
# Define a function. def short_function_name(var_one): return(var_one)
Note the parentheses and the colon. You need both, though you don’t necessarily need parameters.
# Call a function. short_function_name(var_one)
Example long function.
# Define a function. def long_function_name( var_one, var_two, var_three, var_four): return(var_one) # Call a function.
Note the indentation rules. One should avoid lines of code greater than 80 characters.
long_function_name(var_one, var_two, var_three, var_four)
Note the indentation and syntax conventions.
Example Script: Iterative Fibonacci Sequence def fib(n): a, b = 0, 1 for i in range(n): a, b = b, a + b return a for N in range(0, 15): print fib(N)
Python Scripting in Grasshopper a ni–fty guide OBJECT METHODS Most of the time you won’t be defining functions, but calling them. These will often be built-in functions belonging to objects called methods. # Some input brep declared as "my_brep" in Grasshopper. my_flipped_brep = my_brep.Flip() # Declare to component output. a = my_flipped_brep
Note that not all functions require parameters. # Some input brep declared as “my_brep” in Grasshopper. my_capped_brep = my_brep.CapPlanarHoles(tolerance) # Declare to component output. a = my_capped_brep
These are object methods. If you declare an input Type Hint, the Python Editor knows which methods to call for that object. More on this in the following pages.
Python Scripting in Grasshopper a ni–fty guide ANATOMY OF THE GHPYTHON SCRIPTING COMPONENT_PART 01 Optional “code” input allows for referencing external PY files or a [Panel] component. This does not appear by default (right click). The default names of the input variables. If it goes into “x,” then you call “x” inside the script. Optional “out” parameter shows any errors or any output from a print method call. The default names of the output variables. If you declare a = "Thing" then "Thing" will come out into GH.
Use the ZUI +/to add/remove inputs and outputs.
Default type System Value Types
Rhino Value Types When you rightclick, you get this menu. Pay attention to the data structure of your inputs.
Rhino Reference Types
Text Display
Icon Display
Python Scripting in Grasshopper a ni–fty guide ANATOMY OF THE GHPYTHON SCRIPTING COMPONENT_PART 02 When you double click in the center of the component, the editor pops out. (It is not as complex as the C# editor, for better or worse.) Actually helpful in the beginning. Links to GH forum, Rhino.Python forum and rhinoscriptsyntax library help. This is generally how I set up my scripts, especially if I plan to save it as a GHUSER component or it’s contained within a cluster. Note 01: There is no pre-determined bits of code or default imported libraries like in C#. This Python editor is a “blank slate,” so to speak. Note 02: You do not need to declare variables. Python does this for you when you assign them a value. You can, however, cast certain values (like floats to strings and vice versa). 1. Define description, inputs, outputs. 2. Name (and NickName) the component. 3. Import relevant libraries and methods. 4. Declare variables. 5. Code body (action). 6. Declare outputs (push to GH).
Click “Test” to execute the code without closing the editor. This saves your script automatically.
This what the editor looks like when active.
Click “OK” or “Close” to close and execute. “OK” will save your script. “Close” will prompt you to save with a dialogue box.
Debugger (kind of, not really – hopefully in the future). Displays errors, any output from a print method call, and help when using methods. Not always the most useful resource, but can be a quick way of understanding what’s happening in your code. If you want a true Debugger, use the Editor in Rhino by calling it via _EditPythonScript or using a text editor (I have a few workarounds for using RhinoCommon in external editors, if you’re interested).
Python Scripting in Grasshopper a ni–fty guide ANATOMY OF THE GHPYTHON SCRIPTING COMPONENT_PART 03 When you type a period after a library module name or alias:
This is the RhinoCommon Geometry library. Within it are all the series of methods available. If you want to draw a line, for instance, you will need to type Rhino.Geometry.Line(point_01, point_02) where the variables are pre-defined with Point3d values.
When you type an open parenthesis after a method name:
Description of method. Return type (Parameters and their types)
Python Scripting in Grasshopper a ni–fty guide CONTROL STRUCTURES Loops
for x in range(lower_int_bounds, upper_int_bounds, step_size): # Do something.
Conditionals
# Import libraries. if some_condition == True: # Do something. elif some_other_condition == True: # Do something else. else: # Do the other thing.
Example Script
# Import libraries. import math import rhinoscriptsyntax as rs import Rhino # Define variables and lists. var_01 = Var_01 var_02 = Var_02 step = Step Pts = [] # Draw a sine wave using points. for x in rs.frange(var_01, var_02, step): y = N * math.sin(x) pt = Rhino.Geometry.Point3d(x, y, 0) Pts.append(pt)
Python Scripting in Grasshopper a ni–fty guide PYTHON CODING RESOURCES The Python script engine is entirely based on RhinoCommon, the geometry library inside Rhino/Grasshopper. So I encourage you to learn about the methods available in RhinoCommon at the SDK Documentation website here, and looking at the examples found here: “Using RhinoCommon from Python.” You should also learn about the methods in the rhinoscriptsyntax module here, and looking at the examples found here: “Rhino.Python rhinoscriptsyntax Module.”
Python website IronPython website Rhino Scripting forum Grasshopper Scripting forum
Python Scripting in Grasshopper a ni–fty guide USEFUL KEYWORDS, METHODS, AND HIDDEN SECRETS print str(some_variable) Write the contents of the string to the “out” output. rh_doc = Rhino.RhinoDoc.ActiveDoc Get access to the currently active Rhino Document. gh_doc = ghenv.Component.OnPingDocument() Get access to the currently active Grasshopper Document. Note: Naming this ghdoc is a no-no. That variable contains a reference to the current Grasshopper document solution. I’d use it sparingly. gh_canvas = Grasshopper.Instances.ActiveCanvas Get access to the currently active Grasshopper canvas. The scriptcontext module. GHPython defaults to the active Grasshopper document, so if you want to target the active Rhino document, you will need to point to it using the below method import scriptcontext as sc sc.doc = Rhino.RhinoDoc.ActiveDoc
The ghpythonlib library.* *See next page.
try: except: “Handle” errors without killing the current execution. Example below. try: print my_pt_list[5].ToString() # This could fail if the my_pt_list array has fewer than six members. except Exception, e: print str(e) # Print the error.
Python Scripting in Grasshopper a ni–fty guide GHPYTHONLIB: GHCOMP (NODE IN CODE) GHPython’s “Node in Code” feature allows you to access and execute (almost) any installed component with a Python script. This is the components module. Example Script: [Brep | Plane] Component
# Import libraries. import ghpythonlib.components as ghcomp # Name the component. ghenv.Component.Name = "Brep | Plane" ghenv.Component.NickName = 'Sec' # Node in Code sec = ghcomp.BrepXPlane(B, P) C = sec[0] P = sec[1]
These do the same thing.
Python Scripting in Grasshopper a ni–fty guide GHPYTHONLIB: PARALLEL The ghpythonlib also has a module called parallel. It contains a single function, “run,” which takes a list of data and a single function that should be called for each item in the list as its inputs. The run function calls this function on as many threads as there are processors in your computer, then returns the values in the same order as the input list. Example Script: [Offset on Srf] Component
from ghpythonlib import parallel as ghpllel import Rhino tolerance = Rhino.RhinoDoc.ActiveDoc.ModelAbsoluteTolerance # Function to be executed by parallel.run def offset_srf(args): crv, srf = args crv_length = crv.OffsetOnSurface(srf, D, tolerance) return [curve for curve in crv_length] # Run parallel if P: args = [[C[i], S[i]] for i in range(len(C))] OC = ghpllel.run(offset_srf, args, True) else: pass
These do the same thing.
Python Scripting in Grasshopper a ni–fty guide PARTING THOUGHT
Some things in programming are bad; they can really make you mad. Other things just make you swear and curse. When you’re chewing on code’s gristle, don’t grumble, give a whistle! And this’ll help things turn out for the best ... And Always Look on the Bright Side of Life!
