Skip to content

Class JoeScan::Pinchot::ScanSystem

ClassList > 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
property uint? IdlePeriodUs
Gets the idle scan period set by StartScanning(StartScanningOptions) .
property bool IsConfigured
Obtains the configuration state of the scan system. If true , the system's configuration has already been sent to the scan head viaPreSendConfiguration . Iffalse , the configuration will be sent whenStartScanning(uint, DataFormat, ScanningMode) is called and there will be a time penalty before receiving profiles.
property bool IsScanning
Gets a value indicating whether the scan system is actively scanning.
property IReadOnlyCollection< ScanHead > ScanHeads
Gets a read-only collection of ScanHead s belonging to the scan system.
property 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) orAddPhaseElement(uint, Laser) after this function has been called.
void AddPhaseElement (uint id, Camera camera)
Adds a camera from theScanHead with__id to the current phase.
void AddPhaseElement (uint id, Camera camera, ScanHeadConfiguration configuration)
Adds a camera from theScanHead with__id to the current phase. Overwrites theScanHeadConfiguration that was applied withScanHead.Configure(ScanHeadConfiguration) with__configuration instead.
void AddPhaseElement (uint id, Laser laser)
Adds a laser from theScanHead with__id to the current phase.
void AddPhaseElement (uint id, Laser laser, ScanHeadConfiguration configuration)
Adds a laser from theScanHead with__id to the current phase. Overwrites theScanHeadConfiguration that was applied withScanHead.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 ScanHeads s.
ScanHead CreateScanHead (uint serialNumber, uint id)
Creates a ScanHead and adds it toScanHeads .
void Disconnect ()
Disconnects from all ScanHeads 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.
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.
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 StartScanning (uint periodUs, DataFormat dataFormat, ScanningMode mode=ScanningMode.Profile)
Starts scanning on all ScanHeads .
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 inScanHeads , 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 inScanHeads .
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

property 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.

See also: StartScanningOptions.IdlePeriodUs

property IsConfigured

Obtains the configuration state of the scan system. If true , the system's configuration has already been sent to the scan head viaPreSendConfiguration . Iffalse , the configuration will be sent whenStartScanning(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).

property IsScanning

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

bool IsScanning;

A value indicating whether the scan system is actively scanning.

See also: StartScanning(uint, DataFormat, ScanningMode), StartScanning(StartScanningOptions)

property 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.

property 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

function AddPhase

inline void Pinchot::ScanSystem::AddPhase ()

function AddPhaseElement [1/5]

Adds a camera from theScanHead with__id to the current phase. 

inline void Pinchot::ScanSystem::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.

function AddPhaseElement [2/5]

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

inline void Pinchot::ScanSystem::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.

function AddPhaseElement [3/5]

Adds a laser from theScanHead with__id to the current phase. 

inline void Pinchot::ScanSystem::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.

function AddPhaseElement [4/5]

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

inline void Pinchot::ScanSystem::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.

function ClearFrames

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

inline void Pinchot::ScanSystem::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.

function ClearPhaseTable

inline void Pinchot::ScanSystem::ClearPhaseTable ()

function Connect

Attempts to connect to all ScanHeads s. 

inline IReadOnlyCollection< ScanHead > Pinchot::ScanSystem::Connect (
    TimeSpan connectTimeout
)

Parameters:

  • connectTimeout The connection timeout period.

Returns:

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

Exception:

function CreateScanHead

Creates a ScanHead and adds it toScanHeads . 

inline ScanHead Pinchot::ScanSystem::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:

function Disconnect

Disconnects from all ScanHeads s. 

inline void Pinchot::ScanSystem::Disconnect ()

Exception:

function DiscoverDevices

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

inline Dictionary< uint, DiscoveredDevice > Pinchot::ScanSystem::DiscoverDevices ()

Returns:

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

function DiscoverDevicesAsync

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

inline async Task< Dictionary< uint, DiscoveredDevice > > Pinchot::ScanSystem::DiscoverDevicesAsync ()

Returns:

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

function Dispose [1/2]

inline void Pinchot::ScanSystem::Dispose ()

function GetMinScanPeriod

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

inline uint Pinchot::ScanSystem::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.

function GetScanHeadByID

Gets a ScanHead by ID. 

inline ScanHead Pinchot::ScanSystem::GetScanHeadByID (
    uint id
)

Parameters:

Returns:

The ScanHead.

Exception:

function GetScanHeadBySerialNumber

Gets a ScanHead by serial number. 

inline ScanHead Pinchot::ScanSystem::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 .

function 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. 

inline void Pinchot::ScanSystem::PreSendConfiguration ()

Exception:

  • 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

function ScanSystem

Initializes a new instance of the scan system class. 

inline Pinchot::ScanSystem::ScanSystem (
    ScanSystemUnits units
)

Parameters:

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

function StartScanning [1/2]

Starts scanning on all ScanHeads . 

inline void Pinchot::ScanSystem::StartScanning (
    uint periodUs,
    DataFormat dataFormat,
    ScanningMode mode=ScanningMode.Profile
)

scan system must be connected. Verify IsConnected is true and/or call Connect 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.

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 scan head has a firmware version that is incompatible with frame scanning (when mode is ScanningMode.Frame).

See also: StartScanning(StartScanningOptions), StopScanning

function StartScanning [2/2]

Starts scanning on all ScanHead s. 

inline void Pinchot::ScanSystem::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:

See also: StartScanning(uint, DataFormat, ScanningMode), StopScanning

function StopScanning

Stops scanning on all ScanHead s. 

inline void Pinchot::ScanSystem::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:

function TakeAnyProfile

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

inline bool Pinchot::ScanSystem::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 guarenteed to be taken from equally or in any order.

function TakeFrame

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

inline IFrame Pinchot::ScanSystem::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.

function TryTakeAnyProfile

Tries to take an IProfile from any profile queue inScanHeads . 

inline bool Pinchot::ScanSystem::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 guarenteed to be taken from equally or in any order.

function TryTakeFrame

Tries to take an IFrame. 

inline bool Pinchot::ScanSystem::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

function Dispose [2/2]

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

inline virtual void Pinchot::ScanSystem::Dispose (
    bool disposing
)

Parameters:

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