geMoldInsight/docs/archive/topics/ai/FREECAD_SETUP.md

# FreeCAD 安装配置指南

## 一、FreeCAD 安装

### 1.1 Windows 安装
```bash
# 方法1：使用 pip 安装
pip install freecad

# 方法2：下载官方安装包
# 访问 https://www.freecad.org/downloads.php
# 下载 FreeCAD 0.21.2 或更新版本
```

### 1.2 Linux 安装
```bash
# Ubuntu/Debian
sudo apt-get install freecad freecad-python3

# CentOS/RHEL
sudo yum install freecad

# 或使用 pip
pip install freecad
```

### 1.3 验证安装
```python
# 验证 FreeCAD Python API 是否可用
import FreeCAD
import Part
import PartDesign

print("FreeCAD 版本:", FreeCAD.Version())
print("安装成功!")
```

## 二、项目依赖配置

### 2.1 更新 requirements.txt
```txt
# 现有依赖
flask>=2.3.0
flask-cors>=4.0.0
pythonocc-core>=7.6.0
numpy>=1.24.0
scipy>=1.10.0
pandas>=2.0.0
matplotlib>=3.7.0
plotly>=5.14.0
psycopg2-binary>=2.9.0
sqlalchemy>=2.0.0
trimesh>=3.20.0
pyvista>=0.38.0
requests>=2.28.0
pytest>=7.3.0

# 新增 FreeCAD 相关依赖
freecad>=0.21.0
freecad.part>=0.21.0
freecad.partdesign>=0.21.0

# AI 相关依赖
openai>=1.0.0
langchain>=0.0.300
scikit-learn>=1.3.0
torch>=2.0.0
```

### 2.2 安装依赖
```bash
pip install -r requirements.txt
```

## 三、FreeCAD 模块结构

### 3.1 模块规划
```
src/core/freecad/
├── __init__.py
├── mold_generator.py      # 模具生成器
├── stp_importer.py        # STP文件导入
├── cavity_splitter.py     # 型腔分割
├── runner_designer.py     # 流道设计
├── cooling_designer.py    # 冷却系统设计
└── standard_parts.py      # 标准件库
```

### 3.2 核心类设计

#### FreeCADMoldGenerator（模具生成器）
- `import_stp_file()` - 导入STP文件
- `analyze_draft_angles()` - 拔模角分析
- `detect_parting_line()` - 分型线检测
- `split_cavity_core()` - 型腔/型芯分割

#### FreeCADSTPImporter（STP导入器）
- `read_step_file()` - 读取STEP文件
- `validate_geometry()` - 几何验证
- `repair_geometry()` - 几何修复

#### FreeCADCavitySplitter（型腔分割器）
- `create_parting_surface()` - 创建分型面
- `boolean_split()` - 布尔运算分割
- `create_mold_base()` - 创建模架

## 四、配置参数

### 4.1 模具参数配置
```python
# config/mold_parameters.py

# 材料收缩率
MATERIAL_SHRINKAGE = {
    "ABS": 0.005,
    "PP": 0.016,
    "PC": 0.007,
    "POM": 0.020,
    "Nylon": 0.015
}

# 拔模角度配置
DRAFT_ANGLES = {
    "textured": 3.0,      # 纹面
    "polished": 1.5,      # 抛光
    "standard": 2.0       # 标准
}

# 模具钢材参数
MOLD_STEELS = {
    "P20": {"hardness": 30, "price": 1.0},
    "718": {"hardness": 35, "price": 1.2},
    "S136": {"hardness": 48, "price": 1.8},
    "NAK80": {"hardness": 40, "price": 2.0}
}
```

### 4.2 FreeCAD 配置
```python
# config/freecad_config.py

# FreeCAD 工作目录配置
FREECAD_WORKSPACE = "workspace/freecad"
FREECAD_TEMPLATES = "templates/freecad"

# 几何精度设置
GEOMETRY_TOLERANCE = 1e-6
BOOLEAN_PRECISION = 1e-5

# 导出设置
EXPORT_FORMATS = ["step", "stl", "iges"]
EXPORT_PRECISION = 0.001
```

## 五、测试验证

### 5.1 功能测试
```python
# tests/test_freecad_integration.py

def test_stp_import():
    """测试STP文件导入功能"""
    generator = FreeCADMoldGenerator()
    result = generator.import_stp_file("test.stp")
    assert result.success
    assert result.shape is not None

def test_cavity_split():
    """测试型腔分割功能"""
    generator = FreeCADMoldGenerator()
    cavity, core = generator.split_cavity_core(test_shape)
    assert cavity.Volume > 0
    assert core.Volume > 0
```

### 5.2 性能测试
```python
# tests/benchmark_freecad.py

def benchmark_boolean_operations():
    """布尔运算性能测试"""
    # 测试不同复杂度的布尔运算性能
    pass
```

## 六、故障排除

### 6.1 常见问题

#### FreeCAD 导入失败
- **问题**: `ImportError: No module named 'FreeCAD'`
- **解决**: 确保 FreeCAD 正确安装，检查 Python 路径

#### 布尔运算失败
- **问题**: 复杂几何体布尔运算报错
- **解决**: 使用几何修复工具，简化几何体

#### 内存不足
- **问题**: 大模型处理时内存溢出
- **解决**: 分块处理，使用内存优化算法

### 6.2 调试工具
```python
# utils/freecad_debug.py

def debug_geometry(shape):
    """几何体调试工具"""
    print(f"顶点数: {len(shape.Vertexes)}")
    print(f"边数: {len(shape.Edges)}")
    print(f"面数: {len(shape.Faces)}")
    print(f"体积: {shape.Volume}")
    print(f"表面积: {shape.Area}")
```

## 七、最佳实践

### 7.1 内存管理
- 及时清理 FreeCAD 文档对象
- 使用分块处理大模型
- 避免同时打开多个复杂文档

### 7.2 错误处理
- 所有 FreeCAD 操作添加异常捕获
- 提供详细的错误信息和恢复建议
- 实现自动几何修复机制

### 7.3 性能优化
- 使用缓存机制存储中间结果
- 并行处理多个几何操作
- 优化布尔运算算法

---
*文档版本：v1.0*  
*创建日期：2026-02-17*