CadQuery中非默认方向圆柱体的质心计算问题分析

问题描述

在CadQuery项目中，当用户创建非默认方向的圆柱体时，发现质心位置计算存在异常。具体表现为：当圆柱体方向向量为默认的(0,0,1)时，质心计算正确；但当方向向量为其他值(如(1,0,0)或(0,1,0))时，质心位置出现明显偏移。

技术背景

CadQuery是一个基于Python的参数化CAD建模框架，它使用OpenCASCADE作为底层几何引擎。在CadQuery中，圆柱体是通过Workplane.cylinder()方法创建的，该方法最终调用Solid.makeCylinder()来生成几何体。

问题重现

通过以下代码可以重现该问题：

# 默认方向(0,0,1) - 质心正确
cq.Shape.centerOfMass(cq.Workplane("XY").cylinder(radius=1, height=10, direct=cq.Vector(0, 0, 1)).val())
# 返回: Vector: (-1.55e-16, -2.79e-17, 0.0) ≈ (0,0,0)

# X方向(1,0,0) - 质心错误
cq.Shape.centerOfMass(cq.Workplane("XY").cylinder(radius=1, height=10, direct=cq.Vector(1, 0, 0)).val())
# 返回: Vector: (5.0, 6.26e-18, -5.0)

# Y方向(0,1,0) - 质心错误
cq.Shape.centerOfMass(cq.Workplane("XY").cylinder(radius=1, height=10, direct=cq.Vector(0, 1, 0)).val())
# 返回: Vector: (-6.26e-18, 5.0, -5.0)

问题根源分析

问题出在Workplane.cylinder方法的实现中。当创建圆柱体时，代码会根据centered参数调整圆柱体的位置偏移量(offset)，但这些偏移量的计算没有考虑方向向量(direct)的影响。

具体来说，代码中计算偏移量的部分如下：

offset = Vector()
if not centered[0]:
    offset += Vector(radius, 0, 0)
if not centered[1]:
    offset += Vector(0, radius, 0)
if centered[2]:
    offset += Vector(0, 0, -height / 2)

这段代码假设圆柱体的方向始终是Z轴方向(0,0,1)，因此在计算偏移量时直接在X、Y、Z坐标上进行加减。当圆柱体方向改变时，这些偏移量没有被正确地转换到新的坐标系中，导致质心计算错误。

解决方案建议

要解决这个问题，需要对偏移量进行坐标系转换。具体来说：

1. 首先计算在默认坐标系(方向为(0,0,1))下的偏移量
2. 然后根据实际的方向向量(direct)构建旋转矩阵
3. 最后将偏移量应用这个旋转矩阵，得到在新坐标系下的正确偏移量

这种方法可以确保无论圆柱体的方向如何，偏移量都能被正确地应用，从而保证质心计算的准确性。

临时解决方案

在官方修复此问题前，用户可以手动调整圆柱体的位置。例如，对于X方向的圆柱体，可以这样创建：

# 手动调整位置
cyl = cq.Workplane("XY").cylinder(radius=1, height=10, direct=cq.Vector(1, 0, 0))
cyl = cyl.translate((0, 0, 5))  # 手动调整位置

总结

这个问题揭示了CadQuery在处理非默认方向几何体时的一个局限性。理解这个问题的根源有助于用户在使用CadQuery进行复杂建模时避免类似的陷阱。对于开发者来说，这也提示我们需要更加全面地考虑几何变换对各类操作的影响。