Files
make-cad/docs/LocalCoordinateSystem.md
T
2025-06-30 23:12:35 +08:00

7.1 KiB

LocalCoordinateSystem 类文档

概述

LocalCoordinateSystem是一个上下文管理器类,用于临时切换到指定的局部坐标系。它使用Python的with语句来管理坐标系的切换,确保在代码块执行完毕后自动恢复原来的坐标系。

类定义

class LocalCoordinateSystem:
    """局部坐标系上下文管理器"""

构造函数

def __init__(self, 
             origin: Tuple[float, float, float], 
             x_axis: Tuple[float, float, float], 
             y_axis: Tuple[float, float, float])

参数

  • origin: 新坐标系的原点位置
  • x_axis: 新坐标系的X轴方向
  • y_axis: 新坐标系的Y轴方向

属性

  • cs: CoordinateSystem对象,封装的坐标系

方法

enter()

进入上下文时的操作

  • 将新坐标系压入坐标系栈
  • 返回: CoordinateSystem对象

exit(exc_type, exc_val, exc_tb)

退出上下文时的操作

  • 从坐标系栈中弹出当前坐标系
  • 自动恢复到上一个坐标系

相关函数

get_current_cs() -> CoordinateSystem

获取当前活动的坐标系

  • 返回: 当前坐标系对象
  • 从全局坐标系栈的顶部获取

使用示例

基本用法

from simplecadapi.core import LocalCoordinateSystem, get_current_cs
from simplecadapi.operations import make_point

# 查看默认坐标系
print(f"默认坐标系: {get_current_cs()}")

# 使用局部坐标系
with LocalCoordinateSystem(
    origin=(10, 5, 0),
    x_axis=(1, 0, 0),
    y_axis=(0, 1, 0)
) as local_cs:
    print(f"局部坐标系: {get_current_cs()}")
    
    # 在局部坐标系中创建点
    point = make_point(1, 1, 0)  # 局部坐标(1,1,0)
    print(f"点的全局坐标: {point.global_coords}")  # 应该是(11,6,0)

# 自动恢复到原坐标系
print(f"恢复后的坐标系: {get_current_cs()}")

嵌套坐标系

from simplecadapi.operations import make_rectangle

# 第一层局部坐标系
with LocalCoordinateSystem(
    origin=(10, 0, 0),
    x_axis=(1, 0, 0),
    y_axis=(0, 1, 0)
) as cs1:
    print(f"第一层坐标系原点: {get_current_cs().origin}")
    
    # 嵌套第二层局部坐标系
    with LocalCoordinateSystem(
        origin=(0, 10, 0),   # 相对于cs1的偏移
        x_axis=(0, 1, 0),    # 90度旋转
        y_axis=(-1, 0, 0)
    ) as cs2:
        print(f"第二层坐标系原点: {get_current_cs().origin}")
        
        # 在嵌套坐标系中创建几何体
        rect = make_rectangle(5, 3)
        
    print(f"退出第二层,当前坐标系: {get_current_cs().origin}")
    
print(f"完全退出,当前坐标系: {get_current_cs().origin}")

在不同坐标系中创建几何体

from simplecadapi.operations import make_box, extrude
from simplecadapi.core import LocalCoordinateSystem

# 创建多个在不同坐标系中的立方体
boxes = []

# 第一个立方体:默认坐标系
box1 = make_box(2, 2, 2)
boxes.append(("默认坐标系", box1))

# 第二个立方体:平移坐标系
with LocalCoordinateSystem(
    origin=(5, 0, 0),
    x_axis=(1, 0, 0),
    y_axis=(0, 1, 0)
):
    box2 = make_box(2, 2, 2)
    boxes.append(("平移坐标系", box2))

# 第三个立方体:旋转坐标系
with LocalCoordinateSystem(
    origin=(0, 5, 0),
    x_axis=(0, 1, 0),     # X轴指向Y方向
    y_axis=(-1, 0, 0)     # Y轴指向-X方向
):
    box3 = make_box(2, 2, 2)
    boxes.append(("旋转坐标系", box3))

for name, box in boxes:
    print(f"{name}中的立方体: {box}")

倾斜平面上的草图

from simplecadapi.operations import make_circle, extrude
import math

# 创建倾斜45度的坐标系
angle = math.pi / 4  # 45度
with LocalCoordinateSystem(
    origin=(0, 0, 0),
    x_axis=(1, 0, 0),
    y_axis=(0, math.cos(angle), math.sin(angle))  # 倾斜的Y轴
):
    # 在倾斜平面上创建圆形草图
    circle_sketch = make_circle(3)
    
    # 垂直拉伸(相对于倾斜平面)
    cylinder = extrude(circle_sketch, distance=5)
    print(f"倾斜圆柱体: {cylinder}")

复杂装配中的坐标系管理

def create_component_at_position(pos, orientation):
    """在指定位置和方向创建组件"""
    x_axis, y_axis = orientation
    
    with LocalCoordinateSystem(pos, x_axis, y_axis):
        # 组件由多个基础几何体组成
        base = make_box(4, 4, 1)
        
        # 在组件坐标系中继续操作
        with LocalCoordinateSystem(
            origin=(0, 0, 1),
            x_axis=(1, 0, 0),
            y_axis=(0, 1, 0)
        ):
            pillar = make_cylinder(0.5, 3)
            
        return base, pillar

# 创建多个组件
components = []

# 组件1:原点位置,默认方向
comp1 = create_component_at_position(
    (0, 0, 0), 
    ((1, 0, 0), (0, 1, 0))
)
components.append(comp1)

# 组件2:平移位置,旋转方向
comp2 = create_component_at_position(
    (10, 0, 0),
    ((0, 1, 0), (-1, 0, 0))  # 90度旋转
)
components.append(comp2)

print(f"创建了 {len(components)} 个组件")

坐标系栈的手动管理(不推荐)

from simplecadapi.core import _current_cs, CoordinateSystem

# 查看当前坐标系栈深度
print(f"坐标系栈深度: {len(_current_cs)}")

# 手动创建坐标系(不推荐,请使用with语句)
manual_cs = CoordinateSystem(origin=(5, 5, 5))

# 注意:直接操作_current_cs是不安全的
# _current_cs.append(manual_cs)  # 不推荐
# # 进行操作...
# _current_cs.pop()  # 容易忘记,导致栈不平衡

# 推荐使用with语句
with LocalCoordinateSystem(origin=(5, 5, 5), x_axis=(1, 0, 0), y_axis=(0, 1, 0)):
    # 安全的坐标系切换
    pass

异常处理中的坐标系管理

def safe_operation_in_local_cs():
    """演示异常情况下坐标系的正确恢复"""
    print(f"操作前坐标系: {get_current_cs().origin}")
    
    try:
        with LocalCoordinateSystem(
            origin=(100, 100, 100),
            x_axis=(1, 0, 0),
            y_axis=(0, 1, 0)
        ):
            print(f"局部坐标系: {get_current_cs().origin}")
            
            # 模拟可能抛出异常的操作
            if True:  # 修改为False可以避免异常
                raise ValueError("模拟操作失败")
                
            # 正常的几何操作
            box = make_box(1, 1, 1)
            return box
            
    except ValueError as e:
        print(f"捕获异常: {e}")
        return None
    
    finally:
        # with语句确保即使发生异常也能正确恢复坐标系
        print(f"操作后坐标系: {get_current_cs().origin}")

# 测试异常安全性
result = safe_operation_in_local_cs()
print(f"最终坐标系: {get_current_cs().origin}")  # 应该是默认坐标系

注意事项

  1. 总是使用with语句来确保坐标系的正确恢复
  2. 支持任意深度的嵌套坐标系
  3. 异常安全:即使发生异常也会正确恢复坐标系
  4. 不要直接操作_current_cs列表,使用上下文管理器
  5. 局部坐标系中创建的所有几何体都会自动转换到全局坐标系
  6. 坐标系的切换不影响已创建的几何体
  7. 嵌套坐标系的变换是累积的(相对变换)