# Planetary Reducer System Demo

## 简介

这是一个面向行星减速器和关节模组的公式化设计、生成与验证 demo。系统从 `input/` 中的需求 JSON 出发，先建立构型图，再枚举并求解齿轮参数，随后用图驱动运动学方程验证传动比和转向，最后调用 SimpleCADAPI 真实生成 STEP/model/session，并用读回的装配数据、统一 `PlacementSolver` 位姿计划和 OCP/PythonOCC 几何检测生成验证报告。

当前主要支持单级 `simple_2k_h`、两级串联 `simple_2k_h_cascade`、`ferguson_wolfrom` 独立减速器，以及基于电机 STEP 和外壳资产的关节模组装配。关节模组当前只支持同轴输入/输出接口的 `simple_2k_h` 和 `simple_2k_h_cascade`；`ferguson_wolfrom` 的输入位于偏心行星销轴区域，暂不适配当前同轴电机和外壳接口。项目刻意区分输入、输出和过程文档：所有源需求和外部资产放在 `input/`，所有生成结果只进入 `output/`，说明文档和阶段报告放在 `progress/`。如果 CAD 或 OCP 环境不可用，生成和验证会真实失败并输出错误，不生成假 STEP 或假验证报告。

This project formalizes, solves, generates, and validates planetary reducers and
joint modules with real parameter solving, real kinematics, real CAD generation,
and real geometry checks.

## Project Layout

```text
input/      user requirements and source assets
output/     generated run outputs only
progress/   documents, reports, and working notes
src/        implementation
tests/      regression tests
```

Reducer configurations live under:

```text
src/planetary_reducer/configurations/
```

Reducer-internal component poses are solved by:

```text
src/planetary_reducer/placement/
```

- `src/models.py`：定义系统中所有核心数据模型。
- `src/cli.py`：命令行入口，负责 `run`、`joint-run`、`auto-joint-run` 等流程。
- `src/configurations/`：集中管理减速器构型，比如单级和两级串联。
- `src/placement/`：统一计算各零件的三维位置和姿态。
- `src/parameter_solver.py`：根据需求枚举并求解齿数、模数、行星数量等参数。
- `src/kinematics.py`：根据构型图建立运动方程，验证传动比和转向。
- `src/cad/`：调用 SimpleCADAPI 生成真实 STEP、model.json 和装配 manifest。
- `src/validators.py`：总验证入口，统一执行公式、运动学、装配、位姿和几何检查。
- `src/relation_validators/`：验证构型图中的啮合、转动副、固定、刚性和同轴关系。
- `src/physical_validators/`：验证工业装配中的轴承、销轴、螺栓、配合和间隙关系。
- `src/joint_module/`：生成并验证由电机、外壳和行星减速器组成的完整关节模组。

## CLI

Run a reducer:

```bash
PYTHONPATH=src \
/Users/lk/miniconda3/bin/python -m planetary_reducer.cli run \
  --input input/requirements/reducers/simple_2k_h/simple_2kh_industrial_ratio_7p5_spur.json \
  --output output/runs/industrial_ratio_7p5_spur
```

Run a joint module:

```bash
PYTHONPATH=src \
/Users/lk/miniconda3/bin/python -m planetary_reducer.cli joint-run \
  --input input/requirements/joint_modules/3500_motor_housing.json \
  --output output/runs/joint_3500_motor_housing
```

Auto-design a joint module from motor STEP and housing Python:

```bash
PYTHONPATH=src \
/Users/lk/miniconda3/bin/python -m planetary_reducer.cli auto-joint-run \
  --motor-step input/assets/motors/3500_motor_part2.step \
  --housing-python input/assets/housings/gear_housing.py \
  --output output/runs/auto_joint_3500
```

The CLI intentionally accepts `--input` only under `input/` and `--output` only
under `output/`.

List all formula-driven CAD part generators copied from SimpleCADAPI:

```bash
PYTHONPATH=src \
/Users/lk/miniconda3/bin/python -m planetary_reducer.cli list-parts
```

Generate one standalone parametric part:

```bash
PYTHONPATH=src \
/Users/lk/miniconda3/bin/python -m planetary_reducer.cli generate-part \
  --part roller_chain_sprocket \
  --parameters '{"n_teeth": 12, "chain_pitch": 6.35, "roller_diameter": 3.3, "sprocket_thickness": 3.0, "bore_radius": 1.2}' \
  --output output/runs/parts/roller_chain_sprocket
```

## Run Output

Reducer runs use:

```text
output/runs/<run>/
  input_snapshot/
  formula/
  kinematics/
  placement/
  cad/
  validation/
  exports/
```

Important files include:

```text
formula/formula_instance.json
kinematics/kinematic_solution.json
placement/placement_plan.json
cad/reducer.step
cad/assembly_manifest.json
validation/validation_report.json
```

`placement/placement_plan.json` is the reducer-internal pose source of truth.
`assembly_manifest.json` must match it.