Command macros and scripting

All Rhino commands can be used in command macros. Command macros can be run by typing the command at the command prompt, from toolbar buttons, shortcut keys, command aliases, from the ReadCommandFile command, or using the Paste command into Rhino's command stream.

Writing Command Macros

Write command macros just as you would type the command sequence at the command line.

Special characters

Meaning in macro

(Space)

A space character in macros acts like pressing Enter.

When scripting a name (or a text string) that contains spaces, you need to enclose it in double-quotes to avoid breaking the command sequence.

For example:

_-SelName "Table 01"

_-SelName Table 01

*
(asterisk)

Causes the command to repeat automatically without pressing Enter to restart.

!
(exclamation point)

Cancels the previous command.

An exclamation point (!) in the beginning of a macro cancels any previous command. At other locations, it cancels the macro. If necessary, the exclamation point can be used at the end of the macro.

-
(hyphen / dash)

Suppresses dialog box.

Basically, all commands can be made into macros at the command line (even commands that have dialog boxes by default). To suppress the dialog box and use command-line options, prefix the command name with a hyphen (-). A few commands (e.g., DevLoft) have options only available at the command-line.

_
(underscore)

Runs commands and options in English.

Rhino is localized in several languages. Commands and options are translated differently in different languages. To make macros work worldwide, we suggest writing macros in English with an underscore in front of every command and option.

For example:

Cerchio 3Punti 0,0,0 1,1,0 0,3,0

This macro only works in the Italian version of Rhino.

 

_Circle _3Point 0,0,0 1,1,0 0,3,0

This macro works in all language versions of Rhino.

'
(apostrophe)

The next command is a nestable command.

View and construction plane manipulation and object snaps are nestable. Geometry creation commands are not nestable.

One-shot object snaps and sub-object picking filters are automatically nestable and do not require an apostrophe.

\
(backslash)

If the last character in a toolbar button macro is "\", the macro runs without proceeding Enter at the end.

For example:

Create a toolbar button with a macro "5\". Clicking the button enters 5 to the command line and stops there for further input. This feature can be used to create a toolbar that works like an on-screen numeric keypad.

~
(tilde)

Suppresses command options for clutter free command feedback. The options still work as usual.

;

(semicolon)

Comment.

Lines beginning with a semicolon (;) are not part of the macro, but let you document the macro or try alternative input.

For example:

; This is a test macro
_Circle 0,0,0 15
_Line 0,0,0 pause ;15,0,0
; Line 0,0,0 0,15,0
_Line 0,0,0 -15,0,0

::
(double colon)

Layer nesting is indicated by a double colon - "::" between layer names. In the -Layer command, add a new layer nested under Layer 01 using a macro like this:

! _-Layer New "Layer 01:: New Layer" Enter

#
(hash)

Enables history recording for the following command.

For example: #ArcBlend

%
(percent)

Disables history recording for the following command.

For example: %ArcBlend

Examples

Draw a circle

This macro creates a circle centered at 5,5 with a radius of 10:

! _-Circle 5,5 10

The spaces between the entries are the same places you would press Enter when typing the command by hand.

Deselect objects and start the Move command

This macro starts the Move command, but makes sure no objects are selected before asking you to select objects to move:

! _SelNone _Move

Create a curve through points

This macro creates a set of three points, selects them all, and fits a polyline through the points:

! _SelAll _Points _Pause _Pause _Pause _Enter _Invert _CurveThroughPt _EnterEnd

How this script works:

! _SelAll

Cancels all previous commands and selects all the objects currently in the model.

_Points

Runs the Points command.

_Pause

_Pause

_Pause

Allows picking three point locations.

_Enter

Simulates pressing Enter, which stops the creation of point objects.

_Invert

Inverts the selection. All visible objects in the scene were selected at the beginning of the script, so after Invert only the newly created point objects are selected.

_CurveThroughPt

Creates a polyline through the point objects.

_EnterEnd

Completes the command.

Bypass a dialog box

! -_Rebuild _Pause _Points=10 _Degree=3 _Enter

Select a curve, then run this macro. All options will be set by the macro.

To try these scripts

  1. Select the macro right from this Help topic.
  2. Press Ctrl + C to copy it to the Clipboard.
  3. Click in the Rhino command prompt, and press Ctrl + V to paste the macro.
Special scripting commands

Pause

Stops for user input in a macro.

Example:

! _Circle _Pause 50

This macro asks for a point and then draws a circle with a 50 unit radius centered there.

MultiPause

Stops a script for the duration of multiple selections, for example in Join, Polyline, and FilletEdge.

Enter

Simulates pressing Enter inside a macro.

This command does not repeat the previous command like pressing Enter does.

EnterEnd

Completes the command.

SetRedrawOff

Prevents screen redraw, construction plane or camera changes during macros.

SetRedrawOn

Turns screen redraw back on after SetRedrawOff.

NoEcho

Turns off echoing of macro commands to the command history window.

Echo

Turns on echoing of macro commands to the command history window.

If you do not know what to type in a macro, run the hyphenated version of the command. Highlight and copy the command sequence and paste it into your macro text as a starting point.

MacroEditor

Toolbar Menu Panel Gear Menu

Tools

Tools

Commands >

Macro Editor

Panels

Macro Editor

Macro Editor

The MacroEditor command opens an edit window for macro creation and testing.

Macro Editor panel

Panel options

Steps

  1. Type commands in the Macro Editor window.
  2. To test, click Run.
  3. To delete the macro, click Delete.

Notes

  • Selecting some text and clicking Run will run only that selected part of the macro.
  • There is a right click context menu for selecting all, copy, paste, delete, run, etc.

ReadCommandFile

Toolbar Menu

Tools

Tools

Commands >

Read from File

The ReadCommandFile command reads and executes a command macro from a text file.

Steps

  • In the Open Text File dialog box, select the file to read.
    The file contents are copied into the command line, and the lines of the command file are interpreted as if they were typed into the command line.

Notes

  • When building command files, use the Enter command, which is equivalent to pressing Enter to execute commands.
  • If you read in a particular file often, assign ReadCommandFile to a toolbar button along with a filename. For example: -ReadCommandFile myfile.txt
  • If the file name has spaces, surround the text with quote marks. For example: -ReadCommandFile "my file.txt".

Example

Make a text file like the following example that has commands for creating all your curves in it, and then create the curves all at once with ReadCommandFile.

! _interpcrv
23,5,0
23.2,5,0
23.7,5.2,1
_Enter
_interpcrv
26.1,4.9,1.1
26.8,4.9,1.0
27.1,4.8,0.9
_Enter

etc&.

Echo

Toolbar Menu

Not on toolbars.

Not on menus.

The Echo command turns on echoing of macro commands to the command history window.

To turn echoing off, use the NoEcho command.

NoEcho

Toolbar Menu

Not on toolbars.

Not on menus.

The NoEcho command turns off display of macro commands in the command history window.

  • To turn echoing on use the Echo command.

NoEcho or _NoEcho needs to be the very first word in the macro for it to work properly. Everything, including the exclamation point should follow, separated by a single space.

Enter

Toolbar Menu

Not on toolbars.

Not on menus.

The Enter command functions as pressing Enter for use in scripts or toolbar button programming.

Example

This script sets a construction plane by three picked points:

'_CPlane _3Point

_Pause _Pause _Pause _Enter

The Enter command does not repeat the previous command like pressing the Enter key does.

EnterEnd

Toolbar Menu

Not on toolbars.

Not on menus.

The EnterEnd command functions as pressing the Enter key to complete a command string for use in macros or toolbar button programming.

EnterEnd is handy when a command is deep, in terms of command options such as Options or DocumentProperties, and you want to exit after one of these without counting how many Enters you need to get back to a blank command prompt. For example:

! _-DocumentProperties _Mesh _Custom _MaxEdgeSrf .01

would require at least two or three enters to exit the command. With EnterEnd, the command exits as soon as you want it to.

Example

! _-DocumentProperties _Mesh _Custom _MaxEdgeSrf .01 _EnterEnd

Exit

Toolbar

Menu

Shortcut

Not on toolbars.

File

Exit

Ctrl (CMD) + Q

The Exit command closes the current Rhino session.

To access command-line options

  • Type a hyphen in front of the command name -Exit.
Command-line options

Yes

 

No

 

Cancel

 

Pause

Toolbar Menu

Not on toolbars.

Not on menus.

The Pause command stops a macro for user input.

Example

This macro asks for a point and then draws a circle with a 50 unit radius centered there.

! _Circle _Pause 50

MultiPause

Toolbar Menu

Not on toolbars.

Not on menus.

The MultiPause command stops a macro for user input.

Example

This macro asks for objects to join.

! _Join _MultiPause

Run

Toolbar Menu

Not on toolbars.

Not on menus.

The Run command runs another application from inside Rhino.

Steps

  • Type the name and path of the file to run.

SetRedrawOff

Toolbar Menu

View

Not on menus.

The SetRedrawOff command disables screen redraw, construction plane, or camera changes during scripts.

To turn screen redraw back on

SetRedrawOn

Toolbar Menu

View

Not on menus.

The SetRedrawOn command enables screen redraw, construction plane, or camera changes during scripts.

To turn screen redraw off

Scripting

RhinoScript is a plug-in for running scripts. Scripting languages allow loops, variable names, browsing for files, queries, and other

The commands to use:

The basic steps are

  1. Write a script function.
    RhinoScripts use the file extension .rvb.
  2. Run the LoadScript command to load a script into memory.
  3. Use the RunScript command to run the function name.

Dragging a .rvb file onto the Rhino window will load and run the script.

For more help on scripts

  • From the Rhino Help menu, click Plug-ins and then click RhinoScript.

For more information on Rhino-specific scripting, see: http://wiki.mcneel.com/rhino/basicmacros.

LoadScript

Toolbar Menu

Not on toolbars.

Tools menu

Rhino Script >

Load

The LoadScript command reads a script file from disk, loads it into the script interpreter, and runs it.

Dragging a .rvb file onto the Rhino window will load and run the script.

Steps

  • In the Load Script File dialog box, click the Add button.

RunScript

Toolbar Menu

Not on toolbars.

Tools menu

Rhino Script >

Run

The RunScript command runs a previously loaded script.

Dragging a .rvb file onto the Rhino window will load and run the script.

Steps

  • In the Run Script Subroutine dialog box, click the Help menu.

EditScript

Toolbar Menu

Tools

Rhino Script >

Edit

The EditScript command opens a text editor utility for editing RhinoScript files.

Steps

  • In the Edit Script dialog box, click the Help menu.

RunPythonScript

Toolbar Menu

Not on toolbars.

Tools

Python Script >

Run

The RunPythonScript command runs a Python script.

For the on-line Rhino.Python programmers reference, see: http://developer.rhino3d.com/guides/rhinopython/.

-RunPythonScript

Options

ResetEngine

Forces the python engine to re-initialize. This is only useful while python scripts that span multiple files are being written and tested.

EditPythonScript

Toolbar Menu

Tools

Tools

Python Script >

Edit

The EditPythonScript command edits a Python script.

For more information on Rhino-specific scripting, see: http://wiki.mcneel.com/developer/python.

Script Compiler

Toolbar

Menu

Grasshopper

New in V7

Tools

Tools

Script Compiler

The Script Compiler application turns script files (.rvb, .py, gh, ghx) into *.rhp plug-ins.

 

The Script Compiler application is installed by the Rhino installer at:

C:\Program Files\Rhino <version>\System\RhinoScriptCompiler.exe

Steps

  1. Select Tools > Script Compiler.

  2. Press the keys of the highlighted letters to go through actions.