Group Scanning¶

Functions to Scan and collect data. More...

Public Functions¶

Type	Name
EXPORTED void PRE	jsProfileInit (jsProfile * profile) Initializes a given `jsProfile` to a known invalid state to indicate it has not been populated with data from the scan head.
EXPORTED void PRE	jsRawProfileInit (jsRawProfile * profile) Initializes a given `jsRawProfile` to a known invalid state to indicate it has not been populated with data from the scan head.
EXPORTED int32_t PRE	jsScanHeadClearProfiles (jsScanHead scan_head) Empties the internal client side software buffers used to store profiles received from a given scan head.
DEPRECATED EXPORTED int32_t PRE	jsScanHeadGetDiagnosticImage (jsScanHead scan_head, jsCamera camera, jsLaser laser, jsDiagnosticMode mode, uint32_t laser_on_time_us, uint32_t camera_exposure_time_us, jsCameraImage * image) Obtains a single camera image from a scan head to be used for diagnostic purposes.
DEPRECATED EXPORTED int32_t PRE	jsScanHeadGetDiagnosticImageCamera (jsScanHead scan_head, jsCamera camera, jsDiagnosticMode mode, uint32_t laser_on_time_us, uint32_t camera_exposure_time_us, jsCameraImage * image) Obtains a single camera image from a scan head to be used for diagnostic purposes.
DEPRECATED EXPORTED int32_t PRE	jsScanHeadGetDiagnosticImageLaser (jsScanHead scan_head, jsLaser laser, jsDiagnosticMode mode, uint32_t laser_on_time_us, uint32_t camera_exposure_time_us, jsCameraImage * image) Obtains a single camera image from a scan head to be used for diagnostic purposes.
EXPORTED int32_t PRE	jsScanHeadGetDiagnosticProfileCamera (jsScanHead scan_head, jsCamera camera, jsDiagnosticMode mode, uint32_t laser_on_time_us, uint32_t camera_exposure_time_us, jsRawProfile * profile) Obtains a single camera profile from a scan head to be used for diagnostic purposes.
EXPORTED int32_t PRE	jsScanHeadGetDiagnosticProfileLaser (jsScanHead scan_head, jsLaser laser, jsDiagnosticMode mode, uint32_t laser_on_time_us, uint32_t camera_exposure_time_us, jsRawProfile * profile) Obtains a single camera profile from a scan head to be used for diagnostic purposes.
EXPORTED int32_t PRE	jsScanHeadGetProfiles (jsScanHead scan_head, jsProfile * profiles, uint32_t max_profiles) Reads `jsProfile` formatted profile data from a given scan head. The number of profiles returned is either the max value requested or the total number of profiles ready to be read out, whichever is less.
EXPORTED int32_t PRE	jsScanHeadGetProfilesAvailable (jsScanHead scan_head) Obtains the number of profiles currently available to be read out from a given scan head.
EXPORTED int32_t PRE	jsScanHeadGetRawProfiles (jsScanHead scan_head, jsRawProfile * profiles, uint32_t max_profiles) Reads `jsRawProfile` formatted profile data from a given scan head. The number of profiles returned is either the max value requested or the total number of profiles ready to be read out, whichever is less.
EXPORTED int32_t PRE	jsScanHeadWaitUntilProfilesAvailable (jsScanHead scan_head, uint32_t count, uint32_t timeout_us) Blocks until the number of requested profiles are available to be read out from a given scan head.
EXPORTED int32_t PRE	jsScanSystemClearFrames (jsScanSystem scan_system) Empties the internal client side software buffers used to store profiles for frame scanning.
EXPORTED int32_t PRE	jsScanSystemGetFrame (jsScanSystem scan_system, jsProfile * profiles) Reads one frame of `jsProfile` formatted profile data.
EXPORTED int32_t PRE	jsScanSystemGetProfilesPerFrame (jsScanSystem scan_system) Returns the number of profiles comprising a single frame of scan data. This number should be used to appropriately size the arrays used to call `jsScanSystemGetProfileFrame` and`jsScanSystemGetRawProfileFrame` .
EXPORTED int32_t PRE	jsScanSystemGetRawFrame (jsScanSystem scan_system, jsRawProfile * profiles) Reads one frame of `jsRawProfile` formatted profile data.
EXPORTED bool PRE	jsScanSystemIsFrameAvailable (jsScanSystem scan_system) Checks if enough data has been collected to construct a frame of profile data.
EXPORTED bool PRE	jsScanSystemIsScanning (jsScanSystem scan_system) Gets scanning state for a scan system.
EXPORTED int32_t PRE	jsScanSystemStartFrameScanning (jsScanSystem scan_system, uint32_t period_us, jsDataFormat fmt) Commands scan heads in system to begin scanning, returning geometry and/or brightness values to the client in an organized frame of profiles, with each frame being comprised of one cycle through the phase table corresponding with one complete period.
EXPORTED int32_t PRE	jsScanSystemStartScanning (jsScanSystem scan_system, uint32_t period_us, jsDataFormat fmt) Commands scan heads in system to begin scanning, returning geometry and/or brightness values to the client.
EXPORTED int32_t PRE	jsScanSystemStopScanning (jsScanSystem scan_system) Commands scan heads in system to stop scanning.
EXPORTED int32_t PRE	jsScanSystemWaitUntilFrameAvailable (jsScanSystem scan_system, uint32_t timeout_us) Blocks until a frame of scan data is available to be read.

Detailed Description¶

These are functions that deal with scanning and collecting profiles from the ScanSystem.

Public Functions Documentation¶

function jsProfileInit¶

Initializes a given jsProfile to a known invalid state to indicate it has not been populated with data from the scan head.

EXPORTED void PRE jsProfileInit (
    jsProfile * profile
)

Parameters:

profile Reference to jsProfile to initialize.

function jsRawProfileInit¶

Initializes a given jsRawProfile to a known invalid state to indicate it has not been populated with data from the scan head.

EXPORTED void PRE jsRawProfileInit (
    jsRawProfile * profile
)

Parameters:

profile Reference to jsRawProfile to initialize.

function jsScanHeadClearProfiles¶

Empties the internal client side software buffers used to store profiles received from a given scan head.

EXPORTED int32_t PRE jsScanHeadClearProfiles (
    jsScanHead scan_head
)

Note:

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

Parameters:

scan_head Reference to scan head.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanHeadGetDiagnosticImage¶

Obtains a single camera image from a scan head to be used for diagnostic purposes.

DEPRECATED EXPORTED int32_t PRE jsScanHeadGetDiagnosticImage (
    jsScanHead scan_head,
    jsCamera camera,
    jsLaser laser,
    jsDiagnosticMode mode,
    uint32_t laser_on_time_us,
    uint32_t camera_exposure_time_us,
    jsCameraImage * image
)

Note:

This function should be called after jsScanSystemConnect(), but not after the system has been set to scan by calling jsScanSystemStartScanning().

Deprecated

Will be removed in a future release.

Parameters:

scan_head Reference to scan head.
camera Camera to use for image capture.
laser Laser to be in view of image capture.
mode Must be set to JS_DIAGNOSTIC_FIXED_EXPOSURE.
laser_on_time_us Time laser is on in microseconds.
camera_exposure_time_us Time camera exposes in microseconds.
image Pointer to memory to store camera image data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanHeadGetDiagnosticImageCamera¶

Obtains a single camera image from a scan head to be used for diagnostic purposes.

DEPRECATED EXPORTED int32_t PRE jsScanHeadGetDiagnosticImageCamera (
    jsScanHead scan_head,
    jsCamera camera,
    jsDiagnosticMode mode,
    uint32_t laser_on_time_us,
    uint32_t camera_exposure_time_us,
    jsCameraImage * image
)

Note:

This function should be called after jsScanSystemConnect(), but not after the system has been set to scan by calling jsScanSystemStartScanning().

Note:

This function will automatically select the correct camera / laser pair, as used when scanning, when performing the capture.

Deprecated

Will be removed in a future release.

Parameters:

scan_head Reference to scan head.
camera Camera to use for image capture. The laser to be in view of the image will be chosen based on the chosen camera.
mode Must be set to JS_DIAGNOSTIC_FIXED_EXPOSURE.
laser_on_time_us Time laser is on in microseconds.
camera_exposure_time_us Time camera exposes in microseconds.
image Pointer to memory to store camera image data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanHeadGetDiagnosticImageLaser¶

Obtains a single camera image from a scan head to be used for diagnostic purposes.

DEPRECATED EXPORTED int32_t PRE jsScanHeadGetDiagnosticImageLaser (
    jsScanHead scan_head,
    jsLaser laser,
    jsDiagnosticMode mode,
    uint32_t laser_on_time_us,
    uint32_t camera_exposure_time_us,
    jsCameraImage * image
)

Note:

This function should be called after jsScanSystemConnect(), but not after the system has been set to scan by calling jsScanSystemStartScanning().

Note:

This function will automatically select the correct camera / laser pair, as used when scanning, when performing the capture.

Deprecated

Will be removed in a future release.

Parameters:

scan_head Reference to scan head.
laser Laser to be in view of image capture. The camera that takes the image will automatically be chosen based on the chosen laser.
mode Must be set to JS_DIAGNOSTIC_FIXED_EXPOSURE.
laser_on_time_us Time laser is on in microseconds.
camera_exposure_time_us Time camera exposes in microseconds.
image Pointer to memory to store camera image data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanHeadGetDiagnosticProfileCamera¶

Obtains a single camera profile from a scan head to be used for diagnostic purposes.

EXPORTED int32_t PRE jsScanHeadGetDiagnosticProfileCamera (
    jsScanHead scan_head,
    jsCamera camera,
    jsDiagnosticMode mode,
    uint32_t laser_on_time_us,
    uint32_t camera_exposure_time_us,
    jsRawProfile * profile
)

Note:

This function should be called after jsScanSystemConnect(), but not while the system is set to scan by calling jsScanSystemStartScanning().

Note:

This function will automatically select the correct camera / laser pair, as used when scanning, when performing the capture.

Note:

Only JS_DIAGNOSTIC_FIXED_EXPOSURE is supported; in a future release, JS_DIAGNOSTIC_AUTO_EXPOSURE will be supported.

Parameters:

scan_head Reference to scan head.
camera Camera to use for profile capture.
mode JS_DIAGNOSTIC_FIXED_EXPOSURE to use the laser on time and camera exposure provided as function arguments, JS_DIAGNOSTIC_AUTO_EXPOSURE to dynamically adjust camera & laser according to jsScanHeadConfiguration provided to the jsScanHeadSetConfiguration function.
laser_on_time_us Time laser is on in microseconds.
camera_exposure_time_us Time camera exposes in microseconds.
profile Pointer to memory to store profile data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanHeadGetDiagnosticProfileLaser¶

Obtains a single camera profile from a scan head to be used for diagnostic purposes.

EXPORTED int32_t PRE jsScanHeadGetDiagnosticProfileLaser (
    jsScanHead scan_head,
    jsLaser laser,
    jsDiagnosticMode mode,
    uint32_t laser_on_time_us,
    uint32_t camera_exposure_time_us,
    jsRawProfile * profile
)

Note:

This function should be called after jsScanSystemConnect(), but not while the system is set to scan by calling jsScanSystemStartScanning().

Note:

This function will automatically select the correct camera / laser pair, as used when scanning, when performing the capture.

Note:

Only JS_DIAGNOSTIC_FIXED_EXPOSURE is supported; in a future release, JS_DIAGNOSTIC_AUTO_EXPOSURE will be supported.

Parameters:

scan_head Reference to scan head.
laser Laser to use for profile capture.
mode JS_DIAGNOSTIC_FIXED_EXPOSURE to use the laser on time and camera exposure provided as function arguments, JS_DIAGNOSTIC_AUTO_EXPOSURE to dynamically adjust camera & laser according to jsScanHeadConfiguration provided to the jsScanHeadSetConfiguration function.
laser_on_time_us Time laser is on in microseconds.
camera_exposure_time_us Time camera exposes in microseconds.
profile Pointer to memory to store profile data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanHeadGetProfiles¶

Reads jsProfile formatted profile data from a given scan head. The number of profiles returned is either the max value requested or the total number of profiles ready to be read out, whichever is less.

EXPORTED int32_t PRE jsScanHeadGetProfiles (
    jsScanHead scan_head,
    jsProfile * profiles,
    uint32_t max_profiles
)

Note:

If no profiles are available this will return immediately. Care should be taken if this function is used in a loop; it is advised to either sleep when 0 profiles are returned, or first call jsScanHeadWaitUntilProfilesAvailable() before jScanHeadGetProfiles() so as to avoid excessive CPU usage.

Parameters:

scan_head Reference to scan head.
profiles Pointer to memory to store profile data. Note, the memory pointed to by profiles must be at least sizeof(jsProfile) * max_profiles in total number of bytes available.
max_profiles The maximum number of profiles to read. Should not exceed JS_SCAN_HEAD_PROFILES_MAX.

Returns:

The number of profiles read on success, negative value mapping to jsError on error.

function jsScanHeadGetProfilesAvailable¶

Obtains the number of profiles currently available to be read out from a given scan head.

EXPORTED int32_t PRE jsScanHeadGetProfilesAvailable (
    jsScanHead scan_head
)

Parameters:

scan_head Reference to scan head.

Returns:

The total number of profiles able to be read on success, negative value jsError on error.

function jsScanHeadGetRawProfiles¶

Reads jsRawProfile formatted profile data from a given scan head. The number of profiles returned is either the max value requested or the total number of profiles ready to be read out, whichever is less.

EXPORTED int32_t PRE jsScanHeadGetRawProfiles (
    jsScanHead scan_head,
    jsRawProfile * profiles,
    uint32_t max_profiles
)

Parameters:

scan_head Reference to scan head.
profiles Pointer to memory to store profile data. Note, the memory pointed to by profiles must be at least sizeof(jsProfile) * max_profiles in total number of bytes available.
max_profiles The maximum number of profiles to read. Should not exceed JS_SCAN_HEAD_PROFILES_MAX.

Returns:

The number of profiles read on success, negative value mapping to jsError on error.

function jsScanHeadWaitUntilProfilesAvailable¶

Blocks until the number of requested profiles are available to be read out from a given scan head.

EXPORTED int32_t PRE jsScanHeadWaitUntilProfilesAvailable (
    jsScanHead scan_head,
    uint32_t count,
    uint32_t timeout_us
)

Parameters:

scan_head Reference to scan head.
count The number of profiles to wait for. Should not exceed JS_SCAN_HEAD_PROFILES_MAX.
timeout_us Maximum amount of time to wait for in microseconds.

Returns:

0 on timeout with no profiles available, positive value indicating the total number of profiles able to be read after count or timeout_us is reached, or negative value jsError on error.

function jsScanSystemClearFrames¶

Empties the internal client side software buffers used to store profiles for frame scanning.

EXPORTED int32_t PRE jsScanSystemClearFrames (
    jsScanSystem scan_system
)

Note:

Under normal scanning conditions where the application consumes frames as they become available, this function will not be needed. It's 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 frame is desired.

Parameters:

scan_system Reference to system of scan heads.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanSystemGetFrame¶

Reads one frame of jsProfile formatted profile data.

EXPORTED int32_t PRE jsScanSystemGetFrame (
    jsScanSystem scan_system,
    jsProfile * profiles
)

Note:

If no frame is available this will return immediately. Care should be taken if this function is used in a loop; it is advised to either sleep when 0 profiles are returned, or first call jsScanSystemWaitUntilFrameAvailable() before jsScanSystemGetProfileFrame() so as to avoid excessive CPU usage.

Parameters:

scan_head Reference to scan head.
profiles Pointer to memory to store frame of profile data. Note, the memory pointed to by profiles must be at least sizeof(jsProfile) * jsScanSystemGetProfilesPerFrame() in total number of bytes available.

Returns:

The number of set profiles in frame on success, negative value mapping to jsError on error.

function jsScanSystemGetProfilesPerFrame¶

Returns the number of profiles comprising a single frame of scan data. This number should be used to appropriately size the arrays used to call jsScanSystemGetProfileFrame andjsScanSystemGetRawProfileFrame .

EXPORTED int32_t PRE jsScanSystemGetProfilesPerFrame (
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

The number of elements in frame of scan data, or negative value mapping to jsError on error.

function jsScanSystemGetRawFrame¶

Reads one frame of jsRawProfile formatted profile data.

EXPORTED int32_t PRE jsScanSystemGetRawFrame (
    jsScanSystem scan_system,
    jsRawProfile * profiles
)

Note:

If no frame is available this will return immediately. Care should be taken if this function is used in a loop; it is advised to either sleep when 0 profiles are returned, or first call jsScanSystemWaitUntilFrameAvailable() before jsScanSystemGetProfileFrame() so as to avoid excessive CPU usage.

Parameters:

scan_head Reference to scan head.
profiles Pointer to memory to store frame of profile data. Note, the memory pointed to by profiles must be at least sizeof(jsRawProfile) * jsScanSystemGetProfilesPerFrame() in total number of bytes available.

Returns:

The number of set profiles in frame on success, negative value mapping to jsError on error.

function jsScanSystemIsFrameAvailable¶

Checks if enough data has been collected to construct a frame of profile data.

EXPORTED bool PRE jsScanSystemIsFrameAvailable (
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

Boolean true if frame is available, false otherwise.

function jsScanSystemIsScanning¶

Gets scanning state for a scan system.

EXPORTED bool PRE jsScanSystemIsScanning (
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

Boolean true if scanning, false if not scanning.

function jsScanSystemStartFrameScanning¶

Commands scan heads in system to begin scanning, returning geometry and/or brightness values to the client in an organized frame of profiles, with each frame being comprised of one cycle through the phase table corresponding with one complete period.

EXPORTED int32_t PRE jsScanSystemStartFrameScanning (
    jsScanSystem scan_system,
    uint32_t period_us,
    jsDataFormat fmt
)

Parameters:

scan_system Reference to system of scan heads.
period_us The scan period in microseconds.
fmt The data format of the returned scan profile data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanSystemStartScanning¶

Commands scan heads in system to begin scanning, returning geometry and/or brightness values to the client.

EXPORTED int32_t PRE jsScanSystemStartScanning (
    jsScanSystem scan_system,
    uint32_t period_us,
    jsDataFormat fmt
)

Note:

The internal memory buffers of the scan heads will be cleared of all old profile data upon start of scan. Ensure that all data from the previous scan that is desired is read out before calling this function.

Parameters:

scan_system Reference to system of scan heads.
period_us The scan period in microseconds.
fmt The data format of the returned scan profile data.

Returns:

0 on success, negative value mapping to jsError on error.

function jsScanSystemStopScanning¶

Commands scan heads in system to stop scanning.

EXPORTED int32_t PRE jsScanSystemStopScanning (
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

0 on success, negative value jsError on error.

function jsScanSystemWaitUntilFrameAvailable¶

Blocks until a frame of scan data is available to be read.

EXPORTED int32_t PRE jsScanSystemWaitUntilFrameAvailable (
    jsScanSystem scan_system,
    uint32_t timeout_us
)

Parameters:

scan_system Reference to system of scan heads.
timeout_us Maximum amount of time to wait for in microseconds.

Returns:

0 on timeout with no frames are available, positive value indicating the total number of frames able to be read, or negative value jsError on error.