====== 01 概念与架构 ======

===== RhinoCompute 是什么 =====

RhinoCompute 可以理解为“把 Rhino 的几何引擎放到 Web 服务后面”。客户端通过 HTTP 或 HTTPS 发送请求，服务端在无界面的 Rhino/Rhino.Inside 环境中执行几何计算、Grasshopper 求解或扩展端点逻辑，然后把 JSON 结果返回给客户端。

它适合以下场景：

  * Web 应用需要生成或分析 Rhino 几何，但浏览器本身无法运行完整 RhinoCommon。
  * 团队希望把 Grasshopper 定义集中放在服务器上，由多个客户端复用。
  * 需要并行处理多个几何任务，或者不希望长耗时求解阻塞 Rhino/Grasshopper 主界面。
  * 需要把 Rhino 几何能力接入自动化流程、后台服务、报价系统、参数化设计平台。

===== 关键名词 =====

^ 名词 ^ 作用 ^
| RhinoCommon | Rhino 的 .NET SDK。完整 Rhino 环境内可用，包含大量几何、文档、命令和插件能力。 |
| rhino3dm | 基于 openNURBS 的轻量库，用于读写 3dm 和构造基础几何。它不包含所有 RhinoCommon 运算。 |
| Rhino.Inside | 允许 Rhino 在另一个 64 位进程内运行的技术。Compute 依赖它启动无界面的 Rhino。 |
| compute.geometry | 实际执行几何和 Grasshopper 求解的 REST 服务。 |
| rhino.compute | 对外入口和服务管理层，负责认证、反向代理、子进程、超时、空闲关闭等。 |
| Hops | Grasshopper 客户端组件，用来把外部 Grasshopper 定义当成“函数”调用。 |
| Core-Hour Billing | 在 Windows Server 或 Linux Server 上运行 Compute 时使用的核心小时计费模型。 |

===== 两层服务结构 =====

官方本地调试文档和当前源码都把 Compute 拆成两个核心工程：

  * ''compute.geometry'' 暴露 REST API，负责 Rhino 几何计算、Grasshopper 定义求解、自定义 Compute 端点。
  * ''rhino.compute'' 是更高层入口，负责接收客户端请求、认证、启动多个 ''compute.geometry'' 子进程、转发请求、控制空闲关闭。

典型请求链如下：

<code>
客户端 / Hops
  |
  | HTTP POST + RhinoComputeKey
  v
rhino.compute
  |
  | 认证、路由、选择子进程、反向代理
  v
compute.geometry 子进程
  |
  | Rhino.Inside 启动无界面 Rhino
  | RhinoCommon / Grasshopper / 插件逻辑
  v
JSON 结果
</code>

===== 端点类型 =====

Compute 的端点可分为三类：

  * 健康和诊断端点：例如 ''/version''、''/healthcheck''、''/activechildren''、''/sdk''。
  * RhinoCommon 风格端点：客户端库把方法调用序列化成 HTTP 请求。
  * Grasshopper/Resthopper 端点：接收 Grasshopper 定义和输入树，返回输出树。
  * 自定义端点：Rhino 插件通过 ''RegisterComputeEndPoint'' 注册静态方法。

===== Compute 与 Hops 的区别 =====

RhinoCompute 是服务端。Hops 是 Grasshopper 里的客户端组件。

Hops 会读取另一个 Grasshopper 文件或 REST 端点的输入输出定义，把它表现成当前画布上的一个组件。求解时，Hops 把输入发送给本地或远程 Compute；Compute 在无界面的 Rhino/Grasshopper 环境里求解后返回结果。

这意味着：

  * 只想从 Web、Python、JavaScript、C# 调 Rhino 几何能力，用 Compute 客户端库即可。
  * 想在 Grasshopper 内复用外部定义、拆分复杂画布、远程并行求解，用 Hops。
  * Hops 本身不是服务器，Hops 背后仍然需要 RhinoCompute 或 ghhops_server 这类服务来执行。

===== 无状态请求模型 =====

Compute 更适合“输入一批几何/参数，输出一批结果”的无状态任务。每个请求都应尽量自包含：

  * 不依赖服务器上某个长期打开的 Rhino 文档状态。
  * 不把用户会话状态藏在 Grasshopper 定义之外。
  * 大文件和共享资源要有明确路径、URL、缓存策略和权限边界。

如果业务必须维护会话状态，建议在 Compute 外层应用服务中管理，例如数据库、对象存储、任务队列、用户会话，再把单次几何计算请求交给 Compute。

===== 生产架构示例 =====

<code>
浏览器 / CAD 平台 / 后台任务
  |
  v
业务 API 服务
  |  负责用户、权限、任务、文件、数据库
  v
RhinoCompute 服务
  |  负责 Rhino/Grasshopper 几何求解
  v
对象存储 / 数据库 / 日志监控
</code>

不要把 Compute 当成完整业务后端。它更像几何计算执行器。业务认证、文件上传、队列、重试、审计、限流、租户隔离，应由外层服务承担。

===== 本章检查点 =====

  * 你是否能说明 ''rhino.compute'' 和 ''compute.geometry'' 的区别？
  * 你是否知道 Hops 是客户端组件，不是服务端？
  * 你是否能判断一个任务是否适合无状态 Compute 调用？

===== 参考资料 =====

  * [[https://developer.rhino3d.com/guides/compute/compute-faq/|Compute FAQ]]
  * [[https://developer.rhino3d.com/en/guides/compute/development/|Running and Debugging Compute Locally]]
  * [[https://developer.rhino3d.com/guides/compute/hops-component/|The Hops Component]]