IObjectDetectionClient

interface thread-safe

namespace AR51.Net;

public interface IObjectDetectionClient

Live tracked objects, for example props. Use it through IAR51Client.ObjectDetection, or on its own as an ObjectDetectionClient with the service's address.

Works exactly like ISkeletonClient. Two ways to receive objects: call StartAsync and handle ObjectReceived, or read StreamAsync with await foreach. All members are safe to use from any thread.

Units

Positions are in meters, in the AR 51 world: left-handed, X right, Y up, Z forward (the same axes as Unity). See Data conventions.

How-to

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

Properties

Property	Type	Access	Description
IsAvailable	bool	get	true when the object detection service's address is known (always, for a standalone ObjectDetectionClient).

Method summary

Method	Returns
StartAsync	Task
StopAsync	Task
StreamAsync	IAsyncEnumerable<TrackedObject>

→ 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
ObjectReceived	TrackedObjectEventArgs	Raised for every object received while started, one event per object per frame, on a background thread. Keep handlers short: they run on the receiving thread. An exception thrown by a handler is logged and does not stop the others or the stream.

Example

ar51.ObjectDetection.ObjectReceived += (_, e) =>
    Console.WriteLine($"{e.Object.Name} at {e.Object.Position} m");

Method details

StartAsync

method

Task StartAsync(CancellationToken cancellationToken = default);

Starts receiving objects into ObjectReceived. Returns at once; calling it again does nothing.

Parameters

cancellationTokenCancellationTokenIgnored. Optional.

ReturnsTaskA completed task.

Throws

ObjectDisposedExceptionThe client was disposed.

note

Receiving begins as soon as the service is reachable, and resumes by itself after the service restarts or the network drops, until StopAsync or dispose.

StopAsync

method

Task StopAsync(CancellationToken cancellationToken = default);

Stops receiving objects: stops ObjectReceived, ends every StreamAsync loop running now, and waits until the event stream is closed. Calling it again does nothing.

Parameters

cancellationTokenCancellationTokenStops waiting for the stream to close; the stream still closes. Optional.

ReturnsTaskA task that completes when the event stream is closed.

note

StreamAsync loops end normally, without an exception, after the object they are handling. Loops started after this call are not affected.

StreamAsync

method

IAsyncEnumerable<TrackedObject> StreamAsync(CancellationToken cancellationToken = default);

Streams objects until StopAsync is called (the loop ends normally), cancellationToken is cancelled, or the connection drops. Works without StartAsync.

Parameters

cancellationTokenCancellationTokenStops the stream. Optional.

ReturnsIAsyncEnumerable<TrackedObject>Objects in the order they arrive, one per object per frame.

Throws

AR51ExceptionThe object detection service is not available, or the stream failed.

OperationCanceledExceptioncancellationToken was cancelled.

ObjectDisposedExceptionThe client was disposed.

note

Each call opens its own stream, which closes when the loop ends. Unlike ObjectReceived, it does not reconnect: start a new loop after an AR51Exception.

Related types

Small types used by this interface, documented here.

TrackedObjectEventArgs

class · sealed

public sealed class TrackedObjectEventArgs : EventArgs

Data for IObjectDetectionClient.ObjectReceived.

Property	Type	Access	Description
Object	TrackedObject	get	The received object.

Constructor

public TrackedObjectEventArgs(TrackedObject trackedObject);

Creates the event data.

See also

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