FAQ
트러블슈팅
뷰포트가 검정 화면 / 첫 실행 때 멈춘 것처럼 보임
증상: docker compose up 후 Isaac Sim 창의 뷰포트가 검게 보이고 제목이 "New Stage*",
로딩 바가 정지된 것처럼 보입니다.
정상 동작입니다. 3차원 가상 캠퍼스 데이터를 불러오는 데 수 분(보통 2~5분,
첫 실행은 더 오래) 걸리며, 그동안 강제 종료하지 마십시오. 로그에
[Runtime] Startup complete in <N>s 와 이어서 Auto-plan: waiting for a participant to register... 가 나오면 기동 완료이며, 그때 씬이 나타납니다. 진행은 docker compose logs -f 로
확인하십시오.
WSL2 에서 화면이 뜨지 않거나 카메라 영상이 나오지 않음
증상: HEADLESS=false 로 실행했는데도 3차원 뷰포트 창이 끝내 나타나지 않습니다. 헤드리스로
실행한 경우에는 ros2 topic list 에 CCTV 카메라 토픽(/marc/env/cctv/...)이 보이지 않습니다.
반면 IMU·오도메트리처럼 카메라가 아닌 토픽은 정상적으로 보입니다.
원인: WSL2(윈도우 안에서 실행하는 리눅스)는 지원 대상이 아닙니다. 플랫폼이 사용하는 Isaac Sim 은 RTX 렌더러를 전제로 동작하며, 뷰포트 화면과 CCTV·로봇 카메라 영상은 모두 이 렌더러가 만들어 내는 결과물입니다. WSL2 는 Isaac Sim 이 지원하는 운영체제 목록에 포함되어 있지 않으며, GPU 가 가상화 계층을 거쳐 전달되는 환경에서는 이 렌더 경로의 동작이 보장되지 않습니다. 실제로 WSL2 에서는 뷰포트 창이 표시되지 않거나 카메라 토픽이 발행되지 않는 사례가 확인되었습니다. 영상이 만들어지지 않으면 카메라 토픽도 발행되지 않습니다. 반면 카메라와 무관한 센서 값은 렌더러를 거치지 않으므로, 위와 같은 차이가 보인다면 통신(DDS) 문제가 아니라 렌더러 문제로 판단하시면 됩니다.
확인 방법: 우분투에서 nvidia-smi 로 보이는 드라이버 번호가 윈도우용 번호(예: 581.xx)와
같다면 WSL2 입니다. 리눅스용 드라이버는 580.159.03 처럼 표기됩니다. 아래 명령으로도 확인할 수
있으며, 하나라도 해당하면 WSL2 환경입니다.
uname -r # ends with -microsoft-standard-WSL2 on WSL2
ls /dev/dxg # this device node exists only on WSL2
해결: 네이티브 Ubuntu 22.04 에 직접 설치하여 실행하십시오(듀얼 부팅 또는 별도의 리눅스 장비). 가상 머신과 WSL2 는 모두 지원하지 않습니다. 참고로 플랫폼과 참가자 애플리케이션은 서로 다른 장비에서 실행해도 되므로, 플랫폼용 리눅스 장비 한 대만 준비하시면 됩니다.
ROS 2 Humble <-> Isaac Sim Python 충돌
증상: 플랫폼 기동 시 import 오류가 나거나 잘못된 Python 이 잡힙니다. 참가자 SDK(Python 3.10)와 Isaac Sim(Python 3.11)이 충돌하는 경우입니다.
해결: 셸을 분리하십시오. Isaac Sim 셸에서 PYTHONPATH·LD_LIBRARY_PATH 의 /opt/ros 를
제거합니다(플랫폼 실행 스크립트가 이미 처리). 참가자 에이전트는 ROS 2 Humble(3.10) 셸에서, 플랫폼은
자체 셸에서 실행하십시오.
GPU 인식 실패
증상: 컨테이너 안에서 GPU 가 보이지 않거나, Failed to initialize NVML 이나
could not select device driver 같은 오류로 실행이 실패합니다.
해결: NVIDIA Container Runtime 이 설치돼 있고 호스트 드라이버가 최신인지, 컨테이너가 GPU 를
요청하는지(--gpus all 또는 compose deploy.resources 블록) 확인하십시오. 호스트와 컨테이너 내부
양쪽에서 nvidia-smi 로 검증하십시오.
기동 직후 RTX 렌더러 크래시 (Segmentation fault)
증상: GPU 는 정상 인식되고 익스텐션도 모두 로드되지만, 로그에 rclpy loaded 가 찍힌 직후
씬을 불러오는 도중 프로그램이 종료됩니다. 로그 마지막에는 librtx.scenedb.plugin.so 또는
libcarb.scenerenderer-rtx 프레임과 함께 Segmentation fault 가 남습니다.
원인: 그래픽카드 자체의 문제가 아니라 드라이버가 원인인 경우가 많습니다. Isaac Sim 5.1 이 검증한 production 드라이버(580.159.03)보다 지나치게 앞선 베타/개발자(Vulkan beta) 드라이버(예: 595.71.05 등 590 번대)에서는 RTX 가 씬을 빌드하는 도중 크래시가 발생합니다(정상 카드인 RTX 4090 에서도 재현됨).
해결: 먼저 설치된 드라이버 버전을 확인하십시오.
nvidia-smi --query-gpu=driver_version --format=csv,noheader
아래처럼 한 줄로 드라이버 버전이 출력됩니다. 여기서 590 번대 이상의 베타/개발자 드라이버가 나오면 원인일 가능성이 높습니다.
595.71.05
이 경우 드라이버를 production 계열(검증본 580.x, 최소 570)로 교체하십시오. 교체한 뒤에는 이전 드라이버로 만들어진 셰이더 캐시를 비우고 다시 실행하십시오(캐시 경로는 플랫폼 폴더 기준입니다).
rm -rf ../.runtime-data/cache/*
그래도 같은 지점에서 종료된다면, 2순위로 BIOS 에서 IOMMU(VT-d) 를 끄고 재시도하십시오.
docker compose up 실패: unknown or invalid runtime name: nvidia
증상: docker compose up 이 unknown or invalid runtime name: nvidia 로 실패합니다.
원인: compose 파일은 runtime: nvidia 를 요구하는데, 호스트에서 docker run --gpus all 이
동작하더라도(CDI 경로) Docker 데몬에 이름이 nvidia 인 런타임이 등록되지 않았을 수 있습니다.
해결: 아래로 한 번 등록하고 Docker 를 재시작하십시오.
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker info | grep -i runtimes # "nvidia" should now appear
DDS 통신 안 됨
증상: 참가자 애플리케이션과 플랫폼이 서로를 찾지 못하거나(디스커버리 실패) 토픽이 오가지 않습니다.
해결: 두 머신이 동일 ROS_DOMAIN_ID 와 동일 LAN 을 공유하는지, 방화벽이 DDS(UDP, 디스커버리용
멀티캐스트)를 허용하는지 확인하십시오. 데모는 network_mode: host 로 호스트 NIC 상에서
디스커버리합니다. 8MP CCTV 스트리밍에는 기가비트 이상 LAN 이 필요합니다. 또한 플랫폼은 ROS 2
Humble 의 기본 미들웨어인 Fast DDS(RMW)를 사용하므로, 참가자도 기본 설정을 그대로 두십시오. RMW 를
다른 것(예: Cyclone DDS)으로 바꾸면 서로 통신(디스커버리)이 안 될 수 있습니다.
빌드 실패: marc-base:ros2-isaacsim-5.1: pull access denied
증상: 플랫폼 빌드가 marc-base:ros2-isaacsim-5.1: pull access denied, repository does not exist 로 실패합니다.
원인: 플랫폼 이미지의 바탕이 되는 base 이미지(marc-base:ros2-isaacsim-5.1)는 레지스트리에서
내려받는 이미지가 아니라 참가자 PC 에서 직접 빌드하는 로컬 이미지입니다. 이 base 이미지를 먼저
빌드하지 않으면 pull 을 시도하다 위 오류가 납니다.
해결: 시작하기 3단계의 marc.sh setup 을 먼저 실행하여 base 이미지를
빌드하십시오(최초 1회). 이 명령은 NGC 로그인 안내도 함께 표시합니다.
bash simulation-platform/marc.sh setup
base 이미지가 빌드되었는지는 아래 명령으로 확인하십시오.
docker image ls marc-base:ros2-isaacsim-5.1
성공했다면 아래와 같이 이미지가 한 줄 표시됩니다.
REPOSITORY TAG IMAGE ID CREATED SIZE
marc-base ros2-isaacsim-5.1 0123456789ab 3 minutes ago XX.XGB
성능이 느리거나 VRAM 이 부족함
증상: 프레임레이트가 낮거나 VRAM 이 부족합니다.
해결: 해상도를 낮추고, 동시에 구독하는 CCTV 스트림 수를 줄이고, 무거운 추론은 참가자의 별도 하드웨어에서 수행하십시오.
주최측이 배포 이미지를 갱신·공지한 경우 (최신본 다시 받기)
증상: 주최측이 문제를 수정한 이미지를 같은 태그로 다시 배포하고 공지했는데, 이미 받아 둔 이전 이미지가 그대로 사용됩니다. Docker 는 같은 태그를 자동으로 다시 받지 않기 때문입니다.
해결: 주최측이 재배포하는 것은 플랫폼 콘텐츠 이미지(ghcr.io/marc-challenge/marc-platform-content:2026)입니다.
이 이미지를 명시적으로 다시 받은 뒤, 플랫폼을 다시 빌드하십시오.
# 1) 갱신된 콘텐츠 이미지를 다시 받기 (같은 태그라도 최신 digest 로 갱신됨)
docker pull ghcr.io/marc-challenge/marc-platform-content:2026
# 2) 그 콘텐츠로 플랫폼 이미지를 다시 빌드·실행
cd simulation-platform
bash marc.sh platform
공지에서 다른 태그나 별도의 이미지 이름을 안내한 경우, 위 이름 대신 공지된 이름으로 pull 하십시오.
RViz2 에서 라이다/TF 를 볼 때 TF_OLD_DATA 경고가 계속 나옴
증상: RViz2 에서 포인트클라우드는 표시되는데 TF_OLD_DATA ignoring data from the past ...
경고가 끊임없이 출력되어 로그를 읽기 어렵습니다.
원인: 플랫폼은 시뮬레이션 시간(sim time)으로 타임스탬프를 찍는데, RViz2 는 기본값이 실제 벽시계 시간(wall clock)이라 두 시간원이 어긋나면서 나오는 경고입니다. 오작동이 아니며 표시는 정상입니다.
해결: RViz2 를 sim time 으로 실행하십시오.
rviz2 --ros-args -p use_sim_time:=true
Fixed Frame 은
world로 둡니다.PointCloud2 디스플레이의 Reliability Policy 는
Best Effort로 두면 안정적입니다(Reliable 로도 수신되지만 디스커버리 타이밍에 따라 놓칠 수 있습니다).
표준 tf2 도구가 /tf_static 을 수신하지 못함 (QoS 비호환) — 해결됨(2026.R01)
이 문제는 2026.R01 배포부터 해결되었습니다. 플랫폼이 /tf_static 을 TRANSIENT_LOCAL(latched)
로 발행하므로 표준 tf2 리스너·RViz2 가 정상 수신합니다. CCTV 카메라 extrinsic 은 world 기준
카메라 id 프레임(예: rig_1_a)으로 조회할 수 있습니다.
ros2 run tf2_ros tf2_echo world rig_1_a
이전 버전을 쓰고 있다면 최신 콘텐츠 이미지로 갱신하십시오(위 “주최측이 배포 이미지를 갱신·공지한 경우” 참조).
매니퓰레이션 연습 환경에서 no SESSION_ACK within 30s 가 나오고 등록이 안 됨
증상: 연습 환경(manip-trainer)을 띄우고 클라이언트를 실행하면 다음 로그가 남고 등록이
끝나지 않습니다. 조작 패널도 no client - Register / connect first 상태로 남아 있습니다.
[REGISTER] starting handshake to /marc/ops/register
[REGISTER] no SESSION_ACK within 30s - check token/runtime
원인: 오류가 아니라 연습 환경의 정상 동작입니다. 이 환경은 로봇 입출력만 제공하고 팀 등록·세션
발급 같은 대회 진행 계층은 싣지 않으므로, 등록 요청에 응답할 상대가 없습니다. 배정 토큰도 필요하지
않습니다. /marc/ops/register 토픽이 목록에 보이는 것은 클라이언트 자신이 그 토픽을 만들었기
때문입니다.
해결: 등록 결과를 기다리지 말고 그대로 로봇 제어로 넘어가십시오. 타임아웃을 짧게 주고 반환값을
확인하지 않으면 됩니다. connect() 가 돌아온 시점에 ROS 2 노드와 통신 채널은 이미 만들어져 있어
팔 제어와 상태 조회는 정상 동작합니다.
client = MARCClient.from_env() # MARC_TOKEN may be any non-empty value here
client.connect(timeout=3.0) # the trainer has no registration - ignore the result
client.send_arm_command(...) # commands take effect right away
베이스라인 코드(participant_app.py)를 출발점으로 삼았다면, 그 코드는 대회 런타임 기준이라
connect() 가 실패하면 실행을 멈추도록 되어 있습니다. 연습 환경에서 쓸 때는 그 중단 처리를 빼십시오.
패널에는 클라이언트가 팔 관절 명령을 보내기 시작하면 team <id> connected 로 바뀝니다. 그 전까지
표시되는 no client - Register / connect first 는 등록을 요구하는 뜻이 아니며, 문구 자체는 다음
배포에서 정정됩니다. 클라이언트와 연습 환경의 MARC_TEAM_ID 는 서로 같아야 합니다.
공지
다음 3종 공지는 필수이며 빌드·제출 방식을 규정합니다.
1. 심사 실행환경은 인터넷이 차단됩니다
빌드 시점에는 인터넷으로 모델 가중치·의존성을 이미지에 baking 할 수 있습니다. 그러나 런타임에는 외부 네트워크 접속·공개 API·다운로드가 금지됩니다. 에이전트는 완전 자기완결형으로 설계하십시오.
2. 제3자 OSS / USD 라이선스 및 attribution
플랫폼·SDK·자산에는 각자의 라이선스를 가진 제3자 오픈소스 SW 와 USD 자산이 포함됩니다. 사용·재배포하는 모든 자산의 라이선스·attribution 요건을 준수하십시오. 통합 제3자 공지 목록이 공개 자료와 함께 제공됩니다.
3. 대회 배경 장소는 변경될 수 있습니다
공개되는 배경 USD 는 연습용 1종뿐입니다. 실제 대회는 다른 배경일 수 있으므로, 연습 씬 레이아웃에 종속된 가정을 하드코딩하지 마십시오.
변경 이력
배포 이미지·키트의 버전별 주요 변경입니다. 새 리비전을 받으려면 스타터킷을 git pull 로 갱신한 뒤
플랫폼을 다시 빌드하십시오(bash marc.sh platform — 참조된 콘텐츠 이미지를 자동으로 받습니다).
2026.R03
데이터셋 생성기의 정답(bounding box) 좌표 오류를 바로잡았습니다. 갱신 후 학습 데이터를 다시 생성해 주십시오. 캔·티슈처럼 바닥에 떨어뜨려 배치하는 물체와 자전거·킥보드·쓰레기통처럼 넘어뜨려 배치하는 물체의 좌표가 실제 위치보다 위쪽으로 기록되어 있었습니다. 사람·벤치·차량처럼 처음 놓인 자리에서 움직이지 않는 대상의 좌표는 영향이 없습니다.
정답 파일 형식과 제출 형식은 그대로이므로 참가자 코드는 고치실 것이 없습니다. 이 문제는 학습 데이터에만 해당하며 대회 채점에는 영향이 없습니다.
데이터를 다시 만드시는 부담을 덜기 위해, 장면을 한 번에 여러 개 만드는 방법을 추가했습니다.
TRAINER_AUTO_SCENES에 원하는 장면 수를 지정하면 화면 없이 자동으로 생성합니다. 사용법은 기술 가이드의 “장면을 한 번에 많이 만들기” 를 참고하십시오.장면마다 정답 상자를 그려 넣은 확인용 이미지(
<카메라>_overlay.png)를 함께 저장합니다. 한 장만 열어 보면 라벨이 제대로 붙었는지 눈으로 확인할 수 있습니다.화면을 켜고 실행할 때와 화면 없이 실행할 때(
HEADLESS)의 렌더 밝기가 서로 달랐던 것도 함께 바로잡았습니다. 이제 두 방식이 같은 영상을 만들며, 대회 채점 환경과도 같습니다. 어느 쪽으로 데이터를 만드셔도 됩니다.이 문제는 참가팀이 생성된 데이터셋을 직접 검증하고 예시 이미지까지 만들어 알려주신 덕분에 확인했습니다. 알려주신 팀에 감사드립니다.
2026.R02
학습 데이터(데이터셋 생성기 GT 파일) 형식은 변경이 없습니다 — 기존에 만든 데이터·모델은 그대로 유효하며 재학습이 필요하지 않습니다.
Stage 1 채점에서 기준 랜드마크의 정답 좌표를 문항이 지정한 카메라 안에서 찾도록 정정했습니다. 이전에는 이름이 같은 랜드마크가 여러 카메라에 배치되어 있으면 다른 카메라에 있는 같은 이름의 랜드마크 좌표를 정답으로 쓰는 경우가 있었습니다. 예를 들어 주차장 카메라의 문항인데 공원 카메라에 있는 같은 이름의 쓰레기통이 정답 좌표가 되는 식입니다.
이 정정으로 일부 문항의
anchor_coord채점 결과가 달라집니다. 이전 연습 결과의 점수는 참고용으로만 보시고, 갱신한 뒤 다시 실행해 확인하십시오. 제출 형식과 채점 항목 자체는 그대로이므로 참가자 코드는 고치실 것이 없습니다.데모가 사용하는 참조 정답 데이터(
demo/mock_demo_data.yaml)도 함께 갱신했습니다. 데모를 참고 구현으로 쓰고 계셨다면 스타터킷을git pull하시면 자동으로 반영됩니다.이 문제는 참가팀의 상세한 제보로 확인했습니다. 알려주신 팀에 감사드립니다.
2026.R01
학습 데이터(데이터셋 생성기 GT 파일) 형식은 변경이 없습니다 — 기존에 만든 데이터·모델은 그대로 유효하며 재학습이 필요하지 않습니다.
CCTV 카메라의 위치·방향(extrinsic)을
/tf_static에 카메라 id 프레임으로 발행하도록 정정했습니다. 이제 표준 tf2 로world와 카메라 id 사이 변환을 조회할 수 있고, latched(TRANSIENT_LOCAL)로 발행되어 RViz2·tf2 리스너가 정상 수신합니다.카메라별 지면 높이 토픽
/marc/env/cctv/{id}/ground_height(std_msgs/Float32, latched)를 추가했습니다. 픽셀을 world 로 역투영할 때 사용합니다.좌표 규약 설명을 보강했습니다(CCTV 프레임 = ROS optical, GT 파일 euler = USD prim; api-reference· technical-guide 참조).