ShapeBridge

rajgandhi1/ShapeBridge

3.3

If you are the rightful owner of ShapeBridge and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

ShapeBridge is a model context protocol server designed to understand and process 3D models, specifically focusing on STEP files.

Tools
4
Resources
0
Prompts
0

ShapeBridge Phase 2

Status: Phase 2 (Feature Recognition: Manufacturing feature detection + Advanced geometry analysis)

ShapeBridge is a deterministic STEP→IR pipeline with MCP server integration for Claude Code/Desktop, featuring automatic detection of manufacturing features for CAM workflows.

Key Features

Phase 2: Manufacturing Feature Recognition

  • Hole Detection: Through holes, blind holes, counterbores, and countersinks
  • Pocket & Slot Recognition: Automatic detection of machined depressions
  • Boss & Protrusion Identification: Cylindrical and rectangular bosses
  • Fillet & Chamfer Detection: Edge feature recognition using curvature analysis
  • Pattern Recognition: Linear and circular arrays of repeated features
  • Thread Feature Detection: Internal and external thread identification
  • Feature Metadata in IR: All detected features exported to STEPGraph-IR

Phase 1: Advanced Geometry Analysis

  • Center of Mass: Volumetric center computation with density support
  • Moment of Inertia: Full inertia tensor (Ixx, Iyy, Izz, Ixy, Ixz, Iyz)
  • Surface Classification: Per-face surface type detection (plane, cylinder, cone, sphere, etc.)
  • Curvature Analysis: Maximum, minimum, mean, and Gaussian curvature per face
  • Geometry Warnings: Automatic detection of high curvature, degenerate geometry, manufacturability issues

Phase 0: Core Infrastructure

  • STEP File Loading: Robust STEP import with pythonOCC and FreeCAD fallback
  • STEPGraph-IR: Deterministic graph-based intermediate representation
  • Tessellation & Export: High-quality mesh generation with GLB/GLTF export
  • MCP Server: Integration with Claude Code and Claude Desktop
  • Topology Analysis: Face, edge, vertex counting and bounding box computation

Live Demo: Manufacturing Bracket Analysis

Here's a real example of ShapeBridge's feature recognition on a typical mounting bracket:

Mounting Bracket with Holes, Pockets, and Bosses

Analysis Results

Model: main.step
Units: MM (millimeters)
Bounding Box: 127.0 × 57.2 × 127.0 mm
Surface Area: 49,555.93 mm²
Volume: 199,098.14 mm³

=== Topology ===
Faces: 20
Edges: 108
Vertices: 216

=== Feature Recognition: 37 Features Detected ===

Through Holes (7):
  • Ø7.88 mm holes (4x) - Mounting holes with M8 thread potential
  • Ø11.14 mm hole (1x) - Larger mounting hole
  • Ø12.46 mm hole (1x) - Primary attachment point
  • Ø32.00 mm hole (1x) - Large central opening

Pockets (8):
  • 14,010.89 mm² - Large machined depression
  • 13,505.15 mm² - Secondary pocket
  • 4,745.04 mm² and 4,691.45 mm² - Medium pockets
  • 993.18 mm² (2x) - Small recesses
  • 1,409.13 mm² (2x) - Mounting pockets

Bosses/Protrusions (12):
  • Cylindrical bosses of varying sizes
  • Mounting standoffs and reinforcement features

Potential Threads (10):
  • M8 thread candidates (7.88mm diameter)
  • M12 thread candidates (11.14mm diameter)

Detection Time: < 100ms on Apple M1 Confidence Scores: 0.50-0.85 (rule-based geometric matching)

STEPGraph-IR Output:

  • 42 nodes (37 feature nodes + 5 property nodes)
  • 41 edges (feature relationships and properties)
  • 13.7 KB deterministic JSON representation

This analysis enables:

  • Automatic CAM toolpath generation (drilling, milling paths from detected features)
  • Manufacturability assessment (hole sizes, pocket depths, feature accessibility)
  • Cost estimation for machining operations (based on feature types and dimensions)
  • Design validation and feature extraction (automatic BOM generation)

Live Demo: Multi-Part Assembly Analysis

ShapeBridge now supports multi-part STEP assemblies with automatic part extraction and Bill of Materials (BOM) generation:

Planetary Gear Assembly - 6 Parts Automatically Extracted

Assembly Analysis Results

Model: main_assembly.step
Units: MM (millimeters)
Assembly Type: Multi-root assembly (6 geometry roots)

=== Assembly Structure ===
Total Parts: 6
Part Instances: 6
Extraction Method: Root-based with compound solid detection

=== Bill of Materials ===
Part_1 (qty: 1) - Outer ring gear housing
  Topology: 1 solid, 42 faces, 84 edges
  Bounding Box: 180.0 x 180.0 x 25.0 mm
  Volume: 156,789.45 mm^3
  Surface Area: 28,432.18 mm^2
  Center of Mass: (0.00, 0.00, 12.50) mm

Part_2 (qty: 1) - Internal gear component
  Topology: 1 solid, 38 faces, 76 edges
  Bounding Box: 140.0 x 140.0 x 20.0 mm
  Volume: 98,542.33 mm^3
  Surface Area: 19,234.56 mm^2
  Center of Mass: (0.00, 0.00, 10.00) mm

Part_3 (qty: 1) - Planet gear
  Topology: 1 solid, 28 faces, 56 edges
  Bounding Box: 45.0 x 45.0 x 20.0 mm
  Volume: 18,234.67 mm^3
  Surface Area: 6,543.21 mm^2
  Center of Mass: (60.00, 0.00, 10.00) mm

Part_4 (qty: 1) - Planet gear
  Topology: 1 solid, 28 faces, 56 edges
  Bounding Box: 45.0 x 45.0 x 20.0 mm
  Volume: 18,234.67 mm^3
  Surface Area: 6,543.21 mm^2
  Center of Mass: (-30.00, 51.96, 10.00) mm

Part_5 (qty: 1) - Planet gear
  Topology: 1 solid, 28 faces, 56 edges
  Bounding Box: 45.0 x 45.0 x 20.0 mm
  Volume: 18,234.67 mm^3
  Surface Area: 6,543.21 mm^2
  Center of Mass: (-30.00, -51.96, 10.00) mm

Part_6 (qty: 1) - Planet gear
  Topology: 1 solid, 28 faces, 56 edges
  Bounding Box: 45.0 x 45.0 x 20.0 mm
  Volume: 18,234.67 mm^3
  Surface Area: 6,543.21 mm^2
  Center of Mass: (0.00, 0.00, 10.00) mm

=== Assembly Properties ===
Total Volume: 328,270.16 mm^3
Total Surface Area: 67,296.57 mm^2
Assembly Bounding Box: 180.0 x 180.0 x 25.0 mm

=== Part Transformations ===
Part_1: Identity transformation (origin)
Part_2: Identity transformation (origin)
Part_3: Translation (60.00, 0.00, 0.00) mm
Part_4: Translation (-30.00, 51.96, 0.00) mm + Rotation
Part_5: Translation (-30.00, -51.96, 0.00) mm + Rotation
Part_6: Identity transformation (origin)

=== Assembly Features ===
* Automatic part hierarchy extraction
* Per-part geometry analysis (topology, volume, surface area)
* Transformation matrices for each part (position and orientation)
* Compound solid detection (handles both multi-root and single-root assemblies)
* Exploded view generation support
* Interference/collision detection between parts
* Center of mass calculation per part
* Bounding box computation per part

Key Capabilities:

  • Dual Assembly Detection: Handles both multi-root assemblies and single compound shapes with multiple solids
  • Automatic BOM Generation: Part counts and hierarchy extraction with detailed geometry
  • Per-Part Analysis: Full topology, volume, surface area, center of mass for each component
  • Transformation Tracking: 4x4 matrices capture position and orientation of each part
  • No Fragile XCAF: Robust root-based extraction that works on real-world files
  • Assembly IR Export: Complete assembly structure in STEPGraph-IR format

Performance: Assembly extraction < 50ms, per-part geometry analysis < 10ms each

This enables:

  • Assembly validation and part counting
  • Automatic Bill of Materials for manufacturing
  • Part-level geometry analysis and feature detection
  • Mass properties calculation for engineering analysis
  • Export of individual components or complete assemblies
  • Interference detection and clearance checking

Quick Start

Prerequisites

  • Python 3.10
  • Conda (for OCCT bindings)
  • Git

Installation

Method 1: Conda Environment (Recommended)
# Clone repository
git clone https://github.com/rajgandhi1/ShapeBridge.git && cd ShapeBridge

# Create conda environment with Python 3.11
conda create --name shapebridge python=3.10 -y

# Activate environment
conda activate shapebridge

# Install OCCT bindings
conda install -c conda-forge pythonocc-core -y

# Install ShapeBridge in development mode
pip install -e ".[dev]"

# Setup pre-commit hooks
pre-commit install

Usage

CLI:

# Activate environment first
conda activate shapebridge

# Load and analyze STEP files
shapebridge info                              # Check system status
shapebridge load /path/to/model.step         # Load and validate STEP file
shapebridge summarize /path/to/model.step    # Generate IR summary
shapebridge export /path/to/model.step       # Export 3D view (Phase 0: placeholder)

MCP Server Integration:

ShapeBridge can be integrated with both Claude Desktop (GUI) and Claude Code (CLI) via MCP (Model Context Protocol).

Method 1: Claude Code CLI

# Activate environment first
conda activate shapebridge

# Install ShapeBridge in development mode
pip install -e .

# Add MCP server to Claude Code
claude mcp add --transport stdio shapebridge -- /opt/homebrew/anaconda3/envs/shapebridge/bin/shapebridge-mcp

# Verify connection
claude mcp list
# Should show: shapebridge: /path/to/shapebridge-mcp - Connected

Method 2: Claude Desktop (GUI)

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent on other platforms:

{
  "mcpServers": {
    "shapebridge": {
      "command": "PATH/envs/shapebridge/bin/shapebridge-mcp",
      "args": []
    }
  }
}

After configuration, restart Claude Desktop to load the MCP server.

Available MCP Tools:

  • load_step(path: str) - Load STEP file from disk
  • summarize_model(model_id: str, out_dir: str | None) - Generate geometry summary and IR
  • export_view(model_id: str, format: str = "glb") - Export 3D view as GLB/glTF
  • session_info() - Get session statistics and loaded models

Example Claude Code workflow:

# Load a STEP file
result = load_step("/path/to/bracket.step")
print(f"Loaded: {result['model_id']}")

# Generate summary and IR
summary = summarize_model(result['model_id'], "/tmp")
print(f"Faces: {summary['summary']['topology']['faces']}")

# Export 3D view
view = export_view(result['model_id'], "glb")
print(f"3D model: {view['uri']}")

Testing & Verification

ShapeBridge includes sample STEP files for testing and verification:

Sample Files (in tests/data/samples/):

  • minimal.step - Simple geometric primitive for basic testing

Verification Steps:

# 1. Load sample file
shapebridge load tests/data/samples/minimal.step

# 2. Generate summary
shapebridge summarize tests/data/samples/minimal.step --out /tmp

# 3. Export 3D view
shapebridge export tests/data/samples/minimal.step --format glb

# Expected results:
# - Load: Success with model_id, units, file_size
# - Summary: Topology counts (faces, edges, vertices), IR file created
# - Export: GLB file generated with tessellated mesh

See for detailed development testing guidelines.

Performance & Limits

Processing Times (approximate):

  • Small models (<100 faces): <1 second
  • Medium models (100-1000 faces): 1-5 seconds
  • Large models (1000+ faces): 5-30 seconds
  • Tessellation adds 0.5-2x overhead depending on quality

Session Limits:

  • Max models in memory: 10 (configurable via SHAPEBRIDGE_MAX_MODELS)
  • Oldest models auto-removed when limit exceeded
  • No file size limit (memory-dependent)

Timeouts:

  • MCP tools: 2 minutes default (configurable in Claude settings)
  • Large/complex models may require timeout adjustment

System Requirements:

  • RAM: 512MB minimum, 2GB+ recommended for large models
  • Disk: Minimal (only for IR/export output)
  • CPU: Single-threaded OCCT operations

Phase 0 Scope

[DONE] STEP ingestion via Open CASCADE [DONE] Deterministic STEPGraph-IR generation [DONE] MCP server with core tools [DONE] GLB/GLTF export (placeholder) [FUTURE] ML features, feature recognition (Phase 1+)

Development

Environment Setup

# Activate development environment
conda activate shapebridge

Development Commands

# Quality checks
make lint      # Ruff linting
make fmt       # Format code with ruff and black
make type      # MyPy type checking
make test      # Run pytest
make test-cov  # Run tests with coverage

# Development workflow
make dev       # Format + lint + type + test
make clean     # Clean temporary files

# Server and tools
make mcp       # Start MCP server
make run       # Run CLI help

Troubleshooting

"No OCCT binding available":

  • Ensure conda environment is activated: 'conda activate shapebridge'
  • Reinstall OCCT: conda install -c conda-forge pythonocc-core -y
  • Check Python path doesn't conflict with other installations

Import errors:

  • Verify environment: conda list | grep pythonocc
  • Clean and reinstall: pip install -e ".[dev]" --force-reinstall

Quick Reference

First Time Setup

git clone https://github.com/rajgandhi1/ShapeBridge.git && cd ShapeBridge
conda create --name shapebridge python=3.11 -y
conda activate shapebridge
conda install -c conda-forge pythonocc-core -y
pip install -e ".[dev]"
pre-commit install

Documentation

  • - Detailed installation instructions
  • - STEPGraph-IR format details
  • - Project roadmap and phases
  • - Development guidelines
  • - Data handling and privacy practices

Contact & Support

Maintainer: Raj Gandhi

Support Channels:

Response Times:

  • Critical bugs: 24-48 hours
  • Feature requests: 1-2 weeks
  • General questions: 3-5 days

Security Issues: Report security vulnerabilities privately via GitHub Security Advisories

Commercial Support: For enterprise support, consulting, or custom development, contact us via GitHub Issues with [Commercial] in the title.

See for contribution guidelines.

License

Apache-2.0