Rhino Scripting

All Rhino commands can be used in command scripts. Command scripts 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 Scripts

Write command scripts just as you would type the command sequence at the command line. A space between characters or a new line act like pressing Enter

at the command line.

Special characters

Character

Meaning in script

!
(exclamation point)

Cancels the previous command.

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

_
(underscore)

Runs command as English command name.

Rhino can be localized in many languages. The non-English versions will have commands, prompts, command options, dialog boxes, menus, etc., translated into their respective languages. English commands will not work in these versions.

For scripts written in English to work on all computers (regardless of the language of Rhino), the scripts need to force Rhino to interpret all commands as English command names.

For example: In the English version of Rhino, the following script works:

Circle 3Point 0,0,0 1,1,0 0,3,0

But in the French version of Rhino, this won’t work. Instead you need one of these scripts:

Cercle 3Point 0,0,0 1,1,0 0,3,0
_Circle _3Point 0,0,0 1,1,0 0,3,0

To make sure scripts work worldwide, write them in English and put _ in front of all command names and options.

-
(hyphen)

Suppress dialog box.

All commands are now scriptable 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 (-).


(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 first character in a toolbar script is not “!” and the last character is” \”, the script runs on the command line without Enter, so more information can be added.  

This feature is useful for building a command string out of parts like digits, decimal points, angles (such as “<45″) that are on buttons, making a “numeric keypad” on the screen.

;

(semicolon)

Comment.

Lines beginning with a semicolon (;) are not part of the script, but let you document the script 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

Examples

Draw a circle

This script 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.

Unselect objects and start the Move command

This script 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 script creates a set of points, selects them all, and fits a polyline through the points:

! _SelAll _Points _Pause _Pause _Pause _Enter _Invert _CurveThroughPt _Enter

How this script works:

! _SelAll

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

_Points

Runs the Points command.

_Pause x 3

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.

 _Enter

Completes the command.

Bypass a dialog box

! -_Rebuild _Pause _Points=10 _Degree=3 _Enter

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

To try these scripts:

  1. Select the script 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 script.

Special scripting commands

Pause

Stops for user input in a script.

Example:

! _Circle _Pause 50

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

Enter

Simulates pressing Enter in a script.

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

key does.

SetRedrawOff

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

SetRedrawOn

Turns screen redraw back on after SetRedrawOff

NoEcho

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

Echo

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

Notes

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

MacroEditor

Opens an edit window for script creation and testing.

Steps:

  • Type commands in the Macro Editor window.

  • To test, click Run.

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

Rhinoceros MacroEditor Scripting

Utilities > Open macro editor

Rhinoceros Menu2 Scripting

Tools > Commands > Macro Editor

Rhinoceros Gray Book Open Scripting Related topics…

ReadCommandFile

Reads and executes a command script 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&.

Rhinoceros ReadCommandFile Scripting

Tools > Read Command File

Rhinoceros Menu2 Scripting

Tools > Commands > Read from File

Rhinoceros Gray Book Open Scripting Related topics…

Pause

Stops a script for user input.

Example:

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

! _Circle _Pause 50

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

Enter

Functions as pressing the Enter key 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

Notes

  • The Enter command does not repeat the previous command like pressing the Enter

    key does.

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

Echo

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

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

NoEcho

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

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

SetRedrawOn

Enables screen redraw, construction plane, or camera changes during scripts.

Notes

  • Turns screen redraw back on after the SetRedrawOff

    command

Rhinoceros setredrawon Scripting

View > Set Redraw On (Right click)

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

SetRedrawOff

Disables screen redraw, construction plane, or camera changes during scripts.

Notes

  • Turn screen redraw back on with the SetRedrawOn

    command

Rhinoceros SetRedrawOff Scripting

View > Set Redraw Off

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

Cancel

Cancels the current command and deselects objects.

Rhinoceros Cancel Scripting

Main1 > Cancel

Rhinoceros Menu2 Scripting

None

Rhinoceros key 008 Scripting

Keyboard Shortcut: Esc

Rhinoceros Gray Book Open Scripting Related topics…

Exit

Closes the current Rhino session.

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

Run

Runs another application from inside Rhino.

Steps:

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

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

SetUserText

Attaches text information to an object.

The information is stored in a key/value way like the Windows registry uses.

Retrieve the information with the GetUserText
command. This information can also be attached by .NET plug-ins and VisualBasic scripts.

This information is easily accessed in .NET and Visual Basic scripts.

Example

Text key = Weight

Text = Kilograms

Steps:

  1. Select

    objects.

  2. Type a text key.

  3. Type the text.

Options

AttachTo

Object

Attaches text information to the object geometry.

If the information is closely associated with the geometry, attach it to the geometry. For example, a circle’s radius should be attached to the geometry because the information will be invalid if the circle is control-point edited and changed into a NURBS curve.

Attributes

Attaches text information to the attributes of an object.

If the information is higher-level attribute information, like color, then it should be attached to the object’s attributes. Attribute information will persist when an object is control point edited, trimmed, copied, and so on.

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

GetUserText

Retrieves text information attached using the SetUserText
command. This information can also be retrieved by .NET plug-ins and VisualBasic scripts.

Steps:

  1. Select

    objects.

  2. Type a text key or press Enter

    for all keys.

Rhinoceros  ABlankButton Scripting

None

Rhinoceros Menu2 Scripting

None

Rhinoceros Gray Book Open Scripting Related topics…

 

Scripting