ICameraClient

interface thread-safe

namespace AR51.Net;

public interface ICameraClient

The AR 51 cameras: list them with their calibration values, preview their video, change their image settings, and tune those settings automatically. Use it through IAR51Client.Cameras.

Cameras are spread over several camera servers; this client covers all of them. 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 Cameras guide.

Properties

Property	Type	Access	Description
AutoTuneStatus	AutoTuneStatus	get	The latest auto-tune status reported by the camera servers, whoever started the auto-tune. Camera servers that do not report auto-tune progress get an estimate (AutoTuneStatus.IsEstimated) for each auto-tune this client starts; an auto-tune started by another app is not seen on those servers.

Method summary

Method	Returns
GetCamerasAsync	Task<IReadOnlyList<CameraInfo>>
StreamPreviewAsync	IAsyncEnumerable<CameraFrame>
GetSettingsAsync	Task<CameraSettings>
SetSettingsAsync	Task<CameraSettings>
StartAutoTuneAsync	Task
CancelAutoTuneAsync	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
AutoTuneStarted	AutoTuneStatusEventArgs	Raised when an auto-tune starts, whoever started it. Raised on a background thread.
AutoTuneProgressChanged	AutoTuneStatusEventArgs	Raised when an auto-tune's progress changes. Raised on a background thread.
AutoTuneEnded	AutoTuneEndedEventArgs	Raised when an auto-tune ends: completed, failed or cancelled. Raised on a background thread.

Method details

GetCamerasAsync

method

Task<IReadOnlyList<CameraInfo>> GetCamerasAsync(CancellationToken cancellationToken = default);

Gets every camera of the system, with its status and calibration values.

Parameters

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTask<IReadOnlyList<CameraInfo>>The cameras. A camera server that does not answer in time is left out.

Throws

AR51ExceptionNo camera server is available (AR51ErrorCode.ServiceUnavailable).

Example

foreach (CameraInfo camera in await ar51.Cameras.GetCamerasAsync())
    Console.WriteLine($"{camera.Name}: {camera.Width}x{camera.Height} @ {camera.FrameRate} fps, " +
                      $"{(camera.IsConnected ? "connected" : "offline")}");

StreamPreviewAsync

method

IAsyncEnumerable<CameraFrame> StreamPreviewAsync(string cameraId, PreviewOptions? options = null, CancellationToken cancellationToken = default);

Streams a camera's live video as JPEG images until the loop ends or cancellationToken is cancelled.

Parameters

cameraIdstringThe camera's CameraInfo.Id.

optionsPreviewOptions?Image size, frame rate and quality. null uses the camera's own size and frame rate. Optional.

cancellationTokenCancellationTokenStops the preview. Optional.

ReturnsIAsyncEnumerable<CameraFrame>The frames, in the order they arrive.

Throws

AR51ExceptionThe camera does not exist (AR51ErrorCode.Rejected), or the stream failed.

OperationCanceledExceptioncancellationToken was cancelled.

note

Each preview costs network bandwidth: for many cameras at once, request small images at a low frame rate. Ending the await foreach loop stops the preview.

Example

// A small preview that fits 640 x 480; ending the loop stops the stream.
var options = new PreviewOptions { FitWidth = 640, FitHeight = 480, FrameRate = 5 };
await foreach (CameraFrame frame in ar51.Cameras.StreamPreviewAsync(camera.Id, options))
{
    await File.WriteAllBytesAsync($"{camera.Id}.jpg", frame.Jpeg.ToArray());
    break;
}

GetSettingsAsync

method

Task<CameraSettings> GetSettingsAsync(string cameraId, CancellationToken cancellationToken = default);

Gets a camera's image settings.

Parameters

cameraIdstringThe camera's CameraInfo.Id.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTask<CameraSettings>The settings the camera uses now.

Throws

AR51ExceptionThe camera does not exist (AR51ErrorCode.Rejected) or could not be reached.

SetSettingsAsync

method

Task<CameraSettings> SetSettingsAsync(string cameraId, CameraSettings settings, CancellationToken cancellationToken = default);

Changes a camera's image settings. Only the values that differ from the camera's current settings are sent. The server saves them, so they survive a restart.

Parameters

cameraIdstringThe camera's CameraInfo.Id.

settingsCameraSettingsThe new settings. Start from GetSettingsAsync and change values with with.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTask<CameraSettings>The settings the camera uses afterwards: a camera can adjust a value it cannot apply exactly.

Throws

AR51ExceptionThe camera does not exist or refused a value (AR51ErrorCode.Rejected), or could not be reached.

Affects every app using the system

Settings are saved on the server and apply to every app using the system. Excluding a camera from tracking, or changing its exposure during a live session, changes tracking for everyone.

Example

CameraSettings settings = await ar51.Cameras.GetSettingsAsync(camera.Id);
await ar51.Cameras.SetSettingsAsync(camera.Id, settings with { ExposureMicroseconds = 4000, Gain = 2 });

StartAutoTuneAsync

method

Task StartAutoTuneAsync(AutoTuneOptions? options = null, CancellationToken cancellationToken = default);

Starts tuning the cameras' color balance (red, green and blue gain) automatically, using each camera's own one-shot white balance; it takes about two seconds. Follow it with AutoTuneProgressChanged and AutoTuneEnded, then read the new values with GetSettingsAsync.

Parameters

optionsAutoTuneOptions?Which cameras to tune. null tunes all of them. Optional.

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the camera servers have started tuning.

Throws

AR51ExceptionA camera server refused (AR51ErrorCode.Rejected) or no camera server is available.

Affects every app using the system

Changes the image settings of every camera you include (all of them by default), for every app using the system.

Example

ar51.Cameras.AutoTuneProgressChanged += (_, e) => Console.WriteLine($"auto-tune {e.Status.Progress:P0}");
ar51.Cameras.AutoTuneEnded += (_, e) => Console.WriteLine($"auto-tune {e.Outcome}");
await ar51.Cameras.StartAutoTuneAsync();   // all cameras

CancelAutoTuneAsync

method

Task CancelAutoTuneAsync(CancellationToken cancellationToken = default);

Cancels a running auto-tune, whoever started it. The cameras keep the settings they had before. Does nothing if none is running.

Parameters

cancellationTokenCancellationTokenCancels the request. Optional.

ReturnsTaskA task that completes when the camera servers have accepted the request.

Throws

AR51ExceptionA camera server could not be reached.

note

A camera server that cannot cancel is not an error: its auto-tune takes about two seconds and finishes on its own, so it ends as AutoTuneOutcome.Completed.

Related types

Small types used by this interface, documented here.

PreviewOptions

record · sealed

public sealed record PreviewOptions

Options for ICameraClient.StreamPreviewAsync.

note

The image is shrunk to fit inside FitWidth × FitHeight, keeping the camera's aspect ratio, so you always see the whole picture. It is never enlarged beyond the camera's own size.

Property	Type	Access	Default	Description
FitWidth	int?	get · init	—	Largest image width, in pixels. null = no limit (the camera's own width).
FitHeight	int?	get · init	—	Largest image height, in pixels. null = no limit (the camera's own height).
FrameRate	int?	get · init	—	Frames per second to send. null = the camera's own frame rate.
JpegQuality	int	get · init	70	JPEG quality, from 1 (smallest) to 100 (best). 70 by default.

CameraFrame

record · sealed

public sealed record CameraFrame(ReadOnlyMemory<byte> Jpeg, int Width, int Height, double CameraFps, DateTimeOffset ReceivedTime);

One preview image from a camera.

Property	Type	Description
Jpeg	ReadOnlyMemory<byte>	The image, JPEG-encoded.
Width	int	Image width, in pixels.
Height	int	Image height, in pixels.
CameraFps	double	Frames per second the camera is capturing at.
ReceivedTime	DateTimeOffset	When this client received the image (local clock).

AutoTuneOptions

record · sealed

public sealed record AutoTuneOptions

Options for ICameraClient.StartAutoTuneAsync.

Property	Type	Access	Default	Description
CameraIds	IReadOnlyList<string>	get · init	[]	The cameras to tune, by CameraInfo.Id. Empty = all cameras.

AutoTuneStatus

record · sealed

public sealed record AutoTuneStatus(bool IsRunning, double Progress, IReadOnlyList<CameraAutoTuneStatus> Cameras);

The status of an auto-tune across all camera servers.

Property	Type	Description
IsRunning	bool	Whether an auto-tune is running.
Progress	double	Overall progress, from 0 to 1.
Cameras	IReadOnlyList<CameraAutoTuneStatus>	Progress of each camera being tuned.

Property	Type	Access	Description
IsEstimated	bool	get · init	True when the camera servers do not report auto-tune progress and AR51.Net estimates it: progress over about two seconds (the time the servers take), then AutoTuneOutcome.Completed. A server that reports real progress replaces the estimate as soon as it does.

CameraAutoTuneStatus

record · sealed

public sealed record CameraAutoTuneStatus(string CameraId, double Progress, string? Error);

The auto-tune status of one camera.

Property	Type	Description
CameraId	string	The camera's CameraInfo.Id.
Progress	double	Progress, from 0 to 1.
Error	string?	Why tuning this camera failed, or null.

AutoTuneOutcome

enum

public enum AutoTuneOutcome

How an auto-tune ended.

Value	Meaning
Completed = 0	The settings were tuned and applied.
Failed = 1	Tuning failed; see each camera's CameraAutoTuneStatus.Error.
Cancelled = 2	Someone cancelled it; the cameras kept their previous settings.

AutoTuneStatusEventArgs

class · sealed

public sealed class AutoTuneStatusEventArgs : EventArgs

Data for ICameraClient.AutoTuneStarted and ICameraClient.AutoTuneProgressChanged.

Property	Type	Access	Description
Status	AutoTuneStatus	get	The auto-tune status.

Constructor

public AutoTuneStatusEventArgs(AutoTuneStatus status);

Creates the event data.

AutoTuneEndedEventArgs

class · sealed

public sealed class AutoTuneEndedEventArgs : EventArgs

Data for ICameraClient.AutoTuneEnded.

Property	Type	Access	Description
Outcome	AutoTuneOutcome	get	How the auto-tune ended.
Status	AutoTuneStatus	get	The final status, with each camera's result.

Constructor

public AutoTuneEndedEventArgs(AutoTuneOutcome outcome, AutoTuneStatus status);

Creates the event data.

See also

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