如何解决Mujoco编译时的QH6154 qhull精度错误？

问题背景 #

使用Mujoco编译带有OBJ文件的3D对象时，触发Qhull的QH6154精度错误，错误日志如下：

QH6154 qhull precision error: initial facet 1 is coplanar with the interior point
ERRONEOUS FACET:
- f1
    - flags: bottom simplicial flipped
    - normal:         0        0       -1
    - offset:       0.52
    - vertices: p2(v2) p1(v1) p0(v0)
    - neighboring facets: f2 f3 f4

While executing:  | qhull Qt
Options selected for Qhull 2012.1 2012/02/18:
  run-id 1640577472  Qtriangulate  _pre-merge  _zero-centrum  _max-width 1.1
  Error-roundoff 8.5e-16  _one-merge 5.9e-15  _near-inside 3e-14
  Visible-distance 1.7e-15  U-coplanar-distance 1.7e-15  Width-outside 3.4e-15
  _wide-facet 1e-14

precision problems (corrected unless 'Q0' or an error)
      2 flipped facets
      2 degenerate hyperplanes recomputed with gaussian elimination
      4 nearly singular or axis-parallel hyperplanes
      2 zero divisors during back substitute
      3 zero divisors during gaussian elimination

The input to qhull appears to be less than 3 dimensional, or a
computation has overflowed.

Qhull could not construct a clearly convex simplex from points:
- p3(v3):  0.45  0.28  0.52
- p2(v2):  0.45 -0.26  0.52
- p1(v1):  0.45  0.28  0.52
- p0(v0): -0.61 -0.26  0.52

The center point is coplanar with a facet, or a vertex is coplanar
with a neighboring facet.  The maximum round off error for
computing distances is 8.5e-16.  The center point, facets and distances
to the center point are as follows:

center point    0.185     0.01     0.52

facet p2 p1 p0 distance=    0
facet p3 p1 p0 distance= -0.12
facet p3 p2 p0 distance=    0
facet p3 p2 p1 distance= -0.27

These points either have a maximum or minimum x-coordinate, or
they maximize the determinant for k coordinates.  Trial points
are first selected from points that maximize a coordinate.

The min and max coordinates for each dimension are:
  0:     -0.61      0.45  difference= 1.06
  1:     -0.26      0.28  difference= 0.54
  2:      0.52      0.52  difference=    0

If the input should be full dimensional, you have several options that
may determine an initial simplex:
  - use 'QJ'  to joggle the input and make it full dimensional
  - use 'QbB' to scale the points to the unit cube
  - use 'QR0' to randomly rotate the input for different maximum points
  - use 'Qs'  to search all points for the initial simplex
  - use 'En'  to specify a maximum roundoff error less than 8.5e-16.
  - trace execution with 'T3' to see the determinant for each point.

If the input is lower dimensional:
  - use 'QJ' to joggle the input and make it full dimensional
  - use 'Qbk:0Bk:0' to delete coordinate k from the input.  You should
    pick the coordinate with the least range.  The hull will have the
    correct topology.
  - determine the flat containing the points, rotate the points
    into a coordinate plane, and delete the other coordinates.
  - add one or more points to make the input full dimensional.
Error: qhull error
Object name = original-10, id = 0
Traceback (most recent call last):
  File "/home/curious-sapien/datagen/SyntheticArticulatedData/sapien_dataset/dataset_tools.py", line 327, in <module>
    generate_mujoco_scene_xml(urdf_file=args.input_files[0], xml_file=args.output_files[0], obj_type=args.obj_type)
  File "/home/curious-sapien/datagen/SyntheticArticulatedData/sapien_dataset/dataset_tools.py", line 64, in generate_mujoco_scene_xml
    xml_tree = ET.parse(xml_file)
  File "/usr/lib/python3.10/xml/etree/ElementTree.py", line 1222, in parse
    tree.parse(source, parser)
  File "/usr/lib/python3.10/xml/etree/ElementTree.py", line 569, in parse
    source = open(source, "rb")

已尝试无效的方案 #

• 将OBJ文件中所有数值截断至小数点后三位
• 使用Qhull的QJ参数扰动输入

核心问题分析 #

从日志可见，所有点的Z坐标均为0.52（维度2的差值为0），说明输入点集是二维平面结构，Qhull无法在3D空间中构建有效凸包，这是触发错误的根本原因。此外日志中存在重复点（p1和p3坐标完全一致），进一步加剧了共面问题。

针对性解决思路 #

1. 处理维度冗余问题 #

• 删除冗余坐标：直接移除所有点的Z坐标，将3D点转为2D点后再进行凸包计算；或在Qhull参数中指定Qbk:2Bk:0，删除第3个维度（Z轴），让Qhull在2D空间处理
• 手动添加扰动：给每个点的Z坐标添加微小随机值（如1e-8，需大于Qhull的误差阈值8.5e-16但不影响模型形状），不要依赖Qhull自带的QJ，手动控制扰动幅度更可靠

2. 调整Qhull参数 #

• 使用Qs参数：让Qhull遍历所有点寻找初始单纯形，避免只选中极值点导致的共面问题
• 使用QbB参数：将所有点缩放到单位立方体，缩小数值范围以减少精度误差，配合小数截断操作效果更好
• 尝试En参数：设置更小的最大舍入误差，如En1e-17，但需注意可能引发其他数值稳定性问题

3. 修复OBJ文件几何结构 #

• 检查OBJ导出流程，确认是否误将Z轴固定，确保模型是真正的3D结构
• 删除OBJ文件中的重复点，减少共面情况的出现

4. 调整Mujoco配置 #

• 若通过URDF转MJCF，检查URDF中碰撞体的几何参数设置，避免强制对平面结构生成凸包
• 将碰撞体类型改为mesh，绕开Qhull的凸包计算流程

内容的提问来源于stack exchange，提问作者Anmol Gupta