phase 0
This commit is contained in:
Jason Stedwell
@@ -0,0 +1,276 @@
|
||||
# STEP Processor Skill — Project Context
|
||||
### CoWork Memory Document · MPMedia Engineering
|
||||
**Updated:** June 2026 · **Status:** ✅ FULLY TESTED — Smoke-tested on 3 Chinese-sourced STEP files
|
||||
|
||||
---
|
||||
|
||||
## What This Is
|
||||
|
||||
A Python-based CAD processing skill for MPMedia's engineering workflow. Reads STEP/STP files (display enclosures, mounting kits, hardware assemblies) and automates: thumbnail generation, parts BOM export (MPM-branded Excel), Chinese-to-English label translation, STEP file rewriting with English labels, geometric queries, and external dimensional diagram creation.
|
||||
|
||||
Lives as a CoWork skill folder with a `SKILL.md`. Callable from Claude or directly from CLI.
|
||||
|
||||
---
|
||||
|
||||
## Current Working State (as of June 2026)
|
||||
|
||||
### Smoke Test Results
|
||||
All three production STEP files tested end-to-end:
|
||||
|
||||
| File | Faces | Parts (STEP parser) | Translations | _EN.step |
|
||||
|------|-------|---------------------|--------------|----------|
|
||||
| MR16s Gen1 | 5,655 | 28 | 16/16 | ✅ All English |
|
||||
| MR27s Gen1 | 6,732 | 31 | 18/18 | ✅ All English |
|
||||
| MR28uws Gen1 | 5,891 | 31 | 20/20 | ✅ All English |
|
||||
|
||||
### What Works
|
||||
- **STEP loading**: build123d primary, FreeCAD headless fallback
|
||||
- **GBK encoding**: Chinese CAD files fully decoded (see Architecture Notes below)
|
||||
- **BOM extraction**: STEP text parser as primary source — correctly reads Chinese names
|
||||
- **Translation**: Claude API (`claude-haiku-4-5-20251001`) — batched, single call per file
|
||||
- **STEP rewriter**: `_EN.step` produced with English labels in both PRODUCT name fields
|
||||
- **BOM export**: MPM-branded `.xlsx` (Montserrat/Open Sans, Dark Shade header, Gold border, alternating rows)
|
||||
- **Thumbnails**: 6 PNG views via pyrender (front, rear, left, right, iso_left, iso_right)
|
||||
|
||||
### BOM Output Format
|
||||
Columns in Excel output order:
|
||||
|
||||
| Column | Header in Excel |
|
||||
|--------|----------------|
|
||||
| part_number | Part # |
|
||||
| part_description | Part Description |
|
||||
| quantity | Qty |
|
||||
| level | Level |
|
||||
| parent | Parent |
|
||||
| bbox_x_mm | X (mm) |
|
||||
| bbox_y_mm | Y (mm) |
|
||||
| bbox_z_mm | Z (mm) |
|
||||
| notes | Notes |
|
||||
| part_name_supplier | Supplier Part Name |
|
||||
|
||||
`part_description` = translated English name (was `part_name_english` internally).
|
||||
`part_name_supplier` = original Chinese name from supplier file (last column, was `part_name_original`).
|
||||
|
||||
---
|
||||
|
||||
## Architecture Notes (Critical — Read Before Debugging)
|
||||
|
||||
### GBK Encoding Fix
|
||||
STEP files from Chinese CAD tools (SolidWorks CN, etc.) embed raw GBK bytes in `PRODUCT` entity name strings. This caused two separate problems, each with a different fix:
|
||||
|
||||
**Problem 1: BOM shows garbled Chinese (mojibake)**
|
||||
OpenCASCADE (OCC) / build123d's STEP reader applies an internal codec that maps each 2-byte GBK sequence to incorrect Unicode codepoints. This is NOT reversible via latin-1 → GBK round-trip because OCC's codec is not latin-1.
|
||||
|
||||
Fix: Bypass OCC entirely for part name extraction. `bom.py` reads the raw STEP file text directly with encoding detection (UTF-8 → GBK → latin-1 fallback) and parses `PRODUCT` entities via regex. This is the primary name source; OCC assembly walk is fallback only.
|
||||
|
||||
**Problem 2: _EN.step still shows Chinese in CAD viewer**
|
||||
The rewriter (`rewriter.py`) was reading the file as UTF-8, turning GBK bytes into replacement chars (U+FFFD). Chinese names became `???` and never matched the translation map.
|
||||
|
||||
Fix: `rewriter.py` uses the same encoding-detection reader as `bom.py`. File is read as GBK when UTF-8 produces replacement chars.
|
||||
|
||||
**Problem 3: Only first PRODUCT name field was replaced**
|
||||
ISO 10303-21 `PRODUCT` entity format: `#N = PRODUCT('id', 'name', 'description', (#...))`. Both the first and second quoted strings carry the part name. CAD viewers (including OpenCASCADE CAD Assistant) display the second field.
|
||||
|
||||
Fix: Updated `PRODUCT_PATTERN` regex to capture both fields with 5 groups. Replacement writes the translated name into both positions.
|
||||
|
||||
### Translation API Model
|
||||
Current model: `claude-haiku-4-5-20251001`
|
||||
Previous value `claude-sonnet-4-20250514` was returning 404 — updated in `translator.py`.
|
||||
|
||||
### BOM Excel Library
|
||||
`openpyxl` must be installed in the venv. The skill falls back to CSV silently if it's missing — don't rely on this fallback, install it explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites for a New macOS Computer
|
||||
|
||||
### Hardware Requirements
|
||||
- Apple Silicon Mac (M1/M2/M3/M4) — all wheels are native arm64
|
||||
- **No Rosetta required**
|
||||
- macOS 13 Sequoia or later recommended
|
||||
|
||||
### Software Stack
|
||||
```
|
||||
Python 3.10–3.12 (3.13 works but less tested; 3.9 too old)
|
||||
Homebrew (for cairo system libs)
|
||||
~/step-processor-env (Python venv — all pip packages go here)
|
||||
```
|
||||
|
||||
### Python Packages (pip install in venv)
|
||||
```bash
|
||||
pip install cadquery-ocp # OCC kernel, native arm64, ~300MB
|
||||
pip install build123d # STEP loader, primary
|
||||
pip install trimesh pyrender # thumbnail rendering pipeline
|
||||
pip install Pillow numpy pandas # image and data processing
|
||||
pip install anthropic # Claude API client
|
||||
pip install openpyxl # Excel BOM output — REQUIRED
|
||||
pip install cairosvg # SVG→PNG/PDF for diagrams (optional, diagrams only)
|
||||
```
|
||||
|
||||
### System Libraries (Homebrew)
|
||||
```bash
|
||||
brew install cairo pango gdk-pixbuf libffi # required for cairosvg
|
||||
```
|
||||
|
||||
### FreeCAD Fallback (Optional)
|
||||
Only needed if build123d fails on a specific file.
|
||||
- Download official arm64 `FreeCAD.app` from https://github.com/FreeCAD/FreeCAD/releases/latest
|
||||
- Drag to `/Applications`, launch once so macOS approves it
|
||||
- Verify: `/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd --version`
|
||||
|
||||
> **macOS 15 Sequoia:** conda-forge FreeCAD is killed by Gatekeeper. Use the official signed `.app` only.
|
||||
|
||||
### Anthropic API Key
|
||||
The key must be available in the environment where the processor runs.
|
||||
|
||||
**For interactive terminal use:**
|
||||
```bash
|
||||
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
**For Desktop Commander / CoWork (non-interactive shell):**
|
||||
```bash
|
||||
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY"' >> ~/.zshenv
|
||||
```
|
||||
`~/.zshrc` is only sourced in interactive shells. Desktop Commander spawns non-interactive zsh — it reads `~/.zshenv` instead. **Both files should have the key.**
|
||||
|
||||
---
|
||||
|
||||
## Setup — Fast Path (New Mac)
|
||||
|
||||
```bash
|
||||
# 1. Create venv
|
||||
python3 -m venv ~/step-processor-env
|
||||
source ~/step-processor-env/bin/activate
|
||||
|
||||
# 2. Install all packages
|
||||
pip install --upgrade pip
|
||||
pip install cadquery-ocp build123d trimesh pyrender Pillow numpy pandas anthropic openpyxl
|
||||
|
||||
# 3. System libs for diagram export
|
||||
brew install cairo pango gdk-pixbuf libffi
|
||||
pip install cairosvg
|
||||
|
||||
# 4. API key (do BOTH for interactive + Desktop Commander)
|
||||
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY"' >> ~/.zshrc
|
||||
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY"' >> ~/.zshenv
|
||||
source ~/.zshrc
|
||||
|
||||
# 5. Verify
|
||||
python -c "import build123d, openpyxl, anthropic, trimesh; print('ALL OK')"
|
||||
|
||||
# 6. Test run
|
||||
cd /path/to/step-skill-folder
|
||||
python step_processor.py yourfile.step --no-thumbnails --verbose
|
||||
```
|
||||
|
||||
Expected output for Chinese STEP file:
|
||||
```
|
||||
INFO [build123d] Loaded: yourfile.step | NNNN faces | NN parts
|
||||
INFO STEP text parser found NN unique part names
|
||||
INFO BOM extracted: NN parts
|
||||
INFO BOM XLSX → yourfile_bom.xlsx
|
||||
INFO Chinese part names detected — auto-translating
|
||||
INFO API returned NN translations
|
||||
INFO _EN.step written: yourfile_EN.step (NN labels replaced)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
STEP File Skill/
|
||||
step_processor.py ← CLI entry point
|
||||
modules/
|
||||
__init__.py
|
||||
loader.py ← build123d load + GBK mojibake helper
|
||||
bom.py ← STEP text parser + MPM-branded xlsx output
|
||||
renderer.py ← 6-view PNG thumbnails (pyrender)
|
||||
translator.py ← Claude API translation (claude-haiku-4-5-20251001)
|
||||
rewriter.py ← _EN.step writer (GBK-aware, both PRODUCT fields)
|
||||
query_engine.py ← Natural language geometry queries + REPL
|
||||
external_diagram.py ← Dimensional diagram generator
|
||||
schemas/
|
||||
external_diagram_schema.json
|
||||
parts_mapping_schema.json
|
||||
templates/
|
||||
datablock_template.md
|
||||
SKILL.md ← Claude skill instructions
|
||||
INSTALL.md ← Library setup details
|
||||
SETUP_CHECKLIST.md ← Step-by-step setup + progressive tests
|
||||
COWORK_CONTEXT.md ← This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI Reference
|
||||
|
||||
```bash
|
||||
# Activate environment first (every new terminal session)
|
||||
source ~/step-processor-env/bin/activate
|
||||
cd /path/to/STEP\ File\ Skill
|
||||
|
||||
# Default: thumbnails + BOM + auto-translate if Chinese detected
|
||||
python step_processor.py enclosure.step
|
||||
|
||||
# BOM only (no thumbnails, no translate)
|
||||
python step_processor.py enclosure.step --no-thumbnails --no-translate
|
||||
|
||||
# Force translation even if auto-detect is off
|
||||
python step_processor.py enclosure.step --translate
|
||||
|
||||
# Single geometric query and exit
|
||||
python step_processor.py enclosure.step --query "list all mounting holes"
|
||||
|
||||
# Interactive geometry REPL
|
||||
python step_processor.py enclosure.step --repl
|
||||
|
||||
# External dimensional diagram
|
||||
python step_processor.py enclosure.step --diagram
|
||||
python step_processor.py enclosure.step --diagram --diagram-pdf
|
||||
python step_processor.py enclosure.step --diagram --diagram-mode enclosure_plus_mounting
|
||||
|
||||
# Verbose (shows backend selection, timing, fallback notices)
|
||||
python step_processor.py enclosure.step --verbose
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known Issues and Pending Work
|
||||
|
||||
### BOM bbox Enrichment (partial)
|
||||
Rows beyond the first only get 5.0 × 5.0 × 5.0mm placeholder bounding boxes. The OCC child enumeration only retrieves the top-level shape's children correctly. Root cause: build123d's `.children` on compound shapes doesn't walk sub-assemblies for bbox. Fix: map part names from STEP text parser back to OCC children by label — non-trivial due to OCC label mangling on CJK files.
|
||||
|
||||
### Mounting Hole Filter — Minimum Diameter
|
||||
The query engine's mounting hole detector returns PCB vias (0.4mm diameter) alongside actual mounting holes. Needs a minimum diameter threshold (recommend 2.0mm floor). Pending update to `query_engine.py`.
|
||||
|
||||
### Phase 7 Full Test
|
||||
The SETUP_CHECKLIST.md Phase 7 tests have been validated for Tests 1, 2, 4 (BOM, translation, rewrite). Tests 3 (thumbnails), 5 (REPL), 6/7 (diagrams) not yet re-run post GBK fix. Thumbnails were verified in an earlier session; diagram code is scaffolded but output quality against production files not fully validated.
|
||||
|
||||
### Conda freecad_env Cleanup
|
||||
From a prior session: `conda activate freecad_env && conda deactivate && conda env remove -n freecad_env`. The conda FreeCAD approach was abandoned in favor of the signed FreeCAD.app. This env is dead weight on the local machine.
|
||||
|
||||
---
|
||||
|
||||
## Library Stack Decision Log
|
||||
|
||||
| Decision | Choice | Reason |
|
||||
|----------|--------|--------|
|
||||
| CAD kernel | build123d | Native arm64 arm; clean API; same OCC as existing viewer |
|
||||
| Fallback CAD | FreeCAD.app (signed) | conda-forge builds killed by Gatekeeper on Sequoia |
|
||||
| Translation | Claude Haiku API | Batched, manufacturing-context prompted, flags ambiguity |
|
||||
| Diagrams | SVG-first + cairosvg | No GUI dependency; vector quality; cairosvg handles PNG/PDF |
|
||||
| Excel | openpyxl | MPM brand formatting, column control, frozen panes |
|
||||
| Rejected | pythonocc | Rosetta/x64 conda dependency — non-starter on Apple Silicon |
|
||||
| Rejected | conda-forge FreeCAD | Unsigned binaries killed by Gatekeeper on macOS 15 |
|
||||
|
||||
---
|
||||
|
||||
## Planned Integration Points
|
||||
|
||||
- **Odoo V18 MRP**: Model number from `meta.json` triggers lookup of weight, BOM cost, stock status
|
||||
- **CoWork product docs**: `meta.json` feeds product data cards; diagram PNGs embed in Knowledge Base articles
|
||||
- **RDMC** (`rdmc.messagepoint.tv`): Thumbnail PNGs for display inventory visual reference
|
||||
- **OnSign.tv**: Enclosure dimensions for content sizing reference
|
||||
Reference in New Issue
Block a user