Class ScanSystem

A complete system of ScanHeads.

Inheritance

object

ScanSystem

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: JoeScan.Pinchot

Assembly: JoeScan.Pinchot.dll

Syntax

public class ScanSystem : IDisposable

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Constructors

ScanSystem(ScanSystemUnits)

Initializes a new instance of the scan system class.

Declaration

public ScanSystem(ScanSystemUnits units)

Parameters

Type	Name	Description
ScanSystemUnits	units	The units that this scan system and all associated ScanHeads will use.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Properties

IsConfigured

Obtains the configuration state of the scan system. If true, the system's configuration has already been sent to the scan head via PreSendConfiguration(). If false, the configuration will be sent when StartScanning(uint, DataFormat, ScanningMode) is called and there will be a time penalty before receiving profiles.

Declaration

public bool IsConfigured { get; }

Property Value

Type	Description
bool	A bool value indicating whether the scan system is configured (true) or not (false).

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

IsConnected

Gets a value indicating whether all ScanHeads have established network connection.

Declaration

public bool IsConnected { get; }

Property Value

Type	Description
bool	A value indicating whether all ScanHeads have established network connection.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

IsScanning

Gets a value indicating whether the scan system is actively scanning.

Declaration

public bool IsScanning { get; }

Property Value

Type	Description
bool	A value indicating whether the scan system is actively scanning.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

ScanHeads

Gets a read-only collection of ScanHeads belonging to the scan system.

Declaration

public IReadOnlyCollection<ScanHead> ScanHeads { get; }

Property Value

Type	Description
IReadOnlyCollection<ScanHead>	A IReadOnlyCollection<T> of ScanHeads belonging to the scan system.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Units

Gets the units that this scan system and all associated ScanHeads will use for configuration and returned data. Can only be set when a scan system is created.

Declaration

public ScanSystemUnits Units { get; }

Property Value

Type	Description
ScanSystemUnits	The units of the scan system.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Methods

AddPhase()

Adds an empty phase to the end of the phase table. Elements can be added to this newly created phase by calling AddPhaseElement(uint, Camera) or AddPhaseElement(uint, Laser) after this function has been called.

Declaration

public void AddPhase()

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

AddPhaseElement(uint, Camera)

Adds a camera from the ScanHead with id to the current phase.

Declaration

public void AddPhaseElement(uint id, Camera camera)

Parameters

Type	Name	Description
uint	id	The ScanHead ID.
Camera	camera	The Camera that should expose.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
InvalidOperationException	The ScanHead ID doesn't exist in the scan system. -or- The ScanHead is laser driven, and AddPhaseElement(uint, Laser) should be used instead -or- A phase hasn't been created yet with AddPhase() -or- The camera has already been used in the current phase.
ArgumentException	The camera specified does not exist on the scan head.

AddPhaseElement(uint, Camera, ScanHeadConfiguration)

Adds a camera from the ScanHead with id to the current phase. Overwrites the ScanHeadConfiguration that was applied with Configure(ScanHeadConfiguration) with configuration instead.

Declaration

public void AddPhaseElement(uint id, Camera camera, ScanHeadConfiguration configuration)

Parameters

Type	Name	Description
uint	id	The ScanHead ID.
Camera	camera	The Camera that should expose.
ScanHeadConfiguration	configuration	The ScanHeadConfiguration that will be applied to the element for current phase.

Remarks

Only the MaxLaserOnTimeUs, DefaultLaserOnTimeUs, and MinLaserOnTimeUs are overwritten.

Exceptions

Type	Condition
InvalidOperationException	The ScanHead ID doesn't exist in the scan system. -or- The ScanHead is laser driven, and AddPhaseElement(uint, Laser) should be used instead -or- A phase hasn't been created yet with AddPhase() -or- The camera has already been used in the current phase.
ArgumentException	The camera specified does not exist on the scan head.

AddPhaseElement(uint, Laser)

Adds a laser from the ScanHead with id to the current phase.

Declaration

public void AddPhaseElement(uint id, Laser laser)

Parameters

Type	Name	Description
uint	id	The ScanHead ID.
Laser	laser	The Laser that should be on during exposure.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
InvalidOperationException	The ScanHead ID doesn't exist in the scan system. -or- The ScanHead is camera driven, and AddPhaseElement(uint, Camera) should be used instead -or- A phase hasn't been created yet with AddPhase() -or- The camera that is paired with laser has already been used in the current phase.
ArgumentException	The laser specified does not exist on the scan head.

AddPhaseElement(uint, Laser, ScanHeadConfiguration)

Adds a laser from the ScanHead with id to the current phase. Overwrites the ScanHeadConfiguration that was applied with Configure(ScanHeadConfiguration) with configuration instead.

Declaration

public void AddPhaseElement(uint id, Laser laser, ScanHeadConfiguration configuration)

Parameters

Type	Name	Description
uint	id	The ScanHead ID.
Laser	laser	The Laser that should be on during exposure.
ScanHeadConfiguration	configuration	The ScanHeadConfiguration that will be applied to the element for current phase.

Remarks

Only the MaxLaserOnTimeUs, DefaultLaserOnTimeUs, and MinLaserOnTimeUs are overwritten.

Exceptions

Type	Condition
InvalidOperationException	The ScanHead ID doesn't exist in the scan system. -or- The ScanHead is camera driven, and AddPhaseElement(uint, Camera) should be used instead -or- A phase hasn't been created yet with AddPhase() -or- The camera that is paired with laser has already been used in the current phase.
ArgumentException	The laser specified does not exist on the scan head.

ClearFrames()

Empties the internal client side software buffers used to store frames.

Under normal scanning conditions where the application consumes frames as they become available, this function will not be needed. Its use is to be found in cases where the application fails to consume frames after some time and the number of buffered frames becomes more than the application can consume and only the most recent scan data is desired.

When operating in profile scanning mode, use ClearProfiles() instead.

Declaration

public void ClearFrames()

Remarks

Frames are automatically cleared when StartScanning(uint, DataFormat, ScanningMode) is called.

ClearPhaseTable()

Clears all phases and elements added to the phase table.

Declaration

public void ClearPhaseTable()

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Connect(TimeSpan)

Attempts to connect to all ScanHeadss.

Declaration

public IReadOnlyCollection<ScanHead> Connect(TimeSpan connectTimeout)

Parameters

Type	Name	Description
TimeSpan	connectTimeout	The connection timeout period.

Returns

Type	Description
IReadOnlyCollection<ScanHead>	A IReadOnlyCollection<T> of ScanHeads that did not successfully connect.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
InvalidOperationException	ScanHeads does not contain any ScanHeads. -or- IsConnected is true. -or- IsScanning is true. -or- One or more ScanHeads were not seen on the network.
VersionCompatibilityException	A scan head has a firmware version that is incompatible with the API.

CreateScanHead(uint, uint)

Creates a ScanHead and adds it to ScanHeads.

Declaration

public ScanHead CreateScanHead(uint serialNumber, uint id)

Parameters

Type	Name	Description
uint	serialNumber	The serial number of the scan head.
uint	id	The ID to associate with the ScanHead.

Returns

Type	Description
ScanHead	The created ScanHead.

Remarks

scan system must not be connected. Verify IsConnected is false and/or call Disconnect() before calling ths method.

Exceptions

Type	Condition
InvalidOperationException	IsConnected is true. -or- IsScanning is true.
ArgumentException	ScanHeads already contains a ScanHead with serialNumber. -or- ScanHeads already contains a ScanHead with id.

Disconnect()

Disconnects from all ScanHeadss.

Declaration

public void Disconnect()

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
InvalidOperationException	IsConnected is false. -or- IsScanning is true.

DiscoverDevices()

Performs a network discovery to determine what scan heads are on the network.

Declaration

public Dictionary<uint, DiscoveredDevice> DiscoverDevices()

Returns

Type	Description
Dictionary<uint, DiscoveredDevice>	A dictionary of all discovered scan heads where the key is the serial number.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

DiscoverDevicesAsync()

Performs a network discovery to determine what scan heads are on the network.

Declaration

public Task<Dictionary<uint, DiscoveredDevice>> DiscoverDevicesAsync()

Returns

Type	Description
Task<Dictionary<uint, DiscoveredDevice>>	A dictionary of all discovered scan heads where the key is the serial number.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Dispose()

Releases the managed and unmanaged resources used by the scan system.

Declaration

public void Dispose()

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Dispose(bool)

Releases the unmanaged resources used by the scan system and optionally releases the managed resources.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Whether being disposed explicitly (true) or due to a finalizer (false).

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

~ScanSystem()

A complete system of ScanHeads.

Declaration

protected ~ScanSystem()

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

GetMinScanPeriod()

Gets the minimum scan period allowed by the scan system in microseconds.

Declaration

public uint GetMinScanPeriod()

Returns

Type	Description
uint	The minimum scan period allowed by the scan system in microseconds.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
InvalidOperationException	IsConnected is false. -or- The phase table is empty. -or- A loss of communication with any scan head occurred, usually caused by a network or power issue.

GetScanHeadByID(uint)

Gets a ScanHead by ID.

Declaration

public ScanHead GetScanHeadByID(uint id)

Parameters

Type	Name	Description
uint	id	The ID of the desired ScanHead.

Returns

Type	Description
ScanHead	The ScanHead.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
ArgumentException	ScanHeads does not contain a ScanHead with specified id.

GetScanHeadBySerialNumber(uint)

Gets a ScanHead by serial number.

Declaration

public ScanHead GetScanHeadBySerialNumber(uint serialNumber)

Parameters

Type	Name	Description
uint	serialNumber	The serial number of the desired ScanHead.

Returns

Type	Description
ScanHead	The ScanHead.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
ArgumentException	ScanHeads does not contain a ScanHead with specified serialNumber.

PreSendConfiguration()

Prepares the scan system to begin scanning. If connected, this function will send all of the necessary configuration data to all of the scan heads. Provided that no changes are made to any of the scan heads associated with the scan system, the API will skip sending this data to the scan heads when calling StartScanning(uint, DataFormat, ScanningMode) and allow scanning to start faster.

Declaration

public void PreSendConfiguration()

Remarks

• This method is invoked automatically when Connect(TimeSpan) is successful.
• If not manually called between a successful connection and scanning, it will be called automatically in StartScanning(uint, DataFormat, ScanningMode).

Exceptions

Type	Condition
InvalidOperationException	IsScanning is true. -or- IsConnected is true. -or- A loss of communication with any scan head occurred, usually caused by a network or power issue.

See Also

IsConfigured

StartScanning(uint, DataFormat, ScanningMode)

Starts scanning on all ScanHeads.

Declaration

public void StartScanning(uint periodUs, DataFormat dataFormat, ScanningMode mode = ScanningMode.Profile)

Parameters

Type	Name	Description
uint	periodUs	The scan period in microseconds.
DataFormat	dataFormat	The DataFormat.
ScanningMode	mode	The ScanningMode.

Remarks

scan system must be connected. Verify IsConnected is true and/or call Connect(TimeSpan) before calling ths method.

All existing IProfiles will be cleared from all ScanHeads when calling this method. Ensure that all data from the previous scan that is desired is read out before calling this method.

The periodUs is the period in which each individual scan head will generate profiles.

Exceptions

Type	Condition
InvalidOperationException	IsConnected is false. -or- IsScanning is true. -or- There are duplicate elements from the same scan head in the phase table. -or- A loss of communication with any scan head occurred, usually caused by a network or power issue.
ArgumentOutOfRangeException	Requested scan period periodUs is invalid.
VersionCompatibilityException	A scan head has a firmware version that is incompatible with frame scanning (when mode is Frame).

StopScanning()

Stops scanning on all ScanHeads.

Declaration

public void StopScanning()

Remarks

Physical scan heads will take approximately 0.5-1.0 seconds to stop scanning after StopScanning() is called. IProfiles will remain in the profile buffers until they are either consumed or StartScanning(uint, DataFormat, ScanningMode) is called.

Exceptions

Type	Condition
InvalidOperationException	IsScanning is false.

TakeAnyProfile(out IProfile, CancellationToken)

Tries to take an IProfile from any profile queue in ScanHeads, blocking if all the queues are empty.

Declaration

public bool TakeAnyProfile(out IProfile profile, CancellationToken token = default)

Parameters

Type	Name	Description
IProfile	profile	The dequeued IProfile.
CancellationToken	token	Token to observe.

Returns

Type	Description
bool	true if a profile was taken else false.

Remarks

The profile queues are not guarenteed to be taken from equally or in any order.

TakeFrame(CancellationToken)

Tries to take an IFrame, blocking if one isn't ready.

Declaration

public IFrame TakeFrame(CancellationToken token = default)

Parameters

Type	Name	Description
CancellationToken	token	The CancellationToken to observe.

Returns

Type	Description
IFrame	The dequeued IFrame.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
OperationCanceledException	token gets canceled.
InvalidOperationException	Thrown if IsConnected is false for any ScanHead when a timeout occurs while waiting for a frame. This indicates a loss of communication with the scan head, either by a possible network or power issue.

TryTakeAnyProfile(out IProfile, TimeSpan, CancellationToken)

Tries to take an IProfile from any profile queue in ScanHeads.

Declaration

public bool TryTakeAnyProfile(out IProfile profile, TimeSpan timeout = default, CancellationToken token = default)

Parameters

Type	Name	Description
IProfile	profile	The dequeued IProfile.
TimeSpan	timeout	The time to wait for a profile when all the queues are empty.
CancellationToken	token	Token to observe.

Returns

Type	Description
bool	true if a profile was taken else false.

Remarks

The profile queues are not guarenteed to be taken from equally or in any order.

TryTakeFrame(out IFrame, TimeSpan, CancellationToken)

Tries to take an IFrame.

Declaration

public bool TryTakeFrame(out IFrame frame, TimeSpan timeout = default, CancellationToken token = default)

Parameters

Type	Name	Description
IFrame	frame	The dequeued IFrame or null.
TimeSpan	timeout	Time to wait for an IFrame to be taken.
CancellationToken	token	The CancellationToken to observe.

Returns

Type	Description
bool	true if an IFrame was successfully taken, otherwise false if timeout elapsed or token was canceled.

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Exceptions

Type	Condition
InvalidOperationException	Thrown if IsConnected is false for any ScanHead when a timeout occurs while waiting for a frame. This indicates a loss of communication with the scan head, either by a possible network or power issue.

Events

ScanSyncUpdateEvent

This event can be used to listen for ScanSync updates for diagnostic purposes. It will be raised for every 1000 ScanSync updates or roughly once every second.

Declaration

public event EventHandler<ScanSyncUpdateEvent> ScanSyncUpdateEvent

Event Type

Type	Description
EventHandler<ScanSyncUpdateEvent>

Remarks

This class represents a complete scan system. It contains a collection of ScanHead objects, and provides properties and methods for adding ScanHeads, accessing the ScanHeads, connecting/disconnecting to/from the ScanHeads, and starting/stopping scanning on the ScanHeads.

Implements

IDisposable