RhinoScript入门

RhinoScript入门

RhinoScript 是以VB语法作为语言基础的，任何一个RhinoScript脚本运行在当前的Rhino环境中时都可以使用Rhino本身的函数和子程序调用，以及某些Rhino环境变量。注意在脚本或者其他插件中，Rhino的当前环境被称之为“文档(document)”。

RhinoScript实际为文本文档，为了实现各版本之间的兼容性，请使用标准的ASC编码的脚本文件，即使是注释也不要使用中文。一般的RhinoScript格式后缀为rvb。

一，RhinoScript的载入

在使用RhinoScript前需要将rvb文件载入到文档中。常用的方法如下：

如上图所示，可以使用Tools|RhinoScript|Load，来加载rvb文件。也可以在Rhino命令行中输入“LoadScript”命令进行载入。

在菜单或者命令操作之后会有如下的对话框出现：

点击ADD按钮可以加入新的RVB文件到列表中。在列表中选择一个文件，点LOAD即可加载。点REMOVE

即可从列表中删除一个文件。

RhinoScript加载规则如下：

如果RVB文件中只包含子程序或者函数的定义，这时候没有“裸语句”， Rhino仅仅检查语法规则，不运行任何一个子程序或者函数。但RVB文件中还包含“裸语句”，这时Rhino会解吸并运行这个脚本。

二，RhinoScript作为命令运行

在RhinoScript被载入之后，这个RVB文件内部的一些函数或者子程序便可以当作特殊命令被使用，但并不是RVB文件内的所有函数或者子程序可以被当作特殊命令使用，只有满足如下条件的子程序才可以被使用。使用条件是：

必须为标准的VB子程序，并且这个子程序不可以带任何参数。

如下一段摘自Rhino4 RhinoScript帮助文档的程序

Sub Test1()

MsgBox "Test1"

End Sub

Sub Test2(strMessage)

MsgBox strMessage

End Sub

Function Test3()

MsgBox strMessage

Test3 = strMessage

End Function

其中只有Test1可以被当作命令使用。Test2带有参数，而Test3是函数，所以他们不能被使用。

使用VB子程序的特殊命令是：-RunScript “子程序名称”，注意前面有减号“-”

如上面的代码运行：

-RunScript Test1

就可以调用Test1()子程序

可以用Tools|RhinoScript|Run菜单命令来管理或者运行RhinoScript命令，也可以用RunScript命令完成同样的功能。执行菜单命令或者RunScript命令后会出现如下的对话框。

里面有当前所有可用子程序名称。

下面给出一段实际代码：

'

Function set_rhomboid()

'add ArrPoint(3) to document.

'you can delete it, while delete all operation of PointName(3)

PointName(3) = nt(ArrPoint(3))

'add 4 lines to document.

'calculate the ArrPoint(3)

Vector(0) = ArrPoint(1)(0) - ArrPoint(0)(0)

Vector(1) = ArrPoint(1)(1) - ArrPoint(0)(1)

Vector(2) = ArrPoint(1)(2) - ArrPoint(0)(2)

ArrPoint(3)(0) = ArrPoint(2)(0) + Vector(0)

ArrPoint(3)(1) = ArrPoint(2)(1) + Vector(1)

ArrPoint(3)(2) = ArrPoint(2)(2) + Vector(2)

'init the Vector and ArrPoint(3) into array type

Vector = Array(0,0,0)

ArrPoint(3) = Array(0,0,0)

'get the third point

ArrPoint(2)=nt("input the third point")

If False = IsArray(ArrPoint(2)) Then

Exit Function

End If

PointName(2) = nt(ArrPoint(2))

'get the second point

ArrPoint(1)=nt("input the second point")

If False = IsArray(ArrPoint(1)) Then

Exit Function

End If

PointName(1) = nt(ArrPoint(1))

'get the first point

ArrPoint(0) = nt("input the first point")

If False = IsArray(ArrPoint(0)) Then

Exit Function

End If

'get the identifier string of the point, for using

PointName(0) = nt(ArrPoint(0))

'define local var

Dim ArrPoint(3), PointName(3), LineName(3), Vector, GroupName

LineName(0) = e(ArrPoint(0), ArrPoint(1))

LineName(1) = e(ArrPoint(0), ArrPoint(2))

LineName(2) = e(ArrPoint(1), ArrPoint(3))

LineName(3) = e(ArrPoint(2), ArrPoint(3))

'delete help points from PointName(0) to PointName(3)

Object(PointName(0))

Object(PointName(1))

Object(PointName(2))

Object(PointName(3))

'make a new group and add 4 lines(from LineName(0) to LineName(3)) to the group

'like this, user can operate this rhomboid as a single object

GroupName = up()

If False = p(GroupName) Then

Exit Function

End If

ectToGroup LineName(0), GroupName

ectToGroup LineName(1), GroupName

ectToGroup LineName(2), GroupName

ectToGroup LineName(3), GroupName

'return this gruop name for more operation

set_rhomboid = GroupName

End Function

Sub setrb()

'-RunScript setrb

as "addrh", "_-RunScript setrb"

set_rhomboid()

End Sub

上面一段代码只有一个函数，和一个无参子程序，来提供给Rhino命令使用。整个程序只有一个函数set_rhomboid产生功能。

set_rhomboid先让用户输入三个点，然后函数使用这三个点计算第四个点，然后由这四个点连成一个平行四边，并将作为标记的四个点删除，只留下四条线段。并将这四条线段加入到同一个组内，使这个平行四边成为一个对象。

注意最后一行的“裸语句”as "addrh", "_-RunScript setrb"。

这是一个Rhino子程序as的调用，作用是给一段标准的Rhino命令起一个“别名”，之后就可以使用这个别名来实现这个Rhino命令的功能。本例中为"_-RunScript setrb"，注意前面的“_”是不能少的。然后就可以在命令行里输入addrh来实现-RunScript setrb命令的作用，而实际上就是最终调用函数set_rhomboid()。

三，启动Rhino时自动加载RVB文件

一般情况下当然是希望Rhino时自动加载一些RVB，来扩展Rhino的功能，方法如下：

TOOLS|Options

弹出如下对话框：

选择RhinoScript一项，在右端方可进行启动加载脚本文件的操作。

另外RhinoScript函数：rtupScript (strScriptFile [, intIndex])也可以完成这个操作

strScriptFile是一个RVB文件路径，intIndex是一个0起始索引，用来表示这个strScriptFile在加载列表中的加载顺序，0索引先加载。函数成功则返回一个整数，其为加入的新RhinoScript在加载列表中的索引。调用失败返回Null。

四，自定义Rhino工具条

在Rhino中可以由用户自定义一些工具条，每个工具条按钮可以关联一个基本的Rhino系统命令，也可以关联到一个自定义的别名命令（使用as）。下面介绍如何填加工具条。

填加工具条只前要先编辑工具条。Rhino4的环境中带有工具条的操作工具。使用方法如下。

Tools|ToolBar Layout

打开如下对话框，在这里可以完成Rhino所有的工具条的编辑，载入和关闭操作。

注意，在Rhino中有工具条集合（toolbar collection）的概念，一个工具条集合中可以包含多个工具条，只有在同一个工具条集合中的工具条才可以级联。如上图，上面的列表框中的“default”就是当前载如入的工具条集合，而下面的是这个工具条集合的所有工具条，前面的复选框表示工具条是否作直接显示。注意没有勾选的工具条虽然不被直接显示，但可能被作为直接显示工具条的下级级联工具条。

制作新工具条的方法如下：

在这个对话框中，File|New，指定一个新的文件名，注意后缀为“.tb”。这时候就会生成一个与文件名同名的工具条集合在列表中出现。选中这个工具条集合然后用Toolbar|New为选中的这个工具条集填加工具条，如下图：

在工具条上右键“Add Button”可以为工具条添加新的按钮，刚建立的工具条会有一个默认按钮。

下面讲述按钮的编辑方法。下面的工具条已经添加好了一定数量的按钮。

删除多余的按钮：将鼠标停在要按钮按住SHIFT，正键（一般是左键）拖动要删除的按钮，见它拖出工具条范围，放开鼠标就可以删除这个按钮。

编辑按钮：将鼠标停在要按钮按住SHIFT，反键（一般是右键）点击要编辑的按钮，就会弹出如下对话框。

Rhino工具条按钮的正反键都可以执行不同的命令。可以在“Left mouse button command”或者“Right mouse

button command”编辑框里进行动作编辑，具体的编辑方式在下一部分讲述。Tooltips里面的两个编辑框主要用来编辑按钮的鼠标浮动提示。Linked toolbar中可以给按钮设置一个级联工具条。级联工具条只能与当前的工具条在同一个在工具条集合里面。拥有下级工具条的按钮有下脚会有一个三角形的小标记。任何无

动作的鼠标点击都可以弹出下级工具条。点击Edit Bitmap按钮可以编辑按钮的图形。如下：

在一切编辑好之后在Toolbars对话框中保存这个工具条集合到文件中。

五，工具条脚本程序

所有的工具条动作最终都必须成为对Rhino插件的调用，这里先介绍RhinoScript中可以使用的脚本程序的设计方式。

先介绍几个常用的RhinoScript工具条函数。

rCollectionNames ()

得到当前载入的所有工具条集合。工具条集合在RhinoScript中以字符串方式表示，而且对于同一个文件中的工具条集合名字不因为多次载入而变化。

函数成功则返回一个装有所有名字字符串的数组。失败返回NULL。

olbarCollection (strFile)

从文件载入一个工具条集合（注意Rhino的一个工具条集合文件进保存一个工具条集合）。

strFile为文件路径。函数成功返回工具条集合名字字符串，失败返回NULL。

olbar (strName, strToolbar)

显示一个工具条。strName为工具条集合的名字字符串，strToolbar为工具条名字字符串，就是在“Toolbar

Properties”对话框中输入的。

如果成功显示这个工具条集合则返回TRUE ，否则返回FALSE或者NULL。如果返回NULL表示调用失败，返回FALSE表示无法成功显示。

barVisible (strName, strToolbar)

确定一个工具条是否为直接显示的工具条。参数与olbar相同。返回值含义。

NULL：调用失败

TRUE：此工具条是直接显示的

FALSE：此工具条未被显示

oolbarCollection (strName [, blnPrompt])

关闭（卸载）一个工具条集合，卸载之后这个集合中说有的工具条便不在被显示。

strName：要卸载的工具条集合的名字

blnPrompt：BOOL型参数，为TRUE表示询问是否将工具条集合的改过保存到文件中。为FALSE表示不询问也不保存。

下面写一个工具条加载函数

Function TestRS_LoadToolBar()

'test the main toolbar in this collection is visible or not

'if disvisible, show it

If (VarType(strName) <> vbNull) Then

If False = barVisible(strName, "Toolbar_test_1") Then

Else

TestRS_LoadToolBar = Null

olbar strName, "Toolbar_test_1"

TestRS_LoadToolBar = strName

'if this toolbar collection is not loaded, open the toolbar collection.

'note the search paths, because the current path maybe one of this script file path, System and Rhino main path.

If 0 = Flag Then

strName = olbarCollection("")

If (VarType(strName) = vbNull) Then

strName = olbarCollection("..script_")

End If

If (VarType(strName) = vbNull) Then

strName = olbarCollection("script_")

End If

Flag = 0

'find out needed toolbar collection "mytesttoolbar" from all loaded toolbar collections

arrNames = rCollectionNames()

If IsArray(arrNames) Then

For Each strName In arrNames

Next

If "mytesttoolbar" = strName Then

'find the needed toolbar collection, set the flag = 1

Flag = 1

Exit For

Dim arrNames, strName

Dim Flag

End If

End If

End If

Else

End If

TestRS_LoadToolBar = Null

End If

End Function

函数很简单，先检查“mytesttoolbar”工具条集合，是否已经被载入，如果没有被载入则载入它。Flag仅仅是个标志。注意载入时文件没测试的内容。这个函数使用了相对路径来进行载入的，这样可以无所谓文件放置的位置。在不同的情况下“当前路径” 可能是，“System”，“System”所在路径，脚本文件所在路径。注意我这里把文件放在了script_plug目录下，script_plug目录在“System”所在路径目录下，也就是Rhino所在的路径下。

通过正常打开或者已经打开而得到工具条集合名字之后，用barVisible检查主工具条（Toolbar_test_1）是否是被显示的，如果没有被显示则显示它。最后函数返回工具条集合的名字。

六，工具条综合应用

这里我先把绘制平行四边型的功能关联到一个按钮上

先把函数用一个无参子程序调用，来形成一个Rhino命令，如下：

Sub add_rhomboid()

set_rhomboid()

End Sub

SHIFT+反键点击一个按钮，给左键加一个脚本命令。

在Left mouse button command编辑框里加入

!-RunScript add_rhomboid

足以前面的“!”不能少。这样在左键点击“i”按钮时相当于执行了-RunScript add_rhomboid命令。

一般这样的工具条还可以提供一个卸载功能，所以先写一个卸载函数，也将其用无参子程序调用，如下：

Function TestRS_UnLoadToolBar()

'close the toolbar collection

oolbarCollection "mytesttoolbar", True

End Function

Sub UN_LOAD_RS_TEST_TOOLBAR()

TestRS_UnLoadToolBar()

End Sub

用同样的方式给“禁止按钮”加一行命令。

!-RunScript UN_LOAD_RS_TEST_TOOLBAR

最后保存对mytesttoolbar工具条集合的修改。然后就可以生效了。注意：用上面的方式卸载工具条集合的时候第一次载入时，不能卸载，而之后就会正常，不知道为什么？希望有高手指点。

最后注意，所有的RhinoScript都是出现在RVB文件中的，所以想正常执行工具条按钮的动作必须先载入相应的RVB文件。所以最方便的方法就是用RVB文件载入工具条集合。在载入RVB文件时载入工具条集合。具体方法就是在RVB文件最后加一些裸语句来完成载入工作。很简单，直接调用上面的TestRS_LoadToolBar就可以了。

TestRS_LoadToolBar()

还有一点在编写RVB文件时要注意，在一个Rhino环境中（文档中），所有的被载入的RVB文件，命令行，以及用Rhino的VBscript编辑器正在测试的脚本都使用的是同一个环境。也就是说，他们可以相互访问变量，这样如果有同名的变量存在就会出现冲突，这个设计程序时要注意。而且Rhino的VBscript编辑器对于同一段程序先测试运行之后，这段程序便成为当前环境的一部分，所以最好的测试方式就是把程序写到子程序或者函数中，然后用裸语句调用。子程序或函数一般不会产生类型冲突，这样比较保险。

七，从HTML对话框获得数据

Rhino支持从一个HTML的文件得到数据，对话框的内容就是HTML文件描述的页面内容。同时HTML内部可以按照DHTML规则运行VBSCRIPT脚本程序，并且可以向主程序传回数值。

首先介绍一个函数：

x (strFileName [, arrArguments [, strOptions]])

它可以用HTML文件建立一个模太对话框

strFileName

HTML文件路径，当前路径为RHINO所在路径。

arrArguments

传入HTML文件的参数，可以是任意类型。可由HTML环境中的Arguments得到。

strOptions

对话框窗口的初始化参数，都是字符串，如下：

dialogHeight:sHeight

窗口高度

dialogLeft:sXPos

窗口左上角X坐标

dialogTop:sYPos

窗口左上角Y坐标

dialogWidth:sWidth

窗口宽度

这4个数据的单位可以是px或者em，默认是em

center:{ yes | no | 1 | 0 | on | off }

页面是否居中

resizable:{ yes | no | 1 | 0 | on | off }

窗口大小是否固定

scroll:{ yes | no | 1 | 0 | on | off }

窗口是否有滚动条

strOptions这个参数是一个形如：“XXX1:xxx1;XXX2:xxx2”这样形式的字符串。

函数失败返回Null

函数成功返回从HTML页面返回的值，是Variant类型，在使用的时候最好使用基础类型，比如字符串，来表达复杂类型值。

在HTML页面中用Value返回。

HTML页面从调用返回。

下面一个组程序，它从一个HTML页面返回四个数据，两两一组，组成2个2D点坐标，然后主掉程序使用这两个点在X-Y平面上绘制平行四边形。

HTML文件

Communication Dialog

注意OnOk过程。sResult的值是一个“;”分隔的四个数据的字符串，下面注意将这单个字符串变成4个DOUBLE数据的方式。

Function GetParFromHtml()

ReturnValue = x("script_")

PRINT typename(ReturnValue)

If ("Empty" = typename(ReturnValue)) Or ("Null" = typename(ReturnValue)) Then

GetParFromHtml = Null

Exit Function

Dim ReturnValue, ReturnString

Dim RetArray(1)

End If

ReturnString = Split(ReturnValue, ";")

If False = IsArray(ReturnString) Then

GetParFromHtml = Null

Exit Function

End If

RetArray(0) = Array(0, 0, 0)

RetArray(0)(0) = CDbl(ReturnString(0))

RetArray(0)(1) = CDbl(ReturnString(1))

RetArray(0)(2) = 0.0

RetArray(1) = Array(0, 0, 0)

RetArray(1)(0) = CDbl(ReturnString(2))

RetArray(1)(1) = CDbl(ReturnString(3))

RetArray(1)(2) = 0.0

GetParFromHtml = RetArray

End Function

Split(ReturnValue, ";")将ReturnValue按照符号";"将ReturnValue分成字符串数组，并返回数组CDbl将字符串转化为DOUBLE数据。

这个函数GetParFromHtml就是从HTML得到必要数据并将这些数据变成两个点放在数据RetArray返回。

下面的程序就是利用这两个点和（0，0，0）点绘制平行四边形。

Function add_rhomboid(PointSrc, Point0, Point1)

'make a new group and add 4 lines(from LineName(0) to LineName(3)) to the group

'like this, user can operate this rhomboid as a single object

GroupName = up()

If False = p(GroupName) Then

add_rhomboid = Null

Exit Function

'add 4 lines to document.

LineName(0) = e(ArrPoint(0), ArrPoint(1))

LineName(1) = e(ArrPoint(0), ArrPoint(2))

LineName(2) = e(ArrPoint(1), ArrPoint(3))

LineName(3) = e(ArrPoint(2), ArrPoint(3))

'calculate the ArrPoint(3)

Vector(0) = ArrPoint(1)(0) - ArrPoint(0)(0)

Vector(1) = ArrPoint(1)(1) - ArrPoint(0)(1)

Vector(2) = ArrPoint(1)(2) - ArrPoint(0)(2)

ArrPoint(3)(0) = ArrPoint(2)(0) + Vector(0)

ArrPoint(3)(1) = ArrPoint(2)(1) + Vector(1)

ArrPoint(3)(2) = ArrPoint(2)(2) + Vector(2)

'init the Vector and ArrPoint(3) into array type

Vector = Array(0,0,0)

ArrPoint(3) = Array(0,0,0)

ArrPoint(0) = PointSrc

ArrPoint(1) = Point0

ArrPoint(2) = Point1

If (False = IsArray(Point1)) Or (False = IsArray(Point0)) Or (False = IsArray(PointSrc)) Then

Exit Function

End If

Vector = Array(0, 0, 0)

Dim ArrPoint(3), LineName(3), Vector, GroupName

End If

ectToGroup LineName(0), GroupName

ectToGroup LineName(1), GroupName

ectToGroup LineName(2), GroupName

ectToGroup LineName(3), GroupName

'return this gruop name for more operation

add_rhomboid = GroupName

End Function

Sub AddRhomboidFromHtml()

Point = GetParFromHtml()

If ("Empty" = typename(Point)) Or ("Null" = typename(Point)) Then

Exit Sub

End If

add_rhomboid Array(0, 0, 0), Point(0), Point(1)

Dim Point

End Sub

add_rhomboid用来绘制平行四边形，利用PointSrc-Point0，PointSrc-Point1两条线段作为平行四边形的两边，并计算出另两个边，将四条线段绘制并填加到一个组内。

AddRhomboidFromHtml就是利用将上面两个函数绘制这个平行四边形。对话框如下：

注意("Empty" = typename(Point)) Or ("Null" = typename(Point))这种类型判断方式，这样是比较安全的。当在对话框点关闭按钮关闭时返回值是EMPTY类型。

下面加一个绘制六面体的函数：

Function add_hexahedron(Point0, PointList, flag)

AllLines(0)=e(Point0, PointList(0))

AllLines(1)=e(Point0, PointList(1))

AllLines(2)=e(Point0, PointList(2))

If False = IsArray(PointList) Then

add_hexahedron = Null

Exit Function

Dim AllLines(11)

Dim LineCurve(3)

Dim MidPoint(3)

Dim x, y, z, i

Dim GroupName

End If

Else

add_hexahedron = Null

End If

For i = 0 To 11 Step 1

Next

add_hexahedron = GroupName

ectToGroup AllLines(i), GroupName

If 0 <> flag Then

GroupName = up()

If False = p(GroupName) Then

add_hexahedron = Null

Exit Function

x=MidPoint(2)(0)+PointList(1)(0)-Point0(0)

y=MidPoint(2)(1)+PointList(1)(1)-Point0(1)

z=MidPoint(2)(2)+PointList(1)(2)-Point0(2)

MidPoint(3)=Array(x,y,z)

AllLines(9)=e(MidPoint(0), MidPoint(3))

AllLines(10)=e(MidPoint(1), MidPoint(3))

AllLines(11)=e(MidPoint(2), MidPoint(3))

x=PointList(2)(0)+PointList(0)(0)-Point0(0)

y=PointList(2)(1)+PointList(0)(1)-Point0(1)

z=PointList(2)(2)+PointList(0)(2)-Point0(2)

MidPoint(2)=Array(x,y,z)

AllLines(7)=e(MidPoint(2), PointList(2))

AllLines(8)=e(MidPoint(2), PointList(0))

x=PointList(1)(0)+PointList(2)(0)-Point0(0)

y=PointList(1)(1)+PointList(2)(1)-Point0(1)

z=PointList(1)(2)+PointList(2)(2)-Point0(2)

MidPoint(1)=Array(x,y,z)

AllLines(5)=e(MidPoint(1), PointList(1))

AllLines(6)=e(MidPoint(1), PointList(2))

x=PointList(0)(0)+PointList(1)(0)-Point0(0)

y=PointList(0)(1)+PointList(1)(1)-Point0(1)

z=PointList(0)(2)+PointList(1)(2)-Point0(2)

MidPoint(0)=Array(x,y,z)

AllLines(3)=e(MidPoint(0), PointList(0))

AllLines(4)=e(MidPoint(0), PointList(1))

End If

End Function

函数使用Point0-PointList（0），Point0-PointList（1），Point0-PointList（2）三条线段来绘制一个六面体。

Flag不为0的时候函数将六面体的8条边加入一个组中并返回这个组的名字。

script_plug里面是这个教程最终使用的VBScript代码，TB文件和HTML文件的包，希望对大家有用。将这三个文件放入script_plug的目录下载入使用即可（如“五，工具条脚本程序”一节的目录组织方式）。

注意。代码与前面的例子中的并不完全相同，有一些修改。工具条也给子工具条填加了动作。

OVER

MeteorCode

2009-12-26