ICalibrationClient

interface thread-safe

namespace AR51.Net;

public interface ICalibrationClient

Camera calibration and the tracked area (capture bounds). Use it through IAR51Client.Calibration.

A calibration ends by itself once it has collected enough data, or when someone stops it. This client reports every calibration, whoever started it (this app, Mocap Studio or another client). All members are safe to use from any thread.

How-to

This page is reference (facts only). For a walkthrough with a complete sample, see the Calibration guide.

Properties

Property	Type	Access	Description
Status	CalibrationStatus	get	The latest calibration status reported by the server, whoever started the calibration.

Method summary

Method	Returns
StartCalibrationAsync	Task
StopCalibrationAsync	Task<CalibrationResult>
GetCaptureBoundsAsync	Task<CaptureBounds>
SetCaptureBoundsAsync	Task

→ Full descriptions in Method details below.

Events

Standard .NET events (EventHandler<T>): subscribe with +=, unsubscribe with -=. They are raised on a background thread.

Event	Args	Raised when
CalibrationStarted	CalibrationStatusEventArgs	Raised when a calibration starts, whoever started it. Raised on a background thread.
CalibrationProgressChanged	CalibrationStatusEventArgs	Raised when a running calibration's progress or error changes. Raised on a background thread.
CalibrationEnded	CalibrationEndedEventArgs	Raised when a calibration ends: it collected enough data, or someone stopped it. Raised on a background thread. The outcome is known only for a calibration this client started; for one started elsewhere it is CalibrationOutcome.Unknown.

Method details

StartCalibrationAsync

method

Task StartCalibrationAsync(CancellationToken cancellationToken = default);

Starts a camera calibration. It ends by itself once it has enough data, or call StopCalibrationAsync.

Parameters

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes once the calibration is running.

Throws

AR51ExceptionA calibration is already running (AR51ErrorCode.Rejected), or the calibration service is not available.

Affects every app using the system

Tracking keeps running on the current calibration meanwhile. A successful calibration replaces every camera's calibration for every app connected to the AR 51 system; a failed or cancelled one leaves the current calibration in place.

note

This client keeps the calibration running: if it is stopped or disposed (for example the app shuts down) before the calibration ends, the calibration is cancelled.

Example

ar51.Calibration.CalibrationProgressChanged += (_, e) =>
    Console.WriteLine($"{e.Status.Progress:P0}, error {e.Status.ReprojectionErrorPixels:F2} px");
ar51.Calibration.CalibrationEnded += (_, e) =>
    Console.WriteLine($"calibration {e.Result.Outcome}");
await ar51.Calibration.StartCalibrationAsync();

StopCalibrationAsync

method

Task<CalibrationResult> StopCalibrationAsync(CancellationToken cancellationToken = default);

Finishes the running calibration now, whoever started it, and waits for its result. Does nothing if none is running.

Parameters

cancellationTokenCancellationTokenStops waiting for the result; the calibration still stops. Optional.

ReturnsTask<CalibrationResult>The result: CalibrationOutcome.Succeeded or CalibrationOutcome.Failed when enough data was collected, CalibrationOutcome.Cancelled when stopped too early, and CalibrationOutcome.Unknown for a calibration started elsewhere or when none was running.

Throws

AR51ExceptionThe calibration service is not available.

Affects every app using the system

Ends the running calibration now, whoever started it — including one an operator started in Mocap Studio. Ended before it has enough data, it is Cancelled.

GetCaptureBoundsAsync

method

Task<CaptureBounds> GetCaptureBoundsAsync(CancellationToken cancellationToken = default);

Gets the tracked area: people outside it are not tracked.

Parameters

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTask<CaptureBounds>The tracked area.

Throws

AR51ExceptionThe calibration service is not available.

SetCaptureBoundsAsync

method

Task SetCaptureBoundsAsync(CaptureBounds bounds, CancellationToken cancellationToken = default);

Sets the tracked area. People outside it are no longer tracked, so a wrong value makes people disappear.

Parameters

boundsCaptureBoundsThe new area.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the server has applied the area.

Throws

ArgumentExceptionbounds has no volume: its size is 0 or less on some axis.

AR51ExceptionThe calibration service is not available.

Affects every app using the system

Applies immediately for every app using the system: anyone outside the new area stops being tracked. Double-check the values first.

Example

CaptureBounds bounds = await ar51.Calibration.GetCaptureBoundsAsync();
// People outside the area are no longer tracked: double-check before applying.
await ar51.Calibration.SetCaptureBoundsAsync(bounds with { Size = bounds.Size + new Vector3(0.5f, 0, 0.5f) });

Related types

Small types used by this interface, documented here.

CalibrationStatus

record · sealed

public sealed record CalibrationStatus(bool IsRunning, double Progress, double ReprojectionErrorPixels, string? Message);

The status of camera calibration.

Property	Type	Description
IsRunning	bool	Whether a calibration is running.
Progress	double	Progress, from 0 to 1.
ReprojectionErrorPixels	double	The calibration error so far, in pixels: lower is better. 0 before any error was measured.
Message	string?	A message for the operator from the server, for example "Calculating final camera calibration...", or null.

CalibrationOutcome

enum

public enum CalibrationOutcome

How a calibration ended.

Value	Meaning
Unknown = 0	Not known: the calibration was started by another app, or none was running.
Succeeded = 1	The calibration succeeded; ICameraClient.GetCamerasAsync returns the new values.
Failed = 2	The calibration failed; the cameras keep their previous values.
Cancelled = 3	The calibration was stopped before it had enough data; the cameras keep their previous values.

CalibrationResult

record · sealed

public sealed record CalibrationResult(CalibrationOutcome Outcome, double ReprojectionErrorPixels);

The result of a calibration.

Property	Type	Description
Outcome	CalibrationOutcome	How the calibration ended.
ReprojectionErrorPixels	double	The final calibration error, in pixels: lower is better.

CalibrationStatusEventArgs

class · sealed

public sealed class CalibrationStatusEventArgs : EventArgs

Data for ICalibrationClient.CalibrationStarted and ICalibrationClient.CalibrationProgressChanged.

Property	Type	Access	Description
Status	CalibrationStatus	get	The calibration status.

Constructor

public CalibrationStatusEventArgs(CalibrationStatus status);

Creates the event data.

CalibrationEndedEventArgs

class · sealed

public sealed class CalibrationEndedEventArgs : EventArgs

Data for ICalibrationClient.CalibrationEnded.

Property	Type	Access	Description
Result	CalibrationResult	get	How the calibration ended.

Constructor

public CalibrationEndedEventArgs(CalibrationResult result);

Creates the event data.

See also

• Calibration guide — walkthrough with a complete, compiled sample
• Class index — every AR51.Net type
• Data conventions, threading and errors