OSC 메시지 형식
사용할 프로그램에서 수신 연동을 직접 구성할 때 참고해주세요. 네트워크와 첫 메시지 확인은 Stage 2 · Settings의 OSC output을 참고하세요.
아래는 현재 송신 구현 기준입니다. 이전 설치의 연동을 유지보수할 때는 실제 수신 type tag를 확인해주세요. 특히 스켈레톤에는 이전 형식이 있습니다.
전송 방식
OSC over UDP입니다. 수신 포트와 Target port를 같게 설정합니다.
주소는 대소문자를 구분합니다. 기본 점군 주소는
/MOVIN/PointCloud이며 설치 구성에 따라 달라질 수 있습니다.OSC 숫자는 big-endian입니다. 데이터그램을 일반 문자열로 읽지 말고 OSC 디코더로 주소·문자열 패딩·type tag·인수를 처리해주세요.
UDP는 패킷 유실·중복·순서 변경이 생길 수 있습니다. 한 패킷 수신이 한 프레임 전체 수신은 아닙니다.
연결 테스트
/movin/test의 type tag는 ,i이며 signed int32 값 하나를 담습니다. 추적 인원수가 아닌 테스트 값입니다. 프리뷰 중에도 Test connection을 선택하면 전송합니다.
점군
기본 주소는 /MOVIN/PointCloud입니다. 정수 5개 뒤에 XYZ float 묶음이 이어집니다.
seq, total_points, chunk_idx, num_chunks, chunk_n, x1, y1, z1, ...seq
프레임 순서 번호. 같은 값의 청크끼리 묶습니다.
total_points
완성된 프레임의 전체 점 수
chunk_idx
이 청크의 번호. 0부터 시작합니다.
num_chunks
해당 프레임의 전체 청크 수
chunk_n
이 청크에 포함된 점 수
XYZ 묶음
3 × chunk_n개의 float32 인수. 단위는 미터입니다.
Type tag는 ,iiiii 뒤에 f가 3 × chunk_n개 이어집니다. 점 하나인 청크는 ,iiiiifff입니다. Blob이 아니라 OSC 인수 목록입니다.
프레임은 다음과 같이 조립합니다.
seq별로 묶고 전체 점 수·청크 수가 일치하는지 검사합니다.chunk_idx별로 저장하며 같은 청크가 다시 오면 중복 처리하지 않습니다.0부터num_chunks - 1까지 모이면 번호순으로 점을 이어 붙이고total_points와 비교합니다.프로그램에 맞는 대기 시간을 정해 불완전한 프레임을 만료시킵니다. 서로 다른 프레임의 청크를 섞지 말고 재연결 때 이전 상태를 정리해주세요.
선택한 점군에 점이 없으면 점군 청크도 전송되지 않습니다. 수신 타임아웃을 두고 오래된 표시를 지우거나 상태를 표시해, 마지막 프레임이 계속 남지 않도록 구성해주세요.
스켈레톤
본마다 메시지가 전송됩니다. Root는 /VMC/Ext/Root/Pos, 나머지는 /VMC/Ext/Bone/Pos 주소를 사용합니다. 현재 형식은 다음과 같습니다.
actor,bone은 문자열입니다. 기본 actor 접두사MOVIN에 슬롯 번호가 붙습니다. 예:MOVIN_0. 프레임뿐 아니라 actor도 구분해서 처리해주세요.Actor 이름은 출력 슬롯을 뜻하며 실행 간 유지되는 영구적인 사람 식별자가 아닙니다.
위치 단위는 미터, 쿼터니언 순서는 x, y, z, w입니다.
Root·Hips는 실시간 위치, 다른 본은 리그 오프셋을 보냅니다. 회전은 스켈레톤 계층에 대한 로컬 회전입니다. 모든 본을 독립적인 월드 좌표 점으로 놓거나 위치 필드가 모두 같은 의미라고 가정하지 마세요.
frame_idx는 int32 프레임 번호이며 초 단위 타임스탬프가 아닙니다. 표준 VMC에는 없는 필드이므로 일반 VMC 수신기와 바로 호환되지 않을 수 있습니다.사라진 actor는 타임아웃으로 처리해주세요. OSC를 수신하는 것만으로 캐릭터가 움직이지는 않으므로 본 이름과 변환을 사용하는 리그에 매핑해야 합니다.
현재 본 이름은 다음과 같습니다.
계층은 Root → Hips → Spine → Chest → Neck → Head입니다. 양쪽 Shoulder는 Chest에 연결되고 UpperArm → LowerArm → Hand로 이어집니다. 양쪽 다리는 Hips에서 UpperLeg → LowerLeg → Foot → Toes로 이어집니다.
이전 스켈레톤 형식
이전 연동에는 ,sfffffffi 형식이 사용될 수 있습니다. 숫자 필드는 같지만 actor 없이 bone 문자열만 있습니다. 지금의 Spine·Chest 자리에 있는 본은 각각 Chest·UpperChest라는 이름이었습니다. 수신 type tag로 구분하고 현재 형식 파서에 그대로 넣지 마세요.
수신 프로그램에서 좌표 확인
처리·표시 좌표계는 Y-up입니다. 기본 송신은 X를 반전하며 스켈레톤 회전은 쿼터니언 Y·Z도 반전합니다. 설치에 따라 변환 설정이 달라질 수 있으므로 workspace 스크린샷만 보고 송신 좌표를 추정하거나 확인 없이 미러 변환을 한 번 더 적용하지 마세요.
한 사람이 움직이며 수신 화면의 원점·크기·앞·오른쪽을 확인하고, 한쪽 팔을 들어 좌우 본 매핑도 확인해주세요. 사용하는 엔진에 맞는 변환을 점군·스켈레톤에 일관되게 한 번 적용합니다.
패킷은 오는데 콘텐츠가 이상하면 센서를 다시 보정하기 전에 청크 조립, type tag, 본 매핑, 좌표 변환부터 확인해주세요.
마지막 업데이트