jason/step-parse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

phase 0

Browse Source
This commit is contained in:
Jason Stedwell
2026-06-17 16:03:26 -05:00
parent fa1e9b68c7
commit c1abe36822
99 changed files with 1562887 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skill.src/SETUP_CHECKLIST.md
+392
View File
@@ -0,0 +1,392 @@
# STEP Processor — macOS Setup Checklist
### Apple Silicon (Mac Studio M-series) · No Rosetta Required
Work through this top to bottom. Each section has a ✅ verification command
so you know it worked before moving on.
---
## PHASE 1 — Prerequisites
### 1.1 — Confirm Python version
```bash
python3 --version
```
**You need Python 3.10, 3.11, or 3.12.**
3.13 will work but is less tested. 3.9 is too old.
If your version is wrong, install via Homebrew:
```bash
brew install python@3.11
```
Then use `python3.11` explicitly in all commands below.
---
### 1.2 — Confirm Homebrew is installed
```bash
brew --version
```
If missing:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
---
### 1.3 — Create a dedicated virtual environment
Keep everything isolated from your system Python.
Pick a folder — e.g. your CoWork dev directory.
```bash
python3 -m venv ~/step-processor-env
source ~/step-processor-env/bin/activate
```
You should see `(step-processor-env)` in your terminal prompt.
**All pip commands below assume this environment is active.**
✅ Verify:
```bash
which python # should point inside step-processor-env
```
---
## PHASE 2 — Primary Library: build123d
### 2.1 — Upgrade pip first
```bash
pip install --upgrade pip
```
---
### 2.2 — Install cadquery-ocp (the OCC kernel, native arm64)
This is now on PyPI directly — no manual wheel download needed.
```bash
pip install cadquery-ocp
```
This is a large download (~300MB). Let it run.
✅ Verify:
```bash
python -c "import OCP; print('OCP kernel OK')"
```
---
### 2.3 — Install build123d
```bash
pip install build123d
```
✅ Verify:
```bash
python -c "import build123d; print('build123d OK')"
```
---
### 2.4 — Install the rendering stack
```bash
pip install trimesh pyrender Pillow numpy pandas anthropic openpyxl
```
> **Note:** `openpyxl` is required for Excel BOM output. If missing, the skill silently
> falls back to CSV. Install it here to get MPM-branded `.xlsx` output.
✅ Verify each:
```bash
python -c "import trimesh; print('trimesh OK')"
python -c "import pyrender; print('pyrender OK')"
python -c "import PIL; print('Pillow OK')"
python -c "import pandas; print('pandas OK')"
python -c "import anthropic; print('anthropic OK')"
python -c "import openpyxl; print('openpyxl OK')"
```
---
## PHASE 3 — Diagram Export: cairosvg
Required for converting SVG diagrams to PNG and PDF.
### 3.1 — Install system libraries via Homebrew
```bash
brew install cairo pango gdk-pixbuf libffi
```
### 3.2 — Install cairosvg
```bash
pip install cairosvg
```
✅ Verify:
```bash
python -c "import cairosvg; print('cairosvg OK')"
```
If you get a library not found error, run this and retry:
```bash
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig"
pip install cairosvg
```
---
## PHASE 4 — Fallback Library: FreeCAD Headless
Only needed if build123d fails on a specific file.
> **macOS 15 Sequoia note:** The conda-forge FreeCAD package is killed silently
> by Gatekeeper on Sequoia due to unsigned binaries. Use the official signed
> FreeCAD.app instead (approach below). Conda approach will NOT work on Sequoia.
### 4.1 — Install official FreeCAD.app (signed & notarized)
Download the latest arm64 release from:
```
https://github.com/FreeCAD/FreeCAD/releases/latest
```
Open the .dmg and drag FreeCAD.app to /Applications as normal.
Launch it once from /Applications so macOS registers the security approval.
### 4.2 — Verify headless via app bundle
The binary is `freecadcmd` (all lowercase) inside the bundle:
```bash
/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd --version
# Should print: FreeCAD 1.x.x Revision: ...
```
✅ Verify Python import:
```bash
/Applications/FreeCAD.app/Contents/Resources/bin/python -c \
"import sys; sys.path.insert(0, '/Applications/FreeCAD.app/Contents/Resources/lib'); \
import FreeCAD; print('FreeCAD', FreeCAD.Version())"
```
**Key paths for loader.py:**
- CLI binary: `/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd`
- Python interpreter: `/Applications/FreeCAD.app/Contents/Resources/bin/python`
- Module path (add to sys.path): `/Applications/FreeCAD.app/Contents/Resources/lib`
The code invokes FreeCAD using the bundle's own Python — no conda env needed.
---
## PHASE 5 — API Key
### 5.1 — Set your Anthropic API key
```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshenv
source ~/.zshrc
```
> **Important:** Add the key to **both** `~/.zshrc` AND `~/.zshenv`.
> `~/.zshrc` is only sourced in interactive terminal sessions.
> `~/.zshenv` is sourced for all zsh invocations including Desktop Commander's
> non-interactive shells — without it, translation will silently fail when
> running via CoWork/Desktop Commander.
✅ Verify:
```bash
echo $ANTHROPIC_API_KEY # should print your key (or at least sk-ant-...)
```
---
## PHASE 6 — Place the Skill Files
### 6.1 — Copy the step-processor folder to your working location
Recommended: somewhere in your CoWork project or a dedicated tools directory.
```
~/your-project/
step-processor/
step_processor.py
modules/
__init__.py
loader.py
bom.py
renderer.py
translator.py
rewriter.py
query_engine.py
external_diagram.py
schemas/
external_diagram_schema.json
parts_mapping_schema.json
templates/
datablock_template.md
SKILL.md
INSTALL.md
```
### 6.2 — Activate your environment before running
```bash
source ~/step-processor-env/bin/activate
cd ~/your-project/step-processor
```
---
## PHASE 7 — Test Run (do this when you have a STEP file ready)
Work through these tests in order. Stop at the first failure and fix it
before continuing.
---
### TEST 1 — Confirm the skill loads without errors
```bash
python step_processor.py --help
```
Expected: prints the CLI help/usage block with no ImportError or traceback.
---
### TEST 2 — Load a STEP file and extract BOM
Replace `yourfile.step` with your actual file path.
```bash
python step_processor.py /path/to/yourfile.step --no-thumbnails --verbose
```
Expected output:
```
INFO Loading: yourfile.step
INFO [build123d] Loaded: yourfile.step
INFO BOM extracted: N parts
INFO BOM XLSX → /path/to/yourfile_bom.xlsx
```
Open the `.xlsx` file to confirm part names look right.
If you see Chinese characters in the `Supplier Part Name` column — that's expected and correct.
The `Part Description` column will be populated with English in Test 4.
If you see a CSV instead of xlsx, `openpyxl` is not installed — run `pip install openpyxl`.
---
### TEST 3 — Generate thumbnails
```bash
python step_processor.py /path/to/yourfile.step --no-bom --verbose
```
Expected: 6 PNG files appear next to the STEP file:
`yourfile_front.png`, `yourfile_bottom.png`, `yourfile_left.png`,
`yourfile_right.png`, `yourfile_iso_left.png`, `yourfile_iso_right.png`
Open them in Preview to confirm they look like your enclosure from different angles.
---
### TEST 4 — Translation (requires API key)
Only run this if the BOM from Test 2 has Chinese part names.
```bash
python step_processor.py /path/to/yourfile.step --no-thumbnails --translate --verbose
```
Expected: `part_name_english` column in the CSV is now populated with English names.
A `yourfile_EN.step` should appear if Chinese labels were found in the STEP file itself.
---
### TEST 5 — Geometry query REPL
```bash
python step_processor.py /path/to/yourfile.step --no-thumbnails --no-bom --repl
```
At the `>` prompt, try:
```
> bounding box
> list all holes
> all parts
> help
> exit
```
Confirm the output tables look reasonable for your file.
---
### TEST 6 — External dimensional diagram
```bash
python step_processor.py /path/to/yourfile.step --diagram --verbose
```
Expected files next to the STEP:
- `yourfile__external-diagram.svg`
- `yourfile__external-diagram.png`
- `yourfile__meta.json`
Open the SVG in a browser (drag and drop into Safari or Chrome) to inspect the diagram.
Open the PNG for the rasterized version.
Open the JSON to confirm the metadata block populated correctly.
---
### TEST 7 — Diagram with PDF output
```bash
python step_processor.py /path/to/yourfile.step --diagram --diagram-pdf --verbose
```
Expected: adds `yourfile__external-diagram.pdf` to the outputs.
Open in Preview to confirm it renders cleanly.
---
## Quick Reference — Re-activating After Restart
Every time you open a new terminal session:
```bash
source ~/step-processor-env/bin/activate
cd ~/your-project/step-processor
export ANTHROPIC_API_KEY="sk-ant-..." # only if not already in ~/.zshrc
```
---
## Troubleshooting Quick Reference
| Symptom | Fix |
|---------|-----|
| `ModuleNotFoundError: build123d` | `pip install build123d` (check env is activated) |
| `ModuleNotFoundError: OCP` | `pip install cadquery-ocp` |
| `ModuleNotFoundError: cairosvg` | `brew install cairo && pip install cairosvg` |
| `pyrender` offscreen crash | Expected on some macOS setups — thumbnails will warn but diagram still generates |
| BOM shows no parts / 1 part | Normal for single-body STEP files — the STEP text parser falls back to 1-row BOM |
| Chinese labels not translated | Check `$ANTHROPIC_API_KEY` is set. If running via CoWork/Desktop Commander, add key to `~/.zshenv` not just `~/.zshrc` |
| BOM output is CSV not xlsx | `openpyxl` not installed — `pip install openpyxl` with venv active |
| `_EN.step` entity count mismatch warning | File has unusual STEP encoding — rewrite skipped, original untouched, BOM still correct |
| FreeCAD fallback not working | Use signed FreeCAD.app — conda-forge is Gatekeeper-blocked on Sequoia. Path: `/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd` (all lowercase) |
| Diagram SVG opens blank | Check `yourfile__meta.json` warnings array for geometry errors |