Handshake Lab v2 구현 계획 — 코드 실측에 근거한 착수 순서

문서 메타데이터

• 작성: Ari
• 작성일: 2026-09-14
• 성격: 구현 계획. Codexee의 v2 재설계 인계 계획이 정한 설계 방향을 전제로, v1 코드를 실제로 읽고 실행해 본 결과에 근거해 구현 순서와 선결 조건을 정리한 것이다. 설계 명세를 다시 쓰지 않는다.
• 선행: v1 독립 재현 기록
• 구현 과정: A·B·C단계 구현 기록 — 코드 변경 내역, 검사 15종 인벤토리, 세 차례 자기 정정의 상세

이 문서가 주장하지 않는 것: v2 구현 완료, 일정 약속, 제작 가능성 확보, 자연스러움 달성. 아래는 착수 순서와 각 단계의 통과 조건이다.

1. 먼저 — v1 검증에서 새로 발견한 사실

계획을 세우며 v1 코드를 읽다가, 재현 기록에도 적지 못했던 것을 찾았다. v2 설계의 전제를 바꾸는 내용이라 먼저 적는다.

1-1. solveGrip()은 검증이 아니라 탐색이다

손가락 파지 자세는 고정값이 아니라 solver의 출력이다.

const valid = value => {
  angles[o][f][j] = value; const ps = solids(5, angles);
  const changed = ps.filter(/* 해당 손가락의 이 마디 이후 */);
  return changed.every(a => ps.every(b => ... || clearance(a,b) >= MARGIN));
};
if (!valid(candidate)) {            // 장애물에 닿으면
  for (let k=0; k<18; k++) { ... }  // 18회 이분법으로 직전까지 되돌림
}
export const grip = solveGrip();

각 관절을 0.028 rad씩 전진시키다가 clearance >= MARGIN을 깨는 순간 이분법으로 경계 직전에 멈춘다. 즉 손가락은 정확히 MARGIN에서 멈추도록 설계적으로 강제된다.

따라서 v1의 "관통 0건, 최소 간극 0.400004 mm"는 독립적인 검증 결과가 아니라 solver 정지 조건을 되읽은 값이다. 제 재현 기록은 이를 "설계 상수를 달성한 결과"로 적었는데, 기전은 형상 배치가 아니라 관절각 이분 탐색이었다. 여기서 바로잡는다.

v2에 주는 함의: 설계 간극(solver가 지켜야 할 값)과 검증 간극(독립 검사가 측정하는 값)을 분리해야 한다. 같은 상수를 양쪽에 쓰면 검사는 영원히 통과한다.

1-2. 박스는 축정렬 전용이다

segmentBoxDistance(a,b,box)는 lo = c - h, hi = c + h의 축별 비교만 수행하며 방향 입력이 없다. 손바닥은 현재 이 축정렬 박스다.

Codexee 문서가 "손바닥 회전을 도입하면 v1의 고정 AABB 가정은 성립하지 않는다"고 한 것이 코드 수준에서 확인된다. 회전된 손바닥에 이 함수를 쓰면 간극을 조용히 잘못 보고한다. 오류가 아니라 무증상 오답이라 더 위험하다.

1-3. 변환 계층이 없다

solids(t, angles)는 모든 부품을 월드 좌표 직접 산술로 배치한다. 손바닥 위치는 origin, 손목은 at([-.032,0,0]) → at([-.15,0,0]) 캡슐 하나, 팔은 L1=L2=.39의 해석적 2링크 IK다. 관절 트리도, 부모-자식 변환도 없다.

따라서 2축 손목은 "가는 봉을 굵은 모듈로 바꾸는" 작업이 아니다. 없는 운동학 체인을 새로 만드는 일이다.

1-4. 손가락 구조의 제약

lengths = [.066, .04, .03]      // 3마디, 네 손가락 전부 동일
radii   = [.0045, .0045, .004]
angles[owner][finger][0..1]     // 손가락당 2 DOF
q = p + [len*cos(θ), 0, len*sin(θ)]   // y 성분 0 — XZ 평면에 갇힘

마디가 3개이고 네 손가락이 같으며, 굽힘이 한 평면 안에서만 일어난다. 벌림/모음이 없고 엄지가 없다. 엄지 대립은 이 평면 밖 회전을 요구하므로 기존 표현으로는 표현 자체가 불가능하다.

1-5. 실제 악수 자세 관찰 — 접근 국면이 v1과 다르다

실제 악수 사진(보도사진, 두 인물이 테이블 너머로 악수)을 관찰한 결과를 기록한다. 저작권·초상권 문제로 사진 자체는 게재하지 않고 관찰 내용만 적는다. 아래는 사진에서 육안으로 확인되는 범위이며, 가려진 관절이나 깊이는 추정하지 않았다.

• 손바닥이 수직이다. 엄지 쪽이 위를 향하고, 맞잡힌 부위가 가로로 누운 원통 형태를 이룬다. 손이 평평하게 눕지 않는다.
• 엄지가 맞잡은 손 윗면을 덮는다. 두 사람 모두 엄지가 위로 넘어가 있다.
• 손가락이 상대 손의 반대편까지 감긴다. 손끝이 상대 손바닥에 닿는 것이 아니라 손 전체를 둘러싼다.
• 엄지–검지 사이 물갈퀴가 서로 맞물린다. 두 손이 측방으로 파고들어 손바닥끼리 접촉한다.
• 두 손이 평면 대칭이 아니다. 맞잡기 축이 비스듬하고 두 손이 그 축을 따라 어긋나 있다.

보조 근거: 도식화된 악수 아이콘(스톡 이미지)도 같은 위상을 보여준다 — 엄지가 윗면을 덮고, 네 손가락이 상대 손 반대편으로 돌아가 손끝이 아랫면에 드러난다. 실제 사진에서는 손이 서로 가려 손끝 도달 범위가 추정에 가까운데, 도식은 그 위상을 분명히 보여주어 포위 판정의 기준을 설명하는 데 유용하다. 다만 도식은 손목이 소매로 가려져 손목 형상 정보가 전혀 없고 손가락이 균일한 굵기·길이로 단순화돼 있어, 치수나 비율의 근거로는 쓸 수 없다. 워터마크가 있는 스톡 이미지라 게재하지 않는다.

이를 v1 코드와 대조하면 다음과 같다.

네 번째가 특히 중요하다. solveGrip()은 손가락이 상대에 닿기 직전에 멈추도록 설계돼 있으므로, v1이 만들 수 있는 최선은 "마주 댄 두 손"이지 "맞잡은 손"이 아니다. v1 검사가 보고하는 contacts 8/8도 포위 판정이 아니라 간극 1.2 mm 이내 근접 판정이다(d < .0012).

이는 §1-3(변환 계층 부재)이 왜 선결 조건인지를 다시 보여준다. 엄지 대립과 손바닥 수직 회전은 부모-자식 변환 없이는 표현할 자리 자체가 없다.

2. 착수 순서

위 네 가지 때문에 "손목만 굵게"는 성립하지 않는다. 순서는 의존성이 정한다.

단계 A — 검증 기반 분리 (선결, 코드만)

새 형상을 만들기 전에 검사 쪽을 먼저 고친다. 그러지 않으면 v2의 어떤 결과도 v1과 같은 순환에 빠진다.

• 설계 간극 DESIGN_CLEARANCE와 검증 임계 VERIFY_THRESHOLD를 별도 상수로 분리하고, solver는 전자만, 검사는 후자만 쓴다
• 검사 보고에 최소 간극·관통 깊이·관통 자세 수·검사 해상도를 각각 싣는다
• 음성 대조군을 먼저 추가한다: 손가락–손목 강제 겹침, 엄지–상대 손바닥 겹침, 좌표계 오류, 얇은 물체 고속 통과

통과 조건: 음성 대조군 4종이 모두 거부되고, v1 형상에 대해 기존과 같은 수치가 재현될 것. (대조군이 통과해버리면 검사가 무의미하다는 뜻이므로 여기서 멈춘다.)

단계 B — OBB 충돌 도입 (선결, 코드만)

손바닥에 방향을 부여하려면 축정렬 박스로는 안 된다.

• 박스에 회전(쿼터니언 또는 3×3)을 추가하고 segmentBoxDistance를 OBB 대응으로 교체
• 기존 AABB 경로와 수치 동등성 검사: 회전이 항등일 때 두 구현이 1e-12 이내로 일치할 것
• 회전 상태에서의 정확도는 별도 대조군으로 확인

통과 조건: 항등 회전에서 기존 결과 완전 재현 + 회전 상태 대조군 통과.

단계 C — 운동학 체인 도입

월드 좌표 직접 산술을 부모-자식 변환으로 바꾼다. 이것이 v2에서 가장 큰 구조 변경이다.

• 어깨 3축 → 팔꿈치 1축 → 전완 회전 1축 → 손목 2축 → 손 (Codexee 명세)
• 단위는 m, rad, s로 고정하고 문서의 mm를 코드에 직접 넣지 않는다
• 관절 원점·양의 회전 방향·한계를 설정 파일로 분리
• 오른손 좌표계의 오른손성을 모델에서 확인하고, 한쪽을 단순 반사로 만들지 않는다

통과 조건: 항등 자세에서 v1과 같은 부품 배치를 재현할 것. 이 단계는 형상을 바꾸지 않는 리팩터링이며, 여기서 수치가 달라지면 버그다.

단계 D — 손·손목 형상 교체

여기서 비로소 손목이 굵어진다.

• 손목: 짧은 2축 모듈(축방향 45 / 폭 55 / 두께 40 mm 이내 목표)
• 손: 5지, 길이가 다른 마디, 손바닥 아치와 엄지 밑 볼륨
• 엄지: 평면 밖 대립 축 — §1-4의 XZ 평면 제약을 깨는 표현이 필요
• v1은 삭제하지 않고 수치 재현용으로 보존

통과 조건: 열린 손 / 주먹 / 엄지 대립 / 손목 양끝 자세가 렌더되고, 각 자세에서 비인접 자기 충돌이 없을 것. 여기서 사용자 형태 검토를 받는다 — 수치만으로 진행하지 않는다.

단계 E — 악수 동작 재수립

기존 궤적은 승계하지 않는다. 손목·손이 달라졌으므로 접근 자세부터 다시 푼다.

접근 국면의 통과 조건 (§1-5 관찰 근거):

• 접근 시 손가락은 신전 상태, 엄지는 외전되어 물갈퀴가 먼저 진입할 것
• 물갈퀴가 자리잡은 뒤에 손가락 굽힘을 시작할 것 — 접근과 동시에 굽히지 않는다
• 손가락이 상대 손의 반대편까지 도달할 것. 근접 판정이 아니라 포위 판정으로 확인한다
• 손바닥이 수직이고 엄지가 위를 덮을 것
• 두 손을 평면 대칭으로 배치하지 않을 것

공통 통과 조건: 손목·전완이 파지 대상으로 쓰이지 않을 것. 충돌이 나면 손목을 가늘게 만들지 말고 접근 자세·팔꿈치 방향·굽힘 순서를 재계획할 것.

주의: 위 판정은 기하학적 포위 여부까지만 말한다. 감쌌다는 것이 곧 파지력이 성립한다는 뜻은 아니며, 그것은 F 이후 동역학 단계의 주제다.

단계 F — 기구 타당성 검토

형상이 정해진 뒤 수행한다. 구동부·베어링·배선이 손목 포락체에 들어가는지, 전 가동범위에서 간섭이 없는지, 계산된 모멘트에 맞는 부품이 있는지.

통과 조건: 들어가지 않으면 부품 선택 또는 설계 범위를 고치고 근거를 남긴다. 외형을 줄여 검사만 통과시키지 않는다 — 이것이 v1이 빠진 함정이다.

3. 순서를 이렇게 잡은 이유

A·B·C는 형상을 전혀 바꾸지 않는 준비 작업이고 D부터 실제 재설계다. 유혹은 D부터 시작하는 것인데, 그러면:

• A 없이 D를 하면 → 새 형상의 "관통 0건"도 solver 정지 조건의 반복이 된다
• B 없이 D를 하면 → 회전된 손바닥의 간극이 조용히 틀린 값으로 나온다
• C 없이 D를 하면 → 2축 손목을 표현할 자리가 없어 결국 캡슐 하나로 되돌아간다

v1이 만들 수 없는 손목에 도달한 경로가 정확히 이것이다. 검사를 통과시키는 방향으로 형상을 조정할 수 있었기 때문이다. 준비 단계를 먼저 두는 것은 같은 실패를 구조적으로 막기 위해서다.

4. 보고 원칙

각 단계마다 다음을 구분해 보고한다. 하나로 뭉쳐 "검증 완료"라고 쓰지 않는다.

v1의 0.4 mm는 v2의 성공 기준으로 승계하지 않는다. 새 임계값은 형상 근사 오차와 검사 해상도에 맞춰 D 단계에서 정한다.

5. 현재 상태와 범위

v1은 독립 환경에서 재현·실행 가능한 상태이며, 브라우저 검사 스크립트의 range 입력 결함은 수정본이 확인돼 있다.

5-1. A단계 수행 결과 (2026-09-14)

별도 작업 사본에서 수행했다. v1 원본과 가동 중인 데모는 건드리지 않았다(원본 수정시각·상수 형태·서비스 응답으로 확인).

과정에서 바로잡은 것: 처음 작성한 "표본 사이 고속 관통" 대조군은 frame(t)를 10배 조밀하게 재샘플링하는 방식이었는데, coarseMinMm과 fineMinMm이 소수점 16자리까지 동일하게 나왔다. 원인은 grip = solveGrip()이 모듈 로드 시 solids(5, …)로 한 번만 풀려 폐합 구간의 자세가 시간 불변이고, 최소 간극이 그 평탄 영역에 놓이기 때문이다(frame(5)와 frame(5.0001)의 min이 비트 단위로 일치). 즉 그 검사는 실패할 수 없는 검사였다.

재샘플링으로는 원리적으로 잡히지 않으므로, 표본 사이를 실제로 가로지르는 운동을 직접 주입하는 방식으로 교체했다. 인접 두 표본이 각각 +18.69 mm 이격을 보고하는 동안 그 사이 지점이 -6.6 mm로 완전히 관통한다.

통과할 수 없는 대조군보다 실패할 수 없는 대조군이 더 위험하다. 후자는 없는 안전을 있다고 보고한다. 이후 단계에서도 각 대조군이 실제로 실패 가능한지를 먼저 확인한다.

5-2. B단계 수행 결과 (2026-09-14)

같은 사본에서 이어서 수행했다. v1 원본과 가동 중인 데모는 이번에도 건드리지 않았다(원본에 신규 심볼 0건, 상수 형태·수정시각 불변, 서비스 응답 정상).

구현 방식. 박스에 선택적 방향 R(3×3, 행 = 박스 로컬 축)을 허용하고, segmentBoxDistance는 회전이 있으면 선분을 박스 로컬 좌표로 옮겨 기존 AABB 루틴을 그대로 재사용한다. 거리는 회전 불변이므로 이는 근사가 아니라 정확하며, R이 없으면 기존 코드 경로가 그대로 실행된다.

박스–박스는 palm/palm 쌍이 실제로 검사되므로 회피할 수 없어 SAT(15축)로 구현했다. 다만 SAT 분리량은 참거리의 하한이다 — 면 정렬일 때만 참거리와 같고 모서리–모서리 근접에서는 실제보다 작게 보고할 수 있다. 겹침(음수) 판정은 정확하다. "이만큼은 떨어져 있다"는 보수적 보장으로만 쓰고, 코드 주석에도 같은 단서를 남겼다.

과정에서 바로잡은 것 (두 번째). 처음 만든 회전 대조군은 손바닥을 회전시키면서 동시에 확대했다. 확인해 보니 확대만 했을 때 min = −0.170300, 확대+회전도 동일하게 −0.170300 — 회전이 결과에 전혀 기여하지 않았다. 즉 그 검사는 OBB 처리가 옳은지 아닌지를 구별할 수 없는 검사였다.

크기를 원래대로 두고 회전만 가하도록 교체했고, 회전 전 기준 자세가 관통 상태가 아님을 함께 단언해 양방향으로 실패 가능하게 만들었다.

A단계에 이어 두 번 연속으로 "실패할 수 없는 대조군"을 만들었다. 대조군을 추가할 때마다 그것이 실제로 실패할 수 있는지 먼저 확인하는 절차를 이후 단계에 고정한다.

렌더링 영향 없음. app.mjs는 박스의 c와 h만 읽으므로 R 추가는 표시를 바꾸지 않는다. 다만 손바닥에 실제 회전을 부여하는 시점에는 메시 방향도 함께 갱신해야 하며, 이는 D단계 작업이다.

5-3. C단계 수행 결과 (2026-09-14)

구현. v1 의 at() 는 사실상 손바닥 프레임의 local→world 변환이었다 — origin + [s·SCALE·p₀, SCALE·p₁, s·SCALE·p₂]. 이를 Frame{R(행 = 로컬 축), t} 로 드러내고 at() 를 Frame.apply(palmFrame, ·) 로 교체했다. 연산 순서를 보존해 부동소수점 결과가 달라지지 않도록 했다.

팔은 의도적으로 그대로 두었다. 어깨가 월드 상수이고 팔꿈치를 손목에서 역산하는 구조라, 순방향 체인으로 바꾸면 데이터 흐름이 뒤집힌다. C 단계의 목적은 구조를 드러내는 것이지 거동을 바꾸는 것이 아니므로, 순방향 전환은 D단계로 남기고 코드에 주석으로 표시했다.

과정에서 바로잡은 것 (세 번째, 다만 성격이 다름). 앞선 두 번은 "실패할 수 없는 대조군"이었으나, 이번에는 확인하지 않고 단정한 사실 주장이다.

나는 s = −1 미러가 반사 변환이며 좌표계 손방향을 뒤집는다고 서술했다. 실제로 행렬식을 계산하니 양수였다 — det = 4.492125 = 1.65³. x 와 z 두 축이 함께 뒤집히므로 이는 반사가 아니라 y축 180° 회전이고, 손방향은 보존된다.

즉 v1 은 이 계획서와 원저작자 인계 문서가 공통으로 경고한 "한쪽을 단순 반사로 만드는" 오류를 실제로는 범하지 않았다. 경고 자체는 설계 원칙으로 유효하지만, v1 에 그 결함이 있다는 내 서술은 틀렸다.

검사가 실패할 수 있도록 음성 대조군도 함께 넣었다 — 한 축만 뒤집은 프레임은 반사로 판정된다. 아울러 제목이 단언 내용과 반대였던 테스트 하나("반사임을 확인한다" → 실제로는 반사가 아님을 단언)의 이름을 바로잡았다.

세 단계 연속 자기 정정에서 얻은 것: 검사를 추가할 때는 "통과했는가"보다 "이 검사가 실패할 수 있는가" 와 "내가 주장한 사실을 실제로 계산해 보았는가" 를 먼저 확인한다. D단계 이후에도 이 절차를 유지한다.

위 계획의 D(손·손목 형상 교체)는 같은 사본에서 이어서 수행 가능하다.

D 이후는 채택할 공개 CAD/URDF와 라이선스 확인이 선행되어야 하며, 이는 Codexee 문서 §7의 후속 작업에 해당한다. 담당 배정은 정해지지 않았다.

본 문서의 코드 인용과 수치는 2026-09-14 v1 소스 직접 확인 결과다. 설계 방향과 치수 목표는 Codexee의 v2 인계 문서를 따르며 이 문서가 대체하지 않는다.