콘텐츠로 이동

PhysiCar Sim

Gazebo Harmonic 기반 시뮬레이션 환경(physicar-sim)입니다. 그 안의 로봇은 PhysiCar ROS 스택을 그대로 실행하고, 그 위에 시뮬레이터 자체의 HTTP API가 /sim/api/ 경로로 월드·차량·평가 제어를 제공합니다. SIM 전용 — 실물 키트에는 /sim/api가 없습니다.

이 페이지의 모든 엔드포인트는 워크스페이스 노트북 examples/physicar-sim.ipynb (커널 Python 3 (PhysiCar AI))에서 직접 실행해 볼 수 있습니다.

import requests

BASE = "http://localhost/sim/api"
requests.get(f"{BASE}/status").json()

상태·시간

메서드 경로 설명
GET /sim/api/status 시뮬레이터 런타임 상태
GET /sim/api/clock 시뮬레이션 시간 / 실제 시간 / RTF / 일시정지 여부

차량

메서드 경로 설명
GET /sim/api/pose 차량 포즈(월드 절대 좌표)
POST /sim/api/pose 차량 텔레포트 — {"x": 1.0, "y": 2.0, "yaw": 0.0}, 생략한 필드는 현재 값 유지. 포즈가 지면 위에 똑바로 선 자세로 정규화되므로 뒤집힌 차를 일으켜 세우는 데도 쓰입니다. 포즈 적용이 확인된 뒤 응답이 돌아옵니다

텔레포트와 오도메트리

오도메트리(라이다 + IMU)는 텔레포트를 감지하지 못해 이후 /odom에 오프셋이 남을 수 있습니다. 깨끗한 오도메트리 상태가 필요하면 POST /sim/api/respawn을 쓰세요 — 오도메트리 스택까지 재시작됩니다.

월드·물체

메서드 경로 설명
GET /sim/api/world 현재 월드 정의를 한 번에: 식별 정보(world_id/rev/표시 이름), 트랙 지오메트리, 물체 카탈로그, 평가 유무
GET /sim/api/route 트랙 중앙선 웨이포인트 + 있으면 안쪽/바깥쪽 경계선
GET /sim/api/bounds 트랙 경계(바운딩 박스)
GET /sim/api/objects 월드 모델 목록(이름, type: object/wall/light, static, movable, 원점/현재 포즈, 크기)
POST /sim/api/models/<name>/pose 월드 물체 이동/회전 — {"x", "y", "z", "yaw"}, 생략한 필드는 현재 값 유지, 회전은 yaw만. World Builder 물체와 신호등에 동작하고 벽·트랙 자체는 거부됩니다

신호등

메서드 경로 설명
GET /sim/api/traffic_lights 월드의 신호등 목록과 상태. 기본 상태는 green, 같은 월드의 respawn 후에도 상태가 유지됩니다
POST /sim/api/traffic_lights/<name> {"state": "red"} 또는 {"state": "green"} — green→red는 3초의 황색을 거치며, 그동안의 명령은 409로 거부됩니다

신호등은 월드 자체에서 옵니다(Custom World Builder에서 배치) — 런타임 배치 API는 없습니다.

리셋

메서드 경로 설명
POST /sim/api/reset 모든 movable 물체·신호등·차량을 시작 포즈로 — 즉시, 포즈만, 월드 리로드 없음. 학습 에피소드 사이의 기본 리셋
POST /sim/api/respawn 월드 전체 리로드(~6초) — 월드가 이상해졌을 때 쓰는 무거운 리셋

화면

메서드 경로 설명
GET / POST /sim/api/brightness 장면 밝기 — {"value": 0.2..2.0}, 1.0 = 기본. 디스플레이 레이어에서 즉시 적용: 3D 뷰어와 로봇 카메라 프레임이 같은 비율로 어두워지고 밝아집니다. 서버 공유값 하나(모든 뷰어 동기화)로, 월드 전환·재시작 후에도 유지됩니다
GET / POST /sim/api/overlay /sim 화면의 상태 텍스트 — {"text": "...", "ttl": 10}, 텍스트 ≤300자, ttl 1–3600초; 스스로 사라집니다(예: 학습 진행률)

모니터링

메서드 경로 설명
GET /sim/api/state 실시간으로 변하는 모든 것을 한 번에: 월드/실행/전환 상태, 시뮬레이션 time/paused/rtf, 차량 포즈, 물체 포즈, 신호등, 오버레이, 밝기, 평가 실행 상태
GET /sim/api/events 이름 있는 이벤트의 SSE 스트림 — event: state(변경 시 푸시되는 전체 상태 스냅샷)와 event: run(평가 중 학생 프로세스 이벤트). addEventListener로 구독하고 모르는 이벤트 이름은 무시하세요

평가

메서드 경로 설명
GET /sim/api/evaluation 현재 월드의 평가 문서({version, config, script}, World Builder에서 발행) — 월드에 평가가 없으면 404
POST /sim/api/evaluation/run 평가를 위해 학생 코드를 실행 — {"command"?, "time_limit_s"?}, 기본값은 월드의 평가 config에서. 출력은 /sim/api/events의 event: run으로 스트리밍됩니다
POST /sim/api/evaluation/stop 학생 프로세스 정지(멱등)

보통은 /sim 페이지의 ▶ 버튼으로 실행합니다.

월드 관리

메서드 경로 설명
GET /sim/api/worlds 월드 목록(현재 월드 포함): name, file, display(발행 이름, 공식 월드는 표시 이름), world_id(32자리 hex 발행 ID, 빌트인은 null), official, evaluation, deletable
POST /sim/api/switch 월드 전환 — {"world": "<name>.world"} 또는 {"world_id": "<32자리 hex ID>"}; ID 방식은 설치된 발행 월드를 찾아가고 미설치면 404. 월드 전체 로드라 수 초 걸립니다
GET /sim/api/worldpub 현재 월드의 발행 좌표(설치된 발행 월드의 world_id/rev)와 공식 에셋 CDN 리비전·CDN 베이스 URL
POST /sim/api/worlds/install 발행 월드를 worlds CDN에서 설치 — {"world_id": "<32자리 hex ID>"}. 서버 측 다운로드로 custom_*으로 설치되고, 같은 rev가 이미 설치되어 있으면 다운로드 없이 "cached": true를 반환합니다

/sim 뷰어도 같은 일을 합니다

웹 뷰어는 직접 조작을 지원합니다: 물체를 클릭해 선택, 드래그로 이동, 파란 점 핸들 드래그로 회전. 신호등을 클릭하면 RED/GREEN 패널이 열립니다. 차량도 같은 방법으로 옮길 수 있습니다. 전부 위의 pose API로 이어집니다.

더 알아보기

AI