"Scripting in Rhinoceros"

One of the most powerful features in Rhinoceros is command scripting. Rhinoceros features command scripting capabilities that let you automate modeling tasks and create new commands and icons to perform customized functions. Commandscripts can even build a whole model for you, based on different kinds of imported data or scripted procedures. You don't have to be a programmer or expert user to write command scripts in Rhinoceros.

A Commandscript or Macro is a series of Rhinoceros commands listed together in a text file so that they can be executed automatically in succession. This chapter will show you the different ways to run a Commandscript, the proper way to format Commandscripts, and get you started creating your own scripts.

Running Commandscripts

There are three different ways to run a commandscript in Rhinoceros. If you are new to Rhinoceros or if you have never written any commandscripts it is important that you understand the three different ways to run a commandscript in Rhinoceros. By working through the three easy examples you will gain a good understanding of their differences.

• The first is assigning correctly formatted text to a mouse button or hotkey and then clicking the icon. Commandscripts that are run from Icons or hotkeys should be commands that you use all the time. So you may not want a huge, rarely used macro to a mouse button of an icon or taking away precious hotkey space.
• The second way is by typing commandpaste or clicking the commandpaste Icon in the Tools toolbox. For Commandpaste to work you need to have correctly formatted text copied to the Windows clipboard first. Command paste is mainly used to test commandscripts. It can also be used to execute quick one-time macros you create on the fly or you don't want to save.
• The third is the Rhinoceros command Runcommandscript.. Runcommandscript is used to execute commandscripts from a saved text file. You first have to write the macro in a text editor. You then save it as a .txt file and then execute it in Rhinoceros. These commandscripts should be fully tested and free from errors. You should store your commandscripts in a separate distinct folder. You can share the fully tested ones with others and combine them to make other commandscripts.

Click on the following three examples to take you step by step through the three different ways to run a commandscript in Rhinoceros.

Commandscripting Syntax

Think of each command in Rhinoceros as a small commandscript. Every command in Rhinoceros has an official "command name". The command name does not necessarily match the command's label that you see in a menu or an icon's tooltip. Only official command names can be used within a commandscript or when typing commands from the keyboard into Rhinoceros. For example, the command labeled "Change layer" in a menu must be typed Changelayer, without a space in a commandscript. Changelayer is the official command name for this function.

Avoid errors by always using the official command name when you type a command. To guarantee accuracy, you can copy the official command names from the help files, and paste them directly into your scripts. You can also type the word "commands" at the command prompt and Rhinoceros will send all its command names to the command history or to the Windows clipboard. You can then view the entire list of Rhinoceros command names in the command history by pressing the F2 hotkey on your keyboard or you can paste it into a text file. 

1. Type the commands in your script just as you would at the command prompt in Rhinoceros.
2. A space between characters or a new line in your script mimics the user pressing the Enter key at the command prompt. The spaces between the entries are the same places you would press Enter when typing the command by hand.
3. The word enter, ! enter, or ! can end a script or a script sequence.
4. An exclamation point ! and a space after it (remember to put a space after the ! symbol) are usually used to begin a script . The exclamation point ! symbol cancels any previous command. The exclamation point can also be used at the end of the script it is similar to ending a script with the enter key.
5. Three-dimensional spatial coordinates that are used to locate a point in space in Rhinoceros must not have spaces in between the numbers and commas.
   A point located at cplane 12units X axis,10 units Y axis, and 8 units Z axis in Rhinoceros would be written in a script:
   12,10,8 not 12, 10, 8
6. Commandscripts are viewport sensitive this means that scripts work differently depending on which viewport is active before you process the commandscript.
7. Commandscripts are generally not written as one line of text with spaces only, although they can be.
   Here is an example:
   ! Polyline 0 10,0,0 10<60 0 enter
   This will work but it makes it harder for the user to read. Notice that it is very hard to sort out the spatial coordinates.
   Commandscripts should generally be written with line breaks between the commands and three-dimensional spatial coordinates to make it easier to script, debug and understand at a glance. Below in the left hand column is the same script with line breaks in between commands and three-dimensional spatial coordinate points. Notice how much easier it is to read.

Customizing Rhinoceros with Commandscripts

Writing simple Commandscripts assigned to icons will give you a basic understanding of how scripting works because you will become familiar with command names, what they do, and how they interact with each other. This will give you practice writing commandscripts before you go on to tackle larger and more complex projects.

Creating commandscripts on icons lets you customize Rhinoceros with your modeling, editing and display preferences. So you can change your modeling tools and add options to them in Rhinoceros to get your job done quickly and efficiently.

Customizing command "options" that appear at the Rhinoceros command prompt in the middle of modeling.
Quite a few commands that you use everyday in Rhinoceros have extra options to them that you have to input from the keyboard as you model. These are often one letter commands like c, y or n. For instance if you rotate an object, Rhinoceros also gives you the option to copy that object and rotate the copied object instead of the original. After you click the rotate icon you would do this by typing c at the keyboard. This can seem like it is easy enough. But if you need to rotate copies all the time and do it repeatedly this creates extra work. Usually you forget to type in the c option after many times of doing this and end up doing a regular rotate that you must cancel or undo. Since Rhinoceros has many commands with these extra options you can customize or make icons already with your pre-selected options to avoid fatigue and mistakes.
*Remember * You need to select the object you wish to rotate, scale etc. first then click the icon for these commandscripts to work.

 Rotate copy Icons

In Rhinoceros open up the transform toolbar and drag it into the Rhinoceros workspace. Hold the control key down on your keyboard and left mouse click over the Rotate Icon. Ok to duplicate box pops up click Ok.

Shift key right mouse click over one of the duplicated Rotate icons In the Left button command enter... ! Rotate c In the Right button command enter... ! Rotate3d c Change the Tooltip to read ... Rotate copy | Rotate 3d copy, click Ok. Change the color of the icon if you wish to make the new custom icon easier to identify.

Click the ! InterpCrv icon

 

In the Top Viewport create a curve similar to left hand figure . Pre-select the curve by left mouse clicking on it. The curve should be highlighted in yellow. *Remember* you need to select the curve first for these commandscripts to work.

Left mouse click the Rotate Copy icon you created

Click in the topViewport  near the center of the Viewport. Holding the shift key down to activate ortho click to the left of the last point. Notice that now you can rotate and copy the curve at the same time. Make some copies.

Scale copy Icons
These icons work similar to the Rotate copy icons. The procedure is exactly the same as above so I will not illustrate the first four steps.

1. Drag the Scale toolbar out into the Rhinoceros workspace.
2. Hold the control key down on your keyboard and left mouse click over the Scale | Scale2d icon.
3. Ok to duplicate box pops up click yes.
4. Shift key right mouse click over the one of the duplicate Scale | Scale2d icons.

In the left mouse button box enter... ! Scale c In the right mouse button box enter... ! Scale2d c Change the icons tooltip to read Scale copy | Scale 2d copy Click Ok.

Create a sphere by clicking the Sphere Icon

Select the sphere by left mouse clicking on it.The sphere should be highlighted in yellow. *Remember* you need to select the sphere first for this commandscript to work. Click the Scale copy icon you made

Click in the top Viewport to the left of the highlighted sphere. Click roughly under the last point (see image to the left) Create scaled copies.

Rendered image of the Scale Copy commandscript in action. The orient, orient 3d icons all have the "c" option that you may want to customize too.

Copy In place change layer Icon

This commandscript lets you copy any object in Rhinoceros without being prompted for xyz coordinates or typing I. The copied object is then automatically put on any layer you choose. Another one of those commands that automatically performs an option for you, in this case the Inplace option but with a further twist.

In the Right button command box of the Copy Icon type or copy and paste the text below into Rhinoceros. ! Copy inplace Changelayer Change the icons tooltip to read Copy | Copy Inplace changelayer

Draw a curve in top view

Pre-pick the curve *Remember* you need to select the curve first for this commandscript to work. Right mouse Click the Copy Icon Notice the layer box comes up Select layer 01 Click Ok

The copied curves' wireframe color should be red and should be copied to layer 01.

Command scripts assigned to icons that control the "Appearance" of Rhinoceros

These Icons are good to have on your main toolbar since you can only access the appearance of Rhinoceros through the main menu then clicking tools/options / appearance, then your preferences. Therefore these commandscripts are great time savers for getting to that extra screen real estate quickly. This also helps when you want to see your model as large as possible on the screen either for viewing or rendering.

Toggle Menus on/off Icon

This commandscript is great to get rid of all menus and prompts in Rhinoceros and just use your icons. Then just click the Toggle menus Icon and you are back to normal. This will give you more room when you need it quickly.

Shift key left mouse click on a blank icon from the Rhinocereos maintoolbar.

In the Left button command box type or copy and paste the text below. (See image on the left): Showtitle ShowMenu ShowCommandPrompt In the Tooltips box type Toggle Menus Click Edit bitmap and draw a simple T Click Ok

• Click the Toggle Menus icon you just created the Rhinoceros workspace should look like the image below. Notice how much more screen real estate this gives you to work in. Click the Toggle Menus icon to go back to your previous settings and restore the menus.

Toggle toolbars on/off with an Icon

Toggling toolbars on and off can be done from icons too this lets you bring up whatever toolbar arrangement you can imagine. I have kept this one simple. This icon only toggles your left modeling toolbar off. This is why. If you click the Toggle Menus Icon you just made and then toggle off your left toolbar you will have much more screen real estate for checking your model and rendering in. This setup still gives you the main toolbar so you have rendering and other options as well as the icon to click to get back your left toolbar.

Shift key left mouse click over the Toggle Menus icon you just created.

In the Rightbutton command box type or copy and paste the text below. (See image on the left): ToggleToolbar "Main" In the Tooltips box type | Main Toolbar Click Ok

• Right mouse click the Toggle Menus | Main Toolbar icon. The icon turns the left hand menu off (see image below). Right mouse click the Toggle Menus | Main Toolbar icon again to restore the Main menu.

Assigning a command script to a hotkey that toggles all your toolbars on/off

Toggling toolbars on and off can be done from icons too but in this case you will assign it to a Hotkey. This way you can click the Toggle menus Icon then hit the Hotkey on your keyboard with the alltoolbars off toggle and you will have one full big screen of only your beautiful model. This is great for presenting a model to someone and for moving around in the model.

Go to the main Menubar and then click the Tools\options\shortcut keys.

After the F3 hot key type in ToggleToolbar "Main" ToggleToolbar "standard" Click Ok to save settings.

• Click the Toggle menus Icon you just created turning off all menus, see image below.

• Now press the F3 hotkey you made. Notice how much screen real estate you have to move your model around in. The image below shows the perspective window maximized with a model present.

• Press the F3 hotkey to bring back your toolbars
• Click the Toggle Menus icon to bring back your toolbars.

These small commandscripts are very useful to know and to have assigned to icons. They streamline your work in Rhinoceros by giving you the outside applications you use most available at the click of a mouse  button inside Rhinoceros. Some of these run commands will launch an external program like a bitmap editor or calculator right in the middle of modeling. 

The word "run" tells Rhinoceros to run an external .exe file. Notice the quote symbols around the path statement. This helps Rhinoceros to read the path statement because there are spaces in it and normally Rhinoceros would then read each word as command.

1. Go to the Render Toolbar and drag it out into the Rhinoceros workspace.
2. Duplicate the icon. In the left command button box add the commandscript:
   run "C:\your photoeditor here"
3. In the tooltips type Image viewer and click the Icon to launch your thumbnail viewer or photoeditor .

Adding the standard windows calculator toRhinoceos

One thing that Rhinoceros doesn't have yet is the ability to perform math calculations or the conversions of Standard Units (like Inches to meters) from one form to another. Having quick acess to a calculator helps when you need to perform conversions or math calculations.

Shift key right mouse click over an empty icon In the left command button box add the commandscript: run "C:\WINDOWS\calc.exe"" In the tooltips type Calculator You can copy and paste the bitmap for the icon if you to make it easier to identify. Click Ok Click the Calculator icon you just created to launch the Windows calculator.

You must make a link to the standard windows Notepad to follow the rest of the tutorials even if you haven't created any commandscripts yet.

You will use the Windows Notepad to write your command scripts.  
Adding a link to Windows Notepad.

Click on a blank icon in the main toolbar

Type this commandscript in the left button command box run "C:\WINDOWS\Notepad.exe"  Edit the bitmap and add the windows

Assigning an often used commandscript to a Rhinoceros alias

Rhinoceros aliases can be used to make command scripts smaller by substituting a word for a whole macro or part of a macro. You find aliases under the Menubar Tools\options\aliases. It saves on typing if you are repeating a whole macro often too. This word or alias for an entire script can then become part of another script. In fact a whole script can be composed of only command aliases which are really names of complex command scripts. Usually though I would create an alias of a certain script when you create a function that is universal to all or many different macros. Then you can include that command script easily in a different command script by typing its alias instead of the whole script.

Here is a great example of a commandscript that should be made into a Rhinoceros alias because it can be included in many kinds of different commandscripts. It is universal to all commandscripts. Rhinoceros is missing one often used command that is the command to select the object you last made or created. What makes this even more clever is that this was invented by Rhinoceros user Pascal Golay not a McNeel programmer. At this point no one has tried all the different combinations of commands that can be strung together to create other needed macros and even absent commands. Because no one has tried all the different combinations of commands this will remain a source of inspiration.

 **Important** you must have this command as an alias for the following chapter and for the rest of the command scripts to run.

Go to the main Menubar and then click the Tools\options\aliases.

Click New

In the Alias Box Type in lastcreated In the Command string box type in ! All Undo Invert Redo click ok.

Figure 45

Create a sphere Then create a curve Click in the Rhinoceros workspace to make sure nothing is highlighted or pre-selected. Type lastcreated at the Rhinoceros command prompt and hit the enter key. Notice it selects the last object you made or created, in this case the curve. Assign the Lastcreated command to an icon if you wish.

Commandscripts that add extra Solids to the Solid toolbar

Even though Rhinoceros ships with a great set of solids. You may find that it is lacking some, or that you may want to make your own solids designed to fit your needs. This is easy to do the following examples show you how.

Adding a Golden rectangle box.

Drag the Solid toolbar into the Rhinoceros workspace. Duplicate the Box icon from the box toolbar and drag /move it to the Solid toolbar.

In the Left button command box type: ! Box w0 w16.18034,10 10 enter In the tooltips write : Golden Box

Click the Golden Box icon to create a golden section box.

Adding a tetrahedron to the Rhinoceros solids toolbox.

You can copy the command script from the text in this book. Using the Windows notepad and then follow steps 2-6, or you can open the file form the secrets of Rhinoceros cd.

Open the Windows Notepad and then open the file tetrahedron1.txt from the secrets of Rhinoceros CD.The commanscript is also located below you can copy and paste it from there too. Copy the entire contents of the file to the Windows clipboard. In Rhinoceros drag the Solid tool bar out into the workspace. Edit the Golden box icon. In the Right Button box paste the tetrahedron1.txt file. In the Tooltips box write Tetrahedron. Click Ok

Right mouse click Golden Box | Tetrahedron icon.

That's it not much to it. Notice you didn't have to know any programming code or even leave Rhinoceros to write these macros. You only used the basic Rhinoceros commands learned easily from the help files and by practice. You learned most of the syntax the symbols and protocol for writing successful macros in Rhinoceros just from these examples! No need for compilers or anything else. It's really a testimony to how brilliant the programmers are for making it this simple.

By now you should be comfortable making commandscripts and assigning them to Icons. You learned Rhinos' easy command syntax and you have made all the custom Icons and the one command alias that you will need to tackle the advanced scripting you will do in the next chapter.