mirror of
https://github.com/Rulez777/FramePicoTracker.git
synced 2026-10-18 02:01:18 +02:00
44 lines
4.2 KiB
Markdown
44 lines
4.2 KiB
Markdown
# Reimplementation contracts and versioned interfaces
|
||
|
||
This is an explanatory specification derived from the inspected first-party interfaces. It is not a copy of their implementation or an assertion that a new implementation is already admitted. Obtain the matching source and confirm the version before integration.
|
||
|
||
## PTP2 measured-pose loopback
|
||
|
||
The current inspected Python/C++ pair uses a packed88byte little-endian record over UDP localhost39571. Time is Linux CLOCK_MONOTONIC nanoseconds ON FRAME, not a remote PC clock. The producer must first transform calibrated optical measurements into OpenVR standing space.
|
||
|
||
| Offset | Size | Field |
|
||
|---|---|---|
|
||
|0|4|ASCII magicPTP2|
|
||
|4|4|uint32 chip identity, nonzero|
|
||
|8|4|uint32 flags:bit0connected,bit1pose_valid,bit2verified battery present; all other bits rejected|
|
||
|12|8|uint64 sequence|
|
||
|20|8|uint64 source_time_ns|
|
||
|28|12|float32 positionXYZ in OpenVR world metres|
|
||
|40|16|float32 quaternionXYZW; consumer normalizes admitted norm|
|
||
|56|12|float32 linear velocityXYZ|
|
||
|68|12|float32 angular velocityXYZ|
|
||
|80|4|float32 battery percent0..100 if verified, otherwise exactly−1|
|
||
|84|4|float32 quality0..1|
|
||
|
||
Admission requires correct magic/size/flags, finite values with absolute value≤1e6, nonzero source time not in the future and age≤250000000ns, quaternion squared norm0.81..1.21, and positive quality plus connected when pose_valid is true. Unknown battery stays absent/−1, never guessed. Field-size/packing checks matter because sequence/source are unaligned in this packed layout.
|
||
|
||
The driver sets poseTimeOffset from the actual source age. Connected-but-out-of-range and a fresh measured valid pose are different states. Invalidation after missing/stale/uncertain data is mandatory. A sequence accepted by the transport does not authorize the producer to claim a measured pose.
|
||
|
||
## Camera binding and transforms
|
||
|
||
Each recording frame must identify the source camera and match exactly one local factory serial and active calibration entry. The inspected KB schema requires cameraModelkb, supported zero pre-rotation, positive focal lengths, finitefx/fy/cx/cy/k1..k4, exactwidth/height and monotonic inversion in the admitted pixel domain. Crop/thermal/half-pixel conventions must be established by the caller, not inferred from image size.
|
||
|
||
Camera rays are unit rays in the camera frame with positiveZ forward. No OpenVR/world transformation is implicit in pixel-to-ray conversion. Compose measured camera-to-tracker with actual same-exposure head/world pose and the appropriate HEAD/CAD/reference/active-camera chain. Validate units and rigid axes. Do not catch an out-of-domain KB inversion as a valid ray.
|
||
|
||
## Native mode and notifications
|
||
|
||
The authored FW189 interface uses schema/nonce/identity-bound queries and switches; active mode, pending mode andN are separate. Preserve per-command6bit sequence,32bit/actual transport tag width and current peer link attribution. Native16 transport ACK can trigger a fresh query, but only an exact native reply can complete applied-mode proof. Mode proof expires on its finite lease and is revoked by disconnect/target change.
|
||
|
||
Timed optical10 uses its exact current8byte command packet within16byte timing metadata in the selected path. Sample feedback11 is a separate independent command; it must not be concatenated into that packet. Native19 admission requires the actual current producer state, upstream gates and optical/clock/mode proofs, not an ACK or generated fixture.
|
||
|
||
## Historical SDK-PC bridge, not the standalone path
|
||
|
||
The separate SDK3.4.0/Unity2022.3.22f1 prototype used TCP39500 with12byte little-endian header: uint32magic0x31425450(PTB1),uint16version1,uint16type,uint32payload length. Type2Hello is UTF-8JSON; type1Frame carries headset monotonic seconds, frame counter, HMD7floats and variable tracker records. Pose uses Unity left-handed+Yup/+Zforward metres andXYZW quaternion after SDK conversion; raw SDK velocities need an explicit frame/unit audit. PC output used OSC/VMT localhost39570.
|
||
|
||
These fields document an alternate architecture only. Do not feed its PC clock/Unity poses into PTP2 without explicit conversion and Frame-time/world calibration, and do not claim it meets the onboard-Roy standalone objective.
|