MotionBuilder插件(HandDriver2.1+)

一、系统要求

  • MotionBuilder 2019,2020版本

  • Windows 7 SP1 及以上版本

  • 本手册适用于HandDriver2.1版本

二、开发准备

  • 请首先确保UDEXREAL HandDriver 软件已经成功安装,如果还未进行此操作,请先安装。

  • 下载HandDriver的MotionBuilder插件包到本地,插件包下载地址为(提取码: p943):

  • 请注意MotionBuilder2.1+插件需要配合新版HandDriver2.1+使用。

  • 旧版本MotionBuilder插件不建议使用,如仍要使用请匹配HandDriver对应版本。

三、快速开始

3.1. 运行 UDEXREAL HandDriver软件

在电脑上运行UDEXREAL HandDriver软件,确保手套正确连接并使用。软件使用方法参见UDHandDriver软件介绍

3.1.1. 数据发送设置

1

在HandDriver软件中点击右上方的螺母形状按键,系统弹出设置窗口:

2

在弹出的设置窗口中,选择“数据发送”选项,并根据需要进行自定义设置:

  • 勾选“数据发送”,即打开数据发送开关。

  • 点选IMU,使用MotionBuilder插件时必须要点选IMU。

  • 数据格式欧拉角、四元数、VMC为三选一,三者为互斥选项。针对本插件选择欧拉角。

  • 选择发送帧率,支持120Hz、90Hz、60Hz三种帧率,发送帧率默认为120Hz。

  • 点击目标地址中的“+”图标,填入接收端的IP地址和端口号,方可进行数据发送(本地发送填写127.0.0.1)。

  • 端口号默认为5555,如无特别情况,请使用该默认端口号,否则需要修改插件端对应端口号。

  • 设置完成后,点击“应用”按钮进行保存。

  • 数据发送选项设置完成后,请不要退出软件,保证软件在后台运行,否则无法获取手套数据。

3.2. 运行 MotionBuilder软件

本教程以MotionBuilder2019为例,在MotionBuilder2020中的所有配置及操作是完全一致的,只需要自行区分本地安装文件的路径是归属于哪个版本。

3.2.1. MB插件配置

1

在本地解压下载的插件安装包,文件夹构成如下图所示:

  • Model文件夹内含有一个示例模型SampleBody.fbx。

  • Plugin & Json内含有三个dll文件:UDE_MBPlugin.dll,UDE_MBServer.dll,jsoncpp.dll;以及三个Json文件:UDGloveConfig.json,HierarchyBody.json,HierarchyHand.json; 一个角色化数据的XML文件:SampleTemplate.xml。

  • Python Scripts内含有两个Python脚本:GenJson.py,pythonidelib_init.py。

  • 根目录下有一个图片文件UDE_icon.png。

2

找到MotionBuilder在本地安装的目录,通常为:...本地路径/Autodesk/MotionBuiulder 20xx,其目录结构应如下图所示:

  • 将UDE_icon.png 复制粘贴到此目录下的bin/system/内。

  • 将UDE_MBPlugin.dll,UDE_MBServer.dll,jsoncpp.dll,UDGloveConfig.json,HierarchyBody.json,HierarchyHand.json 全部复制粘贴到此目录下的bin/x64/plugins/内。

  • 启动MotionBuilder程序,在加载界面可以看到加载插件的信息。

circle-exclamation
3

在左上角选择File->Open 然后选择SampleBody.fbx,打开。

4

在设置中单击关闭模型的Textures纹理。

5

可以在场景中看到导入的默认人体模型。

在右下角的Asset Browser标签内(默认打开),单击左边目录节点Templates中的Devices,可以看到所有默认及安装的插件。

单击按住UDE Plugin图标不放,将鼠标拖到显示模型的场景中再松手,此时会提示选择导入关节节点Json的目录。

6

如果之前已经正确将三个Json文件放到指定的plugins文件夹内,直接点击确定会跳出已经选择好骨骼结构的提示框。

左下角会自动加载插件的页面。如果不是接入全身动捕的情况,要勾选右侧的“If Need Bind Model Body”,模型绑定中选择名为DeformationSystem的选项,这是示例模型模型根部关节点的名称。如果这一步没有出现DeformationSystem,那么请重新重复第二步中复制粘贴三个Json文件的步骤,并重新从右下角将插件图标拖入场景位置,重新加载插件。

7

如果右侧设置中最上方的Listening Port为默认的5555,且没有更改HandDriver内串流的默认端口号(也为5555),那么点击脚本内的Online按钮即可开始串流。

8

如果一切都运行无误,Online的图标将会变成绿色,数据量大约在120 samples左右。

此时已经可以正确地在将HandDriver的动作串流到人体模型手上。

3.2.2. 使用其他模型的预设置

以下操作以示例模型为例。

1

如果想要驱动其他模型进行串流,就需要有一些额外的设置。回到刚刚打开软件的步骤,现在从File->open选择想导入的其他模型。随后在场景中可以看到导入的模型。

circle-exclamation
2

在左上角的操作栏中点击Window->PythonEditor

circle-exclamation
3

在弹出的新窗口中,点击左上角的文件夹图标,然后在目录中选择插件解压包内Python Scripts文件夹里的GenJson脚本,打开(脚本的所在的路径中请勿带有中文字符,否则可能造成无法读取)

4

Python脚本提供了一些适配特殊情况的修正,在最上方的红色注释范围内。

  • FingerHasEndTip: 类型为布尔值,判断模型手关节是否含有末端点。默认为True,正常情况下模型每根手指均有不活动的末端关节点,命名中通常含有“Tip”。如果遇到特殊情况,比如没有末端关节点多个末端关节点,或是含有许多冗杂关节点的时候,需要将这项改为False,并编辑接下来的三个参数。

  • LeftFingerPublicString: 类型为单个字符串,仅在FingerHasEndTip为False时生效。为左手常规手指关节的通用子字符。比如模型中左手手指关节名称为L_Finger01,L_Finger02,L_Finger03,则通用子字符为“L_Finger”(区分大小写),这一项设置的作用是,在手部根关节下遍历所有子关节时,会自动筛掉不含通用子字符的关节点。如果常规手指关节并没有通用子字符,则不需要更改,保持字符串为空。

  • RightFingerPublicString: 同上,为右手的常规手指关节通用子字符。

  • ForbidSubString:类型为字符串List,仅在FingerHasEndTip为False时生效。为手部节点中需要被过滤掉的关节所含有的字符。例如手关节中有许多不参与关节活动的额外关节,名称为Thumb01half,Ring02half等等,“half”是这些额外关节的通用子字符串,因此所有名称中含有“half”(区分大小写)的节点都会被过滤掉。判断时会考虑list中的所有字符串,所以需要注意不要加入长度与特征过于少的字符串,以避免被正常关节点覆盖。例如“_in”,是某些额外关节点,是名称为Middle01_in,Middle02_in的子字符。但如果只写“in”,那么正常必须保留的index01,或Finger01等也会被过滤掉。

  • PortsAvailable:类型为整数List,单独生效。作用为插件能监听的端口号,可以有若干个(不建议过多),默认为5555,5556,5557。常规运行时不需要更改,插件默认使用的端口号为5555。假如遇到端口号被占用或必须更改端口号的情况,可以在此更改想监听的端口号。请注意,当List为空,或内部参数类型不为整数型时插件会无法正常运行。

注意:请勿随意更改除此部分以外的Python脚本代码,以防生成的Json错误导致插件崩溃。

5

随后在软件布局左下角的Navigator中找到茶壶图标的Scene,单击点开后会显示模型的层级结构,双击Scene下一层的根节点,在左侧的讯息框中可以看到All Models(1)下出现了该根关节点的名称。

Tips:如果Scene下出现了两个节点,那么大概率其中一个是Mesh,另一个才是骨骼的根关节,请选择骨骼的根关节点,不可以多选。如果该层级有更多的节点,那么请选择包含手部骨骼的一个最高层级节点作为根关节。

6

随后右键点击子节点Root_M,选择Expand Branch(展开分支),然后在所有关节点中找到代表右手和左手的根节点。

注意,需要按住Ctrl键,先点击右手的根关节,然后再点击左手的根关节。此时右侧的信息栏也会显示右手与左手的根关节名称。必须先选择右手,再选择左手,才能确保串流时的左右手对应。这样看到显示了三个关节点。

7

选择完毕后在刚才弹出的新窗口内点开GenJson.py,然后点击上方的运行,运行完毕后在控制台内会显示加载进Json的各种关节点信息。如果最后控制台打印提示Json文件导入成功,即可继续下一步。

该步骤后如果出现如下报错,是由于MotionBuilder安装在C盘,因此无法在非管理员权限下进行写入,需要退出后以管理员权限重新运行MotionBuilder,并重复上述流程。

circle-exclamation

具体方法:

1

右键Scene层级,然后插入一个空的根节点。

2

随后选择场景内原先的若干节点,将它们移至空的根节点下,设置空节点为Parent。

3

这样原先的若干节点都放进了这个新建的根节点内,随后再点选这个新的根节点,重复上面的Json生成操作即可。

新生成的骨骼信息Json文件会自动替换掉之前放在plugins文件夹内的默认Json文件,并且plugin目录下将生成一个以所选骨骼根节点命名的文件夹,内部也储存了该模型的三个Json文件。(该功能在3.3中会详细说明)。

circle-exclamation

如果实际运行不正确,按上述操作步骤为新模型重新生成一次,或是尝试手动更新Json,以确保plugins中的Json文件为最新生成的。

circle-exclamation

随后按照之前的步骤重新导入插件,此时如果在Model binding下拉选项中看到了新导入模型根关节的节点名称(此处为另一个测试模型的节点),并选择,那么以上更换Json文件的步骤就成功了。

点击Online运行,如果插件可以串流成功,且活动手部,模型上也有动作反馈,那么就可以进入设置调节步骤。

请注意,更换模型后的动作如果很怪异是正常的,需要完成适配设置后才能表现正常。

3.3. MotionBuilder插件功能详解

3.3.1. Initial Set页面

以红色序号作为索引

  1. 插件信息标签,框内的更新时间与文档描述一致时插件为最新版本。目前最新版时间为(2025.01.10)

  2. 折叠组件按钮,按下时会收起序号到序号范围内的功能,再次按下可以展开,不会影响已经设定好的设置,以便在上方窗口内观察模型校调的表现。

  3. Json选取。如果通过Python脚本为各种不同模型生成了Json,plugin内将会生成多个以模型所选根关节为名字的文件夹,此处会自动读取这些文件夹供绑定不同模型时的快速选择。

如果没有通过Python生成Json的话,这里就只有Default选项,代表读取默认路径中的Json文件,左侧的方框内将显示现在的读取路径,默认及其它plugin文件夹外的路径将显示[Default or OtherPath]。

通过Python脚本为实例模型生成Json后,就可以在这里看到选择该文件夹路径的选项。

选择之后点击右侧的指代的Auto Import按钮,会自动重新导入该文件夹内的Json,导入后会有弹窗提示,并且方框内也将更新为目前路径为[DeformationSystem]。

由此这样不需要为同一模型重复生成Json就能快速完成绑定。例如再为一个Test模型生成Json后,也可以看到该选择。

另:在初始拖入插件选择路径时,也可以直接选择plugin内所需的子文件夹路径,达成绑定某指定的模型。

  1. 自动导入Json按钮,可以基于①③的设定,跳过选择路径的弹窗直接自动导入。中的选项将决定自动导入的路径,中的选项将决定额外的命名操作。

  2. Json修改,默认为None,在示例模型使用中不需要理会。当已经通过Python生成Json文件后,场景中加入了其它与该Json所保存的模型结构和空间位置信息完全一致,只是在命名上有差异的情况,可以使用此设置便捷绑定该命名不同的模型的设置。(通过Motionbuilder在场景内merge进来的完全一样的模型时设置的不同Namespace可以自动适配,不需要额外设置)

circle-exclamation

下拉菜单内包含的选项自上而下分别为:无操作,增加前缀,删除前缀,更改前缀,增加后缀,删除后缀,更改后缀,同时增加前后缀,增加前缀并删除后缀,删除前缀并增加后缀,同时删除前后缀。

选择仅增加或删除选项时,后侧会出现单个输入框,例如此处的xxx(使用时需要精确区分大小写) 表示要适配一个模型命名所有关节点命名前缀多了“Test”的情况。

选择修改或前后缀同时增减选项时,会出现两个输入框。在Modified时,左侧为需要读取的字符,右侧为需要替换成的字符。在其它前后缀同时增减时,左侧代表的是前缀字符,右侧为后缀字符。例如单独为上述带有“Test”前缀的模型生成Json后,现在出现一个与该模型完全一致但关节点命名前缀变为“Name”的,可以一次性适配,相当于执行了一次删除前缀Test又增加前缀Name的过程。

当设置时输入框为空又点击重新导入Json按钮时,会弹出错误提示。在前后缀输入本质上错误时(例如需要更改或删除的前后缀没有找到等)不会产生任何效果。

操作例子:

已经为带有前缀Test的模型生成Json文件,选择模型绑定时就只能绑定该模型,场景内不含Test前缀的无法绑定。

执行一次删除Test前缀的方法,点击重新导入Json。

随后就可以绑定到该不含前缀的模型上,但此时也会无法绑定含有Test前缀的模型。

如果需要切换回去,只需要将设置选择成None,再重新导入即可。该设置为一次性操作,尽管调整为适配删除Test前缀的情况,但原始Json中仍旧含有Test前缀,所有调节需要以原始Json作为基准来进行。

  1. 重新导入Json文件按钮,与拖入插件时选择Json路径的功能完全一致,此处选择Plugin内的子文件夹路径时也可以在Json Selection右侧的方框内显示该路径的文件夹名字。

  2. 监听串口号,可以从Python脚本中预先设置的串口号中选择。

  1. 角色名称,根据当前串口号中含有的所有角色名称选择指定角色的传输数据,默认选择为第一个角色。当没有检测到角色时显示为“None”(包括角色名称正好也是“None”的情况)。

  2. 是否需要绑定全身骨骼的设定,默认不勾选。在使用静态模型时需要勾选,接入全身动捕骨骼时不需要勾选。

  3. 是否需要读取模型本地旋转,如果使用了则文本后的括号显示为used,未使用为not used。在模型导入时如果子节点中有本地旋转时需要设置。具体方法如下:

如果绑定模型后出现类似下图的错误形态

需要先勾选该选项,然后通过按钮进行重新导入,再重新绑定模型。请注意,该勾选只在重新导入时产生效果,寻常状态下是否勾选都不会有作用,是否应用请参照左侧文本后括号内的提示。

  1. (该方法已经做了自动检测适配,正常情况下不需要变动设置)手部骨骼关节数量及根关节设置,有16、20 root 4、21 root 5这三种。16关节为手根部关节+每根手指三个活动关节,20关节在16关节的基础上,除了拇指的四根手指会各有一个不需要驱动的根关节,21关节则是每根手指都有不活动的跟关节。

根据模型实际情况选择该设置。有时根关节的层级在手指上为第一关节,有时因为拇指没有根关节,所以后续手指的根关节可以视为前一根手指的第四关节。在插件的Joints页面可以观察得到。

例如此处的每根手指上的root为第一关节,那么就选择20 root 1。

  1. 是否需要修改手指关节在手上的排列顺序。未选择时将使用默认顺序(拇指、食指,中指、无名指、小指 ),如果需要适配模型内不同的手指关节顺序,点击后将会展开配置栏。

请根据手指关节的实际顺位在此进行设置(例如模型的手指关节顺序为食指、中指,小指,无名指,拇指,则此处排序应为5、1、2、4、3),设置完毕后取消点选CheckBox也会保存当前设置,关节顺序可以在常用建模软件内自行查看或是在Joints页内观察得知,详情请看后文对Joints页的说明。

  1. 在online时Joints中会实时更新关节点的位置及旋转,如果右手的根关节有一个默认旋转角(如下图,右手根关节的默认旋转角不为0),同时模型的手部出现了麻花状的扭曲或是明显错误的变形,则需要选择LeftHand(如果两只手的表现正常,那么即使有默认旋转角度也可以忽略)。如果两只手都需要则选择Both,都不需要则默认是None。

在示例模型中,若关闭此设置会看到手的姿态明显有误。

  1. 为限制大拇指根关节俯仰角活动比率的一个百分数(范围是0-1),可以根据实际需要的模型表现来设置。

  2. 拇指2和3关节对应的坐标轴,因为在不同模型上存在2,3与根关节变换不对应的情况,所以可能需要额外设置,在调整好其它手指根关节表现后依次尝试XYZ选项,取表现正确的即可。

  3. 右手大拇指根关节的偏移角,可以调节大拇指在三个轴向上的默认旋转角偏移,来达到尽可能正确或是想要的活动姿态。参数没有限制范围。

  4. 同上,为对应左手大拇指的相同设置。

  5. 右手手指的三个轴向的顺序,默认1代表旋转角,2代表偏航角,3代表俯仰角。调试时可先令三轴中的两轴为零,然后将1或3填入X或Y或Z,运动手指,观察其表现是否正确。

    • 如先将1填入X,如果运动四个手指没有变化(四指实际上不应有旋转),则说明正确。如果手指出现扭曲,说明旋转不在X轴上,再将1填到Y或Z进行观察,以最终确定旋转在哪个轴上。

    • 也可以尝试先将3填入X,此时握拳,如果四个手指运动正常,则说明正确,如果手指反向上翘,则可以填入-3。如果此时握拳手指运动出现异常,说明俯仰不在X轴上,再将3填到Y或Z进行观察,以最终确定俯仰在哪个轴上。

    • 以此类推,确定后续两个值的填写。需要根据不同模型的表现来进行调节。如果设置为可选数字以外的数值会导致表现不正常或设置无效果。

  6. 同上,为左手手指的轴向调节。

  7. 大拇指轴向单独设置:在其他四根手指表现正常,但拇指活动轴向有误时选用。

该选项不选用时拇指轴向配置与10及11中的设置相同。如果拇指与另外四指不同时,比较快速的调整方法为:

(1)将XY的数值对调,比如四指的XY分别为1、2,则将拇指的XY设置成2、1

(2)将四指的数值正负取反,比如四指为1、-2、3,则拇指为-1、2、-3

(3)请注意左右手是否镜像相反

如果上述快速调整法不行,则建议按照选项“18”的调法尝试。

  1. 如果因为最初设置有误导致模型中无关关节点产生偏移,除了必要手指关节以外的关节点位置无法自行恢复,按下此重置按钮可以将模型所有层级的旋转角设定为初始状态。注意,该设置仅在Online时生效。

  2. 保存所有上面的固定参数设置到Json文件中的按钮,同样的模型再次打开导入插件时会自动读取并应用已保存好的设置,如果更改了设置则需要重新保存。保存成功时会弹出成功信息的提示框。一般保存失败的原因是MotionBuilder安装在C盘且没有以管理员权限运行,所以在C盘内的写入操作被禁止了。

需要注意的是,配置Json导出的路径与当前Json导入的路径一致,请不要以当前已绑定的模型作为路径参考,以免丢失保存路径。

3.3.2. Finger Fix页面

Finger Fix页面上可以分别设置左右手剩余手指所有可活动关节固定偏移角(左右手的偏移角参数是分别作用不关联的),大拇指第一根关节的偏移角在Initial Set页面上已经可以分别设置,这里包含了所有剩下的手指关节。

最下方左侧的Reset按钮可以将当前选择手的所有偏移角清零,右侧Save按钮将同时保存左右手的所有偏移角数据到Json文件中。

3.3.3. Joints页面

该页面会依据之前生成的全身关节的Json文件来实时展示当前模型各个节点在Online中的本地坐标与旋转角数值,可以通过观察关节点在左侧列表从上到下的顺序和构成来调整参数(这里的手指顺序即可对应于Edit Hand Finger Order Type,如上例顺序为1-Thumb、2-Index、3-Middle、4-Ring、5-Pinky),或是根据旋转角变化所属的轴向和数值来判断是否需要进行调整。正常情况下,只有左右手的活动关节会有数值变化,如果在未介入其他插件的条件下出现其他不该活动的部位有数值变化,请检查Initial Set中的参数设置及模型组成是否符合规范。

四、接入全身动捕

4.1 使用示例模型

驱动逻辑:

  1. 接入全身动捕骨骼,根据动捕骨骼重新生成对应Json文件。

  2. 插件覆盖绑定动捕骨骼的手部,将动作直接映射在动捕骨骼的手关节上。

  3. 导入示例模型并完整角色化,在角色控制面板中选择source为动捕骨骼,character选择为示例模型。

首先接入动捕黄色骨骼,将模型稳定在某一特定姿态(最好可以设置为默认T-Pose),按照3.2.2中的方法为动捕骨骼生成对应的全身及手部结构Json文件。

然后拖入插件,在Model Binding选择该动捕骨骼的根关节。

circle-exclamation

如果一切正常,此时可以当看到动捕骨骼上的手指接入了插件的手套数据。(表现校调需要根据该动捕骨骼重新适配参数)

随后请先通过插件内的Online按钮关闭手套数据串流,因为串流中进行各种MotionBuilder内部设置可能会导致程序卡顿。然后在MotionBuiler软件左上角选择File->Merge,导入SampleBody.fbx。

接下来要让第三方全身动捕能够驱动SampleBody示例模型,步骤如下:

1

创建新角色

点击最上方横排小图标中最左侧的Create Character按钮,可以看到现在创建了一个新的空角色(默认名称为Character)。

2

角色化

随后在Scene层级中点击选中示例模型Json的根关节,然后再点击横排小图标中的Load Skeleton Definition按钮。

在最上方的Template下拉菜单内选择最下方的<Browse...>。

定位到插件解压的文件夹内Plugin&Json文件夹,选择SampleTemplate.xml

点击窗口上OK按钮完成匹配。

可以看到角色化配置已经导入成功,该角色的名字是默认的Character。

3

用第三方全身动捕驱动示例模型

然后点击小图标按钮上的Lock Character按钮,选择弹出窗口上的Biped。

最后在上方的Source一栏内选择第三方动捕数据的角色(本例中为Robot)。

这样就可以将第三方动捕骨骼的动作映射到示例模型上。

file-download
19MB

4.2. 使用自定义模型

请先阅读上一章节的“使用示例模型”来了解全过程,本节使用自定义模型的唯一区别在于最初的模型角色化部分,即对应“使用示例模型”中的“角色化”部分(基于一个创建的新角色)。

在新建成场景内导入自定义模型,在左上角的Display下选择X-Ray,可以透视看到模型的骨骼结构。

在右侧的Character Control窗口内点击Skeleton按钮,点击Define。

随后可以看到骨骼定义的结构,在Character Controls的Definition窗口双击某个关节点,然后在场景内点击对应位置的骨骼节点即可完成绑定(也可以点击Scene中的对应骨骼节点)。

file-download
18MB

依照自定义骨骼相对应的关节完成所有节点的绑定,需要将身体基准关节以及所有的手指关节完成适配,直到红色的叉号变成绿色,完成角色化。尤其要注意手部关节点的绑定,如果角色化时绑定关节错误将影响模型手部动作表现。

然后按下最上方横排的按钮中的Lock Character完成锁定。绑定完毕后也可以点击Save Skeleton definition按钮将对应的角色化XML配置文件保存到本地,之后启动直接读取XML就能完成角色化配置。

随后的流程参照上一小章节即可完成全身动捕数据和手部动作的合并接入。

五、录制功能

5.1. 仅使用示例模型录制

录制前需要在插件左侧栏中点击勾选上Recording,在结束录制前请勿取消勾选。

随后在动画栏控制按钮处点击圆圈按钮,在弹出的提示框内选择Overwrite(如果没有动画导入,默认录制为Take 001)。

当圆圈按钮已经为红色触发状态时即可开始录制,按下朝右的播放按钮时可拖动的进度条会开始向右移动,此时场景内示例模型的动作会录制下来。

左侧红色框内增长的数字表示的是录制的总帧数,当决定结束录制时,按下停止的方形按钮,录制结束。

如果需要回放动画,需要将插件内的Live选项取消勾选,让动画完全驱动场景内的模型。

录制效果如下

file-download
646KB

5.2. 多插件及组合录制

如果需要同时在场景内录制多个插件驱动的模型或是搭配全身动捕数据一同录制,录制时请将所有控制需要录制的模型的插件上的Recording选项勾选。

录制操作请参考6.1中描述,回放则是需要将上一步中所有勾选了Recording的插件上的Live都取消勾选,这样就可以达成多个插件间同步组合录制的目的。

如果采用接入全身动捕方案,可以达到如下效果,全身动作和手部动作都被录制下来且可以正常回放。

保存整个场景,或所需的骨骼为FBX文件后,可以在其它软件内浏览录制下来的骨骼动画。

Last updated