Rhino 插件命令开发实战从 CRhinoCommand 类到 5 个核心成员函数实现在三维设计领域Rhino 以其强大的建模能力和开放的插件体系著称。作为插件开发者掌握命令Command的实现是扩展 Rhino 功能的核心技能。本文将深入解析如何从 CRhinoCommand 类派生子类并完整实现其 5 个关键成员函数带你体验一个交互式命令从诞生到运行的全生命周期。1. 命令开发基础架构每个 Rhino 命令都是一个独立的功能单元通过继承 CRhinoCommand 类实现。以下是典型命令类的骨架结构// 命令类声明应放在.cpp文件中避免多重定义 class CMyCommand : public CRhinoCommand { public: CMyCommand() default; // 构造函数 ~CMyCommand() default; // 析构函数 // 必须实现的5个核心函数 UUID CommandUUID() override; const wchar_t* EnglishCommandName() override; const wchar_t* LocalCommandName() override; CRhinoCommand::result RunCommand(const CRhinoCommandContext context) override; }; // 全局唯一命令实例 static class CMyCommand theMyCommand;关键设计原则每个命令必须有全局唯一标识UUID命令名称需同时提供英文版和本地化版本命令实例必须是全局静态单例运行逻辑集中在 RunCommand 函数中实现2. 核心成员函数实现详解2.1 命令唯一标识CommandUUIDUUID 是命令的身份证必须确保全局唯一。推荐使用 Visual Studio 自带的 GUID 生成工具UUID CMyCommand::CommandUUID() override { // {生成的GUID} static const GUID MyCommand_UUID { 0x12345678, 0x9ABC, 0xDEF0, { 0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0 } }; return MyCommand_UUID; }警告重复的 UUID 会导致命令冲突建议新建命令时立即生成新 GUID2.2 命令名称定义Rhino 支持多语言命令名称至少需要实现英文版本// 英文命令名必须实现 const wchar_t* CMyCommand::EnglishCommandName() override { return LMyCommand; } // 本地化命令名可选 const wchar_t* CMyCommand::LocalCommandName() override { return L我的命令; // 中文示例 }命名规范建议使用动词开头的驼峰命名如 CreateSphere避免特殊字符和空格保持名称简短且有描述性2.3 命令运行逻辑RunCommand这是命令的核心功能实现处典型结构包含三个部分CRhinoCommand::result CMyCommand::RunCommand( const CRhinoCommandContext context) { // 第一部分交互准备 if(context.IsInteractive()) { if(!RhinoApp().AskUserForCommandOptions(...)) return CRhinoCommand::cancel; } // 第二部分主逻辑实现 ON_SimpleArrayON_3dPoint points; if(GetUserInputPoints(context, points) ! success) return CRhinoCommand::failure; // 第三部分结果处理 context.m_doc.AddPointObject(points); context.m_doc.Redraw(); return CRhinoCommand::success; }返回值处理规范返回值类型适用场景success命令成功完成failure输入无效或计算失败cancel用户主动取消操作nothing无实际操作如空选择3. 交互式命令开发技巧3.1 用户输入处理Rhino 提供了丰富的输入获取方法// 获取点输入 CRhinoGetPoint gp; gp.SetCommandPrompt(L选择起点); gp.GetPoint(); if(gp.CommandResult() ! success) return gp.CommandResult(); // 获取数值输入 CRhinoGetNumber gn; gn.SetCommandPrompt(L输入半径); gn.SetDefaultNumber(10.0); gn.GetNumber();输入类型对照表输入类型获取方法典型应用场景点CRhinoGetPoint定位操作数值CRhinoGetNumber参数设置对象选择CRhinoGetObject实体编辑选项切换CRhinoGetOption模式选择3.2 对话框集成对于复杂参数可以集成 MFC 对话框// 对话框调用示例 CMyDialog dialog(CWnd::FromHandle(RhinoApp().MainWnd())); if(dialog.DoModal() ! IDOK) return CRhinoCommand::cancel; // 必须同时支持命令行交互 if(!context.IsInteractive()) { RhinoApp().Print(L使用--optionvalue格式设置参数\n); }最佳实践所有对话框命令都应保留命令行接口方便脚本调用4. 命令注册与生命周期4.1 插件初始化注册命令需要在插件类的 OnLoadPlugIn 中注册CRhinoPlugIn::plugin_load_result CMyPlugIn::OnLoadPlugIn() { // 注册所有命令 theMyCommand.Register(); return CRhinoPlugIn::load_ok; }注册过程会自动处理命令名称本地化帮助文档关联快捷键绑定4.2 运行时状态管理利用成员变量保存命令状态class CMyCommand : public CRhinoCommand { // 持久化变量 double m_tolerance 0.01; // 保存设置自动调用 void SaveProfile(CRhinoProfileContext pc) override { pc.WriteDouble(Ltolerance, m_tolerance); } // 加载设置自动调用 void LoadProfile(CRhinoProfileContext pc) override { pc.ReadDouble(Ltolerance, m_tolerance); } };5. 实战创建交互式拉伸命令下面是一个完整的拉伸命令实现示例// ExtrudeCurveCommand.cpp class CExtrudeCurveCommand : public CRhinoCommand { public: CExtrudeCurveCommand() default; UUID CommandUUID() override { static const GUID id { /* 生成的GUID */ }; return id; } const wchar_t* EnglishCommandName() override { return LExtrudeCurve; } CRhinoCommand::result RunCommand( const CRhinoCommandContext context) override { // 1. 选择曲线 CRhinoGetObject go; go.SetCommandPrompt(L选择要拉伸的曲线); go.SetGeometryFilter(ON::curve_object); go.GetObjects(1, 1); if(go.CommandResult() ! success) return go.CommandResult(); // 2. 获取拉伸方向 CRhinoGetPoint gp; gp.SetCommandPrompt(L指定拉伸方向); gp.SetBasePoint(ON_3dPoint::Origin); gp.DrawLineFromPoint(ON_3dPoint::Origin, TRUE); gp.GetPoint(); if(gp.CommandResult() ! success) return gp.CommandResult(); // 3. 获取拉伸距离 CRhinoGetNumber gn; gn.SetCommandPrompt(L输入拉伸距离); gn.SetDefaultNumber(10.0); gn.GetNumber(); if(gn.CommandResult() ! success) return gn.CommandResult(); // 4. 执行拉伸 ON_3dVector dir gp.Point() - ON_3dPoint::Origin; dir.Unitize(); dir * gn.Number(); ON_Extrusion extrusion; if(extrusion.Create(go.Object(0).Curve(), dir)) { context.m_doc.AddExtrusionObject(extrusion); context.m_doc.Redraw(); return success; } return failure; } }; // 全局命令实例 static class CExtrudeCurveCommand theExtrudeCurveCommand;这个示例演示了曲线选择交互方向矢量指定数值参数输入实际几何体创建文档更新流程6. 调试与优化技巧6.1 调试配置在 Visual Studio 中设置调试参数!-- .vcxproj 文件配置示例 -- PropertyGroup Condition$(Configuration)|$(Platform)Debug|x64 LocalDebuggerCommand$(RhinoExePath)/LocalDebuggerCommand DebuggerFlavorWindowsLocalDebugger/DebuggerFlavor /PropertyGroup6.2 性能优化关键性能指标监控方法// 在命令开始时记录时间 ON_wString timerName LMyCommand; CRhinoProfiler::StartTimer(timerName); // ... 执行命令逻辑 ... // 获取执行时间毫秒 double elapsed CRhinoProfiler::StopTimer(timerName); RhinoApp().Print(L执行耗时: %.2f 毫秒\n, elapsed);常见性能瓶颈频繁的文档锁定/解锁不必要的视图重绘大量小对象的逐个添加复杂的循环计算7. 高级命令特性实现7.1 撤销堆栈支持实现可撤销的操作需要特殊处理// 在修改文档前开始撤销记录 context.m_doc.BeginUndoRecord(L添加拉伸体); // 添加对象自动记录到撤销堆栈 context.m_doc.AddExtrusionObject(extrusion); // 结束记录 context.m_doc.EndUndoRecord();7.2 进度反馈长时间操作应提供进度反馈CRhinoProgress progress(处理中, TRUE); progress.SetProgressRange(0, 100); for(int i0; i100; i) { if(progress.ProgressCancelled()) return cancel; progress.SetProgressValue(i); progress.SetProgressText(L正在处理 %d%%, i); // 执行操作... }8. 命令测试与部署8.1 单元测试框架创建专门的测试命令class CTestMyCommand : public CRhinoCommand { // ... 实现命令接口 ... CRhinoCommand::result RunCommand(...) override { // 自动化测试逻辑 if(!TestNormalCase()) { RhinoApp().Print(L测试用例1失败\n); return failure; } RhinoApp().Print(L所有测试通过\n); return success; } };8.2 部署检查清单发布前验证[ ] 命令UUID唯一性[ ] 本地化名称完整[ ] 帮助文档关联[ ] 撤销操作支持[ ] 进度反馈实现[ ] 错误处理完备[ ] 性能达标在实际项目中我发现最常出现的问题是忘记处理取消操作的情况。一个好的实践是在开发早期就实现完整的取消逻辑这能显著提升用户体验。另外将常用功能封装成辅助函数如输入验证、几何计算等可以大大提高代码复用率和可维护性。
Rhino 插件命令开发实战从 CRhinoCommand 类到 5 个核心成员函数实现在三维设计领域Rhino 以其强大的建模能力和开放的插件体系著称。作为插件开发者掌握命令Command的实现是扩展 Rhino 功能的核心技能。本文将深入解析如何从 CRhinoCommand 类派生子类并完整实现其 5 个关键成员函数带你体验一个交互式命令从诞生到运行的全生命周期。1. 命令开发基础架构每个 Rhino 命令都是一个独立的功能单元通过继承 CRhinoCommand 类实现。以下是典型命令类的骨架结构// 命令类声明应放在.cpp文件中避免多重定义 class CMyCommand : public CRhinoCommand { public: CMyCommand() default; // 构造函数 ~CMyCommand() default; // 析构函数 // 必须实现的5个核心函数 UUID CommandUUID() override; const wchar_t* EnglishCommandName() override; const wchar_t* LocalCommandName() override; CRhinoCommand::result RunCommand(const CRhinoCommandContext context) override; }; // 全局唯一命令实例 static class CMyCommand theMyCommand;关键设计原则每个命令必须有全局唯一标识UUID命令名称需同时提供英文版和本地化版本命令实例必须是全局静态单例运行逻辑集中在 RunCommand 函数中实现2. 核心成员函数实现详解2.1 命令唯一标识CommandUUIDUUID 是命令的身份证必须确保全局唯一。推荐使用 Visual Studio 自带的 GUID 生成工具UUID CMyCommand::CommandUUID() override { // {生成的GUID} static const GUID MyCommand_UUID { 0x12345678, 0x9ABC, 0xDEF0, { 0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0 } }; return MyCommand_UUID; }警告重复的 UUID 会导致命令冲突建议新建命令时立即生成新 GUID2.2 命令名称定义Rhino 支持多语言命令名称至少需要实现英文版本// 英文命令名必须实现 const wchar_t* CMyCommand::EnglishCommandName() override { return LMyCommand; } // 本地化命令名可选 const wchar_t* CMyCommand::LocalCommandName() override { return L我的命令; // 中文示例 }命名规范建议使用动词开头的驼峰命名如 CreateSphere避免特殊字符和空格保持名称简短且有描述性2.3 命令运行逻辑RunCommand这是命令的核心功能实现处典型结构包含三个部分CRhinoCommand::result CMyCommand::RunCommand( const CRhinoCommandContext context) { // 第一部分交互准备 if(context.IsInteractive()) { if(!RhinoApp().AskUserForCommandOptions(...)) return CRhinoCommand::cancel; } // 第二部分主逻辑实现 ON_SimpleArrayON_3dPoint points; if(GetUserInputPoints(context, points) ! success) return CRhinoCommand::failure; // 第三部分结果处理 context.m_doc.AddPointObject(points); context.m_doc.Redraw(); return CRhinoCommand::success; }返回值处理规范返回值类型适用场景success命令成功完成failure输入无效或计算失败cancel用户主动取消操作nothing无实际操作如空选择3. 交互式命令开发技巧3.1 用户输入处理Rhino 提供了丰富的输入获取方法// 获取点输入 CRhinoGetPoint gp; gp.SetCommandPrompt(L选择起点); gp.GetPoint(); if(gp.CommandResult() ! success) return gp.CommandResult(); // 获取数值输入 CRhinoGetNumber gn; gn.SetCommandPrompt(L输入半径); gn.SetDefaultNumber(10.0); gn.GetNumber();输入类型对照表输入类型获取方法典型应用场景点CRhinoGetPoint定位操作数值CRhinoGetNumber参数设置对象选择CRhinoGetObject实体编辑选项切换CRhinoGetOption模式选择3.2 对话框集成对于复杂参数可以集成 MFC 对话框// 对话框调用示例 CMyDialog dialog(CWnd::FromHandle(RhinoApp().MainWnd())); if(dialog.DoModal() ! IDOK) return CRhinoCommand::cancel; // 必须同时支持命令行交互 if(!context.IsInteractive()) { RhinoApp().Print(L使用--optionvalue格式设置参数\n); }最佳实践所有对话框命令都应保留命令行接口方便脚本调用4. 命令注册与生命周期4.1 插件初始化注册命令需要在插件类的 OnLoadPlugIn 中注册CRhinoPlugIn::plugin_load_result CMyPlugIn::OnLoadPlugIn() { // 注册所有命令 theMyCommand.Register(); return CRhinoPlugIn::load_ok; }注册过程会自动处理命令名称本地化帮助文档关联快捷键绑定4.2 运行时状态管理利用成员变量保存命令状态class CMyCommand : public CRhinoCommand { // 持久化变量 double m_tolerance 0.01; // 保存设置自动调用 void SaveProfile(CRhinoProfileContext pc) override { pc.WriteDouble(Ltolerance, m_tolerance); } // 加载设置自动调用 void LoadProfile(CRhinoProfileContext pc) override { pc.ReadDouble(Ltolerance, m_tolerance); } };5. 实战创建交互式拉伸命令下面是一个完整的拉伸命令实现示例// ExtrudeCurveCommand.cpp class CExtrudeCurveCommand : public CRhinoCommand { public: CExtrudeCurveCommand() default; UUID CommandUUID() override { static const GUID id { /* 生成的GUID */ }; return id; } const wchar_t* EnglishCommandName() override { return LExtrudeCurve; } CRhinoCommand::result RunCommand( const CRhinoCommandContext context) override { // 1. 选择曲线 CRhinoGetObject go; go.SetCommandPrompt(L选择要拉伸的曲线); go.SetGeometryFilter(ON::curve_object); go.GetObjects(1, 1); if(go.CommandResult() ! success) return go.CommandResult(); // 2. 获取拉伸方向 CRhinoGetPoint gp; gp.SetCommandPrompt(L指定拉伸方向); gp.SetBasePoint(ON_3dPoint::Origin); gp.DrawLineFromPoint(ON_3dPoint::Origin, TRUE); gp.GetPoint(); if(gp.CommandResult() ! success) return gp.CommandResult(); // 3. 获取拉伸距离 CRhinoGetNumber gn; gn.SetCommandPrompt(L输入拉伸距离); gn.SetDefaultNumber(10.0); gn.GetNumber(); if(gn.CommandResult() ! success) return gn.CommandResult(); // 4. 执行拉伸 ON_3dVector dir gp.Point() - ON_3dPoint::Origin; dir.Unitize(); dir * gn.Number(); ON_Extrusion extrusion; if(extrusion.Create(go.Object(0).Curve(), dir)) { context.m_doc.AddExtrusionObject(extrusion); context.m_doc.Redraw(); return success; } return failure; } }; // 全局命令实例 static class CExtrudeCurveCommand theExtrudeCurveCommand;这个示例演示了曲线选择交互方向矢量指定数值参数输入实际几何体创建文档更新流程6. 调试与优化技巧6.1 调试配置在 Visual Studio 中设置调试参数!-- .vcxproj 文件配置示例 -- PropertyGroup Condition$(Configuration)|$(Platform)Debug|x64 LocalDebuggerCommand$(RhinoExePath)/LocalDebuggerCommand DebuggerFlavorWindowsLocalDebugger/DebuggerFlavor /PropertyGroup6.2 性能优化关键性能指标监控方法// 在命令开始时记录时间 ON_wString timerName LMyCommand; CRhinoProfiler::StartTimer(timerName); // ... 执行命令逻辑 ... // 获取执行时间毫秒 double elapsed CRhinoProfiler::StopTimer(timerName); RhinoApp().Print(L执行耗时: %.2f 毫秒\n, elapsed);常见性能瓶颈频繁的文档锁定/解锁不必要的视图重绘大量小对象的逐个添加复杂的循环计算7. 高级命令特性实现7.1 撤销堆栈支持实现可撤销的操作需要特殊处理// 在修改文档前开始撤销记录 context.m_doc.BeginUndoRecord(L添加拉伸体); // 添加对象自动记录到撤销堆栈 context.m_doc.AddExtrusionObject(extrusion); // 结束记录 context.m_doc.EndUndoRecord();7.2 进度反馈长时间操作应提供进度反馈CRhinoProgress progress(处理中, TRUE); progress.SetProgressRange(0, 100); for(int i0; i100; i) { if(progress.ProgressCancelled()) return cancel; progress.SetProgressValue(i); progress.SetProgressText(L正在处理 %d%%, i); // 执行操作... }8. 命令测试与部署8.1 单元测试框架创建专门的测试命令class CTestMyCommand : public CRhinoCommand { // ... 实现命令接口 ... CRhinoCommand::result RunCommand(...) override { // 自动化测试逻辑 if(!TestNormalCase()) { RhinoApp().Print(L测试用例1失败\n); return failure; } RhinoApp().Print(L所有测试通过\n); return success; } };8.2 部署检查清单发布前验证[ ] 命令UUID唯一性[ ] 本地化名称完整[ ] 帮助文档关联[ ] 撤销操作支持[ ] 进度反馈实现[ ] 错误处理完备[ ] 性能达标在实际项目中我发现最常出现的问题是忘记处理取消操作的情况。一个好的实践是在开发早期就实现完整的取消逻辑这能显著提升用户体验。另外将常用功能封装成辅助函数如输入验证、几何计算等可以大大提高代码复用率和可维护性。
