LIVE_HOUSE_TEST_README.md•4.98 kB
# Live House Modeling Test Runners 🏠
This directory contains multiple approaches to demonstrate the MCP-FreeCAD house modeling capabilities on a **real FreeCAD instance with GUI**, allowing you to watch the 3D house being built step by step in real-time!
## ⚠️ Important: Original Scripts Had Issues
The original `run_live_house_test.py` and `run_live_house_test_mcp.py` scripts had problems trying to import FreeCAD modules directly from outside FreeCAD. I've created **fixed versions** that work properly!
## 🛠️ Working Solutions
### **🎯 Option 1: Simple Macro Approach (RECOMMENDED)**
**File:** `run_house_macro.py` + `house_modeling_macro.FCMacro`
This is the **most reliable method** - it runs FreeCAD with a macro that executes inside FreeCAD's environment where all modules are available.
```bash
# Simple and reliable!
python run_house_macro.py
```
**What happens:**
1. 🚀 Starts FreeCAD with GUI automatically
2. 📜 Runs the house modeling macro inside FreeCAD
3. 🏗️ Builds the house step-by-step with 2-second delays
4. 🔍 Leaves FreeCAD open for inspection
### **🎯 Option 2: Fixed MCP Connection Approach**
**File:** `run_live_house_test_fixed.py`
This uses the proper MCP-FreeCAD connection architecture without trying to import FreeCAD directly.
```bash
# Fixed MCP approach
python run_live_house_test_fixed.py
```
**What happens:**
1. 🚀 Starts FreeCAD as separate process
2. 🔗 Establishes MCP connection to FreeCAD
3. 📡 Sends commands to FreeCAD via connection manager
4. 🏗️ Builds house using proper MCP workflow
## 🏠 What These Tests Build
Both approaches create the same house model:
1. **🏗️ Foundation** - 10m × 8m × 0.3m concrete slab (brown)
2. **🧱 Four Walls** - 3m high, 0.3m thick brick walls (red)
3. **🪟 Two Windows** - 1.2m × 1.5m front windows (blue transparent)
4. **🚪 One Door** - 0.9m × 2.1m front door (blue transparent)
## 🚀 Usage Examples
### Basic Usage:
```bash
# Recommended - simple and reliable
python run_house_macro.py
# Fixed MCP approach (more complex)
python run_live_house_test_fixed.py
```
### Custom Timing:
```bash
# For macro approach - edit STEP_DELAY in house_modeling_macro.FCMacro
# Then run:
python run_house_macro.py
# For MCP approach - use delay parameter
python run_live_house_test_fixed.py --delay 1.0 # Fast (1s steps)
python run_live_house_test_fixed.py --delay 5.0 # Slow (5s steps)
```
### Direct FreeCAD Macro:
```bash
# Run macro directly in FreeCAD
./FreeCAD_1.0.0-conda-Linux-x86_64-py311.AppImage --run-macro house_modeling_macro.FCMacro
```
## 🔧 Requirements
- **FreeCAD AppImage** must be in project root: `FreeCAD_1.0.0-conda-Linux-x86_64-py311.AppImage`
- **Python environment** with MCP-FreeCAD dependencies (for MCP approach)
- **GUI environment** (X11/Wayland) for visual display
## 🎬 What You'll See
When running either test, you'll watch:
1. **🚀 FreeCAD starting** with splash screen
2. **📄 New document creation**
3. **🏗️ Foundation appearing** (brown rectangular base)
4. **🧱 Walls rising** one by one (red brick walls)
5. **🪟 Windows appearing** (blue transparent openings)
6. **🚪 Door being cut** (blue transparent opening)
7. **🎨 Final view adjustment** (isometric view, fit all)
Each step has a delay (default 2 seconds) so you can follow the construction process!
## 🐛 Troubleshooting
### Error: "No module named 'FreeCAD'"
- **Solution:** Use `run_house_macro.py` (recommended) or the fixed MCP version
- **Cause:** Original scripts tried to import FreeCAD from outside FreeCAD
### Error: "FreeCAD AppImage not found"
- **Solution:** Ensure `FreeCAD_1.0.0-conda-Linux-x86_64-py311.AppImage` is in project root
- **Check:** `ls -la FreeCAD_*.AppImage`
### Error: Connection issues (MCP approach)
- **Solution:** Try the macro approach instead: `python run_house_macro.py`
- **Alternative:** Check FreeCAD is properly started before connection attempts
### FreeCAD doesn't show GUI
- **Solution:** Ensure you're in a GUI environment (not headless SSH)
- **Check:** Try `echo $DISPLAY` - should show something like `:0`
## 📊 Comparison
| Approach | Reliability | Setup Complexity | MCP Demo Value |
|----------|-------------|------------------|----------------|
| **Macro** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| **Fixed MCP** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
**Recommendation:** Start with the **macro approach** for reliability, then try the **MCP approach** to see the full connection architecture in action!
## 🎯 Next Steps
After running the live house test:
1. **🔍 Inspect the model** - Rotate, zoom, explore the 3D house
2. **✏️ Modify objects** - Try changing dimensions in the tree view
3. **💾 Export the model** - Save as STL, STEP, or other formats
4. **🔧 Modify the code** - Customize house dimensions, add rooms, etc.
5. **🚀 Build your own tests** - Use this as a template for other models!