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.

intent

use this skill when the user asks to write, edit, debug, or distribute scripts for Rhino 7+. covers .rvb, .vbs, .py, and .cs files that automate rhino modeling, manipulate geometry/layers/blocks, pick objects, prompt for input, or build small UIs inside Rhino. pick this skill if the user mentions rhinoscriptsyntax, scriptcontext, RhinoCommon, Rhino.Geometry, RhinoDoc, the Script Editor, command macros, startup scripts, or distribution via toolbar buttons. do not use for non-Rhino scripting or for questions about Rhino's built-in commands alone (absent automation).

inputs

required context

• rhino version: 7 or later (rhino 8 strongly recommended; unified Script Editor supports Python 3, VB, and C# in one window).
• script type: identify whether the user wants RhinoPython (default), RhinoScript/VBScript, RhinoCommon C#, or a command macro.
• task intent: what the user wants to automate (e.g. bulk-modify objects, pick and measure curves, run at startup).

external connections

• Rhino Script Editor: invoke with _ScriptEditor (Rhino 8), _EditPythonScript, or _EditScript (older versions). no auth required; runs in-process inside Rhino.
• Script runtime (IronPython 2.7 vs CPython 3): _-RunPythonScript uses IronPython 2.7 (legacy, limited stdlib); rhinocode script uses CPython 3 (modern, full stdlib). CPython 3 is preferred for new work but requires Rhino 8.3+.
• RhinoCommon API (.NET): available in-process; no external auth. scope: Rhino.Geometry, Rhino.DocObjects, Rhino.Input, Rhino.UI, Rhino.Display, Rhino.FileIO, Rhino.Commands.
• Document and viewport access: via scriptcontext.doc (Python) or Rhino.RhinoDoc.ActiveDoc (RhinoCommon). all work is within the active document; no multi-document scope.

setup guidance

• python scripts: save to disk (e.g. C:\Users\YourUser\AppData\Roaming\McNeel\Rhinoceros\8.0\scripts\), then add the folder to Options → Files → Search paths so Rhino finds it by name.
• vbscript files: same folder pattern; use .rvb extension so Rhino recognizes it.
• startup scripts: place in a search path, then add to Tools → Options → RhinoScript (or Python) → Startup list. executes once per Rhino session, before any document is open.
• toolbar/alias macros: create in Tools → Toolbars or Tools → Aliases. macro string is command-line syntax (e.g. ! _-RunPythonScript "MyScript.py").

procedure

step 1: choose the scripting surface

determine which language and API to use based on the task.

inputs: task type (bulk edit, interactive object pick, performance loop, macro, distribution requirement).

decision logic:

• RhinoPython (default): new scripts, moderate complexity, interactive work. provides rhinoscriptsyntax (simple functions) plus full RhinoCommon access. use .py extension. best ecosystem and most readable.
• RhinoScript (VBScript): maintaining legacy .rvb / .vbs files, or integrating with VBA/COM code in other Autodesk tools. use .rvb or .vbs extension.
• RhinoCommon C# via Script Editor: performance-critical tight loops, complex geometry algorithms, or leveraging .NET libraries not in Python. use .cs extension and Rhino 8 Script Editor.
• command macro (string, no file): pure sequence of existing Rhino commands with no variables, loops, or conditionals. use toolbar/alias only. a macro is not a script: it is a command-line string (e.g. ! _-Line 0,0,0 10,0,0 _Enter). the moment you need a variable, loop, or if, write a script instead.

output: decision made; scripting surface and file extension chosen.

---

step 2: scaffold the script with correct imports and error handling

inputs: scripting surface chosen (from step 1).

for RhinoPython:

import rhinoscriptsyntax as rs
import scriptcontext as sc
import Rhino

def main():
    # your code here
    pass

if __name__ == "__main__":
    main()

optional: add # type: ignore after import rhinoscriptsyntax if your IDE flags it as unresolved (module is always available at Rhino runtime; the type stubs are incomplete).

for RhinoScript (VBScript):

Option Explicit

Call Main()

Sub Main()
    ' your code here
End Sub

always add Option Explicit at the top to catch typos (VBScript is lenient by default).

for RhinoCommon C#:

using Rhino;
using Rhino.Geometry;
using Rhino.DocObjects;

public partial class MyScript
{
    public void Run()
    {
        // your code here
    }
}

for command macro: no scaffold needed; write the command string directly in toolbar/alias.

output: script file created with correct imports, boilerplate structure, and error handling entry point.

---

step 3: implement the core logic

inputs: scaffolded script; task requirements (what the user wants to automate).

procedure by common patterns:

pattern 3a: pick and filter objects (RhinoPython + rhinoscriptsyntax)

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

pattern 3b: pick and filter objects (RhinoPython + RhinoCommon for more control)

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)  # min 1, max 0 (unlimited)

if go.CommandResult() != Rhino.Commands.Result.Success:
    print("cancelled or error")
    return

ids = [go.Object(i).ObjectId for i in range(go.ObjectCount)]
for obj_id in ids:
    rhino_obj = sc.doc.Objects.FindId(obj_id)
    print("selected: {0}".format(rhino_obj.Name or "unnamed"))

pattern 3c: bulk-modify many objects with undo and redraw control

import rhinoscriptsyntax as rs
import scriptcontext as sc

# disable redraw before loop
rs.EnableRedraw(False)

try:
    undo = sc.doc.BeginUndoRecord("bulk modify")
    
    # your loop here
    for obj_id in object_ids:
        rs.ScaleObject(obj_id, center, scale_factor)
    
    sc.doc.EndUndoRecord(undo)
finally:
    # always re-enable redraw, even on crash
    rs.EnableRedraw(True)
    sc.doc.Views.Redraw()

pattern 3d: work directly with RhinoCommon geometry (no file write)

import Rhino
import scriptcontext as sc

doc = sc.doc
tol = doc.ModelAbsoluteTolerance

# create geometry
circle = Rhino.Geometry.Circle(Rhino.Geometry.Point3d(0, 0, 0), 5.0)
curve_id = doc.Objects.AddCircle(circle)

# or add a brep
brep = Rhino.Geometry.Brep.CreateFromCylinder(
    Rhino.Geometry.Cylinder(Rhino.Geometry.Circle(...), height=10.0),
    cap=True,
    tolerance=tol
)
if brep:
    brep_id = doc.Objects.AddBrep(brep)
    if str(brep_id) != "00000000-0000-0000-0000-000000000000":
        print("brep added: {0}".format(brep_id))
    else:
        print("brep creation failed")

doc.Views.Redraw()

pattern 3e: prompt for numeric input, points, or geometry with validation

import Rhino
import scriptcontext as sc

# get a number
gi = Rhino.Input.Custom.GetNumber()
gi.SetCommandPrompt("enter radius")
gi.SetLowerLimit(0.1, False)
gi.Get()

if gi.CommandResult() == Rhino.Commands.Result.Success:
    radius = gi.Number()
else:
    return

# get a point
gp = Rhino.Input.Custom.GetPoint()
gp.SetCommandPrompt("pick center")
gp.Get()

if gp.CommandResult() == Rhino.Commands.Result.Success:
    center = gp.Point()
else:
    return

print("radius={0}, center={1}".format(radius, center))

pattern 3f: poll escape key so user can cancel long loops

import Rhino

for i in range(100000):
    if Rhino.RhinoApp.EscapeKeyPressed:
        print("cancelled by user")
        break
    # do work
    process_item(i)

pattern 3g: run code only at startup, skip in normal sessions

import scriptcontext as sc

if sc.doc is None:
    print("startup mode: loading custom modules")
    # e.g. add a search path, load plugins
else:
    print("normal mode: running in active document")
    # use sc.doc

pattern 3h: detect if Rhino is headless (no UI)

import Rhino

is_headless = getattr(Rhino.RhinoApp, "IsHeadless", None)
if is_headless is None:
    # old Rhino 8 build; fall back to heuristic
    is_headless = (sc.doc.Views.Count == 0) if sc.doc else True

if is_headless:
    print("headless mode: skip UI prompts")
else:
    print("gui mode: user can interact")

output: core logic implemented, follows one or more of the above patterns, handles failure cases (user cancel, empty result sets, invalid geometry).

---

step 4: add document tolerance and geometry validation

inputs: script with core logic; geometry operations or measurements.

procedure:

• always read document tolerance from sc.doc.ModelAbsoluteTolerance (Python) or Rhino.RhinoDoc.ActiveDoc.ModelAbsoluteTolerance instead of hardcoding (e.g. 0.001). users work in mm, m, inches, etc.
• validate geometry before use: check for None, empty result sets, degenerate curves (length near zero), or failed AddBrep (returns System.Guid.Empty).
• when creating geometry, pass tolerance as a parameter (e.g. Brep.CreateFromCylinder(..., tolerance=tol)).

code example:

import scriptcontext as sc

doc = sc.doc
tol = doc.ModelAbsoluteTolerance

# measure a curve with tolerance applied
curve = rs.GetObject("select a curve", filter=rs.filter.curve)
if not curve:
    return

length = rs.CurveLength(curve)
if length < tol:
    print("curve is degenerate (near zero length)")
    return

print("curve length: {0:.4f} (tolerance: {1})".format(length, tol))

output: geometry operations use document tolerance; edge cases (empty, degenerate, failed creation) are handled.

---

step 5: test in the Script Editor and debug

inputs: completed script file.

procedure:

• open the Script Editor: _ScriptEditor (Rhino 8), _EditPythonScript (older).
• load the script and run it (toolbar button or Ctrl+Enter).
• check console output for print() statements and error messages.
• if syntax error: fix and re-run. if runtime error (e.g. AttributeError, ImportError): verify imports, check Rhino version, confirm RhinoCommon API path.
• if object pick fails immediately: user pressed Escape or filter was too narrow. re-check rs.filter.* or GeometryFilter enum.
• if geometry doesn't appear: check for missing doc.Views.Redraw() or rs.EnableRedraw(True).
• if undo doesn't work as expected: wrap batch operations in BeginUndoRecord / EndUndoRecord.

output: script runs without errors; console output confirms expected behavior.

---

step 6: distribute or schedule the script

inputs: tested, working script file.

decision point: how and when should the script run?

branch 6a: distribute to a teammate (ad-hoc run)

1. save the .py / .rvb to a shared folder.
2. add the folder to Options → Files → Search paths.
3. create a toolbar button or alias whose macro is:
   • python: ! _-RunPythonScript "MyScript.py" (IronPython 2.7, older) or rhinocode script "MyScript.py" (CPython 3, Rhino 8.3+).
   • vbscript: ! _-LoadScript "MyScript.rvb" _-RunScript MySubName.
4. the leading ! cancels any running command; - runs in script (no-dialog) mode.
5. share the macro string or the toolbar .rui file.

branch 6b: run at Rhino startup (automatic initialization)

1. place the .py / .rvb in a search path folder.
2. open Tools → Options → RhinoScript (or Python) → Startup section.
3. click Add and select the script file.
4. the script executes once per Rhino session, before any document is open.
   • inside the script, check if sc.doc is None: to detect startup mode and skip document-specific work.
5. restart Rhino to confirm.

branch 6c: run as a command macro in toolbar or alias (pure command sequence)

1. if the task is a simple sequence of existing Rhino commands (no variables, loops, or conditionals), write a macro string instead of a script:

   ! _-Line 0,0,0 10,0,0 _Enter _-Circle 5,0,0 2 _Enter
   

2. create a toolbar button or alias: Tools → Toolbars or Tools → Aliases.
3. paste the macro string into the Macro field.
4. test by clicking the button or typing the alias name.

note: the - prefix suppresses dialogs (script mode); the _ prefix neutralizes locale-specific command names (e.g. _Line instead of Line in non-English Rhino). always use _Enter at the end of prompts or pass a value directly.

output: script is accessible to end users via toolbar, alias, startup list, or search path. distribution method is documented.

---

decision points

scripting surface (Python vs VBScript vs C#)

• if the user is starting new work: recommend RhinoPython. best ecosystem, readable, full RhinoCommon access, easiest debugging.
• if the user is maintaining existing .rvb / .vbs files: use RhinoScript (VBScript). no migration needed.
• if the task is a tight loop over 10k+ objects, or involves complex .NET libraries: use RhinoCommon C# via Script Editor.
• if the task is a pure sequence of existing Rhino commands: use a command macro, not a script. no file needed; macro lives in toolbar/alias.

runtime: IronPython 2.7 vs CPython 3

• if Rhino version is 8.3+ and the user is okay with that requirement: use rhinocode script (CPython 3). modern Python, full stdlib, utf-8 by default.
• if the script must run on Rhino 7 or early Rhino 8 builds: use _-RunPythonScript (IronPython 2.7). limited stdlib, no type hints, non-ASCII characters require # -*- coding: utf-8 -*- declaration.
• if the script must run on both: write for IronPython 2.7