114 lines
2.6 KiB
Markdown
114 lines
2.6 KiB
Markdown
# Topology JSON Authoring Guide
|
||
|
||
这份说明给只负责创建构型 JSON 的机械工程师使用。构型 JSON 只描述机械构件和关系，不填写齿数、模数、目标速比、三维坐标或输出文件。
|
||
|
||
## 文件位置
|
||
|
||
```text
|
||
src/configurations/<family_name>/topology.template.json
|
||
```
|
||
|
||
`family_name` 必须和 JSON 顶层 `family` 一致。
|
||
|
||
## 顶层字段
|
||
|
||
```json
|
||
{
|
||
"template_id": "<family>_v0_1",
|
||
"family": "<family>",
|
||
"description": "one sentence",
|
||
"nodes": [],
|
||
"relations": []
|
||
}
|
||
```
|
||
|
||
## node 字段
|
||
|
||
每个 node 表示一个构件或参考对象：
|
||
|
||
```json
|
||
{
|
||
"id": "sun",
|
||
"kind": "gear",
|
||
"role": "sun",
|
||
"gear_type": "external",
|
||
"repeat": "single",
|
||
"formula_ref": "nodes.sun",
|
||
"stage_id": null,
|
||
"local_role": "sun"
|
||
}
|
||
```
|
||
|
||
填写规则：
|
||
|
||
- `kind`: `gear`、`carrier`、`housing`、`axis`
|
||
- `gear_type`: 外齿轮填 `external`，内齿圈填 `internal`，非齿轮填 `null`
|
||
- `repeat`: 单个构件填 `single`，按行星数量重复的行星轮填 `planet_count`
|
||
- `stage_id/local_role`: 多级构型用于表达级内角色；单级可以省略或填 `null`
|
||
|
||
不要在模板里手写 `planet_1..planet_n`。只写一个 `planet`，并设置 `repeat = planet_count`。
|
||
|
||
## relation 字段
|
||
|
||
每个 relation 表示构件之间的机械关系：
|
||
|
||
```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
|
||
}
|
||
```
|
||
|
||
允许的 `relation_type`：
|
||
|
||
```text
|
||
external_mesh
|
||
internal_mesh
|
||
revolute_joint
|
||
coaxial
|
||
fixed
|
||
rigid
|
||
```
|
||
|
||
常用关系：
|
||
|
||
- `sun --external_mesh--> planet`，`carrier_ref = carrier`
|
||
- `ring --internal_mesh--> planet`，`carrier_ref = carrier`
|
||
- `planet --revolute_joint--> carrier`
|
||
- `sun/ring/carrier --coaxial--> main_axis`
|
||
- `ring --fixed--> housing`
|
||
- `s1_output --rigid--> s2_input`
|
||
|
||
## 不要填写的内容
|
||
|
||
不要在 topology JSON 中填写：
|
||
|
||
- 目标速比
|
||
- 齿数
|
||
- 模数
|
||
- 行星数量候选
|
||
- 坐标和轴线
|
||
- STEP 路径
|
||
- 材料和颜色
|
||
- 验证结果
|
||
|
||
这些内容分别属于 requirement、参数求解、PlacementPlan、CAD 输出和 validation report。
|
||
|
||
## 提交前检查
|
||
|
||
- `template_id` 唯一。
|
||
- `family` 和目录名一致。
|
||
- 所有 relation 的 `source/target/carrier_ref` 都能在 nodes 中找到。
|
||
- 齿轮 `gear_type` 正确。
|
||
- 行星轮使用 `repeat = planet_count`。
|
||
- 行星啮合填写了 `carrier_ref`。
|
||
- 所有主运动构件都有 `coaxial` 到 `main_axis`。
|
||
- 固定关系用 `fixed`，刚性连接用 `rigid`。
|
||
- 没有使用未注册 relation type。
|