Hand-eye 캘리브레이션
카메라가 로봇 어디에 어떤 각도로 달려 있는지를 측정합니다. 이 값이 있어야 카메라가 본 장애물이 로봇 좌표계에 맞게 놓이고, 스택 기동 때 장애물 인식이 켜집니다.
왼쪽 막대의 캘리브 항목은 현재 세션이 카메라 모델을 알려 줄 때만 보입니다. 카메라가 설정돼 있고, 카메라를 켜고 기동한 경우입니다.
패널에는 현재 값과 새 측정 두 화면이 있습니다. 처음 열면 현재 값이 보이고, 다시 측정을 누르면 새 측정으로, 새 측정 패널 머리의 현재 값을 누르면 돌아옵니다. 다시 열면 마지막에 보던 화면이 나옵니다.
새 측정
캘리브레이션 보드(ChArUco 또는 체커보드)를 로봇 앞에 먼저 고정하세요. 보드 사양은 지원팀이 보드와 함께 알려 줍니다.
새 측정을 열면 가운데 캔버스 자리에 캘리브레이션 스테이지가 나타납니다.
- 조준 단계부터 카메라 화면이 크게 보입니다. 진행 중에는 단계·검출 안내와 중단 아이콘 버튼도 그 화면에 있습니다.
- 왼쪽 탭에서 보드 사양·조준·계획·결과·저장을 다룹니다.
- 왼쪽 패널은 화면 폭과 상관없이 스테이지 위에 떠서 열립니다.

- 캡처 방식을 고르세요.
- 수동: FREEDRIVE 모드에서 카메라를 손으로 옮겨 가며 자세 약 18~26개를 직접 만듭니다.
- 자율 구동(기본값): 보드를 한 번 조준하고 이동을 승인하면, 로봇이 두 번째 시드와 계획한 자세를 스스로 구동합니다. 카메라를 다시 단 직후 저장된 값과 실제가 크게 다르면 마운트 확인에서 멈출 수 있습니다. 그때는 수동으로 먼저 측정하세요.
- 보드 종류·칸수·칸 변 길이(mm)와 목표 샘플 수를 입력하세요. ChArUco 보드는 마커 변 길이(mm)와 ArUco 딕셔너리도 필요합니다. 로봇에 현재 값이 있으면 그 측정에 쓴 보드 사양이 미리 채워집니다. 사양이 맞지 않으면 다음 단계로 넘어가지 않습니다.
- 조준 단계에서 카메라 화면의 안내선에 맞춰, 보드가 화면 중앙·0.5–0.7 m 거리에 오도록 Jog 조작으로 로봇을 움직이세요. Jog 조작 패널은 셀 3D 뷰 아래에 있습니다. 보이지 않으면 상단의 분할 보기를 누르세요.
- 자율 구동이면 시드 캡처 시작을 누르고 아래 흐름을 따릅니다. 시드를 두 시점에서 찍는 것은 한 시점만으로는 카메라 마운트 이상과 보드 이동을 구분할 수 없기 때문입니다.
- 가운데 화면에 시드 대기 → 샘플 수집 → 계산 단계가 표시되고, 보드 검출 상태와 다음에 할 일을 안내합니다. 검출 안내 문장은 캘리브레이션 엔진이 낸 글을 그대로 보여 주므로 영어로 나옵니다.
- 결과 화면에서 잔차와 판정을 확인하세요. 판정은 통과 또는 기준 미달이고, 직접 중단한 측정은 중단됨입니다. 기준 미달이어도 확인하면 저장할 수 있지만 다시 측정하기를 권합니다. 기준 미달 기록으로는 로봇에서 확인할 수 없습니다.
- 필요하면 라벨 (선택) 칸을 채우고 적용(재시작 후) 버튼을 누르세요. 버튼 위에 이 로봇의 지금 값과 바뀔 값(이전 → 새 측정값)이 보입니다.
자율 구동 흐름의 단계는 이렇습니다.
- 첫 시드: 조준한 자세에서 움직이지 않고 찍습니다. 보드까지의 거리와 화면 중심에서 벗어난 각도를 구동 시작 때와 같은 기준으로 확인합니다. 미달이면 어느 쪽으로 맞출지 안내하고, 그동안 Jog 조작으로 맞출 수 있습니다. 150초 안에 기준을 통과한 채 멈춰 있어야 찍힙니다.
- 두 번째 시드: 승인 카드에 TCP 이동 거리·위아래 방향·회전 각과 예상 시간이 보입니다. 카메라가 보드 중심을 바라본 채 조금 돌아가는 이동입니다. 60초 안에 이동 승인과 이동 확인을 누르면 카운트다운 뒤 로봇이 천천히 움직여 두 번째 시드를 찍고, 다시 카운트다운 뒤 같은 경로로 처음 자세로 돌아옵니다.
- 조준으로: 돌아온 TCP 위치가 처음 자세와 5 mm 또는 5° 넘게 다르거나, 두 번째 시점에서 쓸 수 있는 보드 뷰를 얻지 못하면 처음 자세로 돌아온 뒤 멈춥니다. 카메라 마운트가 설정과 크게 다름, 보드 크기 설정 오류, 반사나 가림, 영상 끊김이 흔한 원인입니다.
- 계획 생성: 최대 3분 걸립니다. 끝나도 저절로 구동하지 않고, 구동 시작을 눌러야 로봇이 움직입니다. 계획 단계의 뒤로는 조준 단계로 돌아갑니다.
- 시드 캡처·두 번째 시드 이동·계획 생성 중에는 진행 안내 옆과 가운데 화면 아래의 취소로 멈출 수 있습니다. 카운트다운 중에 취소하면 로봇이 움직이지 않고, 이동 중에 취소하면 그 자리에 멈춥니다.
- 스테이지의 중단은 언제든 측정을 끝냅니다. 자율 구동 중이면 이동 중이어도 로봇이 그 자리에 멈춥니다.
취소와 중단은 브레이크를 걸지 않습니다. 브레이크까지 걸려면 하단 로봇 제어 바 오른쪽 끝의 정지를 쓰세요. 비상 정지는 물리 E-Stop 버튼입니다.
라벨을 비워 두면 카메라 모델과 날짜로 이름이 붙습니다(예: zedxm-2026-10-01-v1). 같은 날 두 번째는 -v2 입니다. 이름에는 라벨의 영문·숫자만 들어갑니다. 한글만으로 된 라벨은 기록에는 그대로 남고, 이름은 라벨을 비웠을 때처럼 날짜로 붙습니다. 이름은 저장 뒤 현재 값에서 바꿀 수 있습니다.
저장한 뒤에는 이렇습니다.
- 저장한 값은 다음 기동부터 적용됩니다. 저장 완료 화면은 저장됨 — 재시작 후 적용과 바뀐 값(이전 → 새)을 보여 줍니다.
- 저장 완료 화면의 로봇 스택 다시 시작을 누르고 확인하면 스택이 다시 시작되고, 현재 값의 표시가 재시작 필요에서 실행 중으로 바뀝니다. 재시작 전에는 「로봇에서 확인」이 거부되므로 저장 완료 화면에는 그 버튼이 없습니다. 현재 값 보기로 카드로 가세요.
- 저장 결과는 알림으로도 뜨고, 실패하면 사유가 버튼 위에 남습니다.
- 저장 뒤에도 결과 복사로 결과 전문을 복사할 수 있습니다.
- 저장 중 연결이 끊기면 저장 여부를 알 수 없으니 현재 값에서 확인하세요.
- 적용하지 않은 결과는 로봇 스택을 다시 시작해도 남습니다. 현재 값의 적용 안 된 결과에서 적용할 수 있습니다.
로봇 스택 다시 시작은 plem 화면에서 S 키를 두 번 누른 것과 같습니다. 이 plem 세션의 모든 로봇이 브레이크를 건 뒤 정지했다가 다시 시작하므로 누르면 한 번 더 묻습니다. 그동안 펜던트 연결이 끊기고 다시 시작 중이 보이며, 서버가 돌아오면 원래 화면으로 돌아옵니다. 2분 안에 돌아오지 않으면 plem 화면을 확인하세요.
Job 실행·Jog 세션·캘리브레이션 구동 중이면 이유와 함께 거부합니다. Freedrive 모드나 다른 ROS 프로그램이 로봇을 움직이는 것은 알아채지 못하므로, 로봇이 멈춘 것을 보고 누르세요. 멀티로봇에서는 첫 번째 로봇만 봅니다. plem 화면 없이 띄운 스택에서는 버튼이 꺼지고 이유가 보이며, 그때는 스택을 띄운 곳에서 다시 시작합니다.
실패 뒤 다시 하기
측정이 실패하면 결과 화면의 버튼이 실패 원인에 맞춰 다시 시작할 지점을 고르고, 다시 할 필요가 없는 단계는 건너뜁니다.
| 버튼 | 언제 | 이어지는 곳 |
|---|---|---|
| 같은 계획으로 다시 구동 | 계획은 그대로 쓸 수 있는 실패: 중단, 작업 점유, 이동 실패, 시드 대기 시간 초과, 기준 미달 등. 기준 미달이면 같은 자세로 한 번 더 측정합니다 | 계획 단계의 구동 시작 직전. 구동을 시작하면 보드 위치를 다시 확인하고, 계획 때보다 보드가 많이 움직였으면 구동하지 않습니다 |
| 조준부터 다시 | 계획 자체가 맞지 않는 실패: 보드가 움직임, 도달 가능한 자세나 회전 폭 부족, 모은 샘플로 해를 구하지 못함, 계획 없음 | 조준 단계. 시드를 새로 잡아 계획을 다시 만듭니다 |
| 보드 사양부터 다시 | 보드 사양이 실제 보드와 다름 | 보드 사양 폼 |
수동 측정에는 계획이 없으므로 조준부터 다시 또는 보드 사양부터 다시만 나옵니다.
구동 전 계획 단계(시드 캡처·두 번째 시드 이동·계획 생성)가 실패하면, 계획 단계의 버튼이 로봇 위치에 따라 달라집니다. 취소하면 메시지가 로봇 위치를 알려 줍니다.
| 상황 | 로봇 위치 | 버튼 |
|---|---|---|
| 아래 두 줄이 아닌 실패. 시드 캡처·계획 생성 중에 연결이 끊긴 경우도 여기입니다 | 시스템이 로봇을 움직이지 않았습니다 | 다시 시도. 지금 자세에서 첫 시드부터 다시 찍습니다 |
| 두 번째 시드 이동이 끝나지 않음 · 돌아온 자세가 처음 자세와 다르거나 확인되지 않음 · 그 이동 중에 연결이 끊김 | 처음 자세가 아닐 수 있습니다 | 조준으로 |
| 취소함 | 메시지가 알려 줍니다 | 조준으로 |
조준으로가 나오면 로봇 상태와 카메라 케이블을 확인하고 Jog 조작으로 다시 조준한 뒤 시작하세요.
구동 종료를 확인하지 못했을 때
구동 중 연결이 끊기거나 로봇의 이동 결과가 확인되지 않으면, 가운데 화면에 그 사실과 원인 후보가 나옵니다. 원인 후보는 E-Stop·로봇 모드 변경·컨트롤러 오류·이동 시간 초과·서버 연결 끊김입니다. 이때 로봇이 다시 움직일 수 있습니다.
- E-Stop 버튼으로 구동을 차단합니다.
- E-Stop 버튼으로 구동을 차단했습니다를 누릅니다. 누르기 전에는 화면 잠금이 남고, 계획 단계의 구동 시작도 잠깁니다.
plem화면에서 S 키로 로봇 스택을 정지한 뒤 다시 S 키로 시작합니다. 2단계는 화면 잠금만 풀 뿐, 이전 세션이 끝났는지는 확인하지 않기 때문입니다.- E-Stop 버튼을 해제합니다.
보드 주변을 비우고 비상 정지에 손이 닿는 곳에서 진행하세요. 구동 중과 두 번째 시드 이동 중에는 화면 대부분이 잠기고, 중단·취소하거나 끝나면 풀립니다.
- 잠기는 것: 사이드바의 다른 그룹·탭, 도움말, 하단의 Job 실행·재실행·이어서 실행, 하단의 로봇 모드(BRAKED · TRAJ · FREE), Jog 조작 패널. 좁은 화면에서는 사이드바가 닫힙니다.
- 잠기지 않는 것: 상단의 프로그램·셀 탭과 분할 보기, 하단 오른쪽 끝의 정지. 셀 탭만 보려고 하면 카메라 화면이 남도록 분할로 바뀝니다. 물리 E-Stop 버튼은 화면 잠금과 무관합니다.
구동 중, 시드 캡처·이동·계획 생성 중, 또는 저장하지 않은 결과가 있을 때 새로고침하거나 닫으려 하면 브라우저가 한 번 더 묻습니다. 새로고침하면 이 화면은 처음부터 다시 시작합니다. 진행 중이던 시드 캡처·이동·계획 생성은 서버가 취소하고, 이동 중이었으면 로봇이 그 자리에 멈춥니다.
진행 중인 측정은 서버에 연결된 화면이 하나도 남지 않을 때만 취소됩니다. 다른 화면(다른 펜던트 탭 등)이 연결돼 있으면 측정이 계속될 수 있습니다. 로봇이 움직이면 E-Stop 버튼을 누르세요.
현재 값
연결된 로봇의 Hand-eye 캘리브레이션 카드입니다. 위쪽 현재 값에 이 로봇이 쓰는 값이, 아래 기록에 바꿔 쓸 수 있는 다른 값이 최근 측정순으로 나옵니다. 다른 로봇의 값은 이 카드에서 보거나 바꾸지 않고, plem 화면의 로봇 설정에서 바꿉니다.

측정하고 아직 적용하지 않은 결과가 있으면, 카드 맨 위 적용 안 된 결과에 측정 시각·잔차·품질(통과 · 기준 미달)과 적용 버튼이 나옵니다.
- 결과는 로봇 기기에 남습니다. 새로고침하거나 로봇 스택을 다시 시작해도 사라지지 않습니다.
- 적용 버튼은 새 측정의 적용(재시작 후) 버튼과 같습니다. 새 기록으로 저장해 이 로봇의 현재 값으로 바꿉니다.
- 새 측정을 시작하거나 정밀 관절 영점 보정 적용으로 관절 영점 보정을 적용하면 이 결과는 지워집니다. 옛 관절 값으로 잰 결과이기 때문입니다.
- 측정 때와 카메라 모델·로봇 모델·로봇 시리얼·툴 회전·F/T 센서 모델이 다르면 저장이 거부됩니다. 다시 측정하세요.
- 카메라는 모델로만 비교하므로, 같은 모델의 다른 카메라로 바꾼 것은 구별하지 못합니다.
현재 값 옆의 표시가 적용 상태를 알려 줍니다.
| 표시 | 뜻 |
|---|---|
| 실행 중 | 지금 동작 중인 로봇 스택이 이 값으로 카메라 위치를 쓰고 있습니다 |
| 재시작 필요 | 값을 바꾸거나 해제한 뒤 아직 로봇 스택을 재시작하지 않았습니다. 재시작하면 적용됩니다 |
| (표시 없음) | 아직 판단할 수 없습니다(카메라 위치를 아직 받지 못함 등) |
현재 값에 문제가 있으면 카드가 먼저 알리고, 그 아래에 사유를 함께 보여 줍니다.
| 안내 | 원인 | 할 일 |
|---|---|---|
| 다음 재시작에서 기동이 실패합니다 | 지금 값이 이 로봇과 맞지 않습니다(로봇 모델이 다르거나 기록이 손상됨) | 해제하거나 다른 값을 사용하세요 |
| 다음 재시작부터 이 값 대신 기본 위치를 씁니다 | 카메라나 툴 회전이 측정 때와 다릅니다. 기동은 막지 않고 카메라 기본 위치로 돌아가며, 기본 위치는 툴 회전·F/T 센서를 따라갑니다. 다시 측정할 때까지 인식 기능(nvblox 등)은 꺼집니다 | 지금 구성에서 다시 측정하세요 |
| 이 로봇이 측정한 기록이 아닙니다 | 다른 로봇의 기록이거나 로봇이 적히지 않은 기록입니다. 「로봇에서 확인」이 거부되고, 기동에는 영향이 없습니다 | 이 로봇을 다시 캘리브레이션하거나 이 로봇의 다른 값을 쓰세요 |
| 기록 파일 없음 · 기록이 손상됨 | 가리키는 기록을 읽을 수 없습니다 | 해제하세요 |
| 다시 측정하기를 권장합니다 | 이 값을 측정한 뒤 로봇의 관절 오프셋·기구학 정보가 갱신됐습니다. 파일을 다시 쓴 시각으로 판단하므로 내용이 같아도 표시될 수 있습니다. 같은 경우의 기록에는 다시 측정 권장 배지가 붙습니다 | 경고일 뿐 막지 않습니다 |
| 카메라 설정이 없거나 서로 맞지 않습니다 | 카메라가 설정되지 않았거나 설정끼리 맞지 않습니다 | 로봇 설정 버튼으로 카메라를 설정하거나 다시 저장하세요 |
툴 회전은 그대로 두고 그리퍼나 F/T 센서만 바꾸면 이전 측정값이 그대로 적용되고 인식 기능도 켜집니다. 카메라가 툴에 붙어 있으면 실제 위치와 어긋난 값입니다. 카메라를 쓰기 전에 지금 구성에서 다시 측정하세요.
| 동작 | 위치 | 하는 일 |
|---|---|---|
| 적용 | 적용 안 된 결과 | 적용하지 않은 결과를 새 기록으로 저장해 현재 값으로 바꿉니다. 다음 기동부터 적용됩니다 |
| 다시 측정 | 카드 | 새 측정으로 갑니다 |
| 로봇에서 확인 | 카드 | 아래 확인 창을 엽니다 |
| 해제 | 카드 | 캘리브레이션 없이(공장 기본값) 동작하게 합니다. 다음 기동부터 적용됩니다 |
| 가져오기 | 카드 | 내보낸 YAML 파일을 기록으로 추가합니다. 가져온 값은 고르기 전까지 쓰이지 않습니다 |
| 이 값 사용 | 기록의 ⋯ | 그 값을 이 로봇의 현재 값으로 바꿉니다. 다음 기동부터 적용됩니다 |
| 이름 변경 · 내보내기 | 기록의 ⋯ (현재 값도) | 이름을 바꾸거나 YAML 파일로 내려받습니다 |
| 폐기 | 기록의 ⋯ | 메뉴 안에서 한 번 더 확인한 뒤 지웁니다. 어느 로봇이든 쓰고 있는 값은 폐기할 수 없습니다(현재 값은 해제한 뒤) |
기록마다 품질(통과 · 기준 미달)과 측정 시각·잔차가 나옵니다.
- 다른 로봇이 쓰고 있으면 사용 중: 로봇이 보입니다.
- 다른 로봇에서 측정했으면 다른 로봇(시리얼)에서 측정이 보입니다.
- 이 로봇에 쓸 수 없는 기록(다른 카메라·로봇 모델 등)도 숨기지 않고 흐리게, 사유와 함께 보여 줍니다. 폐기·내보내기로 정리할 수 있게 하기 위해서입니다.
로봇에서 확인
현재 값 카드의 로봇에서 확인 버튼으로 엽니다. 이 버튼은 현재 값이 정상 기록일 때만 보입니다. 오른쪽 위 닫기로 닫습니다.
- 창 위쪽에 현재 값과 그 표시(실행 중 · 재시작 필요)가 나옵니다.
- 그 옆에 광학 좌표계와 병진·회전 잔차가 나옵니다.
- 기준 미달·기록 파일 없음·손상된 기록이면 그 사유가 함께 보입니다.
- 카메라(Camera)만 켜져 있으면 충돌 회피(cuMotion)·환경 맵(nvblox)을 끈 구성에서도 쓸 수 있습니다.
카메라 화면에서 보드 위 한 점을 골라 TCP 위치를 그 위로 옮겨 봅니다.
- 보드 위 한 점을 누릅니다. 로봇이 TCP 위치를 그 점에서 2 cm 위로 옮길 준비를 합니다.
- 이동을 누릅니다. 카운트다운(「N초 후 이동합니다」)이 끝나면 움직입니다. 카운트다운 중 취소하면 움직이지 않습니다.
- TCP 위치가 누른 점 바로 위에 오는지 봅니다. 옆으로 빗나간 만큼이 캘리브레이션 오차입니다. 보드 칸 크기를 자 삼아 가늠하세요.
- 다음 점을 누르기 전에 툴을 몇 cm 위로 올립니다. 툴이 보드에 가까우면 옆 점으로 가는 경로가 보드에 너무 붙어 이동이 거부됩니다.
- 대각선 코너 2~3곳에서 반복합니다.
- 안내와 거부 사유는 화면 언어로 나옵니다. 계획기·카메라가 낸 원문이 있으면 사유 뒤 「상세」에 그대로 붙습니다.
- 기준을 통과하고 보드 사양이 기록된 값에서만 쓸 수 있습니다. 아니면 버튼이 잠기고 사유가 보입니다.
- 저장이나 이 값 사용 뒤에는 스택을 다시 시작해야 합니다.
- 이동 중 연결이 끊기면 취소가 전달되지 않았을 수 있습니다. 로봇이 움직이면 E-Stop 버튼을 누르세요.