Class JoeScan::Pinchot::ScanSystem¶

ClassList > JoeScan > Pinchot > ScanSystem

A complete system of ScanHead s.

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.

Inherits the following classes: IDisposable

Public Properties¶

Type	Name
uint?	IdlePeriodUs Gets the idle scan period set by StartScanning(StartScanningOptions) .
bool	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.
bool	IsConnected Gets a value indicating whether all ScanHead s have established network connection.
bool	IsScanning Gets a value indicating whether the scan system is actively scanning.
IReadOnlyCollection< ScanHead >	ScanHeads Gets a read-only collection of ScanHead s belonging to the scan system.
ScanSystemUnits	Units Gets the units that this scan system and all associated ScanHead s will use for configuration and returned data. Can only be set when a scan system is created.

Public Functions¶

Type	Name
void	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.
void	AddPhaseElement (uint id, Camera camera) Adds a camera from the ScanHead with__id to the current phase.
void	AddPhaseElement (uint id, Camera camera, ScanHeadConfiguration configuration) Adds a camera from the ScanHead with__id to the current phase. Overwrites the ScanHeadConfiguration that was applied with ScanHead.Configure(ScanHeadConfiguration) with__configuration instead.
void	AddPhaseElement (uint id, Laser laser) Adds a laser from the ScanHead with__id to the current phase.
void	AddPhaseElement (uint id, Laser laser, ScanHeadConfiguration configuration) Adds a laser from the ScanHead with__id to the current phase. Overwrites the ScanHeadConfiguration that was applied with ScanHead.Configure(ScanHeadConfiguration) with__configuration instead.
void	ClearFrames () Empties the internal client side software buffers used to store frames.
void	ClearPhaseTable () Clears all phases and elements added to the phase table.
IReadOnlyCollection< ScanHead >	Connect (TimeSpan connectTimeout) Attempts to connect to all ScanHead s.
ScanHead	CreateScanHead (uint serialNumber, uint id) Creates a ScanHead and adds it to ScanHeads .
void	Disconnect () Disconnects from all ScanHead s.
Dictionary< uint, DiscoveredDevice >	DiscoverDevices () Performs a network discovery to determine what scan heads are on the network.
async Task< Dictionary< uint, DiscoveredDevice > >	DiscoverDevicesAsync () Performs a network discovery to determine what scan heads are on the network.
List< DiscoveredScanSync >	DiscoverScanSyncs () Listens for ScanSyncs on the network and report some basic information about them. This function should only be used to get a quick overview of the ScanSyncs on the network. To get more detailed information, such as encoder count and flags, subscribe to ScanSyncUpdateEvent .
void	Dispose () Releases the managed and unmanaged resources used by the scan system.
uint	GetMinScanPeriod () Gets the minimum scan period allowed by the scan system in microseconds.
ScanHead	GetScanHeadByID (uint id) Gets a ScanHead by ID.
ScanHead	GetScanHeadBySerialNumber (uint serialNumber) Gets a ScanHead by serial number.
Dictionary< Encoder, uint >	GetScanSyncMapping () Gets the Encoder to ScanSync mapping. If SetScanSyncMapping(uint, uint?, uint?) hasn't been called, the default mapping is used. Default behavior is to use the ScanSync with the lowest serial number as the_Encoder.Main _encoder. Further Encoder mappings are assigned to ScanSyncs in ascending order of serial number.
void	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.
	ScanSystem (ScanSystemUnits units) Initializes a new instance of the scan system class.
void	SetDefaultScanSyncMapping () Resets any Encoder to ScanSync mapping that has been set. Default behavior is to use the ScanSync with the lowest serial number as the_Encoder.Main _encoder. Further Encoder mappings are assigned to ScanSyncs in ascending order of serial number.
void	SetScanSyncMapping (uint mainSerial, uint? aux1Serial=null, uint? aux2Serial=null) Sets the Encoder to ScanSync mapping.
void	StartScanning (uint periodUs, DataFormat dataFormat, ScanningMode mode=ScanningMode.Profile) Starts scanning on all ScanHead s.
void	StartScanning (StartScanningOptions options) Starts scanning on all ScanHead s.
void	StopScanning () Stops scanning on all ScanHead s.
bool	TakeAnyProfile (out IProfile profile, CancellationToken token=default) Tries to take an IProfile from any profile queue in ScanHeads , blocking if all the queues are empty.
IFrame	TakeFrame (CancellationToken token=default) Tries to take an IFrame , blocking if one isn't ready.
bool	TryTakeAnyProfile (out IProfile profile, TimeSpan timeout=default, CancellationToken token=default) Tries to take an IProfile from any profile queue in ScanHeads .
bool	TryTakeFrame (out IFrame frame, TimeSpan timeout=default, CancellationToken token=default) Tries to take an IFrame .

Protected Functions¶

Type	Name
virtual void	Dispose (bool disposing) Releases the unmanaged resources used by the scan system and optionally releases the managed resources.

Public Properties Documentation¶

IdlePeriodUs¶

Gets the idle scan period set by StartScanning(StartScanningOptions) .

uint? IdlePeriodUs;

The idle scan period in microseconds. If the value is null, idle scanning is disabled.

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 . Iffalse , the configuration will be sent when StartScanning(uint, DataFormat, ScanningMode) is called and there will be a time penalty before receiving profiles.

bool IsConfigured;

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

See also: PreSendConfiguration

IsConnected¶

Gets a value indicating whether all ScanHead s have established network connection.

bool IsConnected;

A value indicating whether all ScanHeads have established network connection.

See also: Connect

IsScanning¶

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

bool IsScanning;

A value indicating whether the scan system is actively scanning.

ScanHeads¶

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

IReadOnlyCollection<ScanHead> ScanHeads;

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

See also: CreateScanHead(uint, uint)

Units¶

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

ScanSystemUnits Units;

The units of the scan system.

Public Functions Documentation¶

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.

void AddPhase()

AddPhaseElement [1/5]¶

Adds a camera from the ScanHead with__id to the current phase.

void AddPhaseElement(
    uint id,
    Camera camera
)

Parameters:

id The ScanHead ID.
camera The Camera that should expose.

Exception:

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 [2/5]¶

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

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

Parameters:

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

Only the ScanHeadConfiguration.MaxLaserOnTimeUs, ScanHeadConfiguration.DefaultLaserOnTimeUs, and ScanHeadConfiguration.MinLaserOnTimeUs are overwritten.

Exception:

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 [3/5]¶

Adds a laser from the ScanHead with__id to the current phase.

void AddPhaseElement(
    uint id,
    Laser laser
)

Parameters:

id The ScanHead ID.
laser The Laser that should be on during exposure.

Exception:

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 [4/5]¶

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

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

Parameters:

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

Only the ScanHeadConfiguration.MaxLaserOnTimeUs, ScanHeadConfiguration.DefaultLaserOnTimeUs, and ScanHeadConfiguration.MinLaserOnTimeUs are overwritten.

Exception:

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.

void ClearFrames()

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 ScanHead.ClearProfiles instead.

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

ClearPhaseTable¶

Clears all phases and elements added to the phase table.

void ClearPhaseTable()

Connect¶

Attempts to connect to all ScanHead s.

IReadOnlyCollection< ScanHead > Connect(
    TimeSpan connectTimeout
)

Parameters:

connectTimeout The connection timeout period.

Returns:

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

Exception:

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¶

Creates a ScanHead and adds it to ScanHeads .

ScanHead CreateScanHead(
    uint serialNumber,
    uint id
)

Parameters:

serialNumber The serial number of the scan head.
id The ID to associate with the ScanHead.

Returns:

The created ScanHead.

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

Exception:

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 ScanHead s.

void Disconnect()

Exception:

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

DiscoverDevices¶

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

Dictionary< uint, DiscoveredDevice > DiscoverDevices()

Returns:

A dictionary of all discovered scan heads where the key is the serial number.

DiscoverDevicesAsync¶

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

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

Returns:

A dictionary of all discovered scan heads where the key is the serial number.

DiscoverScanSyncs¶

Listens for ScanSyncs on the network and report some basic information about them. This function should only be used to get a quick overview of the ScanSyncs on the network. To get more detailed information, such as encoder count and flags, subscribe to ScanSyncUpdateEvent .

List< DiscoveredScanSync > DiscoverScanSyncs()

Returns:

A list of all discovered ScanSyncs on the network.

This function will only report ScanSyncs that all the ScanHeads in the system can see.

Exception:

InvalidOperationException IsConnected is false.
VersionCompatibilityException This exception will be thrown if any ScanHead in the system isn't version 16.3.0 or greater.

Dispose [1/2]¶

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

void Dispose()

GetMinScanPeriod¶

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

uint GetMinScanPeriod()

Returns:

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

Exception:

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¶

Gets a ScanHead by ID.

ScanHead GetScanHeadByID(
    uint id
)

Parameters:

id The ID of the desired ScanHead.

Returns:

The ScanHead.

Exception:

ArgumentException ScanHeads does not contain a ScanHead with specified id .

GetScanHeadBySerialNumber¶

Gets a ScanHead by serial number.

ScanHead GetScanHeadBySerialNumber(
    uint serialNumber
)

Parameters:

serialNumber The serial number of the desired ScanHead.

Returns:

The ScanHead.

Exception:

ArgumentException ScanHeads does not contain a ScanHead with specified serialNumber .

GetScanSyncMapping¶

Gets the Encoder to ScanSync mapping. If SetScanSyncMapping(uint, uint?, uint?) hasn't been called, the default mapping is used. Default behavior is to use the ScanSync with the lowest serial number as the_Encoder.Main _encoder. Further Encoder mappings are assigned to ScanSyncs in ascending order of serial number.

Dictionary< Encoder , uint > GetScanSyncMapping()

Returns:

A dictionary representing the Encoder to ScanSync serial mapping.

Exception:

InvalidOperationException IsConnected is false.
VersionCompatibilityException This exception will be thrown if any ScanHead in the system isn't version 16.3.0 or greater.

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.

void PreSendConfiguration()

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

Exception:

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

See also: IsConfigured

ScanSystem¶

Initializes a new instance of the scan system class.

ScanSystem(
    ScanSystemUnits units
)

Parameters:

units The units that this scan system and all associated ScanHeads will use.

SetDefaultScanSyncMapping¶

Resets any Encoder to ScanSync mapping that has been set. Default behavior is to use the ScanSync with the lowest serial number as the_Encoder.Main _encoder. Further Encoder mappings are assigned to ScanSyncs in ascending order of serial number.

void SetDefaultScanSyncMapping()

Exception:

VersionCompatibilityException This exception will be thrown if any ScanHead in the system isn't version 16.3.0 or greater.
InvalidOperationException IsConnected is false.

SetScanSyncMapping¶

Sets the Encoder to ScanSync mapping.

void SetScanSyncMapping(
    uint mainSerial,
    uint? aux1Serial=null,
    uint? aux2Serial=null
)

Parameters:

mainSerial The serial that should be mapped to Encoder.Main.
aux1Serial The serial that should be mapped to Encoder.Auxiliary1.
aux2Serial The serial that should be mapped to Encoder.Auxiliary2.

Exception:

ArgumentException Any of the serial numbers are 0. -or- Any of the main and aux serial numbers are the same. -or- Aux 2 is mapped to an encoder without mapping aux 1.
InvalidOperationException IsConnected is false. -or- A ScanSync with the supplied serial isn't found on the network.
VersionCompatibilityException This exception will be thrown if any ScanHead in the system isn't version 16.3.0 or greater.

StartScanning [1/2]¶

Starts scanning on all ScanHead s.

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

All existing IProfiles and IFrames 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.

periodUs is the time it takes for one iteration of the phase table to complete.

Parameters:

periodUs The scan period in microseconds.
dataFormat The DataFormat.
mode The ScanningMode.

Exception:

InvalidOperationException IsConnected is false. -or- IsScanning is true. -or- There are no phases or phaseable elements in the phase table. -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 ScanHead has a ScanHead.Version that is incompatible with frame scanning (when mode is ScanningMode.Frame).

StartScanning [2/2]¶

Starts scanning on all ScanHead s.

void StartScanning(
    StartScanningOptions options
)

All existing IProfiles and IFrames 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.

Parameters:

options The scan options.

Exception:

InvalidOperationException IsConnected is false. -or- IsScanning is true. -or- There are no phases or phaseable elements in the phase table. -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 StartScanningOptions.PeriodUs is invalid.
VersionCompatibilityException A ScanHead has a ScanHead.Version that is incompatible with frame scanning (when StartScanningOptions.Mode is ScanningMode.Frame).
ArgumentNullException options is null.

StopScanning¶

Stops scanning on all ScanHead s.

void StopScanning()

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.

Exception:

InvalidOperationException IsScanning is false.

TakeAnyProfile¶

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

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

Parameters:

profile The dequeued IProfile.
token Token to observe.

Returns:

true if a profile was taken else false.

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

TakeFrame¶

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

IFrame TakeFrame(
    CancellationToken token=default
)

Parameters:

token The CancellationToken to observe.

Returns:

The dequeued IFrame.

Exception:

OperationCanceledException token gets canceled.
InvalidOperationException Thrown if ScanHead.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¶

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

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

Parameters:

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

Returns:

true if a profile was taken else false.

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

TryTakeFrame¶

Tries to take an IFrame .

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

Parameters:

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

Returns:

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

Exception:

InvalidOperationException Thrown if ScanHead.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.

Protected Functions Documentation¶

Dispose [2/2]¶

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

virtual void Dispose(
    bool disposing
)

Parameters:

disposing Whether being disposed explicitly (true) or due to a finalizer (false).