Data Conventions, Threading and Errors (C# API)

The rules that hold across all of AR51.Net: units, axes, time, threading and errors.

Units and axes

• Positions are in meters.
• The AR 51 world is left-handed: X right, Y up, Z forward — the same axes as Unity.
• Rotations are System.Numerics.Quaternion; vectors and matrices are System.Numerics types.
• Camera calibration follows the OpenCV convention: focal lengths and principal point in pixels, and WorldToCamera maps a world point into the camera's space (X right, Y down, Z forward). See Cameras.

Time

• CaptureTime — when the cameras captured the data, on the server's clock, in UTC. It's the Unix epoch (1970-01-01) when the server didn't send a valid time.
• ReceivedTime — when your app received it, on your clock.

Their difference is the true delay only when both clocks are synchronized, for example with NTP.

Undetected joints

A body joint the cameras couldn't see is reported at (0, 0, 0) with confidence 0. Use Skeleton.TryGetPosition to tell it apart from a real position.

Threading

• Every member is safe to call from any thread. Create one client and keep it for the life of your application.
• SkeletonReceived and ObjectReceived are raised on the stream's own background thread, one event per skeleton or object, in arrival order. Keep these handlers short: for example, 20 people at 120 frames per second leaves all handlers together about 0.4 ms per skeleton. Copy what you need and do heavy work elsewhere — see hand-off patterns.
• All other events — connection state, servers, devices, calibration, auto-tune, recording — are raised in order, one at a time, on one background thread per client.
• A handler that throws is logged and doesn't stop the other handlers or the stream. Handlers may call StopAsync or DisposeAsync on the client.
• To update a UI, marshal to your UI thread (for example with SynchronizationContext or your framework's dispatcher).

Errors

Failed calls throw AR51Exception; its ErrorCode says why:

ErrorCode	Meaning	What to do
ServiceUnavailable	The server, or the service needed, isn't reachable — for example the client isn't started yet	Call StartAsync first; check the AR 51 machines are running
ConnectionLost	The connection dropped during the call	Retry once the client has reconnected
Timeout	The server didn't answer in time	Retry
Rejected	The server refused the request and says why — for example "a calibration is already running"	Read exception.Message; fix the request or try again later
ServerError	The server failed while handling the request	Retrying is unlikely to help until the server is fixed or restarted
Unknown	Anything else	See the inner exception

Cancelling throws OperationCanceledException; using a disposed client throws ObjectDisposedException — as usual in .NET.

try
{
    await ar51.Calibration.StartCalibrationAsync();
}
catch (AR51Exception exception) when (exception.ErrorCode == AR51ErrorCode.Rejected)
{
    Console.WriteLine($"Refused by the server: {exception.Message}");
}

Reference

AR51Exception · AR51ErrorCode · API reference