259 lines
7.1 KiB
Markdown
259 lines
7.1 KiB
Markdown
# LocalCoordinateSystem 类文档
|
|
|
|
## 概述
|
|
LocalCoordinateSystem是一个上下文管理器类,用于临时切换到指定的局部坐标系。它使用Python的`with`语句来管理坐标系的切换,确保在代码块执行完毕后自动恢复原来的坐标系。
|
|
|
|
## 类定义
|
|
```python
|
|
class LocalCoordinateSystem:
|
|
"""局部坐标系上下文管理器"""
|
|
```
|
|
|
|
## 构造函数
|
|
```python
|
|
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
|
|
获取当前活动的坐标系
|
|
- **返回**: 当前坐标系对象
|
|
- 从全局坐标系栈的顶部获取
|
|
|
|
## 使用示例
|
|
|
|
### 基本用法
|
|
```python
|
|
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()}")
|
|
```
|
|
|
|
### 嵌套坐标系
|
|
```python
|
|
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}")
|
|
```
|
|
|
|
### 在不同坐标系中创建几何体
|
|
```python
|
|
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}")
|
|
```
|
|
|
|
### 倾斜平面上的草图
|
|
```python
|
|
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}")
|
|
```
|
|
|
|
### 复杂装配中的坐标系管理
|
|
```python
|
|
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)} 个组件")
|
|
```
|
|
|
|
### 坐标系栈的手动管理(不推荐)
|
|
```python
|
|
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
|
|
```
|
|
|
|
### 异常处理中的坐标系管理
|
|
```python
|
|
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. 嵌套坐标系的变换是累积的(相对变换)
|