Files
make-cad/docs/core/solid.md
T

20 KiB
Raw Blame History

Solid 实体

概述

Solid 是 SimpleCAD API 中的实体类,表示三维封闭的几何体。实体具有体积,是 CAD 建模中最重要的几何类型之一。它包装了 CADQuery 的 Solid 对象,并添加了标签功能和面的自动标记能力。

类定义

class Solid(TaggedMixin):
    """实体类,包装CADQuery的Solid,添加标签功能"""

继承关系

  • 继承自 TaggedMixin,具有标签和元数据功能

用途

  • 表示三维实体对象
  • 进行布尔运算(并集、交集、差集)
  • 应用特征操作(倒角、圆角等)
  • 计算体积、表面积等物理属性
  • 生成制造数据

构造函数

__init__(cq_solid)

初始化实体对象。

参数:

  • cq_solid (Union[cadquery.Solid, Any]): CADQuery 的实体对象或其他 Shape 对象

异常:

  • ValueError: 当输入的实体对象无效时抛出

示例:

from simplecadapi import (
    make_box_rsolid,
    make_cylinder_rsolid,
    make_sphere_rsolid
)

# 通过 SimpleCAD 函数创建实体
box = make_box_rsolid(width=5, height=3, depth=2)
cylinder = make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=4)
sphere = make_sphere_rsolid(center=(0, 0, 0), radius=1.5)

主要属性

  • cq_solid: 底层的 CADQuery 实体对象
  • _tags: 标签集合(继承自 TaggedMixin)
  • _metadata: 元数据字典(继承自 TaggedMixin)
  • _face_tags: 面标签字典(内部使用)

常用方法

get_volume()

获取实体的体积。

返回:

  • float: 实体的体积

异常:

  • ValueError: 获取体积失败时抛出

示例:

from simplecadapi import make_box_rsolid, make_cylinder_rsolid, make_sphere_rsolid
import math

# 立方体体积
box = make_box_rsolid(width=2, height=3, depth=4)
box_volume = box.get_volume()
print(f"立方体体积: {box_volume}")  # 24.0

# 圆柱体体积
cylinder = make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=5)
cylinder_volume = cylinder.get_volume()
expected_volume = math.pi * 2**2 * 5
print(f"圆柱体体积: {cylinder_volume:.3f}, 期望: {expected_volume:.3f}")

# 球体体积
sphere = make_sphere_rsolid(center=(0, 0, 0), radius=1.5)
sphere_volume = sphere.get_volume()
expected_volume = (4/3) * math.pi * 1.5**3
print(f"球体体积: {sphere_volume:.3f}, 期望: {expected_volume:.3f}")

get_faces()

获取组成实体的所有面。

返回:

  • List[Face]: 面对象列表

异常:

  • ValueError: 获取面列表失败时抛出

示例:

from simplecadapi import make_box_rsolid

box = make_box_rsolid(width=4, height=3, depth=2)
faces = box.get_faces()

print(f"立方体有 {len(faces)} 个面")
for i, face in enumerate(faces):
    area = face.get_area()
    print(f"面 {i}: 面积 {area:.3f}")

get_edges()

获取组成实体的所有边。

返回:

  • List[Edge]: 边对象列表

异常:

  • ValueError: 获取边列表失败时抛出

示例:

from simplecadapi import make_box_rsolid

box = make_box_rsolid(width=4, height=3, depth=2)
edges = box.get_edges()

print(f"立方体有 {len(edges)} 条边")
for i, edge in enumerate(edges):
    length = edge.get_length()
    print(f"边 {i}: 长度 {length:.3f}")

auto_tag_faces(geometry_type)

自动为面添加标签。

参数:

  • geometry_type (str): 几何体类型("box"、"cylinder"、"sphere"、"unknown")

示例:

from simplecadapi import make_box_rsolid, make_cylinder_rsolid

# 立方体面标记
box = make_box_rsolid(width=4, height=3, depth=2)
box.auto_tag_faces("box")

faces = box.get_faces()
for face in faces:
    print(f"面标签: {face.get_tags()}")

# 圆柱体面标记
cylinder = make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=4)
cylinder.auto_tag_faces("cylinder")

faces = cylinder.get_faces()
for face in faces:
    print(f"面标签: {face.get_tags()}")

标签管理方法

继承自 TaggedMixin 的方法:

add_tag(tag)、has_tag(tag)、get_tags()、remove_tag(tag)

set_metadata(key, value)、get_metadata(key, default=None)

使用方法与 Vertex 类似,详见 Vertex 文档。

使用示例

创建和分析基础实体

from simplecadapi import (
    make_box_rsolid,
    make_cylinder_rsolid,
    make_sphere_rsolid
)

def create_basic_solids():
    """创建和分析基础实体"""
    
    # 创建不同类型的实体
    solids = [
        ("box", make_box_rsolid(width=4, height=3, depth=2)),
        ("cylinder", make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=4)),
        ("sphere", make_sphere_rsolid(center=(0, 0, 0), radius=1.5))
    ]
    
    for name, solid in solids:
        # 添加基本标签
        solid.add_tag(name)
        solid.add_tag("basic_geometry")
        
        # 自动标记面
        solid.auto_tag_faces(name)
        
        # 获取几何属性
        volume = solid.get_volume()
        faces = solid.get_faces()
        edges = solid.get_edges()
        
        # 计算表面积
        total_surface_area = sum(face.get_area() for face in faces)
        
        # 分析面的分布
        face_areas = [face.get_area() for face in faces]
        min_face_area = min(face_areas)
        max_face_area = max(face_areas)
        avg_face_area = sum(face_areas) / len(face_areas)
        
        # 存储元数据
        solid.set_metadata("volume", volume)
        solid.set_metadata("surface_area", total_surface_area)
        solid.set_metadata("face_count", len(faces))
        solid.set_metadata("edge_count", len(edges))
        solid.set_metadata("min_face_area", min_face_area)
        solid.set_metadata("max_face_area", max_face_area)
        solid.set_metadata("avg_face_area", avg_face_area)
        
        # 计算体积效率(体积/表面积比)
        volume_efficiency = volume / total_surface_area if total_surface_area > 0 else 0
        solid.set_metadata("volume_efficiency", volume_efficiency)
        
        print(f"{name.upper()} 实体分析:")
        print(f"  体积: {volume:.3f}")
        print(f"  表面积: {total_surface_area:.3f}")
        print(f"  面数: {len(faces)}")
        print(f"  边数: {len(edges)}")
        print(f"  体积效率: {volume_efficiency:.3f}")
        print(f"  面积范围: {min_face_area:.3f} - {max_face_area:.3f}")
        print()

create_basic_solids()

布尔运算示例

from simplecadapi import (
    make_box_rsolid,
    make_cylinder_rsolid,
    union_rsolidlist,
    cut_rsolidlist,
    intersect_rsolidlist
)

def boolean_operations_example():
    """布尔运算示例"""
    
    # 创建基础几何体
    box = make_box_rsolid(width=6, height=4, depth=3)
    box.add_tag("base_box")
    
    cylinder = make_cylinder_rsolid(center=(3, 2, 0), radius=1, height=5)
    cylinder.add_tag("cutting_cylinder")
    
    # 并集运算
    union_result = union_rsolidlist([box, cylinder])[0]
    union_result.add_tag("union_result")
    union_result.add_tag("combined_geometry")
    
    # 差集运算(从盒子中减去圆柱)
    cut_result = cut_rsolidlist(box, cylinder)[0]
    cut_result.add_tag("cut_result")
    cut_result.add_tag("with_hole")
    
    # 交集运算
    intersect_result = intersect_rsolidlist(box, cylinder)[0]
    intersect_result.add_tag("intersect_result")
    intersect_result.add_tag("common_volume")
    
    # 分析结果
    operations = [
        ("原始盒子", box),
        ("原始圆柱", cylinder),
        ("并集", union_result),
        ("差集", cut_result),
        ("交集", intersect_result)
    ]
    
    for name, solid in operations:
        volume = solid.get_volume()
        faces = solid.get_faces()
        surface_area = sum(face.get_area() for face in faces)
        
        solid.set_metadata("operation_type", name)
        solid.set_metadata("volume", volume)
        solid.set_metadata("surface_area", surface_area)
        
        print(f"{name}:")
        print(f"  体积: {volume:.3f}")
        print(f"  表面积: {surface_area:.3f}")
        print(f"  面数: {len(faces)}")
        print(f"  标签: {solid.get_tags()}")
        print()

boolean_operations_example()

特征操作示例

from simplecadapi import (
    make_box_rsolid,
    fillet_rsolid,
    chamfer_rsolid,
    select_edges_by_tag
)

def feature_operations_example():
    """特征操作示例"""
    
    # 创建基础盒子
    base_box = make_box_rsolid(width=8, height=6, depth=4)
    base_box.add_tag("base_geometry")
    base_box.auto_tag_faces("box")
    
    # 分析原始几何体
    original_volume = base_box.get_volume()
    original_faces = base_box.get_faces()
    original_edges = base_box.get_edges()
    
    print(f"原始几何体:")
    print(f"  体积: {original_volume:.3f}")
    print(f"  面数: {len(original_faces)}")
    print(f"  边数: {len(original_edges)}")
    print()
    
    # 圆角操作
    try:
        filleted_box = fillet_rsolid(base_box, radius=0.5)
        filleted_box.add_tag("filleted")
        filleted_box.add_tag("rounded_edges")
        
        filleted_volume = filleted_box.get_volume()
        filleted_faces = filleted_box.get_faces()
        filleted_edges = filleted_box.get_edges()
        
        filleted_box.set_metadata("original_volume", original_volume)
        filleted_box.set_metadata("volume_change", filleted_volume - original_volume)
        filleted_box.set_metadata("volume_ratio", filleted_volume / original_volume)
        
        print(f"圆角后几何体:")
        print(f"  体积: {filleted_volume:.3f}")
        print(f"  体积变化: {filleted_volume - original_volume:.3f}")
        print(f"  面数: {len(filleted_faces)}")
        print(f"  边数: {len(filleted_edges)}")
        print()
        
    except Exception as e:
        print(f"圆角操作失败: {e}")
        filleted_box = None
    
    # 倒角操作
    try:
        chamfered_box = chamfer_rsolid(base_box, distance=0.3)
        chamfered_box.add_tag("chamfered")
        chamfered_box.add_tag("beveled_edges")
        
        chamfered_volume = chamfered_box.get_volume()
        chamfered_faces = chamfered_box.get_faces()
        chamfered_edges = chamfered_box.get_edges()
        
        chamfered_box.set_metadata("original_volume", original_volume)
        chamfered_box.set_metadata("volume_change", chamfered_volume - original_volume)
        chamfered_box.set_metadata("volume_ratio", chamfered_volume / original_volume)
        
        print(f"倒角后几何体:")
        print(f"  体积: {chamfered_volume:.3f}")
        print(f"  体积变化: {chamfered_volume - original_volume:.3f}")
        print(f"  面数: {len(chamfered_faces)}")
        print(f"  边数: {len(chamfered_edges)}")
        print()
        
    except Exception as e:
        print(f"倒角操作失败: {e}")
        chamfered_box = None
    
    # 比较结果
    results = [("原始", base_box)]
    if filleted_box:
        results.append(("圆角", filleted_box))
    if chamfered_box:
        results.append(("倒角", chamfered_box))
    
    print("特征操作比较:")
    for name, solid in results:
        volume = solid.get_volume()
        faces = solid.get_faces()
        tags = solid.get_tags()
        print(f"  {name}: 体积={volume:.3f}, 面数={len(faces)}, 标签={tags}")

feature_operations_example()

复杂几何体创建

from simplecadapi import (
    make_box_rsolid,
    make_cylinder_rsolid,
    make_sphere_rsolid,
    union_rsolidlist,
    cut_rsolidlist,
    translate_shape,
    rotate_shape
)

def create_complex_geometry():
    """创建复杂几何体"""
    
    # 创建主体
    main_body = make_box_rsolid(width=12, height=8, depth=6)
    main_body.add_tag("main_body")
    main_body.add_tag("base_structure")
    
    # 创建圆柱形孔
    holes = []
    hole_positions = [(3, 2, 0), (9, 2, 0), (3, 6, 0), (9, 6, 0)]
    
    for i, (x, y, z) in enumerate(hole_positions):
        hole = make_cylinder_rsolid(center=(x, y, z), radius=0.8, height=8)
        hole.add_tag(f"hole_{i}")
        hole.add_tag("mounting_hole")
        holes.append(hole)
    
    # 创建球形特征
    sphere_feature = make_sphere_rsolid(center=(6, 4, 6), radius=2)
    sphere_feature.add_tag("sphere_feature")
    sphere_feature.add_tag("decorative")
    
    # 创建圆柱形支柱
    support_cylinder = make_cylinder_rsolid(center=(6, 4, 0), radius=1, height=4)
    support_cylinder.add_tag("support_cylinder")
    support_cylinder.add_tag("structural")
    
    # 组合几何体
    complex_solid = union_rsolidlist([main_body, sphere_feature])[0]
    complex_solid = union_rsolidlist([complex_solid, support_cylinder])[0]
    
    # 减去孔
    for hole in holes:
        complex_solid = cut_rsolidlist(complex_solid, hole)[0]
    
    # 标记复杂几何体
    complex_solid.add_tag("complex_geometry")
    complex_solid.add_tag("multi_feature")
    complex_solid.add_tag("machined_part")
    
    # 分析复杂几何体
    volume = complex_solid.get_volume()
    faces = complex_solid.get_faces()
    edges = complex_solid.get_edges()
    
    # 计算几何复杂度
    face_count = len(faces)
    edge_count = len(edges)
    complexity_ratio = edge_count / face_count if face_count > 0 else 0
    
    # 分析面的分布
    face_areas = [face.get_area() for face in faces]
    total_surface_area = sum(face_areas)
    
    # 分类面
    small_faces = [f for f in faces if f.get_area() < 1.0]
    large_faces = [f for f in faces if f.get_area() > 10.0]
    medium_faces = [f for f in faces if 1.0 <= f.get_area() <= 10.0]
    
    # 存储分析结果
    complex_solid.set_metadata("volume", volume)
    complex_solid.set_metadata("surface_area", total_surface_area)
    complex_solid.set_metadata("face_count", face_count)
    complex_solid.set_metadata("edge_count", edge_count)
    complex_solid.set_metadata("complexity_ratio", complexity_ratio)
    complex_solid.set_metadata("small_face_count", len(small_faces))
    complex_solid.set_metadata("medium_face_count", len(medium_faces))
    complex_solid.set_metadata("large_face_count", len(large_faces))
    
    # 根据复杂度添加标签
    if complexity_ratio < 5:
        complex_solid.add_tag("simple_topology")
    elif complexity_ratio < 10:
        complex_solid.add_tag("moderate_topology")
    else:
        complex_solid.add_tag("complex_topology")
    
    print(f"复杂几何体分析:")
    print(f"  体积: {volume:.3f}")
    print(f"  表面积: {total_surface_area:.3f}")
    print(f"  面数: {face_count}")
    print(f"  边数: {edge_count}")
    print(f"  复杂度比: {complexity_ratio:.2f}")
    print(f"  面分布 - 小:{len(small_faces)}, 中:{len(medium_faces)}, 大:{len(large_faces)}")
    print(f"  标签: {complex_solid.get_tags()}")
    
    return complex_solid

complex_geometry = create_complex_geometry()

实体质量分析

from simplecadapi import make_box_rsolid, make_cylinder_rsolid, make_sphere_rsolid

def analyze_solid_quality():
    """分析实体质量"""
    
    # 创建测试实体
    test_solids = [
        ("small_box", make_box_rsolid(width=1, height=1, depth=1)),
        ("large_box", make_box_rsolid(width=10, height=10, depth=10)),
        ("thin_box", make_box_rsolid(width=10, height=10, depth=0.1)),
        ("cylinder", make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=5)),
        ("sphere", make_sphere_rsolid(center=(0, 0, 0), radius=2))
    ]
    
    for name, solid in test_solids:
        solid.add_tag(name)
        solid.add_tag("test_geometry")
        
        # 基本几何属性
        volume = solid.get_volume()
        faces = solid.get_faces()
        edges = solid.get_edges()
        
        # 计算质量指标
        surface_area = sum(face.get_area() for face in faces)
        volume_to_surface_ratio = volume / surface_area if surface_area > 0 else 0
        
        # 分析拓扑复杂度
        face_count = len(faces)
        edge_count = len(edges)
        euler_characteristic = None  # 简化版本不计算欧拉特征数
        
        # 面积分布分析
        face_areas = [face.get_area() for face in faces]
        if face_areas:
            min_area = min(face_areas)
            max_area = max(face_areas)
            area_ratio = max_area / min_area if min_area > 0 else float('inf')
        else:
            min_area = max_area = area_ratio = 0
        
        # 质量评估
        quality_score = 0
        quality_issues = []
        
        # 体积检查
        if volume > 1e-6:
            quality_score += 20
        else:
            quality_issues.append("极小体积")
        
        # 面数检查
        if 4 <= face_count <= 100:
            quality_score += 20
        elif face_count > 100:
            quality_issues.append("面数过多")
        else:
            quality_issues.append("面数异常")
        
        # 面积比检查
        if area_ratio < 1000:
            quality_score += 20
        else:
            quality_issues.append("面积差异过大")
        
        # 体积效率检查
        if volume_to_surface_ratio > 0.1:
            quality_score += 20
        else:
            quality_issues.append("体积效率低")
        
        # 边数合理性检查
        if edge_count < face_count * 10:
            quality_score += 20
        else:
            quality_issues.append("边数过多")
        
        # 存储质量数据
        solid.set_metadata("volume", volume)
        solid.set_metadata("surface_area", surface_area)
        solid.set_metadata("face_count", face_count)
        solid.set_metadata("edge_count", edge_count)
        solid.set_metadata("volume_to_surface_ratio", volume_to_surface_ratio)
        solid.set_metadata("area_ratio", area_ratio)
        solid.set_metadata("quality_score", quality_score)
        solid.set_metadata("quality_issues", quality_issues)
        
        # 质量标签
        if quality_score >= 80:
            solid.add_tag("high_quality")
        elif quality_score >= 60:
            solid.add_tag("good_quality")
        elif quality_score >= 40:
            solid.add_tag("acceptable_quality")
        else:
            solid.add_tag("poor_quality")
        
        print(f"{name.upper()} 质量分析:")
        print(f"  体积: {volume:.6f}")
        print(f"  表面积: {surface_area:.3f}")
        print(f"  面数: {face_count}")
        print(f"  边数: {edge_count}")
        print(f"  体积效率: {volume_to_surface_ratio:.3f}")
        print(f"  面积比: {area_ratio:.2f}")
        print(f"  质量分数: {quality_score}/100")
        if quality_issues:
            print(f"  质量问题: {', '.join(quality_issues)}")
        print(f"  质量等级: {[tag for tag in solid.get_tags() if 'quality' in tag]}")
        print()

analyze_solid_quality()

字符串表示

from simplecadapi import make_box_rsolid

box = make_box_rsolid(width=5, height=3, depth=2)
box.add_tag("example_box")
box.auto_tag_faces("box")
box.set_metadata("material", "aluminum")

print(box)

输出:

Solid:
  volume: 30.000
  face_count: 6
  edge_count: 12
  faces:
    face_0:
      area: 15.000
      normal: [0.000, 0.000, 1.000]
      tags: [top]
    face_1:
      area: 15.000
      normal: [0.000, 0.000, -1.000]
      tags: [bottom]
    face_2:
      area: 10.000
      normal: [0.000, 1.000, 0.000]
      tags: [front]
    face_3:
      area: 10.000
      normal: [0.000, -1.000, 0.000]
      tags: [back]
    face_4:
      area: 6.000
      normal: [1.000, 0.000, 0.000]
      tags: [right]
    face_5:
      area: 6.000
      normal: [-1.000, 0.000, 0.000]
      tags: [left]
  tags: [example_box]
  metadata:
    material: aluminum

与其他几何体的关系

  • 面 (Face): 实体的边界表面
  • 边 (Edge): 面的边界
  • 壳 (Shell): 实体可以分解为壳
  • 复合体 (Compound): 多个实体可以组成复合体

应用场景

  • 机械设计: 零件建模
  • 建筑设计: 建筑构件
  • 产品设计: 工业产品
  • 3D 打印: 制造原型
  • 仿真分析: 有限元分析

注意事项

  • 实体必须是封闭的、有效的几何体
  • 布尔运算可能改变实体的拓扑结构
  • 复杂实体可能包含大量面和边
  • 特征操作可能失败,需要适当的错误处理
  • 自动面标记功能依赖于几何体的规则性
  • 实体的质量直接影响后续操作的成功率和性能