> For the complete documentation index, see [llms.txt](https://help.movin3d.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.movin3d.com/movin-tracin-stage-kr/reference/osc-format.md).

# OSC 메시지 형식

사용할 프로그램에서 수신 연동을 직접 구성할 때 참고해주세요. 네트워크와 첫 메시지 확인은 [첫 데이터 수신 확인](/movin-tracin-stage-kr/setup/receive-output.md)을 참고하세요.

아래는 현재 송신 구현 기준입니다. 이전 설치의 연동을 유지보수할 때는 실제 수신 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 인수 목록입니다.

프레임은 다음과 같이 조립합니다.

1. `seq`별로 묶고 전체 점 수·청크 수가 일치하는지 검사합니다.
2. `chunk_idx`별로 저장하며 같은 청크가 다시 오면 중복 처리하지 않습니다.
3. `0`부터 `num_chunks - 1`까지 모이면 번호순으로 점을 이어 붙이고 `total_points`와 비교합니다.
4. 프로그램에 맞는 대기 시간을 정해 불완전한 프레임을 만료시킵니다. 서로 다른 프레임의 청크를 섞지 말고 재연결 때 이전 상태를 정리해주세요.

선택한 점군에 점이 없으면 점군 청크도 전송되지 않습니다. 수신 타임아웃을 두고 오래된 표시를 지우거나 상태를 표시해, 마지막 프레임이 계속 남지 않도록 구성해주세요.

## 스켈레톤

본마다 메시지가 전송됩니다. Root는 `/VMC/Ext/Root/Pos`, 나머지는 `/VMC/Ext/Bone/Pos` 주소를 사용합니다. 현재 형식은 다음과 같습니다.

```
type tag: ,ssfffffffi
arguments: actor, bone, px, py, pz, qx, qy, qz, qw, frame_idx
```

* `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,
LeftShoulder, LeftUpperArm, LeftLowerArm, LeftHand,
RightShoulder, RightUpperArm, RightLowerArm, RightHand,
LeftUpperLeg, LeftLowerLeg, LeftFoot, LeftToes,
RightUpperLeg, RightLowerLeg, RightFoot, RightToes
```

계층은 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, 본 매핑, 좌표 변환부터 확인해주세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.movin3d.com/movin-tracin-stage-kr/reference/osc-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.