Metadata-Version: 2.4
Name: cad-spec-gen
Version: 2.0.0
Summary: CAD pipeline skill: design doc → structured spec → code generation → 3D renders → photorealistic images
Project-URL: Homepage, https://github.com/proecheng/cad-spec-gen
Project-URL: Repository, https://github.com/proecheng/cad-spec-gen
Author: proecheng
License-Expression: MIT
License-File: LICENSE
Keywords: ai-skill,blender,cad,cadquery,mechanical-design,pipeline
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.0
Provides-Extra: all
Requires-Dist: cadquery>=2.0; extra == 'all'
Requires-Dist: ezdxf>=0.18; extra == 'all'
Requires-Dist: matplotlib>=3.5; extra == 'all'
Requires-Dist: pillow>=9.0; extra == 'all'
Provides-Extra: cad
Requires-Dist: cadquery>=2.0; extra == 'cad'
Requires-Dist: ezdxf>=0.18; extra == 'cad'
Provides-Extra: render
Requires-Dist: matplotlib>=3.5; extra == 'render'
Requires-Dist: pillow>=9.0; extra == 'render'
Description-Content-Type: text/markdown

# CAD Spec Generator — Universal AI Skill for CAD Pipelines

> **From Markdown to machining-ready drawings and photorealistic renders — powered by any LLM.**

A **cross-platform AI skill** for the complete CAD pipeline. Works with Claude Code, GPT-4, GLM-4, Qwen, LangChain, AutoGen, Dify — or any LLM with shell execution. One skill gives your AI agent the ability to: extract specs from design docs, generate GB/T-compliant 2D drawings, produce geometrically accurate 3D renders, and create photorealistic presentation images.

## Installation

### From PyPI (Recommended)

```bash
pip install cad-spec-gen
cad-skill-setup
```

The interactive wizard guides you through:
1. Language selection (中文 / English)
2. Environment detection (Python, CadQuery, ezdxf, Blender, etc.)
3. Optional dependency installation
4. Blender configuration
5. Pipeline config generation
6. Skill file registration

Non-interactive mode: `cad-skill-setup --lang en --target . --skip-deps`

Check environment: `cad-skill-check`

After installation, type `/cad-help` in Claude Code to get started.

### Update

```bash
pip install --upgrade cad-spec-gen
cad-skill-setup --update
```

### Other Platforms

| Platform | How to Install |
|----------|---------------|
| **Any LLM + Shell** | Paste [`system_prompt.md`](system_prompt.md) as system message |
| **GPT-4 / Assistants** | Upload `system_prompt.md` + enable Code Interpreter ([guide](adapters/openai/README.md)) |
| **LangChain / AutoGen** | `from adapters.langchain.tools import cad_tools` ([guide](adapters/langchain/README.md)) |
| **Dify / Coze** | Import `system_prompt.md` to knowledge base ([guide](adapters/dify/README.md)) |

All tools are **plain Python CLI scripts** — no framework lock-in, no vendor dependency.

```
Design Document (.md)
    ↓ cad_spec_gen.py --review — mechanical / assembly / material / completeness checks
DESIGN_REVIEW.md (issues & recommendations, user iterates or proceeds)
    ↓ cad_spec_gen.py — extract 9 categories of structured data
CAD_SPEC.md (single source of truth for all downstream CAD work)
    ↓ codegen/gen_*.py — Jinja2 templates → CadQuery scaffolds
params.py + build_all.py + station_*.py + std_*.py + assembly.py
    ↓ CadQuery parametric modeling
STEP + STD-STEP (standard parts) + DXF (GB/T 2D drawings) + GLB
    ↓ Blender Cycles rendering (GPU auto-detect, CPU fallback)
N-view PNG — 100% geometry-accurate, cross-view consistent (default 5, configurable)
    ↓ AI enhancement (reskin only, geometry locked)
Photorealistic JPG — presentation / defense / business plan ready
    ↓ annotate_render.py — PIL-based component labels (CN/EN)
Labeled JPG — with leader lines and component names
```

## Why This Tool?

| Pain Point | How We Solve It |
|------------|----------------|
| Design docs have scattered parameters, tolerances, BOM across 600+ lines | **One command** extracts all 9 data categories into a single structured spec |
| Design docs may have engineering errors (stress, fit, material) | **Design review** checks mechanics, assembly, materials, completeness before CAD |
| Pure text-to-image AI gets ~42% geometry accuracy | **Hybrid pipeline**: Blender renders exact geometry first, AI only "reskins" the surface |
| "What should I do next?" is hard to answer in a complex pipeline | **Natural-language assistant** scans your project artifacts and recommends the next action |
| Cross-view consistency is poor with AI-generated images | **Blender-first** approach locks geometry across all views; AI inherits consistency |
| 2D drawings don't follow national standards | **GB/T compliant**: first-angle projection, FangSong font, 12-layer DXF with 0.5mm line widths |
| Hard to integrate with other LLMs (GPT, GLM, Qwen...) | **LLM-agnostic**: pure Python CLI + `system_prompt.md` + platform adapters |

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│  Platform Adapters  (pick one, or use system_prompt.md)   │
│  ├── .claude/commands/ → Claude Code slash commands        │
│  ├── openai/       → Function Calling JSON schema         │
│  ├── langchain/    → LangChain/AutoGen Tool wrapper       │
│  └── dify/         → Knowledge base import guide          │
├──────────────────────────────────────────────────────────┤
│  Universal Skill Layer                                    │
│  ├── skill.json         → machine-readable skill manifest │
│  ├── system_prompt.md   → paste into any LLM              │
│  └── skill_cad_help.md  → 16-intent knowledge base        │
├──────────────────────────────────────────────────────────┤
│  Tool Layer  (pure Python CLI, no LLM dependency)         │
│  ├── cad_pipeline.py    → unified 6-phase orchestrator    │
│  ├── cad_spec_gen.py    → spec extraction                 │
│  ├── cad_spec_reviewer.py → design review (4 categories)  │
│  ├── codegen/gen_*.py   → Jinja2 code generation          │
│  ├── bom_parser.py      → BOM parsing                     │
│  └── config/templates/  → subsystem configs + Jinja2 .j2  │
└──────────────────────────────────────────────────────────┘
```

## Pipeline Architecture

```
┌────────────────────────────────────────────────────────────────┐
│                   CAD Hybrid Rendering Pipeline                 │
│                                                                 │
│  1. DESIGN REVIEW (optional, recommended)                         │
│     Design doc (.md) → cad_spec_gen.py --review                   │
│     → DESIGN_REVIEW.md (A.mechanical / B.assembly incl. B5-B8    │
│       floating parts & connection checks / C.material / D.gaps)  │
│     User: "继续审查" / "自动补全" (--auto-fill) / "下一步"          │
│  ✋ [GATE-1] CRITICAL issues block SPEC phase until confirmed     │
│                                                                 │
│  2. SPEC EXTRACTION (this repo)                                   │
│     Design doc (.md) → cad_spec_gen.py → CAD_SPEC.md            │
│     9 sections: params, tolerances, fasteners, connections,     │
│     BOM tree, assembly pose, visual IDs, render plan, gaps      │
│                                                                 │
│  3. CODE GENERATION (Jinja2)                                      │
│     CAD_SPEC.md → codegen/gen_*.py → params.py + build_all.py   │
│     + station_*.py scaffolds + std_*.py (standard parts)         │
│     + assembly.py (with standard parts integrated)               │
│     Templates: templates/*.j2 (scaffold mode, never overwrites) │
│     ⚠ Scaffolds are incomplete: params.py needs correct naming,  │
│     build_all.py needs valid module refs, assembly.py needs       │
│     hand-written mate logic. Complete before Phase 4.             │
│  ✋ [GATE-2] TODO scan — exit code 2 if unfilled TODO: markers   │
│                                                                 │
│  4. PARAMETRIC MODELING                                         │
│  ✋ [GATE-3] orientation_check.py — asserts bounding-box axes    │
│     CadQuery scripts → STEP + GLB + DXF                        │
│     - 3D: assemblies with precise mate constraints              │
│     - 2D: GB/T A3 drawings, 3-view + section views              │
│                                                                 │
│  5. 3D RENDERING (Blender Cycles, GPU auto-detect)                │
│     GLB → N-view PNG (geometry 100% accurate, default 5 views)  │
│     15 PBR material presets · spherical camera system            │
│     Default views: front-iso / rear / side / exploded / ortho   │
│     Views are config-driven: render_config.json camera section   │
│                                                                 │
│  6. AI ENHANCEMENT (optional)                                   │
│     PNG → photorealistic JPG (reskin only, geometry locked)     │
│     Prompt: "Keep ALL geometry EXACTLY" + material description  │
│     Standard parts: simplified shapes → realistic appearance    │
│     Model: configurable via pipeline_config.json (Nano Banana)  │
│                                                                 │
│  Output:  PNG → engineering review / machining reference        │
│           JPG → presentations / proposals / business plans      │
└────────────────────────────────────────────────────────────────┘
```

## Quality Gates

Three mandatory checkpoints block the pipeline on failure:

| Gate | Phase | Check | Exit code |
|------|-------|-------|-----------|
| Gate 1 — CRITICAL review | SPEC | `cad_spec_reviewer.py` finds CRITICAL issues | non-0, user must confirm |
| Gate 2 — TODO scan | CODEGEN | Generated scaffold files contain unfilled `TODO:` markers | 2, prints file:line list |
| Gate 3 — Orientation check | BUILD (pre) | `orientation_check.py` asserts bounding-box principal axes match design doc | non-0; bypass with `--skip-orientation` |

Gate 3 is skipped if `orientation_check.py` does not exist in the subsystem directory (non-mandatory for new subsystems).

## Key Features

### Spec Extraction (`cad_spec_gen.py`)
- **9-section structured output**: parameters, tolerances, fasteners, connection matrix, BOM tree, assembly pose, visual IDs, render plan, completeness report
- **Design review mode** (`--review`): mechanical stress (A1-A3), assembly fit & connection graph (B1-B8), material compatibility (C1-C3), completeness gaps (D1+) → `DESIGN_REVIEW.md`
- **User-driven iteration**: 3 options — "继续审查" (iterate) / "自动补全" (`--auto-fill`, computes missing torques/Ra/units) / "下一步" (proceed)
- **Idempotent**: MD5-based skip — won't regenerate if source unchanged
- **Auto-defaults**: standard bolt torques (8.8 grade), surface Ra by material type
- **Derived calculations**: total cost, part count, BOM completeness %
- **Configurable**: subsystem mapping via JSON config, no hardcoded paths

### Interactive Help (16 Intents)
- **Natural language** — no need to memorize CLI syntax, just ask in plain language
- **16 intents**: environment check, config validation, next-step recommendation, materials, camera, exploded view, rendering, AI enhancement, troubleshooting, file structure, status, cross-model integration, parts/BOM, CAD spec, design review
- **Smart "what's next?"** — scans project artifacts (STEP/DXF/GLB/PNG/JPG) and recommends the highest-priority next action

### 2D Engineering Drawings
- **GB/T national standard**: first-angle projection, A3 sheet, title block
- **12-layer DXF** system with 0.5mm line widths per GB/T 17450
- **FangSong font**, 3.5mm annotation height
- Section views (A-A cut lines), datum triangles, default Ra callouts

### 3D Rendering
- **Blender Cycles CPU** — works on remote desktops without GPU
- **5 standard views** (default, configurable per subsystem): V1 front-iso, V2 rear-oblique, V3 side-elevation, V4 exploded, V5 ortho-front
- **15 PBR material presets**: brushed aluminum, PEEK, carbon fiber, rubber, glass, etc.
- **Exploded views**: radial / axial / custom explosion with assembly lines
- **Config-driven**: `render_config.json` controls materials, cameras, explosion rules

### AI Enhancement (Hybrid Rendering)
- **Geometry-locked**: Blender PNG provides exact geometry; AI only changes surface appearance
- **Standard parts**: simplified CadQuery shapes (motors, bearings, springs) enhanced to realistic appearance via `{standard_parts_description}` prompt
- **Cross-view consistent**: all 5 views share the same 3D source
- **Dual output**: PNG for engineering, JPG for presentation
- **Prompt templates**: auto-generated from render config variables
- **Model selection**: configurable via `pipeline_config.json` — Nano Banana / Nano Banana Pro / Nano Banana 2

## Quick Start

> **Example: End Effector subsystem** — adapt paths for your own subsystem.

```bash
# Scaffold a new subsystem (generates render_config.json, params.py, design doc template)
python cad_pipeline.py init --subsystem robot_arm --name-cn 机器人臂 --prefix GIS-RA
# → output/robot_arm/render_config.json, output/robot_arm/params.py, docs/design/XX-robot_arm.md

# One-click full pipeline (all 6 phases)
python cad_pipeline.py full --subsystem end_effector \
    --design-doc docs/design/04-末端执行机构设计.md --timestamp

# Or step-by-step:

# Phase 1: Design review + spec (recommended first)
python cad_pipeline.py spec --design-doc docs/design/04-末端执行机构设计.md --auto-fill
# → cad/end_effector/DESIGN_REVIEW.md + CAD_SPEC.md

# Phase 2: Generate CadQuery scaffolds
python cad_pipeline.py codegen --subsystem end_effector
# → params.py, build_all.py, station_*.py, std_*.py, assembly.py

# Phase 3-4: Build + render
python cad_pipeline.py build --subsystem end_effector
python cad_pipeline.py render --subsystem end_effector --timestamp
# Note: view script selection is automatic from render_config.json `type` field
# (type=exploded → render_exploded.py, type=section → render_section.py, etc.)

# Phase 5-6: AI enhance + annotate (optional)
# enhance auto-reads render_manifest.json (only current-session renders); use --dir to override
python cad_pipeline.py enhance --subsystem end_effector
python cad_pipeline.py annotate --subsystem end_effector --lang cn,en

# Check pipeline status
python cad_pipeline.py status

# Check environment
python cad_pipeline.py env-check
```

### AI Enhancement Quick Start

After Blender renders your PNGs, enhance them to photorealistic JPGs via the pipeline.
Two backends are supported: **Gemini** (cloud, default) and **ComfyUI** (local GPU, better multi-view consistency).

```bash
# Default: Gemini backend, auto-read render_manifest.json
python cad_pipeline.py enhance --subsystem end_effector

# ComfyUI backend (requires local GPU + ComfyUI running)
# Automatically runs comfyui_env_check.py before submitting — exits if CPU-only or models missing
python cad_pipeline.py enhance --subsystem end_effector --backend comfyui

# Override: process a specific directory instead of manifest
python cad_pipeline.py enhance --subsystem end_effector --dir cad/output/renders_latest

# Check ComfyUI environment manually before first use
python comfyui_env_check.py
```

The enhance step automatically:
- Reads `render_manifest.json` to process only files from the latest render run (not historical files)
- Auto-enriches prompt data from `params.py` via `prompt_data_builder.py` (materials, assembly description, constraints)
- Selects prompt template from `templates/prompt_enhance_unified.txt` (auto-switches by camera type)
- **Gemini**: passes model from `pipeline_config.json` `enhance.model` field; geometry locked via prompt instructions
- **ComfyUI**: uses ControlNet depth+canny to hard-lock geometry; better multi-view consistency; requires local GPU

Switch backend permanently in `pipeline_config.json`:
```json
"enhance": { "backend": "comfyui" }
```

Output: `cad/output/renders/<VN>_<name>_enhanced.jpg`, ~6MB JPG per view, photorealistic studio quality.

### Component Label Annotation

After AI enhancement, add component labels (Chinese/English) via PIL:

```bash
# Annotate single image with Chinese labels
python annotate_render.py V1_enhanced.jpg --config render_config.json --lang cn

# Batch annotate all views in both languages
python annotate_render.py --all --dir ./renders --config render_config.json --lang cn
python annotate_render.py --all --dir ./renders --config render_config.json --lang en
```

Labels are defined in `render_config.json`:
- `components` section: maps IDs to CN/EN names + BOM IDs (from design doc §X.8 BOM)
- `labels` section: per-view coordinates for **visible** components only (occluded = not labeled)
- Coordinates at 1920×1080 reference (configurable via `reference_resolution`), auto-scaled to actual image size

## Adding a New Subsystem

### Option A: One-command scaffold (recommended)

```bash
python cad_pipeline.py init --subsystem <your_subsystem> --name-cn <中文名> --prefix <PREFIX>
```

Generates three files automatically:
- `output/<your_subsystem>/render_config.json` — camera views (V1-V5), materials, CN/EN component names
- `output/<your_subsystem>/params.py` — dimension skeleton
- `docs/design/XX-<your_subsystem>.md` — design doc template

Then edit each file and run the full pipeline:
```bash
python cad_pipeline.py full --subsystem <your_subsystem> --design-doc docs/design/XX-<your_subsystem>.md
```

### Option B: Manual setup

1. **Create directory and config**:
   ```bash
   mkdir cad/<your_subsystem>/
   cp templates/render_config_template.json cad/<your_subsystem>/render_config.json
   ```
   Edit `render_config.json` — fill in subsystem info, materials, camera views, and components.

2. **Auto-generate scaffolds** (if design doc exists):
   ```bash
   python cad_pipeline.py spec --design-doc docs/design/NN-*.md
   python cad_pipeline.py codegen --subsystem <your_subsystem>
   ```

3. **Refine scaffolds**: Edit generated files — params.py needs correct descriptive parameter names (codegen produces line-number based names), build_all.py needs valid module references, assembly.py needs real mate logic. Replace placeholder boxes in station_*.py with actual CadQuery geometry.

4. **Build + render**:
   ```bash
   python cad_pipeline.py full --subsystem <your_subsystem> --skip-spec --skip-codegen --timestamp
   ```

See `templates/render_config_template.json` for field documentation.

## Usage

```
python cad_spec_gen.py [FILES...] --config CONFIG [OPTIONS]

Required:
  --config PATH         JSON config with subsystem mapping

Options:
  --output-dir DIR      Output directory (default: ./output)
  --doc-dir DIR         Design docs directory for --all
  --all                 Process all NN-*.md in doc-dir
  --force               Force regeneration (ignore MD5 check)
  --review              Run design review before spec generation
  --review-only         Run design review only (no spec generation)
  --auto-fill           Auto-fill computable missing values (torques, units, Ra)
```

### Process all subsystems at once

```bash
python cad_spec_gen.py --all --config config/gisbot.json --doc-dir docs/design
```

### BOM parser (standalone)

```bash
python bom_parser.py examples/04-末端执行机构设计.md          # tree view
python bom_parser.py examples/04-末端执行机构设计.md --json   # JSON output
python bom_parser.py examples/04-末端执行机构设计.md --summary # one-line summary
```

## Configuration

Create a JSON config file (see `config/gisbot.json` for a full 18-subsystem example):

```json
{
  "doc_dir": "docs/design",
  "output_dir": "./output",
  "subsystems": {
    "04": {
      "name": "End Effector",
      "prefix": "GIS-EE",
      "cad_dir": "end_effector",
      "aliases": ["ee", "end_effector"]
    }
  }
}
```

## 15 PBR Material Presets

| Category | Presets |
|----------|---------|
| Metal | `brushed_aluminum` `stainless_304` `black_anodized` `dark_steel` `bronze` `copper` `gunmetal` `anodized_blue` `anodized_green` `anodized_purple` `anodized_red` |
| Plastic | `peek_amber` `white_nylon` `black_rubber` `polycarbonate_clear` |

## Documentation

| Document | Language | Description |
|----------|----------|-------------|
| [System Prompt](system_prompt.md) | EN | Universal system prompt — paste into any LLM |
| [Skill Manifest](skill.json) | — | Machine-readable skill definition |
| [User Guide (English)](docs/cad-help-guide-en.md) | EN | Full feature walkthrough, 16 intents, workflows |
| [User Guide (Chinese)](docs/cad-help-guide-zh.md) | 中文 | 完整功能说明、16种意图、典型工作流 |
| [Agent Integration Guide](docs/cad_pipeline_agent_guide.md) | 中文 | LLM/Agent framework integration (GPT, GLM, LangChain, etc.) |
| [CAD Spec Template](templates/cad_spec_template.md) | — | Output format reference with all 9 sections |
| [AI Prompt Templates](templates/) | EN | Unified prompt template (`prompt_enhance_unified.txt`) with auto view-type switching (standard/exploded/ortho/section) |

## Project Structure

```
├── skill.json                      # Machine-readable skill manifest (v1.9.0)
├── system_prompt.md                # Universal system prompt (any LLM)
├── skill_cad_help.md               # Skill knowledge (16 intents + actions)
├── cad_pipeline.py                 # Unified 6-phase pipeline orchestrator
├── cad_paths.py                    # Centralized path resolution
├── pipeline_config.json            # Persistent config (Blender path, render settings)
├── cad_spec_gen.py                 # Spec extraction (CLI entry point)
├── cad_spec_extractors.py          # 8 extraction functions + table parser
├── cad_spec_defaults.py            # Standard defaults, engineering constants
├── cad_spec_reviewer.py            # Design review engine (4 categories)
├── bom_parser.py                   # BOM table parser (also standalone CLI)
├── annotate_render.py              # PIL-based component label annotation (CN/EN)
├── enhance_prompt.py               # Prompt builder for AI enhancement phase
├── prompt_data_builder.py          # Auto-generates material/assembly data from params.py
├── comfyui_enhancer.py             # ComfyUI backend: ControlNet depth+canny geometry lock
├── comfyui_env_check.py            # ComfyUI environment validator (GPU, models, server mode)
├── codegen/                        # Jinja2 code generation from CAD_SPEC.md
│   ├── gen_params.py               # §1 params → params.py
│   ├── gen_build.py                # §5 BOM → build_all.py (STEP + STD + DXF)
│   ├── gen_parts.py                # §5 custom leaf parts → station_*.py scaffolds
│   ├── gen_std_parts.py            # §5 purchased parts → std_*.py (simplified geometry)
│   └── gen_assembly.py             # §4+§5+§6 → assembly.py (incl. standard parts)
├── templates/
│   ├── params.py.j2                # Jinja2: params.py generation
│   ├── build_all.py.j2             # Jinja2: build_all.py generation
│   ├── part_module.py.j2           # Jinja2: part module scaffold
│   ├── assembly.py.j2              # Jinja2: assembly scaffold
│   ├── cad_spec_template.md        # Output template reference
│   ├── design_review_template.md   # Design review output template
│   ├── prompt_enhance_unified.txt  # AI prompt: all views (unified template)
│   └── prompt_section.txt          # Section view prompt template
├── .claude/commands/               # Claude Code slash commands (5 commands)
├── adapters/
│   ├── openai/
│   │   ├── functions.json         # OpenAI Function Calling schema
│   │   └── README.md              # GPT-4 / Assistants setup guide
│   ├── langchain/
│   │   ├── tools.py               # LangChain Tool wrapper
│   │   └── README.md              # LangChain / AutoGen setup guide
│   └── dify/
│       └── README.md              # Dify / Coze setup guide
├── config/
│   └── gisbot.json                # Example: 18-subsystem config
├── examples/
│   └── 04-末端执行机构设计.md       # Example design document
└── docs/
    ├── cad-help-guide-en.md       # User guide (English)
    ├── cad-help-guide-zh.md       # User guide (Chinese)
    └── cad_pipeline_agent_guide.md # Cross-LLM agent integration guide
```

## License

MIT
