modulor

Modulor

エージェントネイティブな2D製図＋3Dモデリングカーネル。GUIもマウスも不要——JSONを入力すれば、ジオメトリが出力されます。

English: Modulor is an agent-native 2D drafting + 3D modeling kernel — the geometry layer for the agent era. No GUI: the entire tool is a self-describing JSON op protocol (77 ops, contract-tested) over a plain-JSON document format, callable via CLI, JSON-Lines pipe, MCP server or Python. Parametric recipes, architectural semantics, freeform surfaces, DXF/glTF interop, a built-in verification loop (measure / validate / render-and-see), and a conformance checker for the format. Agents read AGENT_GUIDE.md; the API contract lives in docs/API.md; the file format spec in docs/FORMAT.md. Named after Le Corbusier's Modulor — a universal measure for building, this time for machines.

従来のCADソフトウェアは、人間の目と手のために設計されています。メニュー、ビューポート、スナップ、ショートカットキー。エージェントがこれらを操作するには、人間の操作を模倣するか、重厚なプラグイン層を経由する必要があります。 Modulorは逆のアプローチを取ります。CADのジオメトリカーネルを残し、インタラクション層を丸ごとエージェントの母語に置き換えます——構造化されたコマンド、構造化された結果、構造化されたエラー、そして「レンダリングして画像にし、自分の目で検証する」フィードバックループです。

                ┌─────────────────────────────────────────┐
   Agent ──────▶│  CLI batch │ CLI pipe │ MCP │ Python API │
                └──────────────────┬──────────────────────┘
                                   ▼
                       JSON 命令（自描述 op 协议）
                                   ▼
                ┌─────────────────────────────────────────┐
                │  几何内核：manifold3d (Clipper2 + Manifold) │
                │  2D/3D 布尔 · 偏移 · 拉伸 · 旋转体 · 切片    │
                └──────────────────┬──────────────────────┘
                                   ▼
        .json 文档 · SVG · DXF · PNG 渲染 · OBJ / STL / GLB

コア機能（77の自己記述型オペレーション、インターフェースは1.0-rcで凍結済み）

拡張エコシステム：ドメイン機能は拡張パッケージに収められています。拡張をインストールすると、mech.gear インボリュート歯車（公式テンプレート）を利用できます。 30行のコードで独自の拡張を作成でき、名前空間とAPIの法的要件は仕組みによって強制されます。詳しくはdocs/PLUGINS.mdをご覧ください。

アイデンティティとガバナンス：プロジェクト名／パッケージ名／CLI／フォーマット識別子は正式に凍結済みです。Standard（仕様。サードパーティによる実装向け）とCore（参照実装。標準的ではありますが、排他的ではありません）の境界、semverと互換性ポリシー、RFCプロセスについてはGOVERNANCE.mdをご覧ください。

標準の2つの要素はどちらも文書化され、テストで保護されています。opプロトコル——docs/API.md（レジストリから生成）と機械可読な契約docs/api.json。実装と契約が一致しない場合、テストは失敗します。ドキュメント形式——docs/FORMAT.mdの仕様とdocs/document.schema.json（JSON Schema）。すべてのサンプルドキュメントはCIでスキーマに照らして検証されます。

主要CADとの相互運用性は契約で保証されています（docs/INTEROP.md）。 DXFはR2000のネイティブオブジェクト（ELLIPSE／SPLINE／HATCH／関連付けられたDIMENSION／BLOCK+INSERT）としてエクスポートされ、AutoCADでそのまま編集できます。インポート時にはブロック構造が保持されます。すべてのエクスポートファイルはCIでezdxf（DXF）とifcopenshell（IFC4）によるセマンティックレベルの検証を受けます。

• パラメトリック（ドキュメント＝データ＋レシピ）：あらゆる数値フィールドで式を使用できます（"bay*3"、"level_top('L2')"、"grid_x('B')"）。recipe_set は生成コマンドを設計意図としてドキュメントに保存します。set_param と regenerate を使えば、1つのコマンドでモデル全体を連動して再構築できます——「柱間隔を4mから5mに変更し、ほかは連動させたままにする」には、この2つの呼び出しだけで十分です。

• 建築セマンティクス：軸グリッドのadd_grid（平面図に通り芯と番号バブルを描画し、交点は式で参照可能）、標高のadd_level、部屋のadd_room（平面図に名称と面積m²を自動表示）、面積レポートのprogram（名称／標高／タイプ別に集計）、勾配屋根のadd_roof（平屋根／片流れ／切妻）、階段のadd_stair（快適性の公式2R+T=630に基づいて段を自動配置）、カーテンウォールのadd_facade

• 案の反復：snapshot／restoreによるスナップショット、2つの案を比較するdiff（パラメーターの変更、エンティティの追加・削除・変更、体積・面積の増減）。レシピを使えば、設計意図を案をまたいで引き継げます

• 2D製図：線／ポリライン／スプライン曲線／円／円弧／矩形／文字、長さ・角度・半径寸法（自動計測）、フィレット／面取り、レイヤー、2Dブーリアン、オフセット

• 建築壁：中心線から壁を作図（直線、閉じたループ、スプライン曲線の壁）。壁に沿った距離でドアや窓の開口部を配置し、平面図には二重線と開閉線を描画、3Dでは自動でソリッド化

• 3Dモデリング：ボリューム／円柱／球／押し出し（ねじり、テーパー）／回転体／堅牢な3Dブーリアン（Manifoldカーネルにより、破綻した面は生成されません）／スライス／平面図・立面図への投影／シェル化

• 自由形状（エージェントの得意分野）：断面ロフトloft（縦方向にスプライン補間して滑らかな曲面を生成）、空間パスに沿ったスイープsweep、自由変形deform（ねじり／円錐化／曲げ）、陰関数曲面add_implicit（数式で形状を彫刻し、smin／smaxで滑らかに融合）、メッシュ平滑化smooth——ザハ級の異形形状表現を、すべてJSONコマンドで実現

• 変換：移動／複製／回転／スケーリング／ミラー／グリッド・円形配列。2D／3Dの両方に対応

• フィードバックループ：measure／validate／空間検索find／render labels=trueでエンティティIDを画像に表示／snapshot・restoreによるドキュメントのスナップショット

• 相互運用：SVG・DXF・OBJ・STL・GLB（PBR）・IFC4セマンティックBIMにエクスポート（壁には実際の開口部を含み、標高／軸グリッド／部屋の面積を計測。Revit／Archicadでそのまま開けます）。DXFのインポートにも対応（LINE／CIRCLE／ARC／POLYLINE（円弧セグメントを含む）／TEXT／MTEXT／SPLINE／ELLIPSE＋レイヤーの色。非対応タイプは件数をレポートし、決して黙って破棄しません）——エージェントは人間が作成した既存の図面を引き継げます

• レンダリング：純粋なNumPyソフトウェアラスタライザーで、平面図PNGと3DシェーディングPNG（特徴エッジ＋座標軸）を生成します。マルチモーダルエージェントは自分で作成したモデルを直接「見る」ことができます——MCPのcad_renderは画像を直接返します

• リアルタイムビューア：modulor serveで厳密に読み取り専用のブラウザーウィンドウを起動します（2D平面図＋WebGL 3Dオービットビュー＋レイヤー切り替え＋ワンクリックダウンロード）。ドキュメントファイルを監視し、どのエージェントがどの経路でドキュメントを変更しても、ページは自動的に更新されます——人間が見て、エージェントが作業します

インストール

pip install modulor          # 内核依赖仅 numpy + manifold3d
pip install modulor[check]   # 可选：格式一致性校验（modulor check --strict）

開発用インストール：このリポジトリをクローンしてからpip install -e .[dev]を実行します。すべてのテストを実行するには、pytest testsを実行します。

60 秒上手

modulor ops                      # 看所有命令（自描述，无需读文档）
modulor ops add_wall             # 看单个命令的参数/默认值/示例

echo [{"op":"add_box","size":[100,60,40]},{"op":"render","path":"a.png"}] > s.json
modulor run model.json s.json    # 批量执行（原子性：失败则不落盘）

modulor repl model.json          # 长会话：一行 JSON 进，一行 JSON 出
modulor mcp                      # MCP stdio 服务器
modulor serve model.json         # 只读查看器：浏览器实时跟随文档变化

查看器：左 2D 平面（滚轮缩放/拖拽平移），右 WebGL 3D（轨道相机）， 底部图层开关，顶部 SVG/DXF/GLB/STL 下载。零前端依赖，单文件 HTML，离线可用。

MCP 客户端配置（如 Claude Code）：

{"mcpServers": {"modulor": {"command": "modulor", "args": ["mcp"]}}}

接入你的 Agent：integrations/ 提供即插即用包——Claude Code skill、Cursor 规则、Codex AGENTS 片段、OpenAI 兼容工具定义（GPT/Kimi/通义/DeepSeek 直接加载）、LangChain/AutoGen/CrewAI 集成、中文接入说明、以及 8 个 CI 实测的命令配方（COOKBOOK）。

示例

modulor run out\studio.json examples\floorplan.json —— 户型图： 闭合外墙环 + 隔墙 + 4 门窗 + 标注链 + 房间标签 → SVG/DXF/PNG → 一键长成 3D（含楼板）→ GLB。

modulor run out\bracket.json examples\bracket.json —— 机械零件： 偏移做圆角板 + 孔阵列 + 腰形槽（2D 布尔）→ 拉伸 → 凸台镗孔（3D 布尔）→ 体积测量 → STL/GLB/OBJ + 剖面 DXF。

modulor run out\zaha.json examples\zaha.json —— 异形建筑： 三断面样条放样出流线塔楼（loft+twist）+ 飘带天蓬（sweep）+ 样条曲线墙 + 隐式曲面融合展亭（add_implicit smin）→ GLB。

modulor run out\param.json examples\parametric.json --as-recipe —— 参数化建筑：5 个参数驱动轴网/标高/柱阵/楼板/幕墙/坡屋顶/楼梯/房间； 之后 {"op":"regenerate","params":{"bay":5000,"floors":4}} 一条命令， 整栋楼重新协调（OFFICE 面积 76.8m² → 120m²，diff 给出完整对比报告）。

建筑平面（双线墙、门扇、标注链）	机械零件（2D/3D 布尔）	异形建筑（放样/扫掠/隐式曲面）

参数化联动——同一份配方，{"op":"regenerate","params":{"bay":5000,"floors":4}} 一条命令重建整楼：

bay=4000 · 3 层	bay=5000 · 4 层（regenerate 之后）

城市体块（分区/裙房塔楼/扭转地标）

规模参考（scripts/bench.py，20 层塔楼 401 条命令）：构建 0.08s、 文档 0.04MB（墙体参数化存储）、着色渲染 2.2s、GLB 导出 0.05s。

设计原则（Agent-native 的含义）

1. 命令即 API，API 即文档：每个 op 自带参数 schema、默认值与示例， help 一个调用拿全；参数拼错会收到 "did you mean ..." 。
2. 一切皆可验证：建完就能 measure、validate、render——Agent 不必 盲信自己的输出。
3. 原子批处理：批量命令要么全部成功落盘，要么报出第几条错在哪，文档不脏。
4. 用标签不用坐标 id：布尔运算会消耗实体，tag 让选择器稳定。
5. 文档就是纯 JSON：可 diff、可入库、可手改，没有二进制黑盒。

项目结构

modulor/
  document.py    文档模型（图层/材质/实体/选择器/序列化）
  engine.py      批处理执行器（原子性、结构化错误）
  geometry.py    向量/仿射/弧离散化/墙体轮廓偏移
  shapes.py      实体 <-> 几何内核（CrossSection/Manifold）桥
  ops/           全部操作：绘图、建模、参数化、建筑语义、变换、查询、导出
  exporters/     SVG · DXF · OBJ · STL · GLB（全部手写，零重依赖）
  render/        软件光栅器、笔画字体、2D/3D 渲染
  cli.py         run / op / repl / ops / new / info / serve / mcp
  mcp_server.py  MCP stdio 服务器（手写 JSON-RPC，无 SDK 依赖）
  viewer/        只读实时查看器（stdlib HTTP + 单文件 HTML + 自写 WebGL）
tests/           行为 + 契约 + 模糊测试（pytest）
examples/        户型图与机械零件全流程脚本
AGENT_GUIDE.md   给 Agent 看的完整使用指南

License

MIT

---

mcp-name: io.github.bcllcc/modulor