Rhino3d Scripts

---
name: rhino3d-scripts
description: 'Authoring and debugging scripts for Rhinoceros 3D (Rhino 8 and later). Use when asked to write RhinoScript (VBScript / .rvb / .vbs), RhinoPython, or RhinoCommon-based scripts; automate Rhino modeling tasks; build command macros; manipulate Rhino geometry, layers, blocks, or document objects; pick objects from the viewport; control redraw and undo; or load and run scripts from the Rhino Script Editor. Covers `rhinoscriptsyntax`, `scriptcontext`, the `Rhino.*` RhinoCommon namespaces (`Rhino.Geometry`, `Rhino.DocObjects`, `Rhino.Input`, `Rhino.UI`, `Rhino.Display`, `Rhino.FileIO`), and the Rhino 8 unified Script Editor.'
---

# 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.

| Surface | When to choose | File ext |
|---|---|---|
| **RhinoPython** (`rhinoscriptsyntax` + RhinoCommon) | Default for new scripts. Best ecosystem, readable, full RhinoCommon access. | `.py` |
| **RhinoScript** (VBScript) | Maintaining legacy `.rvb`/`.vbs` files; integrating with VBA/COM. | `.rvb`, `.vbs` |
| **RhinoCommon (C#/.NET) via Script Editor** | Performance-critical loops, complex geometry, leveraging .NET libraries. | `.cs` |
| **Command macro** | Pure sequence of existing Rhino commands; no logic. | toolbar/alias |

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

```python
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

```python
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

```vbscript
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)

```python
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 `Dim`s 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.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `rs.GetObject` returns `None` immediately | The user pressed Escape, or your `filter` excludes everything. Re-check `rs.filter.*` flags. |
| “Unable to find script” when running by name | The folder isn’t in `Options → Files → Search paths`. |
| VBScript `Type mismatch` on coordinates | You passed a 2-element array. Rhino requires 3-element `Array(x, y, z)`. |
| Python `ImportError: No module named Rhino` | You’re running CPython outside Rhino. RhinoCommon is only available in Rhino’s embedded Python (or via `rhino3dm` for read-only file work). |
| Created geometry doesn’t appear | You forgot `doc.Views.Redraw()`, or `rs.EnableRedraw(False)` was never re-enabled. |
| Undo undoes only the last object of a batch | Wrap the batch in `BeginUndoRecord` / `EndUndoRecord`. |
| Script works alone but fails as a startup script | Startup runs before any document is open — return early or skip document-dependent work when `sc.doc is None`. |
| `rs.Command("...")` returns `False` | The macro string is malformed. Prefix with `!` and `-`, end every prompt with `_Enter` or a value. |

## References

- [references/rhinoscriptsyntax-cheatsheet.md](references/rhinoscriptsyntax-cheatsheet.md) — most-used `rs.*` functions by category.
- [references/rhinocommon-map.md](references/rhinocommon-map.md) — which namespace to import for which task.
- [references/macros-and-loading.md](references/macros-and-loading.md) — command-line macro syntax, `LoadScript` / `RunScript`, search paths.
- [references/vbscript-quirks.md](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

| Token | Meaning |
|---|---|
| `!` | **Cancel** any currently running command before this one starts. Always start macros with `!`. |
| `_` | Use the **English** (invariant) command name, so the macro works in any locale. |
| `-` | Run the command in **script mode** — suppress dialogs, accept input from the macro string. |
| `_Enter` | Press Enter at the current prompt. |
| `Pause` | Stop and wait for the user to supply this input interactively. |
| `;` | Comment to end of line. |
| Newline | Same as a space — a separator between tokens, not a command terminator. |

### Example macros

```text
! _-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`)

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

Or, with the script folder on the search path:

```text
_-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.

```text
_-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:

```python
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:

```text
! _-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

```python
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.

# 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

| Need | Namespace | Key types |
|---|---|---|
| The active document, units, tolerances, undo | `Rhino` | `RhinoDoc`, `RhinoApp` |
| Reading/writing objects in the doc | `Rhino.DocObjects` | `RhinoObject`, `ObjectAttributes`, `Layer`, `ObjectType` |
| Tables (layers, materials, blocks, dim styles) | `Rhino.DocObjects.Tables` | `LayerTable`, `InstanceDefinitionTable`, `MaterialTable` |
| Custom per-object user data | `Rhino.DocObjects.Custom` | `UserData` |
| File I/O (.3dm, import/export) | `Rhino.FileIO` | `File3dm`, `File3dmObject` |

## Geometry

| Need | Namespace | Key types |
|---|---|---|
| Points, vectors, transforms | `Rhino.Geometry` | `Point3d`, `Vector3d`, `Transform`, `Plane`, `BoundingBox` |
| Curves | `Rhino.Geometry` | `Curve`, `NurbsCurve`, `PolylineCurve`, `LineCurve`, `ArcCurve` |
| Surfaces & breps | `Rhino.Geometry` | `Surface`, `NurbsSurface`, `Brep`, `BrepFace`, `Extrusion` |
| Meshes | `Rhino.Geometry` | `Mesh`, `MeshFace`, `MeshNgon` |
| SubD | `Rhino.Geometry` | `SubD`, `SubDFace`, `SubDEdge` |
| Geometry collections (vertices, edges, faces lists) | `Rhino.Geometry.Collections` | `MeshVertexList`, `BrepEdgeList` |
| Intersections | `Rhino.Geometry.Intersect` | `Intersection`, `CurveIntersections` |
| Mesh refinement | `Rhino.Geometry.MeshRefinements` | |
| Space morphs (bend, twist, etc.) | `Rhino.Geometry.Morphs` | `BendSpaceMorph`, `TwistSpaceMorph` |

## User Interaction

| Need | Namespace | Key types |
|---|---|---|
| Prompts, getters, command results | `Rhino.Input` / `Rhino.Input.Custom` | `RhinoGet`, `GetObject`, `GetPoint`, `GetOption` |
| Commands (when building a plugin) | `Rhino.Commands` | `Command`, `Result` |
| Forms, dialogs, panels | `Rhino.UI` | `Dialog`, `Panels`, `RhinoEtoExtensions` |
| UI controls / data sources | `Rhino.UI.Controls` | |
| Gumball | `Rhino.UI.Gumball` | |

## Display & Rendering

| Need | Namespace | Key types |
|---|---|---|
| Viewports, display conduits, draw overlays | `Rhino.Display` | `DisplayPipeline`, `DisplayConduit`, `RhinoViewport` |
| Render content (materials, environments) | `Rhino.Render` | `RenderContent`, `RenderMaterial`, `RenderTexture` |
| Render mesh customization | `Rhino.Render.CustomRenderMeshes` | |
| Post effects | `Rhino.Render.PostEffects` | |

## Runtime & Plugins

| Need | Namespace | Key types |
|---|---|---|
| Plugin lifecycle, settings | `Rhino.PlugIns` | `PlugIn`, `FileImportPlugIn`, `FileExportPlugIn` |
| In-process Rhino (run Rhino from external .NET) | `Rhino.Runtime.InProcess` | `RhinoCore` |
| Native interop (pointers, marshalling) | `Rhino.Runtime.InteropWrappers` | |
| User notifications (toasts) | `Rhino.Runtime.Notifications` | |

## Common Patterns

```python
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

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

# `rhinoscriptsyntax` Cheatsheet

```python
import rhinoscriptsyntax as rs
```

## User Input

| Function | Returns |
|---|---|
| `rs.GetObject(message, filter, preselect, select)` | GUID or `None` |
| `rs.GetObjects(message, filter)` | list of GUIDs |
| `rs.GetPoint(message, base_point)` | `Point3d` or `None` |
| `rs.GetString(message, default, strings)` | str |
| `rs.GetInteger`, `rs.GetReal` | int / float |
| `rs.GetBoolean(message, items, defaults)` | list of bools |

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

| Function | Notes |
|---|---|
| `rs.AddPoint(point)` | |
| `rs.AddLine(start, end)` | |
| `rs.AddPolyline(points)` | `points` is a list of 3-tuples |
| `rs.AddCircle(plane_or_center, radius)` | |
| `rs.AddArc(plane, radius, angle_deg)` | angle in **degrees** |
| `rs.AddCurve(points, degree=3)` | NURBS through control points |
| `rs.AddInterpCurve(points, degree=3)` | NURBS through points |
| `rs.AddSphere(center, radius)` | |
| `rs.AddBox(corners)` | `corners` = 8 points |
| `rs.AddPlanarSrf(curves)` | returns list |
| `rs.AddLoftSrf(curves, ...)` | returns list of GUIDs |
| `rs.AddExtrusion(profile, path)` / `rs.ExtrudeCurveStraight` | |

## Object Properties

| Function | Purpose |
|---|---|
| `rs.ObjectLayer(id [, layer])` | get/set |
| `rs.ObjectColor(id [, color])` | RGB tuple |
| `rs.ObjectName(id [, name])` | |
| `rs.ObjectType(id)` | int matching `rs.filter.*` |
| `rs.IsCurve / IsSurface / IsBrep / IsMesh / IsPoint(id)` | |
| `rs.DeleteObject(id)` / `rs.DeleteObjects(ids)` | |
| `rs.CopyObject(id, translation)` | |
| `rs.MoveObject(id, translation)` | |
| `rs.RotateObject(id, center, angle, axis=None, copy=False)` | angle in degrees |
| `rs.ScaleObject(id, origin, scale)` | scale is a 3-tuple |

## Curves

| Function | |
|---|---|
| `rs.CurveLength(id)` | |
| `rs.CurveDomain(id)` | `(t0, t1)` |
| `rs.EvaluateCurve(id, t)` | `Point3d` |
| `rs.CurveStartPoint / CurveEndPoint(id)` | |
| `rs.CurveClosestPoint(id, point)` | parameter `t` |
| `rs.DivideCurve(id, segments, create_points=False, return_points=True)` | |
| `rs.IsCurveClosed / IsCurvePlanar(id)` | |

## Layers

| Function | |
|---|---|
| `rs.AddLayer(name, color=None, visible=True, locked=False, parent=None)` | |
| `rs.CurrentLayer([layer])` | |
| `rs.LayerNames()` | list |
| `rs.LayerVisible(name [, visible])` | |
| `rs.DeleteLayer(name)` | |
| `rs.ObjectsByLayer(name)` | list of GUIDs |

## Document & View

| Function | |
|---|---|
| `rs.UnitAbsoluteTolerance()` | |
| `rs.UnitSystem()` | int (`rs.unit_system_*`) |
| `rs.EnableRedraw(enable)` | **toggle this around bulk ops** |
| `rs.Redraw()` | force one redraw |
| `rs.ViewNames()` / `rs.CurrentView([name])` | |
| `rs.ZoomExtents(view=None, all=False)` | |

## Selection

| Function | |
|---|---|
| `rs.SelectedObjects()` | list |
| `rs.SelectObject(id)` / `rs.SelectObjects(ids)` | |
| `rs.UnselectAllObjects()` | |
| `rs.InvertSelectedObjects()` | |

## 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):

```python
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:

```vbscript
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`

| Sentinel | Test with | Meaning |
|---|---|---|
| `Empty` | `IsEmpty(x)` | `Dim`’d but never assigned |
| `Null` | `IsNull(x)` | Explicit “no value” — what `Rhino.GetObject` returns on cancel |
| `Nothing` | `x Is Nothing` | An **object** reference that points to nothing — only for `Set` variables |

Wrong sentinel → silently false.

## Parentheses Change Semantics

```vbscript
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:

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

## Arrays Are 0-Based But Have `UBound`, Not `Length`

```vbscript
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

```vbscript
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

```vbscript
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.

```vbscript
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 `&`:

```vbscript
Rhino.Print "Count: " & n
```

## `For Each` Needs a `Variant`

```vbscript
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`).