Rhino3d Scripts

Rhino 3D Scripting Skill

Write production-quality scripts for Rhinoceros 3D. Covers the three scripting surfaces (RhinoScript/VBScript, RhinoPython, direct RhinoCommon .NET) and the Rhino 8+ Script Editor.

When to Use This Skill

• User asks to write, edit, or debug a .rvb, .vbs, or .py Rhino script
• User wants a Rhino command macro or wants to automate a sequence of Rhino commands
• User wants to manipulate geometry, layers, blocks, materials, viewports, or annotations from code
• User mentions rhinoscriptsyntax, scriptcontext, RhinoCommon, Rhino.Geometry, RhinoDoc, or the Script Editor
• User wants to pick objects, prompt for input, or build a small UI inside Rhino
• User asks how to load, run, or distribute a script (startup scripts, aliases, toolbar buttons)

Choosing a Scripting Surface

Pick the surface based on the task, not preference. Recommend Python by default for new work.

A macro is not a script — it is a string of command-line input (e.g. ! _-Line 0,0,0 10,0,0 _Enter). Use a script the moment you need a variable, loop, or conditional.

Prerequisites

• Rhino 7 or later (Rhino 8 strongly recommended — unified Script Editor supports Python 3, VB, and C# in one window).
• Script Editor: type _ScriptEditor (Rhino 8) or _EditPythonScript / _EditScript (older).
• Run a saved file from the command line with _-RunPythonScript or _LoadScript + _RunScript.

Core Patterns

Python: minimal scaffold

import rhinoscriptsyntax as rs
import scriptcontext as sc
import Rhino

def main():
    obj_id = rs.GetObject("Select a curve", filter=rs.filter.curve, preselect=True)
    if not obj_id:
        return
    length = rs.CurveLength(obj_id)
    print("Length: {0:.4f}".format(length))

if __name__ == "__main__":
    main()

Python: working with RhinoCommon directly

import Rhino
import scriptcontext as sc

doc = sc.doc  # Rhino.RhinoDoc.ActiveDoc
tol = doc.ModelAbsoluteTolerance

circle = Rhino.Geometry.Circle(Rhino.Geometry.Point3d(0, 0, 0), 5.0)
curve_id = doc.Objects.AddCircle(circle)
doc.Views.Redraw()

VBScript: minimal scaffold

Option Explicit

Call Main()

Sub Main()
    Dim strObject
    strObject = Rhino.GetObject("Select a curve", 4)  ' 4 = curve filter
    If IsNull(strObject) Then Exit Sub
    Rhino.Print "Length: " & Rhino.CurveLength(strObject)
End Sub

Picking objects with a custom filter (Python, RhinoCommon)

import Rhino
import scriptcontext as sc

go = Rhino.Input.Custom.GetObject()
go.SetCommandPrompt("Select breps")
go.GeometryFilter = Rhino.DocObjects.ObjectType.Brep
go.SubObjectSelect = False
go.GetMultiple(1, 0)
if go.CommandResult() != Rhino.Commands.Result.Success:
    pass
else:
    ids = [go.Object(i).ObjectId for i in range(go.ObjectCount)]

Step-by-Step Workflows

Bulk-modify many objects fast

1. Disable redraw: rs.EnableRedraw(False). 2. Wrap mutations in a single undo record: undo = doc.BeginUndoRecord("My Op") … doc.EndUndoRecord(undo). 3. Use RhinoCommon directly inside the loop (skip rhinoscriptsyntax overhead). 4. Re-enable redraw and call doc.Views.Redraw() in a try/finally so a crash never leaves the viewport frozen.

Distribute a script to a teammate

1. Save the .py / .rvb somewhere on disk. 2. Add the folder to Options → Files → Search paths so Rhino can find it by name. 3. Create a toolbar button or alias whose macro is:

• Python: ! _-RunPythonScript "MyScript.py"
• RhinoScript: ! _-LoadScript "MyScript.rvb" _-RunScript MySubName

4. The leading ! cancels any running command; - runs the command in script (no-dialog) mode.

Run code at Rhino startup

1. Place a .rvb/.py in a search path. 2. Tools → Options → RhinoScript (or Python) → add to Startup list. The file executes once per session.

Gotchas

• `rhinoscriptsyntax` returns GUIDs, RhinoCommon returns objects. Mixing them is fine, but doc.Objects.Find(guid) is the bridge from a rs.* id to a RhinoObject.
• Coordinates differ by surface. Python uses (x, y, z) tuples or Rhino.Geometry.Point3d; VBScript uses 3-element Array(x, y, z). Never pass a Python list to a VBScript helper through COM.
• `Option Explicit` is off by default in VBScript. Typos silently create new variables. Always add Option Explicit at the top of .rvb files.
• VBScript has no block scope. All Dims inside a Sub are hoisted to the top of the procedure. Loop counters leak.
• `Nothing`, `Empty`, and `Null` are different in VBScript. Use IsNull for Rhino.GetObject failure, IsEmpty for uninitialized Variant, Is Nothing for object refs.
• Parentheses change calling semantics in VBScript. Call Foo(a, b) and Foo a, b are valid; Foo(a, b) (no Call, with parens) is not a call to a Sub — it’s a syntax error for multi-arg subs and a forced ByVal for single-arg.
• Tolerance is per-document. Always read doc.ModelAbsoluteTolerance rather than hardcoding 0.001; users work in mm, m, inches, etc.
• Long loops should poll `Rhino.RhinoApp.EscapeKeyPressed` so the user can cancel. Otherwise Rhino appears frozen.
• GUID strings vs `System.Guid`. rhinoscriptsyntax accepts either; RhinoCommon wants System.Guid. Convert with System.Guid(str_id) if needed.
• Don’t call `doc.Views.Redraw()` inside a tight loop. Toggle redraw once outside the loop.
• `.rvb` is just `.vbs` renamed with a Rhino-specific extension so Rhino’s LoadScript recognizes it. Same VBScript engine.
• `Rhino.RhinoApp.IsHeadless` may not exist on older Rhino 8 builds. Use getattr(Rhino.RhinoApp, "IsHeadless", None) and check for None before using. Fall back to a heuristic (e.g. sc.doc.Views.Count == 0) or assume GUI present.
• `RhinoMath` is at `Rhino.RhinoMath`, not `Rhino.DocObjects.RhinoMath`. Accessing Rhino.DocObjects.RhinoMath raises AttributeError.
• `doc.Objects.AddBrep()` returns `System.Guid.Empty` on failure. In Rhino 8 CPython the System namespace may not be directly importable; check the return value as a string: str(obj_id) == "00000000-0000-0000-0000-000000000000".
• `rhinoscriptsyntax` has no type stubs. Static analysers (Pylance/Pyright) flag import rhinoscriptsyntax as rs as unresolvable. Suppress with # type: ignore on the import line; the module is always available at Rhino runtime.
• Never name a script after a Python standard-library module (e.g. random.py, math.py, os.py). IronPython 2.7 (_-RunPythonScript) resolves the script directory before stdlib, so any import random inside the stdlib (e.g. tempfile imports random internally) will find your file instead and fail with Cannot import name <X>. CPython 3 (rhinocode) is unaffected because it resolves stdlib first. Rename the script or avoid importing modules that pull in the shadowed name.
• Em dashes and other non-ASCII characters silently break `_-RunPythonScript` (IronPython 2.7). rhinocode script uses CPython 3 (UTF-8 by default) so the same file works there, making the failure non-obvious. IronPython 2.7 raises SyntaxError: Non-ASCII character '\xe2' at the first offending byte. The most common culprit is the em dash (-- auto-converted to -- by many editors). Add # -*- coding: utf-8 -*- as line 1 of every script that must run under both runtimes, and replace typographic characters with ASCII equivalents: em dash --, arrow ->, multiplication x.

Troubleshooting

References

• references/rhinoscriptsyntax-cheatsheet.md — most-used rs.* functions by category.
• references/rhinocommon-map.md — which namespace to import for which task.
• references/macros-and-loading.md — command-line macro syntax, LoadScript / RunScript, search paths.
• references/vbscript-quirks.md — VBScript-only traps relevant to RhinoScript.

Upstream docs

• RhinoScript landing: <https://docs.mcneel.com/rhino/8/help/en-us/information/rhinoscripting.htm>
• Developer hub: <https://developer.rhino3d.com/>
• RhinoCommon API index: <https://mcneel.github.io/rhinocommon-api-docs/api/RhinoCommon/html/R_Project_RhinoCommon.htm>
• Example scripts repo: <https://github.com/mcneel/rhino-developer-samples/tree/8/rhinoscript>

Macros, Loading, and Running Scripts

Command Macros (no script needed)

A macro is a string of command-line input. Anywhere Rhino accepts a command (alias, toolbar button, _ReadCommandFile), you can place a macro.

Syntax rules

Example macros

! _-Line 0,0,0 10,0,0
! _-Circle 0,0,0 5 _Enter
! _SelAll _Delete
! _-Properties _Object _Name "MyObject" _EnterEnd _Enter
! _-RunPythonScript "MyScript.py"

Running Saved Scripts

Python (.py)

_-RunPythonScript "C:\Users\example\Scripts\MyScript.py"

Or, with the script folder on the search path:

_-RunPythonScript "MyScript.py"

_EditPythonScript opens the legacy editor; _ScriptEditor (Rhino 8) opens the unified editor with Python 3, VB, and C#.

RhinoScript (.rvb, .vbs)

Two steps: load the file (registers its subs/functions), then run a named sub.

_-LoadScript "MyScript.rvb"
_-RunScript MyMainSub

A single .rvb can hold many subs; _RunScript chooses which to invoke.

Search Paths

Options → Files → Search paths — folders listed here are scanned when you reference a script by bare filename. Without this, you must give a full path.

Startup Scripts

Options → RhinoScript → Startup (and Options → Python → Startup) — files in these lists run once when Rhino opens. Useful for registering custom commands or aliases.

Guard against missing document in startup code:

import scriptcontext as sc

def startup():
    if sc.doc is None:
        return

startup()

Toolbar Buttons & Aliases

A toolbar button’s Command field is just a macro. To make a button that runs your script:

! _-RunPythonScript "MyScript.py"

Set the Tooltip to a short description; set the icon via the button editor.

To create an alias: Options → Aliases → New. The alias name becomes a typed command; its value is the macro.

Invoking Macros From a Script

import rhinoscriptsyntax as rs
rs.Command("! _-Line 0,0,0 10,0,0", echo=False)

echo=False suppresses command-history output but does not suppress prompts — always use - and complete every prompt within the macro string.

rhinocode CLI (Rhino 8)

rhinocode is the Rhino 8 command-line tool for running scripts and commands against a running Rhino instance from an external terminal.

Basic commands

rhinocode script "C:\path\to\MyScript.py"            # run a Python script
rhinocode command "_Circle 0,0,0 5 _Enter"           # run a Rhino command
rhinocode --rhino <instance-id> script "MyScript.py" # target a specific instance

<instance-id> looks like rhinocode_remotepipe_75029. Find the ID in Rhino's title bar or by running StartScriptServer in Rhino, which prints the pipe name to the command line.

Architecture — pipe server

rhinocode does not spawn a new Rhino process. It connects to a persistent server that Rhino exposes (StartScriptServer). Scripts execute inside that server process, which means:

• Environment variables are isolated. Variables set in the calling shell (set FOO=bar)

are NOT visible inside the script via os.environ. The server was started before your shell.

• `os.getcwd()` is the server's working directory, not the directory you called rhinocode

from. Do not rely on it for output paths; pass the path explicitly.

• `print()` output IS piped back to the calling terminal — use it freely for status messages.

Passing data into a script

rhinocode does not support positional arguments after the script path — any extra tokens are concatenated onto the file URI, causing a "file does not exist" error. Workarounds:

__file__ is a URI

When running via rhinocode, __file__ is set as a file:/// URI with URL-encoded characters (spaces become %20). Decode it before using it as a filesystem path:

import os, sys, urllib.parse

def _script_dir():
    raw = __file__
    if raw.startswith("file:///"):
        raw = urllib.parse.unquote(raw[len("file:///"):])
        if sys.platform == "win32":
            raw = raw.replace("/", os.sep)
    return os.path.dirname(os.path.abspath(raw))

RhinoCommon Namespace Map

Use this to decide which Rhino.* namespace to import for a task. All of these are accessible from Python with import Rhino.

Document & Object Model

Geometry

User Interaction

Display & Rendering

Runtime & Plugins

Common Patterns

import Rhino
import scriptcontext as sc
import System.Drawing

doc = sc.doc                                          # Rhino.RhinoDoc
tol = doc.ModelAbsoluteTolerance                      # float
view = doc.Views.ActiveView                           # Rhino.Display.RhinoView
layer_index = doc.Layers.Add("MyLayer", System.Drawing.Color.Red)

# Find a Rhino object from a rhinoscriptsyntax GUID
rhobj = doc.Objects.Find(guid)                        # Rhino.DocObjects.RhinoObject
geom  = rhobj.Geometry                                # Rhino.Geometry.GeometryBase

# Add geometry with attributes
attrs = Rhino.DocObjects.ObjectAttributes()
attrs.LayerIndex = layer_index
attrs.Name = "example"
new_id = doc.Objects.AddCurve(curve, attrs)

Undo

undo_serial = doc.BeginUndoRecord("Batch Op")
try:
    # ... many doc.Objects.* calls ...
    pass
finally:
    doc.EndUndoRecord(undo_serial)
    doc.Views.Redraw()

rhinoscriptsyntax Cheatsheet

import rhinoscriptsyntax as rs

User Input

Common rs.filter.* flags (OR them together):

point=1, point_cloud=2, curve=4, surface=8, polysurface=16,
mesh=32, light=256, annotation=512, instance_reference=4096,
text_dot=8192, grip=16384, detail=32768, hatch=65536,
morph_control=131072, sub_d=262144

Creating Geometry

Object Properties

Curves

Layers

Document & View

Selection

Macros from Script

rs.Command(command_string, echo=True) runs a macro exactly as if typed at the command line. Always prefix ! (cancel) and - (no dialog):

rs.Command("! _-Line 0,0,0 10,0,0", echo=False)

VBScript Quirks for RhinoScript

Things that bite when writing .rvb / .vbs files and aren’t obvious to anyone whose mental model is C-family or Python.

Always Start With Option Explicit

Without it, mistyping a variable name silently creates a new Variant set to Empty. Every .rvb file should begin:

Option Explicit

No Block Scope

All Dim declarations inside a Sub/Function are hoisted to the top. A Dim inside an If block is visible after the If ends. Loop counters survive the loop.

Nothing vs Empty vs Null

Wrong sentinel → silently false.

Parentheses Change Semantics

Foo a, b              ' Call a Sub or Function (return value discarded)
Call Foo(a, b)        ' Call a Sub or Function (return value discarded)
x = Foo(a, b)         ' Call a Function and capture the return
Foo(a, b)             ' SYNTAX ERROR for multi-arg subs

Foo(x)                ' Calls Foo passing x BY VALUE, even if Foo declares ByRef
Foo x                 ' Honors Foo's ByRef declaration

If a Sub modifies its argument and your change isn’t taking effect — you wrapped the argument in parentheses.

ByRef Is the Default

Unlike most languages, VBScript passes arguments by reference by default. Functions can mutate their callers’ variables. Be explicit:

Sub Increment(ByRef n)
    n = n + 1
End Sub

Arrays Are 0-Based But Have UBound, Not Length

Dim arr(2)            ' Three elements: arr(0), arr(1), arr(2)
For i = 0 To UBound(arr)
    arr(i) = i * 10
Next

Dim arr(n) creates n+1 elements. ReDim Preserve arr(newSize) resizes (only the last dimension of a multi-dim array).

Set Is Required for Object Assignment

Set fso = CreateObject("Scripting.FileSystemObject")    ' correct
fso = CreateObject("Scripting.FileSystemObject")        ' RUNTIME ERROR

Any time the right-hand side is an object (COM object, RegExp, Dictionary), you must use Set.

Error Handling Is Manual

On Error Resume Next
Rhino.AddCircle Array(0,0,0), -1
If Err.Number <> 0 Then
    Rhino.Print "Failed: " & Err.Description
    Err.Clear
End If
On Error GoTo 0           ' Restore normal error behavior

On Error Resume Next suppresses all errors until On Error GoTo 0. Forgetting to restore is a common bug.

Points Are 3-Element Arrays

Rhino expects Array(x, y, z). A 2-element array (Array(x, y)) raises a type-mismatch error.

Dim pt
pt = Array(1.0, 2.0, 3.0)
Rhino.AddPoint pt

String Concatenation Uses &, Not +

+ on strings works only if both sides are strings. If one side is a number, + does numeric addition and throws a type-mismatch. Always use &:

Rhino.Print "Count: " & n

For Each Needs a Variant

Dim item
For Each item In someCollection
    ' ...
Next

The loop variable must be Variant. You cannot Dim item As Long (VBScript has no typed Dim).