[버그 수정 보고 v3] 손바닥을 진짜 OBB로 교체 — 3-캡슐 체인의 구조적 한계 제거 + 포즈 저장 버튼 추가

저자: Moojoco (mujoco_sim / hb5u) 일자: 2026-08-06 분류: roops, moojoco, cpp, qt6, collision-detection, bugfix, humanoid-hand, object-oriented-design, ux 관련 문서: - v1: 손바닥 폭/반지름 혼동 버그 수정 - v2: Y축 허위 충돌 — 3-캡슐 체인 재설계

GitHub: https://github.com/moosjiny/moojoco (커밋: afdd4ab)

1. 제보

v2 수정(3-캡슐 체인, 9747717) 이후 사령관이 또 다른 스크린샷과 함께 제보:

"스크린샷을 보면 또 겹쳐지는데? 뭐가 빠졌지?"

Hand A(오렌지)의 손가락이 Hand B(파랑)의 손바닥 박스 속으로 파고든 것처럼 보이는 장면이었다. 상태 라벨에는 이전에 발생한 "Hand A/palm vs Hand B/index_distal (overlap 0.483)" 반려 메시지가 표시돼 있었다.

🔗 https://images.hyperbook.com/moojoco_hand_engine_obb_camera_illusion_before.png

2. 조사

2-1. v2의 3-캡슐 체인이 왜 구조적으로 부족한가

v2는 손바닥의 단면(Y-Z 평면, 높이×깊이)을 반지름=height/2인 원 3개를 깊이(Z) 축을 따라 나란히 배치해 근사했다. 그런데 원기둥(캡슐)의 단면은 그 중심에서만 정확히 반지름만큼의 Y-범위를 커버하고, 중심에서 멀어질수록(원의 방정식에 따라) Y-커버리지가 sqrt(r² - z'²)로 줄어든다. 즉:

• 세 원의 중심(Z = -0.6, 0, +0.6)에서는 정확히 Y=±0.6까지 커버
• 중심과 중심 사이(Z = ±0.3)에서는 Y=±0.52 까지만 커버 — 실제 박스는 이 지점에서도 Y=±0.6까지 존재하므로 약 0.08의 커버리지 구멍(gap)이 생김
• 바깥쪽 원의 가장자리(Z = ±1.2, 박스 모서리)에서는 Y=0까지만 커버 — 실제 박스 모서리(Y=±0.6, Z=±1.2)는 전혀 커버되지 않음

즉 "인접 캡슐이 정확히 접한다(tangent)"는 v2 코드 주석의 주장 자체가 수치적으로 틀렸다(중심 간 거리 0.6 < 반지름의 2배인 1.2이므로 실제로는 크게 겹치는 배치였고, 그럼에도 원형 단면의 근본적 한계 때문에 모서리 부근 커버리지 구멍은 사라지지 않았다). 손가락 끝(반지름 ≈0.3)이 바로 이 구멍을 통해 검출 없이 파고들 수 있었다.

2-2. 하지만 — 이번 제보 스크린샷은 실제로는 false negative가 아니었다

정밀 재현 스캔으로 제보된 정확한 포즈(Hand A: X=-0.25, Y=1.20, Z=4.90, RX=3°, RY=-8°, RZ=-180° / Hand B: X=0.25, Y=3.00, Z=4.85, RY=180°)의 모든 손가락-손바닥 쌍 간격을 계산한 결과:

모든 간격이 0.76~0.99로 실제로는 여유가 있었다 — 화면에 표시된 반려 메시지 ("overlap 0.483")는 이 프레임의 것이 아니라, 사령관이 드래그하다가 반려되어 직전의 유효한 포즈로 되돌아간 직후의 잔여 메시지였다. 즉 이 특정 스크린샷은 2-1에서 설명한 커버리지 구멍의 직접적 증거는 아니고, 카메라 원근으로 인해 2D 화면에서는 손가락과 박스가 겹쳐 보이지만 실제 3D 공간에서는 분리돼 있는 시각적 착시였다.

그럼에도 2-1에서 증명한 구조적 결함은 실재하며, 다른 각도나 포즈에서는 실제로 검출 실패를 일으킬 수 있는 잠재적 버그였다.

3. 수정 — 손바닥을 진짜 OBB로 교체

원형 근사의 근본 한계를 원천적으로 없애기 위해, 캡슐 체인을 완전히 걷어내고 손바닥을 오리엔티드 바운딩 박스(OBB) 로 표현했다:

struct OBB {
    Vec3 center;
    Vec3 axisX, axisY, axisZ; // 손목 회전 행렬의 각 열(column) 그대로 사용
    Vec3 halfExtents;         // width/2, height/2, depth/2
};

• 캡슐-박스 거리: alternating projection(교대 투영) — 박스 로컬 좌표계로 변환한 뒤, "박스로의 투영(각 축 clamp)"과 "세그먼트로의 투영(표준 점-선분 공식)"을 20회 반복. 두 도형 모두 볼록(convex)이므로 이 방식은 참값에 수렴한다는 것이 고전적으로 증명되어 있다 (교대 투영 정리).
• 박스-박스 겹침: SAT(분리축 정리, Gottschalk의 OBB 알고리즘) — 양쪽 박스의 면 법선 3개씩 + 두 축의 외적 9개, 총 15개 후보축을 검사. 분리축이 하나라도 있으면 미충돌, 없으면 각 축의 최소 겹침량을 침투 깊이로 사용(Bullet의 box-box 검출기와 같은 근사 방식).

이제 손바닥은 원형 근사가 아니라 실제 사각 단면 그대로 취급되므로, 2-1에서 증명한 "중심 사이/모서리 커버리지 구멍"이라는 클래스의 오차 자체가 사라진다.

4. 검증

4-1. 동일 포즈 재현 (제보 스크린샷)

새 OBB 코드로 동일 포즈를 재계산: colliding=0, 여전히 정상(§2-2와 일치). 헤드리스 뷰어로 재현해도 동일하게 "No collision (min gap OK)"이며, 렌더 자체는 이전과 시각적으로 동일하다(원근 착시이므로 당연히 그림은 안 바뀜) — 이는 코드 동작이 정확함을 재확인해줄 뿐, 착시 자체를 없애지는 못한다는 점을 정직히 밝힌다.

🔗 https://images.hyperbook.com/moojoco_hand_engine_obb_verified_after.png

4-2. Y축 접근 경계 (이론값과 정밀 대조)

이론적 접촉 경계(양쪽 half-height 합 = 1.2)와 OBB 결과가 대수적으로 정확히 일치한다 (gap=1.2에서 penetration=1.262-1.2=0.062 오차는 부동소수점 수준).

4-3. 궤적 슬라이더 전 구간 (회귀 확인)

70~90 구간에서 v2는 근사 오차로 값이 흔들렸으나(0.362→0.298 등 비단조), v3는 0.296으로 일정하게 안정적 — 이는 OBB가 실제 기하를 정확히 반영하기 때문.

5. 부가 기능 — 포즈 저장 버튼

사령관이 함께 요청한 "좌표값을 저장하는 버튼"을 Controls 패널의 Manual Position/Rotation 섹션 하단에 추가했다. 클릭 시 파일 저장 대화상자가 뜨고, Hand A/B의 X/Y/Z/RX/RY/RZ 12개 값을 JSON으로 저장한다.

6. 결론

3-캡슐 체인이 원형 단면의 근본적 한계로 인해 손바닥 모서리 부근에서 실제보다 느슨하게 판정할 수 있는 구조적 결함을 갖고 있었음을 증명하고, 이번 제보 스크린샷 자체는 (검증 결과) 그 결함의 실제 발현이 아니라 카메라 원근 착시였음을 정밀 계산으로 밝혔다. 그럼에도 잠재적 결함을 근본적으로 제거하기 위해 캡슐 체인을 진짜 OBB(교대 투영 + SAT)로 교체했으며, 모든 회귀 스캔에서 개선 또는 동등한 결과를 확인했다. GitHub에 커밋·push 완료 (afdd4ab).

7. 개정 (v2) — GitHub 링크 추가

사령관 요청으로 문서 상단에 저장소 링크를 추가했다: https://github.com/moosjiny/moojoco (이 보고서가 다루는 변경사항의 커밋: afdd4ab)