Grasshopper--VB编程建模1

Version 1 Grasshopper VB Scripting Primer Dr Patrick Janssen patrick@janssen.name 16th March 2009 Introduction This booklet was written for students of the Generative Techniques in Design elective at the Department of Architecture, National University of Singapore. Most of the students had no prior experience with programming, so I have attempted to introduce Grasshopper VB Scripting in a way that is as simple and easy to understand as possible. Note that this is a very broad introduction that necessarily glosses over many of the details. This is just a primer. This is version 1 of this document, and it may continue to evolve. To download the latest version, please go to http://community.nus.edu.sg/ddm . I fact, in this current version, there are still a number of sections labelled as [under construction] – these will be updated soon. The document is based on Rhino3d Version 4 and Grasshopper Version 0.5.0099. Page 1 Version 1 Table of Contents 1 What’s it all about ..........................................................................................5 1.1 VB.NET...................................................................................................5 1.2 Grasshopper Scripting............................................................................5 1.2.1 Where do I write my script? .............................................................6 1.2.2 What about Visual Studio Express? ................................................7 1.2.3 About the code samples ..................................................................7 2 Writing code...................................................................................................8 2.1 Comments ..............................................................................................8 2.2 Code.......................................................................................................8 2.2.1 Statements ......................................................................................9 2.2.2 Variables .........................................................................................9 2.2.3 Control Flow ....................................................................................9 2.2.4 Coding conventions .......................................................................10 3 Working with Value Types ...........................................................................11 3.1 Some common Value Types.................................................................11 3.2 Variables and Value Types...................................................................11 3.2.1 Declaration ....................................................................................11 3.2.2 Assignment....................................................................................12 3.2.3 Combined declaration and assignment .........................................12 3.2.4 Variable use ..................................................................................12 3.3 Some Useful Functions.........................................................................12 3.4 A complete example .............................................................................13 4 Working with Class Types............................................................................14 4.1 Classes and Objects.............................................................................14 4.1.1 Classes..........................................................................................14 4.1.2 Objects ..........................................................................................14 4.1.3 Properties and Methods ................................................................15 4.2 Methods in More Detail.........................................................................15 Page 2 Version 1 4.2.1 Parameters and Arguments...........................................................15 4.2.2 Function Procedures .....................................................................16 4.2.3 Sub Procedures.............................................................................16 4.2.4 Constructors ..................................................................................16 4.3 Variables and Class Types ...................................................................16 4.3.1 Declaration ....................................................................................17 4.3.2 Instantiation ...................................................................................17 4.3.3 Assignment....................................................................................17 4.3.4 Combined declaration, instantiation and assignment ....................18 4.3.5 Parameters and arguments revisited.............................................18 4.3.6 Variable Use..................................................................................18 4.3.7 The dot operator ............................................................................18 4.4 A complete example .............................................................................19 5 Working with Array Types............................................................................20 5.1 Variables of Type Array ........................................................................20 5.2 A complete example .............................................................................20 6 Working with String Types ...........................................................................20 6.1 Variables of Type String .......................................................................20 6.2 A complete example .............................................................................20 7 Control Flow.................................................................................................20 7.1 For… Next ............................................................................................20 7.2 If...Then...Else ......................................................................................20 8 The VB Script Component ...........................................................................21 8.1 The Grasshopper_Custom_Script class ...............................................21 8.1.1 Imports Statements .......................................................................22 8.1.2 Class declaration...........................................................................23 8.1.3 The first region ..............................................................................24 8.1.4 Properties ......................................................................................24 8.1.5 Sub Procedures.............................................................................24 8.1.6 The second region.........................................................................25 Page 3 Version 1 8.2 VB Component Inputs and Outputs ......................................................26 8.2.1 Inputs parameters..........................................................................26 8.2.2 Outputs parameters.......................................................................27 8.2.3 Debugging code ............................................................................27 Page 4 Version 1 1 What’s it all about Rhino3d is a popular 3d NURBS based modelling program developed by McNeel. Grasshopper is a free plugin for Rhino3d, which allows you to do dataflow modelling. With the Grasshopper approach to dataflow modelling, you can create complex parametric models by defining relationships between entities in your model. These relationships are defined using the 'boxes and arrows' approach. The boxes – called components – specify procedures that do something like draw a line. The arrows connect the output from one procedure to the input of another procedure. Grasshopper provides a two components that allow you to create your own custom procedures using scripting. These are the C# Component and the VB Component. In this document, we will be focusing on the VB Component, for which the user has to write a script in the VB.NET programming language. 1.1 VB.NET The Microsoft .NET Framework is a software framework for developing programs and applications for the Microsoft Windows operating system. The framework supports a number of different languages, including Visual Basic DotNET and C# DotNET. Visual Basic DotNET is a full-blown object-oriented programming language. Visual Basic is often referred to using just the initials, VB. The difference between VB and C# is mostly stylistic - the only real difference today is programmer preference. The basis of VB is an earlier programming language called BASIC that was invented by Dartmouth College professors John Kemeny and Thomas Kurtz. VB is easily the most widely used computer programming system in the history of software. VB is not the same as VB for Applications (VBA) or VB Script. VBA is both a language and an integrated programming environment (IDE), which is embedded into many applications. VB Script is a subset of VBA and is a more rudimentary scripting language to allow users to write simple scripts. 1.2 Grasshopper Scripting This scripting in Grasshopper should not be confused with the other scripting options available in Rhino3d. For a long time it has been possible to automate Rhino3d using the RhinoScript scripting language. RhinoScript is written by McNeel and it is based on the Microsoft VBScript language. Since Rhino3, it has also been possible to use VB.NET to write plugins for Rhino. Grasshopper for example is mostly written in VB.NET. However, Rhinoscript and VB.NET plugin development are very Page 5 Version 1 different from writing VB.NET scripts in Grasshopper. (The reason that you cannot use RhinoScript in Grasshopper is because RhinoScript can only operate on objects that are actually inside the document, whereas Grasshopper only draws its geometry into the viewports.) To summarise: 1) Rhino is written in C++ and it exposes a C++ SDK which allows other (i.e. McNeel ) people and companies to write plugins for Rhino. 2) Using this C++ SDK, someone at McNeel wrote a RhinoScript plugin, which in turn allows people to write scripts for Rhino. 3) Using this C++ SDK, someone else at McNeel wrote a DotNET Wrapper plugin, which in turn allows people to write Plugins for Rhino using any DotNET language. 4) Using this DotNET wrapper SDK, another person at McNeel (David Rutten) wrote a plugin called Grasshopper. 5) Grasshopper allows people to create custom components by writing scripts in either the VB.NET language and the C#.NET language. 1.2.1 Where do I write my script? For writing a VB script in Grasshopper you use a simple script editor built into Grasshopper. This creates some confusion at first since the documentation on the Internet for VB tends to start with an introduction to the Visual Studio Express IDE. Page 6 Version 1 If you wish to write a DotNET script inside Grasshopper, all you have to do (assuming you already have Grasshopper installed and running) is: • Open the Logic panel • Drag a VB component onto the canvas • Double click the VB component • Start typing in the white space under where is says ’’’ . The areas in the script window that are greyed out cannot be edited. (Try it – click in the greyed out area and try typing.) When you click OK, Grasshopper will compile your code and (assuming there were no errors during compilation) run it. 1.2.2 What about Visual Studio Express? If you are writing a VB application, you would use a piece of software for programming called an Integrated Development Environment (IDE). For example, for VB there is an IDE called Visual Studio Express that is free of charge. However, for writing a VB script in Grasshopper you do not use this IDE. (You should only use the IDE if you intend to write your own components. This is much more difficult.) Instead you use the simple built-in script editor in Grasshopper as described above. 1.2.3 About the code samples The code samples in the text below are extracts from a longer piece of code. Only those sections with the title ‘a complete example’ will run if you copy them directly into a script. With the other bits of code, it takes up too much space to keep repeating the full set of code, so I tend to leave bits out here and there. But the careful reader should easily be able to fill in the missing bits. (PS At some point, I will improve the code layout to match the format of the Rhinoscript 101 document, which looks much better than this one :) Page 7 Version 1 2 Writing code Programming in VB involves writing two types of things: comments and code. Here is the same example with some comments and some code. 2.1 Comments Comments are lines of text preceded by an apostrophe. These comments are just for you to remind yourself (and maybe others) of what your code is doing. Comments become essential when code gets complex. The your code lines are just comments and can be deleted if you want: ''' ''' The reason that there are three apostrophes rather than just one is because there is also a more advanced way of adding comments, called XML Documentation Comments. However for the moment don’t worry about this. 2.2 Code Code is everything that is not a comment. Code consists of a series of statements that tell the computer what to do. In the example above, there is one statement: Print(“Hello”). This is an execution statement that uses the Print function. The print function is a very useful function that displays some text somewhere. (It does not send anything to you printer – when writing computer programs, print Page 8 Version 1 means ‘display this text’.) In the case of Grasshopper scripts, the text from the print function will always be sent to the out parameter of the VB component. 2.2.1 Statements The three main types of statements that you can write are declaration statements, assignment statements, and execution statements. (Assignment statements are actually a special type of execution statement.) Declaration and assignment statements are mainly to do with telling the computer to create and set variables, where a variable is a name that can be associated with some value. Execution statements are mainly to do with telling the computer to actually do something. An important type of execution statement are things like functions, loops, and if statements, which are referred to as control flow statements. 2.2.2 Variables Variables may be associated with simple types of things like numbers, and more complex types of things like points and lines. These are referred to as Value Types and Reference Types respectively. For Reference Types, there are a number of different types – three Reference Types will be introduced: • Section 4 will introduce Class Types, • Section 5 will introduce Array Types, and • Section 6 will introduce String Types. 2.2.3 Control Flow In the absence of any control flow statements, a computer will step through the statements that it finds in the program file in a sequential manner, from beginning to end, executing each statement in turn. Control flow statements allow you to regulate the flow of your program's execution. For example, you might want to repeat an action ten times. Rather Page 9 Version 1 than repeating the code ten times you can insert a loop structure into your code that will tell the computer to repeat a particular piece of code a certain number of times. • Section 7 will introduce Control Structures In general, the two main types of control structures are decision structures and loop structures. One of each will be introduced: for decisions, If...Then...Else construction will be introduced; for loops the For… Next construction will be introduced. 2.2.4 Coding conventions Code conventions focus on the stylistic aspects of naming and coding. For example, should you start a variable with an upper or lower case letter? (the answer is lowercase). For those new to programming, this type of thing may seem unimportant. But as you do more programming, you realise that it is very important for legibility of code. If you come back to some code a few months later, it is much easier to understand if you have followed some kind of consistent coding conventions. As far as possible, this document follows the standard code conventions. One particular point to note is the use of the line-continuation character, which is an underscore (_). This is used when a long line of code needs to be broken down into smaller lines. Due to the formatting of this document, this has been used in a number of places to fit the code onto the page. Page 10 Version 1 3 Working with Value Types A variable is identified by its name. The name of a variable cannot be the same as one of the language keywords, which are reserved for other purposes. But apart from that, the variable name can be almost anything, like x, or myVar, or blabla. By convention, variables use what is referred to as mixedCase: they start with a lowercase letter and each subsequent word starts with an uppercase letter. 3.1 Some common Value Types Assigning a data type to a variable makes it easier for the computer to figure out how the variable can—or can't—be used. Think of it this way: if you had three variables, two of which held numbers while the third held a name, you could perform arithmetic using the first two, but you can't perform arithmetic on the name. Some of the most important value data types are the following: Boolean True A value that is either true or false Integer 20 Whole numbers less than 2 billion Long 2e9 Whole numbers larger than two billion Double 20.2 Numbers with a fractional part Char A A single character So when you see the word Double in a script, then this is not some function to double some number, it is actually just a type. 3.2 Variables and Value Types A variable can store simple types of things like numbers. For example, I can say, I have a variable whose name is x and who can store a number of type Integer. I can then say that my variable x should store the value 20. These two steps are called declaration and assignment. First, you have to declare the type of each variable, and second you actually assign a value. (You will see later that you can combine declaration and assignment into a single line.) 3.2.1 Declaration A declaration is used to declare the type of variable, using a Dim statement. For example: Dim p As Integer Page 11 Version 1 This statement declares that the variable named x can store an Integer value. 3.2.2 Assignment Once you have declared the type of variable, you can then assign a value to it. For example: p = 20 3.2.3 Combined declaration and assignment In order to save space, you can put declaration and assignment on a single line. However, it is still important to conceptually think of these as two separate steps. Combined declaration and assignment looks like this: Dim p As Integer = 20 3.2.4 Variable use From now on, the variable with name x stores the value 20. For example: Print(p) This Print function would print 20. Another more complex example is this one: p = p + 10 Print(p) This time, the value of the variable x would be increase by 10. The Print function would print 30. This example uses two operators, and addition operator and an assignment operator. The