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

15 KiB
Raw Blame History

Shell 壳

概述

Shell 是 SimpleCAD API 中的壳类,表示由多个面组成的开放或闭合的表面集合。壳是介于面和实体之间的几何体,可以用于创建复杂的表面结构。它包装了 CADQuery 的 Shell 对象,并添加了标签功能。

类定义

class Shell(TaggedMixin):
    """壳类,包装CADQuery的Shell,添加标签功能"""

继承关系

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

用途

  • 表示复杂的表面结构
  • 作为实体的中间状态
  • 创建开放的表面几何体
  • 表示薄壁结构

构造函数

__init__(cq_shell)

初始化壳对象。

参数:

  • cq_shell (Union[cadquery.Shell, Any]): CADQuery 的壳对象或其他 Shape 对象

异常:

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

示例:

from simplecadapi import make_box_rsolid, shell_rsolid

# 创建一个实体,然后制作壳
box = make_box_rsolid(width=5, height=3, depth=2)
# 选择要移除的面创建壳
shell = shell_rsolid(box, thickness=0.2)  # 创建薄壁壳

主要属性

  • cq_shell: 底层的 CADQuery 壳对象
  • _tags: 标签集合(继承自 TaggedMixin)
  • _metadata: 元数据字典(继承自 TaggedMixin)

常用方法

get_faces()

获取组成壳的所有面。

返回:

  • List[Face]: 面对象列表

异常:

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

示例:

from simplecadapi import make_box_rsolid, shell_rsolid

# 创建壳
box = make_box_rsolid(width=4, height=3, depth=2)
shell = shell_rsolid(box, thickness=0.1)

# 获取面
faces = shell.get_faces()
print(f"壳由 {len(faces)} 个面组成")

for i, face in enumerate(faces):
    area = face.get_area()
    print(f"面 {i}: 面积 {area:.3f}")

标签管理方法

继承自 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, shell_rsolid

def create_and_analyze_shells():
    """创建和分析不同类型的壳"""
    
    # 创建盒子壳
    box = make_box_rsolid(width=6, height=4, depth=3)
    box_shell = shell_rsolid(box, thickness=0.2)
    box_shell.add_tag("box_shell")
    box_shell.add_tag("rectangular")
    
    # 创建圆柱壳
    cylinder = make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=5)
    cylinder_shell = shell_rsolid(cylinder, thickness=0.15)
    cylinder_shell.add_tag("cylinder_shell")
    cylinder_shell.add_tag("cylindrical")
    
    # 分析壳
    shells = [box_shell, cylinder_shell]
    
    for shell in shells:
        faces = shell.get_faces()
        total_area = sum(face.get_area() for face in faces)
        
        # 分析面的类型
        face_areas = [face.get_area() for face in faces]
        min_area = min(face_areas)
        max_area = max(face_areas)
        avg_area = sum(face_areas) / len(face_areas)
        
        shell.set_metadata("face_count", len(faces))
        shell.set_metadata("total_surface_area", total_area)
        shell.set_metadata("min_face_area", min_area)
        shell.set_metadata("max_face_area", max_area)
        shell.set_metadata("avg_face_area", avg_area)
        
        # 标记面的大小
        for i, face in enumerate(faces):
            area = face.get_area()
            face.add_tag(f"shell_face_{i}")
            
            if area < avg_area * 0.5:
                face.add_tag("small_face")
            elif area > avg_area * 1.5:
                face.add_tag("large_face")
            else:
                face.add_tag("medium_face")
        
        print(f"壳类型: {shell.get_tags()}")
        print(f"  面数: {len(faces)}")
        print(f"  总表面积: {total_area:.3f}")
        print(f"  平均面积: {avg_area:.3f}")
        print(f"  面积范围: {min_area:.3f} - {max_area:.3f}")
        print()

create_and_analyze_shells()

复杂壳的创建

from simplecadapi import (
    make_box_rsolid, 
    make_cylinder_rsolid, 
    union_rsolidlist, 
    shell_rsolid
)

def create_complex_shell():
    """创建复杂的壳结构"""
    
    # 创建复合几何体
    main_body = make_box_rsolid(width=8, height=6, depth=4)
    main_body.add_tag("main_body")
    
    # 添加圆柱形突出部分
    cylinder1 = make_cylinder_rsolid(center=(2, 1, 4), radius=1, height=2)
    cylinder1.add_tag("protrusion_1")
    
    cylinder2 = make_cylinder_rsolid(center=(6, 5, 4), radius=0.8, height=1.5)
    cylinder2.add_tag("protrusion_2")
    
    # 合并几何体
    combined = union_rsolidlist([main_body, cylinder1])[0]
    combined = union_rsolidlist([combined, cylinder2])[0]
    combined.add_tag("combined_solid")
    
    # 创建壳
    complex_shell = shell_rsolid(combined, thickness=0.3)
    complex_shell.add_tag("complex_shell")
    complex_shell.add_tag("multi_feature")
    
    # 分析复杂壳
    faces = complex_shell.get_faces()
    
    # 按面积分类
    large_faces = []
    medium_faces = []
    small_faces = []
    
    total_area = sum(face.get_area() for face in faces)
    avg_area = total_area / len(faces)
    
    for i, face in enumerate(faces):
        area = face.get_area()
        face.add_tag(f"complex_face_{i}")
        face.set_metadata("area", area)
        face.set_metadata("area_ratio", area / avg_area)
        
        if area > avg_area * 2:
            large_faces.append(face)
            face.add_tag("large")
        elif area > avg_area * 0.5:
            medium_faces.append(face)
            face.add_tag("medium")
        else:
            small_faces.append(face)
            face.add_tag("small")
    
    complex_shell.set_metadata("large_face_count", len(large_faces))
    complex_shell.set_metadata("medium_face_count", len(medium_faces))
    complex_shell.set_metadata("small_face_count", len(small_faces))
    complex_shell.set_metadata("total_surface_area", total_area)
    
    print(f"复杂壳分析:")
    print(f"  总面数: {len(faces)}")
    print(f"  大面数: {len(large_faces)}")
    print(f"  中面数: {len(medium_faces)}")
    print(f"  小面数: {len(small_faces)}")
    print(f"  总表面积: {total_area:.3f}")
    
    return complex_shell

complex_shell = create_complex_shell()

壳的质量检查

from simplecadapi import make_box_rsolid, shell_rsolid

def check_shell_quality():
    """检查壳的质量"""
    
    # 创建测试壳
    test_solids = [
        make_box_rsolid(width=5, height=5, depth=5),  # 立方体
        make_box_rsolid(width=10, height=2, depth=1), # 薄板
        make_box_rsolid(width=1, height=1, depth=10)  # 长条
    ]
    
    test_names = ["cube", "plate", "rod"]
    
    for i, solid in enumerate(test_solids):
        name = test_names[i]
        solid.add_tag(name)
        
        # 创建不同厚度的壳
        thicknesses = [0.1, 0.2, 0.5]
        
        for thickness in thicknesses:
            try:
                shell = shell_rsolid(solid, thickness=thickness)
                shell.add_tag(f"{name}_shell")
                shell.add_tag(f"thickness_{thickness}")
                
                faces = shell.get_faces()
                
                # 检查面的连续性
                edge_count = 0
                total_area = 0
                
                for face in faces:
                    area = face.get_area()
                    total_area += area
                    
                    outer_wire = face.get_outer_wire()
                    edges = outer_wire.get_edges()
                    edge_count += len(edges)
                    
                    # 检查面的有效性
                    if area < 1e-6:
                        face.add_tag("degenerate")
                    elif area > 1000:
                        face.add_tag("oversized")
                    else:
                        face.add_tag("normal")
                
                # 计算质量指标
                face_count = len(faces)
                avg_face_area = total_area / face_count if face_count > 0 else 0
                edge_to_face_ratio = edge_count / face_count if face_count > 0 else 0
                
                shell.set_metadata("thickness", thickness)
                shell.set_metadata("face_count", face_count)
                shell.set_metadata("edge_count", edge_count)
                shell.set_metadata("total_area", total_area)
                shell.set_metadata("avg_face_area", avg_face_area)
                shell.set_metadata("edge_to_face_ratio", edge_to_face_ratio)
                
                # 质量评估
                if face_count < 20 and edge_to_face_ratio < 10:
                    shell.add_tag("good_quality")
                elif face_count < 50 and edge_to_face_ratio < 20:
                    shell.add_tag("acceptable_quality")
                else:
                    shell.add_tag("complex_geometry")
                
                print(f"{name} 壳 (厚度 {thickness}):")
                print(f"  面数: {face_count}")
                print(f"  边数: {edge_count}")
                print(f"  总面积: {total_area:.3f}")
                print(f"  边面比: {edge_to_face_ratio:.2f}")
                print(f"  质量: {shell.get_tags()}")
                print()
                
            except Exception as e:
                print(f"创建 {name} 壳 (厚度 {thickness}) 失败: {e}")
                print()

check_shell_quality()

壳的修复和优化

from simplecadapi import make_box_rsolid, shell_rsolid

def optimize_shell():
    """优化壳的结构"""
    
    # 创建基础壳
    base_solid = make_box_rsolid(width=6, height=4, depth=3)
    shell = shell_rsolid(base_solid, thickness=0.2)
    shell.add_tag("original_shell")
    
    faces = shell.get_faces()
    
    # 分析和标记面
    optimized_faces = []
    removed_faces = []
    
    total_area = sum(face.get_area() for face in faces)
    avg_area = total_area / len(faces)
    
    for i, face in enumerate(faces):
        area = face.get_area()
        face.add_tag(f"face_{i}")
        face.set_metadata("original_area", area)
        
        # 检查面的质量
        if area < avg_area * 0.01:  # 极小面
            face.add_tag("tiny_face")
            face.add_tag("candidate_for_removal")
            removed_faces.append(face)
        elif area > avg_area * 10:  # 极大面
            face.add_tag("oversized_face")
            face.add_tag("needs_subdivision")
            optimized_faces.append(face)
        else:
            face.add_tag("normal_face")
            optimized_faces.append(face)
    
    # 创建优化信息
    shell.set_metadata("original_face_count", len(faces))
    shell.set_metadata("optimized_face_count", len(optimized_faces))
    shell.set_metadata("removed_face_count", len(removed_faces))
    shell.set_metadata("total_area", total_area)
    
    # 标记优化结果
    if len(removed_faces) > 0:
        shell.add_tag("has_removable_faces")
    
    if len(optimized_faces) == len(faces):
        shell.add_tag("well_formed")
    else:
        shell.add_tag("needs_optimization")
    
    print(f"壳优化分析:")
    print(f"  原始面数: {len(faces)}")
    print(f"  优化后面数: {len(optimized_faces)}")
    print(f"  移除面数: {len(removed_faces)}")
    print(f"  总面积: {total_area:.3f}")
    print(f"  平均面积: {avg_area:.3f}")
    print(f"  优化标签: {shell.get_tags()}")
    
    return shell, optimized_faces, removed_faces

shell, optimized_faces, removed_faces = optimize_shell()

壳的比较和分析

from simplecadapi import make_box_rsolid, make_cylinder_rsolid, shell_rsolid

def compare_shells():
    """比较不同类型的壳"""
    
    # 创建不同的基础几何体
    geometries = [
        ("box", make_box_rsolid(width=4, height=4, depth=4)),
        ("cylinder", make_cylinder_rsolid(center=(0, 0, 0), radius=2, height=4)),
    ]
    
    shells = []
    
    for name, geometry in geometries:
        # 创建不同厚度的壳
        for thickness in [0.1, 0.2, 0.3]:
            shell = shell_rsolid(geometry, thickness=thickness)
            shell.add_tag(f"{name}_shell")
            shell.add_tag(f"thickness_{thickness}")
            
            faces = shell.get_faces()
            
            # 计算几何属性
            total_area = sum(face.get_area() for face in faces)
            face_count = len(faces)
            
            # 计算复杂度指标
            edge_count = sum(len(face.get_outer_wire().get_edges()) for face in faces)
            complexity = edge_count / face_count if face_count > 0 else 0
            
            shell.set_metadata("base_geometry", name)
            shell.set_metadata("thickness", thickness)
            shell.set_metadata("face_count", face_count)
            shell.set_metadata("edge_count", edge_count)
            shell.set_metadata("total_area", total_area)
            shell.set_metadata("complexity", complexity)
            
            # 分类复杂度
            if complexity < 5:
                shell.add_tag("simple")
            elif complexity < 8:
                shell.add_tag("moderate")
            else:
                shell.add_tag("complex")
            
            shells.append(shell)
    
    # 比较分析
    print("壳比较分析:")
    print("=" * 50)
    
    for shell in shells:
        base_geo = shell.get_metadata("base_geometry")
        thickness = shell.get_metadata("thickness")
        face_count = shell.get_metadata("face_count")
        total_area = shell.get_metadata("total_area")
        complexity = shell.get_metadata("complexity")
        
        print(f"{base_geo} 壳 (厚度 {thickness}):")
        print(f"  面数: {face_count}")
        print(f"  总面积: {total_area:.3f}")
        print(f"  复杂度: {complexity:.2f}")
        print(f"  分类: {[tag for tag in shell.get_tags() if tag in ['simple', 'moderate', 'complex']]}")
        print()
    
    return shells

shell_comparison = compare_shells()

字符串表示

from simplecadapi import make_box_rsolid, shell_rsolid

box = make_box_rsolid(width=5, height=3, depth=2)
shell = shell_rsolid(box, thickness=0.2)
shell.add_tag("example_shell")
shell.set_metadata("thickness", 0.2)

print(shell)

输出:

Shell:
  face_count: 10
  faces:
    face_0:
      area: 6.000
      normal: [0.000, 0.000, 1.000]
      outer_wire:
        Wire:
          edge_count: 4
          closed: True
    face_1:
      area: 6.000
      normal: [0.000, 0.000, -1.000]
      outer_wire:
        Wire:
          edge_count: 4
          closed: True
    ...
  tags: [example_shell]
  metadata:
    thickness: 0.2

与其他几何体的关系

  • 面 (Face): 壳的组成元素
  • 实体 (Solid): 壳可以封闭形成实体
  • 复合体 (Compound): 多个壳可以组成复合体

应用场景

  • 薄壁结构: 容器、外壳等
  • 建筑表面: 建筑物的外立面
  • 工业设计: 产品外观设计
  • 有限元分析: 薄壁结构的网格生成

注意事项

  • 壳可能是开放的或闭合的
  • 闭合的壳可以形成实体
  • 壳的厚度影响最终的几何形状
  • 复杂壳可能包含大量小面,影响性能
  • 壳的质量直接影响后续操作的成功率
  • 某些操作可能导致壳的拓扑结构发生变化