Differences

This shows you the differences between two versions of the page.

--- fr:rhino:basicmacros [2020/08/14]
127.0.0.1 external edit
+++ fr:rhino:basicmacros [2023/10/27]
noemi
@@ Line 1: / Line 1: @@
-====== A basic tutorial on creating macros (scripting with Rhino commands) ======
+======Creating Macros======
-======Introduction======
+>A basic tutorial on creating macros (scripting together Rhino commands)
-Scripting macros in Rhino is a way to automate many tasks, customize your commands and improve your workflow.
+You can create **macros** in Rhino to automate many tasks, customize your commands, and improve your workflow.
-There may be some confusion about the term “scripting” as it used rather loosely to describe both the process of writing macros (what this section is all about), as well as writing more sophisticated “scripts” in either [[developer:rhinoscript|RhinoScript]] or VB script programming languages, which are very different.
+There may be some confusion about the use of the term “scripting”.  It has been used to describe both the process of writing macros - what this section is about - as well as writing more sophisticated scripts in either [[developer:rhinoscript|RhinoScript]], [[https://developer.rhino3d.com/guides/rhinopython/|Python]], or other programming languages.
-I will use the term “Macro” here exclusively to describe the putting together of strings of ordinary Rhino commands and their options to create an automated function.  This is “scripting” on its simplest of levels, and is easily accessible to any ordinary Rhino user, even if they have no knowledge of programming.  All that is needed is a reasonable understanding of Rhino commands and their structure, as well as a logical mind and a taste for a little experimentation and debugging.
+//The two things are actually very different.// Writing functions in RhinoScript, Python or other programming languages is a lot more complex than creating macros, and requires some programming knowledge and skills.  //We don't cover that here.//
+I use the term “Macro” here exclusively to describe the putting together of strings of ordinary Rhino commands and their options to create an automated function.  This is scripting on its simplest of levels, and is easily accessible to the average Rhino user, even if they have no knowledge of programming.  All you need is a reasonable understanding of Rhino commands and their structure, as well as a logical mind and a taste for a little experimentation and debugging.
-=====The tools you need:=====
-Your brain
-The Rhino Help file -  lists all Rhino commands and their sub-options, this is your most important reference.
+=====The tools you need=====
+  * Your brain :-P
+  * The **Rhino Help file** -  lists all Rhino commands and their sub-options. This is your most important reference.  Pressing F1 (Windows) or the :?: toolbar button (Mac) will get you to the online help.
+  * The Rhino **MacroEditor**, a built-in interface for creating and testing your macros.
+  * An understanding of how to add your macros to your workflow in the form of aliases or toolbar buttons (explained [[developer:macroscriptsetup|here]])
+=====You've already used a macro or two...=====
+First, if you are a user of Rhino, you are already a macro user even though you may not know it.  Many of the commands in Rhino are already “macroed” for you. When you click a toolbar button or call a command from the menu, it is often a preset macro.  For example, the toolbar button **Extrude Closed Planar Curve** from the "Solid" toolbar has the following macro:
+//(shown: V6 for Windows)//
-The Rhino V4 or V3 SR4+ Bonus tool **MacroEditor**, which will allow you to easily run and debug your macros.
+{{:rhino:extrudestraightv6solid.png?400|}}
-=====You've already used a macro or two...=====
+It just calls the **ExtrudeCrv** command and sets it to make a closed solid.  We will see what the "Pause" part does later.
-First, if you are a user of Rhino, you are already a user of macros even though you may not know it.  Many of the commands in Rhino are already “macroed” for you, when you click a toolbar button or call a command from the menu, it is often a preset macro.  To see, Shift+Right click on the button **Extrude Straight**:
-{{:legacy:en:ExtrudeCrvButtonEditor.gif}}
+This is an example of the simplest kind of macro, which just sets a series of options within a single command so that you don’t have to specify them time you use it. **ExtrudeCrv** has several buttons with preset options, **Tapered, AlongCurve, ToPoint, Solid=Yes** (or No) etc.  Check out the macros under all the **ExtrudeCrv** buttons to see how they are laid out.
-This an example of the simplest type of macro, which simply sets a series of options within a single command so that you don’t have to specify each one every time you use it.  **ExtrudeCrv** has several buttons with pre-set options, //Tapered//, //AlongCurve//, //ToPoint//, //Cap=Yes// (solid) etc.  Check out the macros under all the **ExtrudeCrv** buttons to see how they are laid out.
-In a sense, you’re doing the same thing as if you clicked or typed the options one at a time at the command line.  In fact, that’s all macros really are, just a set of instructions to repeat a sequence of commands you would have otherwise input manually one at a time.
+In a sense, you’re doing the same thing as if you clicked or typed the options one at a time at the command line.  In fact, that’s all macros really are -- just a set of instructions to repeat a sequence of commands that you would otherwise input manually one at a time.
-This scripting of options for a single command can also be combined with data entry (i.e. coordinates or other numerical data). It is also possible to string together several commands in a row, resulting in an automated sequence of “events” for manipulating or creating objects.
+This scripting of options for a single command can also be combined with data entry (i.e. coordinates or other numerical data). It is also possible to string together several commands in a row, for an automated sequence of events to manipulate or create objects.
-> **Note:** //Why the _Underscores?  These tell Rhino that the command which follows is in English (no matter what the language you are running Rhino in), which will make your macro “universal”.  If you are running in English and don’t care, you can eliminate them in your macros if you wish, it will not affect anything else.  Also:Why the exclamation point (!) ?  This cancels any previous command that might be running for safety's sake.//
+> **Note:** //Why the _Underscores?  These tell Rhino that the command which follows is in English (no matter what the language you are running Rhino in), which will make your macro universal.  If you are running in English and don’t care, you can eliminate the underscores in your macros if you wish. It will not affect anything else.  Also, why the exclamation point (!)?  This cancels any previous command that might be running, for safety's sake.//
-======Getting Started======
+======Getting started======
-Let’s say you have to place a series of 10 x 10 x 10 boxes with the center of the bottom face landing at the desired point, that point to be specified by either by a mouse click at the desired location or by keyboard entering the coordinates.
+Say you have to place a series of 10x10x10 boxes with the center of the bottom face landing at the desired point, with that point to be specified by either by a mouse click at the desired location or by entering the coordinates by the keyboard.
-One could use the standard Box (Corner to Corner + Height) command, but by default, this will place the insertion point at the first corner of the box.  To have the insertion point where we want, it is easier to use the Box, Center command.   This is in reality just the Box command with the “center” option, so in your macro you will have to activate it.
+You could use the standard Box (**Corner to Corner + Height**) command, but by default this will place the insertion point at the first corner of the box.  To have the insertion point where we want, it is easier to use the Box, Center command.   This is in reality just the Box command with the center option, so you will have to activate it in your macro.
-Open the **MacroEditor**,  type this in:
+Open the **MacroEditor** and  type this in:
-  ! //Box //Center  (this is actually the macro under the Box, Center button if you check)
+  ! _Box _Center
+//(This is actually the macro under the Box, Center button if you check.)//\\
 All entries (command words and numerical inputs) need to be separated by a single space.
-Now, we need to specify the center point.  In order to do this, one needs to tell Rhino to stop processing the command temporarily and wait for a user input in the form of a click or a keyboard entry.  This is accomplished by inserting the command Pause.
+Now, we need to specify the center point.  To do this, you need to tell Rhino to stop processing the command temporarily and wait for an input in the form of a click or a keyboard entry.  Do this by inserting the command Pause.
-  ! //Box //Center _Pause
+  ! _Box _Center _Pause
-Once the data has been entered, we can specify the size of the box directly in the command.  Since the Center option in Box wants a corner of the box as a second input, we can specify its X,Y coordinates:
+Once the data has been entered, you can specify the box size directly in the command.  Since the Center option in Box wants a corner of the box as a second input, you can specify its X,Y coordinates:
-  ! //Box //Center _Pause r5,5
+  ! _Box _Center _Pause r5,5
-(Why the “r”?  we want this coordinate to be relative to the last picked point, that is to say, the box bottom center.  Otherwise the corner will always land at X5, Y5.)
+(Why the "r”?  We want this coordinate to be relative to the last picked point, that is to say, the box bottom center.  Otherwise the corner will always land at X5, Y5.)
-At this point we can put in the height, which in this case is relative to the original starting point
+At this point you can put in the height, which in this case is relative to the original starting point.
-  ! //Box //Center _Pause r5,5 10
+  ! _Box _Center _Pause r5,5 10
 Since there is no further input necessary nor options possible, the macro completes and our box is there.  Note that since we wanted a height equal to the width, another possibility  would just to have been to use Enter instead of 10 for the last entry.
-  ! //Box //Center //Pause r5,5 //Enter
+  ! _Box _Center _Pause r5,5 _Enter
-Now that the macro is running and you are satisfied, [[rhino:macroscriptsetup|make a new toolbar button]] and paste the macro in, give it a recognizable name, like “10 x 10 x 10 bottom centered box”  Note, once the macro has been executed once, right clicking will repeat the whole sequence of this macro, so you can use it many times in a row without clicking the button every time.
+Now that the macro is running, [[rhino:macroscriptsetup|make a new toolbar button]] and paste the macro in. Give it a recognizable name, like “10x10x10 bottom centered box”.  Note, once the macro is executed, right-clicking repeats the whole sequence of this macro, so you can use it many times in a row without clicking the button every time.
-======OK, let’s get a bit more complicated…======
+> //Note on the Pause command://   In earlier versions of Rhino, for some command macros it was necessary to use one Pause for each screen pick needed.  This made it difficult to make macros for commands that had an indeterminate number of screen picks.  Much of that has been fixed in the latest versions, however there are still some exceptions.  For these cases, there is now the Multipause command (V6 and later), which basically allows the user to make as many picks as needed without having to write multiple Pause commands in the macro.
-Some commands invoke dialog boxes with many options.  This would normally stop your macro and wait for you to click the desired options, then continue.  Since you want to automate, you can bypass the dialog by putting a –hyphen (also known as a dash) before the command.  Then you can “script in” all your options and the macro will run to completion without needing your intervention.  Some commands have several levels of sub-options.  If you want to see what’s available, type the command at the command line with the hyphen and look to see what’s proposed in terms of options.  Click on the options and see if they have sub-options.
+For example the macro below
-=====Loft two open curves=====
+  ! _Polyline _Pause _SelLast
-Let’s say you would like to repetitively **Loft** two //OPEN// curves together to form a surface.  Using the standard **Loft** command, you always have to go through the dialog.  If you use the **//–Loft//** version, you can avoid this and things go much faster.  Have a look at the following:
-{@
+will work fine to make the polyline, but it will not be selected at the end.  Why?  Because the single Pause is 'eaten' by the first pick in the polyline, and thus the SelLast command gets executed just after the first pick while we're still making the polyline - and therefore does nothing.  The single pause //does// allow you to finish the polyline with as many points as you want, but there is no longer a SelLast to be run at the end of it - because it ran already and failed.
-====== _-Loft======
-_Pause
-//Type=//Normal
-//Simplify=//None
+However, the following macro
-//Closed=//No
+  ! _Polyline _Multipause _SelLast
+works including selecting the polyline at the end because the Multipause includes //all// the picks for the polyline, allowing the SelLast to be executed and work at the end.
-_Enter
+=====OK, let’s get a bit more complicated…=====
-}@
-Note that the command is invoked, and then immediately after the pause which allows you to pick your curves.  If the pause is removed, the macro won’t work if you have not selected your curves before calling it.  If you have already preselected your curves, no matter, the pause is intelligently ignored.  Then command then proceeds set all your specified options, and once that is done, it actually creates the surface and finishes. Try it with two open curves, either pre or post selecting them.  Try modifying one or more of the options, like substituting ////Closed=//Yes//, or ////Simplify=//Rebuild// (for this you will also have to add a line with ////Rebuild=//20// or some other value).
-=====Modifying it for use with closed curves=====
+Some commands invoke dialog boxes with many options.  Normally, this stops your macro and waits for you to click the desired options, then continue.  Since you want to automate, you can bypass the dialog by putting a –hyphen (also known as a dash) before the command.  Then you can script in all your options and the macro will run to completion without needing your intervention.  Some commands have several levels of sub-options.  If you want to see what’s available, type the command at the command line with the hyphen and look at what’s proposed for options.  Click on the options and see if they have sub-options.
-Now, try it with two closed curves.  You will have a problem.  Why? For closed curves, Loft needs another input from you – the seam location.  This is something that needs to be specified in the macro in the right sequence.  So, you can either choose from various automatic seam options (which are on a sub-option level) or you can adjust it on screen.  Either way, you need to modify the macro.
-Adding a pause in the right place will allow you to check and adjust the seam on screen:
+=====Loft two open curves=====
-{@
+Let’s say you would like to repetitively **Loft** two //OPEN// curves together to form a surface.  If you use the standard **Loft** command, you always have to go through the dialog.  If you use the **//–Loft//** version, you can avoid this and things go much faster.  Look at the following:
-====== _-Loft======
+<code>
+_-Loft
 _Pause
-_Pause  <--
+_Type=_Normal
-//Type=//Normal
+_Simplify=_None
+_Closed=_No
+_Enter
+</code>
+Note that when you invoke the command, immediately a pause lets you pick your curves.  If you remove the pause, the macro won’t work if you have not selected your curves before calling it.  If you have already preselected your curves the pause is intelligently ignored.  The command then sets all your specified options. Once that is done, it creates the surface and finishes. Try it with two open curves, either pre or post selecting them.  Try modifying one or more of the options, like substituting Closed=Yes or Simplify=Rebuild. (For this you also have to add a line with Rebuild=20 or some other value.)
+=====Modifying it to use with closed curves=====
-//Simplify=//None
+Now, try it with two closed curves.  You have a problem.  Why? For closed curves, Loft needs another input from you -– the seam location.  This is something that needs to be in the macro in the right sequence.  So, you can either choose from various automatic seam options (which are on a sub-option level) or you can adjust it on screen.  Either way, you need to modify the macro.
-//Closed=//No
+Adding a pause in the right place lets you check and adjust the seam on screen:
+<code>
+_-Loft
+_Pause
+_Pause  <--
+_Type=_Normal
+_Simplify=_None
+_Closed=_No
 _Enter
-}@
+</code>
-Adding an Enter instead of the Pause tells Rhino you don’t care, just leave the seam the way it is by default.
-{@
+Adding an Enter instead of the Pause tells Rhino you don’t care. Just leave the seam the way it is by default.
-====== _-Loft======
+<code>
+_-Loft
 _Pause
 _Enter  <--
-//Type=//Normal
+_Type=_Normal
+_Simplify=_None
-//Simplify=//None
+_Closed=_No
-//Closed=//No
 _Enter
-}@
+</code>
 Or, you can specify another Loft seam option by stepping down into the seam sub-option level:
-{@
+<code>
-====== _-Loft======
+_-Loft
 _Pause
 _Natural  <--
 _Enter    <--
-//Type=//Normal
+_Type=_Normal
+_Simplify=_None
-//Simplify=//None
+_Closed=_No
-//Closed=//No
 _Enter
-}@
+</code>
-(the Enter after Natural is necessary to exit the “seam” option level and get back up to the Loft options level)
-<color darkslateblue>**//Unfortunately, the same macro will not work correctly for both open and closed curves because of the extra seam option required.  This is one of the limitations of the macro system and the way some Rhino commands have been written.//**</color>
+(The Enter after Natural is necessary to exit the “seam” option level and get back up to the Loft options level.)
+//Unfortunately, the same macro will not work correctly for both open and closed curves because of the extra seam option required.  This is one of the limitations of the macro system and the way some Rhino commands have been written.//
-======Using Macros to set your interface options quickly======
-Macros can also be used to set various GUI and Document Properties options automatically without having to go wading into the Options dialog.  I use the following to set the render mesh the way I want it (note the dash before -_DocumentProperties)
+======Using macros to set your interface options quickly======
-{@
+Macros can also be used to set various GUI and Document Properties options automatically without having to go wading into the Options dialog.  I use the following to set the render mesh the way I want it. (Note the dash before -_DocumentProperties.)
+<code>
 -_DocumentProperties
-//Mesh  //Custom
+_Mesh _Custom
+_MaxAngle=0 _AspectRatio=0
+_MinEdgeLength=0 _MaxEdgeLength=0
+_MaxEdgeSrf=0.01 _GridQuads=16
+_Refine=Yes _JaggedSeams=No
+_SimplePlanes=No
+_Enter
+_Enter
+</code>
-//MaxAngle=0  //AspectRatio=0
+Why are there two Enters at the end?
-//MinEdgeLength=0  //MaxEdgeLength=0
+You went down two levels in -_DocumentProperties, first to the Mesh level, then to the Custom sublevel inside Mesh.  You need one Enter to exit the sublevel and go back to the main level, and one more to exit the command.  Some scripts might even need three enters.
-//MaxEdgeSrf=0.01  //GridQuads=16
+The following is from Jeff LaSor, for turning on or off the crosshair cursor:
-//Refine=Yes  //JaggedSeams=No
+To script Crosshairs  ON or OFF put the following on a button:
+<code>
+  -_Options _Appearance _Visibility
+  _Crosshairs _Enter _Enter _Enter
+</code>
+Notice the reference to each individual command option name.  Specifying them inside the script is like clicking on them with the mouse.  Also note the three Enter entries.  Since each command option takes you down into a new set of sub-level command options, an Enter is required to take you back up.  Since this script went down three levels, it needs to specify three Enters to get all the way out of the command.
-_SimplePlanes=No
+**EnterEnd** is a good way to 'back out' of a command without the need to keep track of how many levels deep you've gone  -
-_Enter
-_Enter
-}@
-Why two Enters at the end?
-Well you went down two levels in -_DocumentProperties, first to the Mesh level, then to the Custom sublevel inside Mesh.  You need one Enter to exit the sublevel and go back to the main level, and one more to exit the command.  Some scripts might even require three enters.  The following is from Jeff LaSor, for turning on or off the crosshair cursor:
+<code>
+  -_Options _Appearance _Visibility _Crosshairs _EnterEnd
+</code>
-To script Crosshairs  ON or OFF you would put the following on a button:
+Or, if you just use an exclamation point **!** at the end (which in a script means “end now!”), it takes you all the way out regardless of how many sub-levels you're in. Note, if you want to continue your macro with something else, do not use !, use the Enters instead, otherwise your macro will always stop at the ! and terminate.
-  -//Options //Appearance //Visibility //Crosshairs //Enter //Enter _Enter
+The script simply toggles the crosshairs ON and OFF. But if you wanted a script that always turned them ON and another that always turned them OFF, here's what they would look like:
-Notice the reference to each individual command option name.  Specifying them inside the script is like clicking on them with the mouse.  Also note the 3 'enter' entries.  Since each command option (in this case) takes you down into a new set of sub-level command options, an 'enter' is required to take you back up.  Since this script went down 3 levels, it needs to specify 3 enters to get all the way out of the command.
-OR, if you just use an exclamation point '!' at the end (which in a script means “end now!”), it will take you all the way out regardless of how many sub-levels you're in. Note – if you want to continue your macro with something else, do not use !, use the enters instead, otherwise your macro will always stop at the ! and terminate.
-The script above simply toggles the crosshairs ON and OFF, but let's say you wanted a script that always turned them ON and another that always turned them OFF...here's what they would look like:
 Always ON version:
+<code>
-  -//Options //Appearance //Visibility //Crosshairs=_Show !
+  -_Options _Appearance _Visibility
+  _Crosshairs=_Show !
+</code>
 Always OFF version:
+<code>
-  -//Options //Appearance //Visibility //Crosshairs_=Hide !
+  -_Options _Appearance _Visibility
-Note the use of the '!' here as mentioned above.... Also note that whatever values options can take on can be assigned directly to that option using the '=' operator.  The Crosshairs option has 2 possible values, "Show" and "Hide", and thus, that's what is used in the assignment.
+  _Crosshairs=_Hide !
+</code>
+Note the use of the **!** here. Also, note you can assign directly the values options can take on to that option using the '=' operator.  The Crosshairs option has two possible values, "Show" and "Hide", and thus, that's what is used in the assignment.
 (Thanks, Jeff)
@@ Line 172: / Line 198: @@
 ======Other useful macro writing tools and commands======
-There are some handy tricks for doing more complex macros.  One is the discriminating use of various selection filters, particularly the use of **SelLast**, which select the last object created/transformed, **SelPrev**,  which selects the previous input object, and **SelNone**, which deselects everything.  There are also possibilities to name objects, group them (and name the group) and then recall them later by that object name or group name.
+There are some handy tricks for doing more complex macros.  One is the discriminating use of various selection filters, particularly **SelLast**, which selects the last object created/transformed, **SelPrev**,  which selects the previous input object, and **SelNone**, which deselects everything.  There are also possibilities to name objects, group them (and name the group) and then recall them later by that object name or group name.
-{@
+<code>
 Select
 SelLast
 SelPrev
 SelNone
 SetObjectName
 SetGroupName
 SelGroup
 SelName
 Group
 Ungroup
+</code>
-}@
 To set a single object name (this in itself is a macro!):
+<code>
-  //Properties //Pause //Object //Name [put your object name here] //Enter //Enter
+  _Properties _Pause _Object _Name
+  [put your object name here] _Enter _Enter
+</code>
 To cancel a single object name (without deleting the object)
+<code>
+  _Properties _Pause _Object _Name
+  “ “ _Enter _Enter (quote space quote for the name)
+</code>
-  //Properties //Pause //Object //Name “ “ //Enter //Enter (quote space quote for the name)
 =====Examples using the above tools=====
-Have a look at the following macro:
-{@
+Look at the following macro:
-====== Select Pause _Setredrawoff======
-//BoundingBox //World _Enter
-//Selnone //Sellast
+<code>
+_Select _Pause _Setredrawoff
+_BoundingBox _World _Enter
+_Selnone _Sellast
+_OffsetSrf _Solid _Pause
+_Delete _Sellast
+_BoundingBox _World _Enter
+_Delete _Setredrawon
+</code>
+It creates an offset bounding box around an object. The offset is input by the user.  See if you can follow the logical sequence.  The Setredrawoff/on stop/restart the screen refresh, eliminates the display flickering as all is executed and speeds up the process.  Beware, if you terminate the command before Setredrawon, you will think Rhino is dead, as the screen no longer updates.  If this happens, don’t panic, typing the command **Setredrawon** will restore the display refresh.
-//OffsetSrf //Solid _Pause
+**//As a final example,//** the following macro creates a point centered on a 2D planar or text object and grouped with it. It assumes that you're in the same view the text was created in, and that the object is really 2D and planar. (Otherwise it will likely fail.)
-//Delete //Sellast
+Note the use of a named group and various selection commands.  The **NoEcho** command temporarily stops the reporting of information to the command line, which, combined with Setredrawoff/on makes the macro run without flashing and without too much info reported to command history.  It will run without those as well, though.
-//BoundingBox //World _Enter
+<code>
+_Select _Pause _Noecho _Setredrawoff
+_Group _Enter _SetGroupName TexTemp
+_BoundingBox _CPlane _Enter
+_SelNone _SelLast _PlanarSrf
+_SelPrev _Delete _SelLast
+_AreaCentroid _Delete
+_Sellast _SelGroup TexTemp
+_Ungroup _Group _Setredrawon
-//Delete //Setredrawon
+</code>
-}@
+//last edited: 28.08.19/msh//
-It creates an offset bounding box around an object, the offset is input by the user.  See if you can follow the logical sequence.  The Setredrawoff/on stop/restart the screen refresh, which eliminates the display flickering as all is executed, and speeds up the process.  Beware, if you terminate the command before Setredrawon, you will think Rhino is dead, as the screen no longer updates.  If this happens, don’t panic, typing the command (Setredrawon) will restore the display refresh.
-**//As a final example,//** the following macro creates a point centered on a 2D planar or text object and grouped with it. It pre-supposes that you're in the same view the text was created in, and that the object is really 2D and planar (otherwise it will likely fail).
+**Please feel free to add to or edit this tutorial!**
-Note the use of a named group and various selection commands.  The **NoEcho** command temporarily stops the reporting of information to the command line, which, combined with Setredrawoff/on makes the macro run without flashing and without too much info being reported to command history.  It will run without those as well, though.
-{@
-====== Select Pause Noecho Setredrawoff======
-//Group //Enter _SetGroupName TexTemp
-//BoundingBox //CPlane _Enter
-//SelNone //SelLast //PlanarSrf //SelPrev //Delete //SelLast
-//AreaCentroid //Delete //Sellast //SelGroup TexTemp
-//Ungroup //Group _Setredrawon
-}@
-==Please feel free to add to or edit this tutorial!==
 This is a work in progress...

McNeel Wiki

Site Tools

Differences

Page Tools