Group Scanning¶

Functions to Scan and collect data.

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

Public Functions¶

Type	Name
void	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.
void	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.
int32_t	jsScanHeadClearProfiles (jsScanHead scan_head) Empties the internal client side software buffers used to store profiles received from a given scan head.
int32_t	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.
int32_t	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.
int32_t	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.
int32_t	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.
int32_t	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.
int32_t	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.
int32_t	jsScanHeadGetProfilesAvailable (jsScanHead scan_head) Obtains the number of profiles currently available to be read out from a given scan head.
int32_t	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.
int32_t	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.
int32_t	jsScanSystemClearFrames (jsScanSystem scan_system) Empties the internal client side software buffers used to store profiles for frame scanning.
int32_t	jsScanSystemGetFrame (jsScanSystem scan_system, jsProfile * profiles) Reads one frame of `jsProfile` formatted profile data.
int32_t	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` .
int32_t	jsScanSystemGetRawFrame (jsScanSystem scan_system, jsRawProfile * profiles) Reads one frame of `jsRawProfile` formatted profile data.
bool	jsScanSystemIsFrameAvailable (jsScanSystem scan_system) Checks if enough data has been collected to construct a frame of profile data.
bool	jsScanSystemIsScanning (jsScanSystem scan_system) Gets scanning state for a scan system.
int32_t	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.
int32_t	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.
int32_t	jsScanSystemStopScanning (jsScanSystem scan_system) Commands scan heads in system to stop scanning.
int32_t	jsScanSystemWaitUntilFrameAvailable (jsScanSystem scan_system, uint32_t timeout_us) Blocks until a frame of scan data is available to be read.

Public Functions Documentation¶

jsProfileInit¶

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

void jsProfileInit(
    jsProfile * profile
)

Parameters:

profile Reference to jsProfile to initialize.

jsRawProfileInit¶

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

void jsRawProfileInit(
    jsRawProfile * profile
)

Parameters:

profile Reference to jsRawProfile to initialize.

jsScanHeadClearProfiles¶

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

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

jsScanHeadGetDiagnosticImage¶

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

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

jsScanHeadGetDiagnosticImageCamera¶

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

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

jsScanHeadGetDiagnosticImageLaser¶

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

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

jsScanHeadGetDiagnosticProfileCamera¶

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

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

jsScanHeadGetDiagnosticProfileLaser¶

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

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

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.

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

jsScanHeadGetProfilesAvailable¶

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

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

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.

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

jsScanHeadWaitUntilProfilesAvailable¶

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

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

jsScanSystemClearFrames¶

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

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

jsScanSystemGetFrame¶

Reads one frame of jsProfile formatted profile data.

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

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 .

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

jsScanSystemGetRawFrame¶

Reads one frame of jsRawProfile formatted profile data.

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

jsScanSystemIsFrameAvailable¶

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

bool jsScanSystemIsFrameAvailable(
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

Boolean true if frame is available, false otherwise.

jsScanSystemIsScanning¶

Gets scanning state for a scan system.

bool jsScanSystemIsScanning(
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

Boolean true if scanning, false if not scanning.

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.

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

jsScanSystemStartScanning¶

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

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

jsScanSystemStopScanning¶

Commands scan heads in system to stop scanning.

int32_t jsScanSystemStopScanning(
    jsScanSystem scan_system
)

Parameters:

scan_system Reference to system of scan heads.

Returns:

0 on success, negative value jsError on error.

jsScanSystemWaitUntilFrameAvailable¶

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

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