블록 추가 / 플랜 실행

플래너의 우측 상단 Plans 타임라인은 그룹마다 한 줄씩 가로로 늘어선 카드 트랙입니다. 카드 한 장이 블록 하나이고, 왼쪽에서 오른쪽 순서로 실행됩니다. 그룹은 서로 로봇을 공유하지 않으므로 여러 그룹을 동시에 돌릴 수 있습니다. 각 블록의 결과(완료 · 중지 · 오류)는 실행 후 카드 우측 상단에 아이콘으로 남습니다.

블록 추가하기 #

1. 추가하려는 그룹 트랙의 오른쪽 끝, + 블록 추가 버튼을 누릅니다.

   같은 플래너 안에 그룹이 여러 개라면 각 그룹마다 별도의 + 버튼이 있습니다. 블록은 누른 그룹에 들어갑니다.

   

2. 블록 종류를 선택합니다.

   선택한 종류에 따라 다이얼로그 아래쪽 입력 항목이 바뀝니다.

   • Joint Position — 워크스페이스 로봇을 저장된 관절 자세로 이동
   • Checkpoint — 학습된 체크포인트로 추론 실행 (시간 종료 또는 Done까지)
   • Query Pose — 외부 ROS 서비스에서 받아온 좌표로 로봇 이동 (관절 / 엔드 이펙터)
   • Segmentation Reach — 카메라로 타겟 물체를 검출해 그 위로 엔드 이펙터를 이동 (depth 카메라 필요)
   • Time Sleep — 지정한 초만큼 대기
   • Sync — 다른 그룹과 만나는 동기화 지점

   

3. 종류별 세부 항목을 채우고 다이얼로그 우측 하단의 저장을 누릅니다.

   종류와 무관하게 공통으로 입력하는 항목은 다음 한 가지뿐입니다.

   • 이름 (선택) — 비워 두면 종류와 워크스페이스/체크포인트 이름으로 자동 생성됩니다. 예: 이동 (워크스페이스 A), pick_v3 실행, 2초 대기, Sync start.

   

   나머지 입력 항목은 선택한 블록 종류에 따라 다릅니다. 각 종류별 입력 항목은 아래 Joint Position 블록, Checkpoint 블록, Time Sleep 블록, Sync 블록 절을 참고하세요.

   입력을 마친 뒤 다이얼로그 우측 하단의 저장을 누르면 블록이 트랙에 추가됩니다.

   

Joint Position 블록 #

지정 워크스페이스의 로봇들을 저장된 관절 자세로 이동시킵니다.

1. 워크스페이스를 선택합니다.

   해당 워크스페이스의 어셈블리에 포함된 모든 로봇의 자세를 한 번에 저장합니다. 선택할 수 있는 워크스페이스는 이 블록이 속한 그룹의 워크스페이스로 자동으로 좁혀집니다.

   

2. 로봇 펜던트로 원하는 자세를 만듭니다.

   워크스페이스에 포함된 각 로봇별로 펜던트가 표시됩니다. 로봇이 켜져 있어야 펜던트가 보이며, 꺼져 있으면 안내 문구가 대신 표시됩니다.

   

3. 현재 자세 적용 버튼으로 자세를 저장합니다.

   현재 로봇의 관절값이 저장된 자세 카드(상단 강조 박스)에 표시됩니다. 저장된 자세는 이동 버튼으로 미리 검증해 볼 수 있습니다.

   

Checkpoint 블록 #

선택한 체크포인트로 워크스페이스에서 실시간 추론을 실행합니다. 끝나는 조건은 시간이거나 Done 신호입니다.

1. 워크스페이스와 체크포인트를 선택합니다.

   체크포인트 목록은 선택한 워크스페이스에서 학습된 항목으로 자동으로 좁혀집니다.

2. 추론 종료 방식과 시간(또는 Done 임계값)을 정합니다.

   • Done 신호까지 실행 (토글) — 켜면 정책의 done 점수가 임계값을 넘는 순간 즉시 다음 블록으로 넘어갑니다. 끄면 지정 시간만큼만 실행합니다.
   • Done 임계값 — Done 토글이 켜졌을 때만 보입니다. 0과 1 사이 값 (기본 0.5).
   • 시간 (초) — Done 토글이 꺼졌을 때 사용. 이 블록이 실행될 시간.
   • 추론 Hz — 초당 정책을 호출하는 횟수.
   • re_inference_steps — 한 번 추론한 액션을 몇 step 동안 재사용할지.
   • temporal_ensemble_coeff — re_inference_steps=1일 때만 표시. 시간 평활 계수.

   

Query Pose 블록 #

외부 ROS2 서비스를 호출해 받은 좌표로 로봇을 이동시킵니다. 비전 인식 노드처럼 매 실행마다 위치가 달라지는 목표(예: 인식된 박스 중심)에 로봇을 보낼 때 사용합니다. 서비스 응답은 어셈블리 슬롯 이름을 키로 하는 JSON 객체로 와야 합니다.

1. 워크스페이스를 선택합니다.

   같은 그룹 안의 워크스페이스 중 하나를 고릅니다. 워크스페이스가 하나뿐이면 자동으로 그 값이 들어가고 셀렉트는 표시되지 않습니다.

2. 포즈 타입을 선택합니다.

   서비스가 응답으로 돌려주는 좌표의 종류입니다.

   • 관절 좌표 — 슬롯별 관절 각도 배열 (예: [0.1, -0.5, 0.7, ...])
   • 엔드 이펙터 좌표 — 슬롯별 EE 위치/자세. 백엔드가 IK로 풀어 관절 값으로 변환합니다 (IK가 활성화된 단일 EE 로봇만 지원).

3. 호출할 서비스 이름을 입력합니다.

   형식은 std_srvs/srv/Trigger입니다. 예: /my_target. 응답 메시지의 message 필드에 JSON 문자열이 담겨 있어야 합니다.

4. 외부 노드 예시 보기 버튼으로 서버 예시 코드를 확인합니다.

   다이얼로그 안에 std_srvs 만으로 동작하는 ROS2 노드 예시 코드가 표시됩니다. 클립보드로 복사한 뒤 호스트에서 python3 my_target_server.py로 실행하면 위 서비스 이름으로 응답을 제공합니다 (별도 colcon build 필요 없음).

5. 이동 시간(초)을 입력합니다.

   서비스에서 받아온 목표 자세까지 보간 이동하는 데 걸리는 시간입니다. 짧을수록 빠르게 움직이지만 속도/저크가 커집니다.

6. 서비스 호출 + 로봇 이동 테스트 버튼으로 실제 동작을 검증합니다.

   서비스를 한 번 호출해서 받아온 좌표로 로봇을 이동시키고, 응답 JSON을 다이얼로그 안에 보여 줍니다. 좌표 형식이 맞지 않거나 IK가 풀리지 않으면 빨간 오류 메시지가 표시되므로, 플랜에 추가하기 전에 미리 검증할 수 있습니다.

Segmentation Reach 블록 #

카메라로 타겟 물체를 검출해 그 위치로 엔드 이펙터를 보내는 블록입니다. 매 실행마다 물체의 실제 위치를 카메라로 다시 찾아 이동하므로, 물체가 놓인 자리가 달라져도 따라갑니다. Query Pose 블록이 외부 비전 노드를 직접 띄워야 하는 데 비해, Segmentation Reach는 EasyTrainer 안에서 검출(YOLOE)·역투영·이동을 모두 처리합니다.

블록은 다음 순서로 동작합니다.

1. 지정한 관찰 자세로 로봇을 이동시켜 카메라가 물체를 보게 합니다.
2. 카메라의 RGB-D(컬러 + 깊이) 영상에서 타겟 물체를 검출합니다.
3. 검출된 마스크와 깊이를 로봇 base 기준의 3차원 좌표로 역투영합니다.
4. 그 위치(오프셋만큼 띄운 지점)로 엔드 이펙터를 이동시킵니다.

1. 카메라(depth)와 워크스페이스를 선택합니다.

   depth를 제공하는 카메라를 고르면 그 아래에 실시간 화면이 표시됩니다. 워크스페이스가 하나뿐이면 자동으로 선택됩니다.

   📸스크린샷 누락/docs/planner/blocks-reach-01-camera.png

   Segmentation Reach — 카메라(depth) 선택과 실시간 스트림

2. 타겟 오브젝트 지정 방식을 고르고 타겟을 지정합니다.

   • 바운딩 박스 (드래그) — 레퍼런스 추가를 누른 뒤 스트림 화면에서 타겟 물체를 드래그해 박스로 감쌉니다. 여러 각도에서 여러 개의 레퍼런스를 추가할수록 다른 시점에서도 같은 물체를 더 잘 찾습니다.
   • 텍스트 프롬프트 — red cube처럼 영어로 물체를 묘사하면 YOLOE가 그 설명으로 검출합니다.

   📸스크린샷 누락/docs/planner/blocks-reach-02-target.png

   Segmentation Reach — 레퍼런스 박스 추가 / 텍스트 프롬프트 입력

3. 검출 추적으로 검출이 되는지 확인합니다.

   검출 추적을 누르면 현재 화면에서 타겟을 찾아 마스크를 겹쳐 보여 주고, 검출 픽셀 수와 중심 좌표를 표시합니다. 뷰를 옮긴 뒤 다시 검출해 같은 물체를 찾는지 확인하세요. 잘 안 잡히면 검출 민감도(conf) 를 0.05까지 낮춰 봅니다(기본 0.1, 낮을수록 민감).

   📸스크린샷 누락/docs/planner/blocks-reach-03-detect.png

   Segmentation Reach — 검출 추적 마스크 오버레이와 검출 정보

4. 도달 위치 오프셋과 회전 허용을 정합니다.

   • X / Y / Z 오프셋 (m) — 검출된 타겟 기준으로 도달 위치를 미세 조정합니다. Z 오프셋은 타겟 위로 띄우는 양입니다(물체를 곧장 찍지 않고 살짝 위에서 멈추게 함).
   • 회전 허용 (방향 가중치) (기본 0.05) — 낮을수록 위치 도달을 우선하고 방향은 느슨하게 풉니다(IK가 안정적). 0이면 방향을 무시하고, 1이면 방향을 엄격히 맞춥니다.
   • 이동 시간(초) 과 관찰 전 대기(초) 를 정합니다.

5. 카메라 장착 방식을 고르고 캘리브레이션합니다.

   • Wrist view 토글 켜짐 — 카메라가 엔드 이펙터에 붙어 함께 움직이는 경우. 파라미터는 EE 기준으로 해석됩니다.
   • Wrist view 토글 꺼짐 — 외부/탑뷰 고정 카메라인 경우. 파라미터는 로봇 base 기준으로 해석됩니다.

   카메라 위치/자세는 보드 없이 터치 캘리브레이션으로 채웁니다. 캘리브레이션 버튼을 누른 뒤 다음을 3회 이상 반복합니다.

   1. 물체가 카메라에 보이는 자세에서 ① 검출 캡처 를 누릅니다.
   2. 키보드로 EE를 움직여 그 물체를 직접 터치한 뒤 ② 터치 기록 을 누릅니다(W/S/A/D/E/Z = 이동, Shift+키 = 회전, C/V = 그리퍼, Space = 정지).
   3. 물체 위치를 바꿔 가며 반복하고, 샘플이 3개 이상 모이면 계산 을 눌러 카메라 마운트 값(오프셋·피치·요·롤)을 산출합니다.

   캘리브레이션이 끝나면 헤더에 캘리브레이션 완료 칩이 표시되고 값이 자동으로 채워집니다.

   📸스크린샷 누락/docs/planner/blocks-reach-04-calibration.png

   Segmentation Reach — 터치 캘리브레이션 패널 (검출 캡처 / 터치 기록 / 계산)

Time Sleep 블록 #

다음 블록까지 지정한 시간만큼 대기합니다. 정책이 끝난 직후 사용자가 결과를 확인하거나 환경을 정리할 시간을 주고 싶을 때 유용합니다.

1. 시간(초)을 입력하고 저장합니다.

   0보다 큰 숫자여야 합니다.

   

Sync 블록 #

다른 그룹과 시점을 맞추는 동기화 지점입니다. 같은 sync_id를 가진 Sync 블록이 다른 그룹에 있으면, 양쪽이 그 지점에 도달할 때까지 서로 기다린 다음 함께 다음 블록으로 넘어갑니다.

1. 동기화 ID를 입력합니다.

   짧은 문자열이면 무엇이든 됩니다 (예: pick_ready, step1, A). 짝을 맞추고 싶은 다른 그룹의 Sync 블록과 정확히 같은 문자열이어야 합니다.

2. 다른 그룹의 같은 위치에도 같은 ID로 Sync 블록을 둡니다.

   예: 왼팔 그룹과 오른팔 그룹이 모두 "물체 잡기" 직후에 같이 멈춰서 만나야 한다면, 두 그룹의 그 위치에 각각 sync_id=pick_ready로 Sync 블록을 추가합니다.

블록 관리 #

추가된 블록은 그룹 트랙의 가로 카드로 표시됩니다. 각 카드에서 다음 동작을 할 수 있습니다.

• 드래그 — 카드를 끌어 같은 트랙 안에서 좌우로 옮기면 실행 순서가 바뀝니다. (실행 중에는 비활성화)
• 우클릭 — 컨텍스트 메뉴로 상세 보기, 블록 편집, 블록 복제, 이 블록만 실행, 블록 삭제 사용
• 배지 — Time Sleep / Checkpoint / Query Pose 블록은 Ns 형태로 시간이, Done 토글이 켜진 Checkpoint는 Done까지 배지가, Sync 블록은 Sync 배지가, Query Pose 블록은 호출할 서비스 이름이 카드 위에 붙습니다.

카드 좌측의 색 막대는 종류를 색으로 구분합니다 (관절 이동: 파랑, 체크포인트: 보라, Query Pose: 남보라, Segmentation Reach: 분홍, 시간 대기: 주황, Sync: 청록).

플랜 실행 #

플래너는 두 가지 실행 방식을 지원합니다.

• 전체 실행 (타임라인 상단 우측) — 모든 그룹을 병렬로 동시에 시작합니다. 그룹 안에서는 블록이 순차로 실행되고, Sync 블록을 만나면 짝이 도달할 때까지 기다립니다.
• 이 그룹만 실행 (각 그룹 트랙 좌측) — 한 그룹만 단독으로 실행합니다. 다른 그룹의 Sync 블록은 짝이 없으므로 no-op으로 넘어갑니다.

1. 실행 방식을 골라 버튼을 누릅니다.

   서버는 시작 직전에 다음을 검증합니다. 하나라도 실패하면 알림으로 원인이 표시되고 실행이 시작되지 않습니다.

   • 사용 중인 워크스페이스가 모두 존재하는지
   • 실행할 그룹의 블록이 참조하는 로봇이 모두 켜져 있는지
   • 체크포인트 블록의 체크포인트가 존재하고 정책이 연결되어 있는지
   • Done 신호까지 실행이 켜진 체크포인트가 has_succeed로 학습되어 있는지
   • Time Sleep 블록의 시간이 0보다 큰지
   • Query Pose 블록의 서비스 이름이 비어 있지 않고 (EE 모드일 때) 워크스페이스 로봇이 IK 가능한 단일 EE 로봇인지
   • Sync 블록의 동기화 ID가 비어 있지 않은지

2. 현재 실행 중인 블록 카드가 파란 테두리와 스피너로 강조됩니다.

   상단 상태 텍스트에는 그룹별 진행 정보가 표시됩니다. 다른 그룹의 Sync 블록을 기다리는 중에는 대기 중 상태로 보입니다.

3. 하단 모니터링 윈도우에서 센서/로봇 상태를 함께 확인합니다.

   체크포인트 블록 실행 시 정책이 보내는 액션이 실시간으로 로봇에 반영됩니다. 모니터링 패널이 타임라인 아래로 배치되어 페이지를 자연 스크롤하면서 보면 됩니다.

4. 각 블록이 끝나면 카드 우측 상단에 결과 아이콘이 남습니다.

   • check_circle (녹색) — 정상 완료
   • cancel (주황) — 사용자 중지
   • error (빨강) — 오류로 종료. 오류 내용은 알림으로 표시됩니다.

5. 이상하거나 위험해 보이면 중지 버튼을 누릅니다.

   전체 실행 상태에서 누르면 모든 그룹이 즉시 중지됩니다. Sync 블록에서 기다리던 그룹도 함께 풀려납니다.

   

실행 중 제약 #

• 실행 중에는 새 블록 추가, 블록 편집/삭제/복제, 카드 드래그, 우클릭 메뉴 모두 비활성화됩니다.
• 페이지를 새로 열어도 서버에서 실행 상태를 다시 받아오므로, 다른 탭/창에서도 진행 중임이 그대로 표시됩니다.

잘 안 될 때 #