393 lines
9.5 KiB
Markdown
393 lines
9.5 KiB
Markdown
# 构型 JSON 填写说明
|
||
|
||
本文档给负责构型设计的机械工程师使用。你只需要按照现有 `topology.template.json` 格式创建新的构型 JSON，不需要关心 Python 代码如何实现。
|
||
|
||
构型 JSON 描述的是“这个传动系统由哪些运动构件组成、构件之间有什么机械关系”。它不填写目标速比、齿数、模数、材料、输出路径，也不填写具体三维坐标。
|
||
|
||
## 1. 文件位置和命名
|
||
|
||
每个构型族一个目录：
|
||
|
||
```text
|
||
src/configurations/<family_name>/topology.template.json
|
||
```
|
||
|
||
例子：
|
||
|
||
```text
|
||
src/configurations/simple_2k_h/topology.template.json
|
||
src/configurations/simple_2k_h_cascade/topology.template.json
|
||
```
|
||
|
||
`<family_name>` 用小写英文和下划线，例如：
|
||
|
||
```text
|
||
simple_2k_h
|
||
simple_2k_h_cascade
|
||
compound_planet
|
||
differential_planet
|
||
```
|
||
|
||
## 2. 顶层结构
|
||
|
||
一个构型 JSON 必须包含：
|
||
|
||
```json
|
||
{
|
||
"template_id": "simple_2k_h_v0_1",
|
||
"family": "simple_2k_h",
|
||
"description": "简短描述",
|
||
"nodes": [],
|
||
"relations": []
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 必填 | 怎么填 |
|
||
|---|---:|---|
|
||
| `template_id` | 是 | 模板唯一编号，建议 `<family>_v0_1` |
|
||
| `family` | 是 | 构型族名称，必须和目录名一致 |
|
||
| `description` | 是 | 一句话说明构型，不写公式长文 |
|
||
| `nodes` | 是 | 构件节点列表 |
|
||
| `relations` | 是 | 构件关系列表 |
|
||
|
||
## 3. nodes 怎么填
|
||
|
||
`nodes` 表示构型里有哪些构件或参考对象。
|
||
|
||
节点格式：
|
||
|
||
```json
|
||
{
|
||
"id": "sun",
|
||
"kind": "gear",
|
||
"role": "sun",
|
||
"gear_type": "external",
|
||
"repeat": "single",
|
||
"formula_ref": "nodes.sun",
|
||
"stage_id": null,
|
||
"local_role": "sun"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 必填 | 可选值 / 填法 | 说明 |
|
||
|---|---:|---|---|
|
||
| `id` | 是 | 英文唯一名 | 关系里会用它引用节点 |
|
||
| `kind` | 是 | `gear` / `carrier` / `housing` / `axis` | 节点类型 |
|
||
| `role` | 是 | `sun`、`ring`、`planet`、`carrier` 等 | 机械角色 |
|
||
| `gear_type` | 是 | `external` / `internal` / `null` | 只有齿轮填齿轮类型 |
|
||
| `repeat` | 是 | `single` / `planet_count` | 是否按行星数量展开 |
|
||
| `formula_ref` | 是 | 字符串 | 便于反查来源 |
|
||
| `stage_id` | 否 | `null` 或 `s1`、`s2` | 多级构型可用 |
|
||
| `local_role` | 否 | `sun`、`ring`、`planet` 等 | stage 内局部角色 |
|
||
|
||
### kind 选择
|
||
|
||
| 机械对象 | `kind` |
|
||
|---|---|
|
||
| 太阳轮、齿圈、行星轮 | `gear` |
|
||
| 行星架 | `carrier` |
|
||
| 壳体、机架、固定参考 | `housing` |
|
||
| 主轴线、参考轴 | `axis` |
|
||
|
||
### gear_type 选择
|
||
|
||
| 齿轮 | `gear_type` |
|
||
|---|---|
|
||
| 太阳轮 | `external` |
|
||
| 行星轮 | `external` |
|
||
| 内齿圈 | `internal` |
|
||
| 非齿轮节点 | `null` |
|
||
|
||
### repeat 选择
|
||
|
||
| 情况 | `repeat` |
|
||
|---|---|
|
||
| 只有一个，例如 sun、ring、carrier、housing | `single` |
|
||
| 按行星数量重复，例如 planet | `planet_count` |
|
||
|
||
注意：不要手写 `planet_1`、`planet_2`、`planet_3`。只写一个 `planet` 节点，并设置：
|
||
|
||
```json
|
||
"repeat": "planet_count"
|
||
```
|
||
|
||
程序会自动展开。
|
||
|
||
## 4. relations 怎么填
|
||
|
||
`relations` 表示节点之间有什么机械关系。
|
||
|
||
关系格式：
|
||
|
||
```json
|
||
{
|
||
"id": "sun_planet_external_mesh",
|
||
"source": "sun",
|
||
"target": "planet",
|
||
"relation_type": "external_mesh",
|
||
"carrier_ref": "carrier",
|
||
"mesh_id": "sun_planet",
|
||
"formula_ref": "relations.sun_planet_external_mesh",
|
||
"stage_id": null
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 必填 | 怎么填 |
|
||
|---|---:|---|
|
||
| `id` | 是 | 关系唯一名 |
|
||
| `source` | 是 | 起点 node id |
|
||
| `target` | 是 | 终点 node id |
|
||
| `relation_type` | 是 | 见下表 |
|
||
| `carrier_ref` | 否 | 行星啮合通常填 `carrier` |
|
||
| `mesh_id` | 否 | 同一组啮合的名字 |
|
||
| `formula_ref` | 是 | 便于反查来源 |
|
||
| `stage_id` | 否 | 多级构型可填 stage 标识 |
|
||
|
||
当前允许的 `relation_type`：
|
||
|
||
| relation_type | 含义 | 典型 source -> target |
|
||
|---|---|---|
|
||
| `external_mesh` | 外齿轮与外齿轮啮合 | `sun -> planet` |
|
||
| `internal_mesh` | 内齿圈与外齿轮啮合 | `ring -> planet` |
|
||
| `revolute_joint` | 转动副 | `planet -> carrier` |
|
||
| `coaxial` | 同轴 | `sun -> main_axis` |
|
||
| `fixed` | 固定到壳体或固定参考 | `ring -> housing` |
|
||
| `rigid` | 刚性连接，同速转动 | `s1_carrier -> s2_sun` |
|
||
|
||
## 5. 常见关系填写规则
|
||
|
||
### 外啮合
|
||
|
||
太阳轮和行星轮外啮合：
|
||
|
||
```json
|
||
{
|
||
"id": "sun_planet_external_mesh",
|
||
"source": "sun",
|
||
"target": "planet",
|
||
"relation_type": "external_mesh",
|
||
"carrier_ref": "carrier",
|
||
"mesh_id": "sun_planet",
|
||
"formula_ref": "relations.sun_planet_external_mesh"
|
||
}
|
||
```
|
||
|
||
要点：
|
||
|
||
- `source` 和 `target` 都应该是 `gear_type = external`。
|
||
- 行星机构里要填 `carrier_ref`，表示啮合是在行星架参考系下建立运动方程。
|
||
|
||
### 内啮合
|
||
|
||
内齿圈和行星轮内啮合：
|
||
|
||
```json
|
||
{
|
||
"id": "ring_planet_internal_mesh",
|
||
"source": "ring",
|
||
"target": "planet",
|
||
"relation_type": "internal_mesh",
|
||
"carrier_ref": "carrier",
|
||
"mesh_id": "ring_planet",
|
||
"formula_ref": "relations.ring_planet_internal_mesh"
|
||
}
|
||
```
|
||
|
||
要点：
|
||
|
||
- 内齿圈节点必须是 `gear_type = internal`。
|
||
- 行星轮节点必须是 `gear_type = external`。
|
||
|
||
### 行星轮转动副
|
||
|
||
行星轮绕行星架销轴转动：
|
||
|
||
```json
|
||
{
|
||
"id": "planet_carrier_pin_revolute",
|
||
"source": "planet",
|
||
"target": "carrier",
|
||
"relation_type": "revolute_joint",
|
||
"carrier_ref": "carrier",
|
||
"mesh_id": null,
|
||
"formula_ref": "relations.planet_carrier_pin_revolute"
|
||
}
|
||
```
|
||
|
||
### 同轴
|
||
|
||
太阳轮、齿圈、行星架和主轴同轴：
|
||
|
||
```json
|
||
{
|
||
"id": "sun_main_axis_coaxial",
|
||
"source": "sun",
|
||
"target": "main_axis",
|
||
"relation_type": "coaxial",
|
||
"carrier_ref": null,
|
||
"mesh_id": null,
|
||
"formula_ref": "relations.sun_main_axis_coaxial"
|
||
}
|
||
```
|
||
|
||
通常至少要写：
|
||
|
||
```text
|
||
sun -> main_axis
|
||
ring -> main_axis
|
||
carrier -> main_axis
|
||
```
|
||
|
||
### 固定
|
||
|
||
齿圈固定到壳体：
|
||
|
||
```json
|
||
{
|
||
"id": "ring_housing_fixed",
|
||
"source": "ring",
|
||
"target": "housing",
|
||
"relation_type": "fixed",
|
||
"carrier_ref": null,
|
||
"mesh_id": null,
|
||
"formula_ref": "relations.ring_housing_fixed"
|
||
}
|
||
```
|
||
|
||
注意：实际哪个构件固定，还会受 requirement 的 `fixed` 字段影响。单级边界变体中，如果 requirement 写 `fixed = sun`，运行时会把 fixed 关系改成 sun 固定到 housing。
|
||
|
||
### 刚性连接
|
||
|
||
两级串联中，前一级输出和后一级输入刚性连接：
|
||
|
||
```json
|
||
{
|
||
"id": "stage_output_to_next_input_rigid",
|
||
"source": "stage_carrier",
|
||
"target": "stage_sun",
|
||
"relation_type": "rigid",
|
||
"carrier_ref": null,
|
||
"mesh_id": null,
|
||
"formula_ref": "cascade.relations.output_to_next_input",
|
||
"stage_id": "cascade"
|
||
}
|
||
```
|
||
|
||
要点：
|
||
|
||
- `rigid` 表示两个运动构件角速度相同。
|
||
- 多级构型里通常由程序根据 stage 生成真实组件名，例如 `s1_carrier -> s2_sun`。
|
||
|
||
## 6. 单级 simple_2k_h 示例
|
||
|
||
这是最常见结构：
|
||
|
||
```text
|
||
sun 输入
|
||
ring 固定
|
||
carrier 输出
|
||
planet 均布
|
||
```
|
||
|
||
必须包含节点：
|
||
|
||
```text
|
||
sun: external gear, single
|
||
planet: external gear, planet_count
|
||
ring: internal gear, single
|
||
carrier: carrier, single
|
||
housing: housing, single
|
||
main_axis: axis, single
|
||
```
|
||
|
||
必须包含关系：
|
||
|
||
```text
|
||
sun --external_mesh--> planet
|
||
ring --internal_mesh--> planet
|
||
planet --revolute_joint--> carrier
|
||
sun/ring/carrier --coaxial--> main_axis
|
||
ring --fixed--> housing
|
||
```
|
||
|
||
对应文件参考：
|
||
|
||
```text
|
||
src/configurations/simple_2k_h/topology.template.json
|
||
```
|
||
|
||
## 7. 两级串联 simple_2k_h_cascade 示例
|
||
|
||
两级串联可以理解为：
|
||
|
||
```text
|
||
s1 是一个 simple_2k_h
|
||
s2 是一个 simple_2k_h
|
||
s1.output 刚性连接到 s2.input
|
||
```
|
||
|
||
模板里使用 `stage_sun/stage_planet/stage_ring/stage_carrier` 表示“每一级的局部节点”。程序会展开成：
|
||
|
||
```text
|
||
s1_sun / s1_ring / s1_planet_1..n / s1_carrier
|
||
s2_sun / s2_ring / s2_planet_1..n / s2_carrier
|
||
```
|
||
|
||
对应文件参考：
|
||
|
||
```text
|
||
src/configurations/simple_2k_h_cascade/topology.template.json
|
||
```
|
||
|
||
## 8. 填写检查清单
|
||
|
||
提交新的构型 JSON 前，逐项检查：
|
||
|
||
- `template_id` 唯一。
|
||
- `family` 和目录名一致。
|
||
- 每个 `relation.source`、`relation.target` 都能在 `nodes.id` 中找到。
|
||
- 齿轮节点的 `gear_type` 正确。
|
||
- 非齿轮节点的 `gear_type` 是 `null`。
|
||
- 需要重复的行星轮只写一个节点，并设置 `repeat = planet_count`。
|
||
- 每组行星啮合关系都填写了正确的 `carrier_ref`。
|
||
- 主运动构件都和 `main_axis` 有 `coaxial` 关系。
|
||
- 固定关系使用 `fixed`。
|
||
- 级间或同轴齿轮组刚性连接使用 `rigid`。
|
||
- 没有使用未注册的 `relation_type`。
|
||
- 没有在 topology JSON 中填写齿数、模数、速比、坐标、材料或输出路径。
|
||
|
||
## 9. 不应该写进构型 JSON 的内容
|
||
|
||
以下内容不要写进 `topology.template.json`：
|
||
|
||
- `target_ratio`
|
||
- `z_sun`、`z_planet`、`z_ring`
|
||
- `module_mm`
|
||
- `planet_count_candidates`
|
||
- `face_width_mm`
|
||
- `center_xyz_mm`
|
||
- `axis_xyz`
|
||
- STEP 文件路径
|
||
- 材料、颜色、轴承型号
|
||
- validation report 结果
|
||
|
||
这些属于 requirement、参数求解、placement、CAD 或验证输出，不属于构型模板。
|
||
|
||
## 10. 常见错误
|
||
|
||
| 错误 | 后果 |
|
||
|---|---|
|
||
| 忘记写 `carrier_ref` | 行星啮合运动方程无法正确使用行星架参考系 |
|
||
| 把 `planet_1/planet_2/planet_3` 写进模板 | runtime 无法按候选行星数自动展开 |
|
||
| 内齿圈写成 `external` | 内啮合验证失败 |
|
||
| 非齿轮节点 `gear_type` 没写 `null` | schema 或验证失败 |
|
||
| 使用未注册 relation type | 验证器会报 unsupported relation type |
|
||
| 在 topology 中写齿数和模数 | 构型和参数耦合，无法复用 |
|
||
|