Pinchot C API
Typedefs
- void * jsScanSystem
- void * jsScanHead
- enum jsConstants
- enum jsError
- enum jsScanHeadType
- enum jsCamera
- enum jsLaser
- enum jsEncoder
- enum jsDataFormat
- struct jsScanHeadCapabilities
- struct jsScanHeadConfiguration
- struct jsScanHeadStatus
- struct jsProfileData
- struct jsProfile
- struct jsRawProfile
- struct jsCameraImage
Functions
- void jsGetAPIVersion(const char ** version_str)
- void jsGetAPISemanticVersion(uint32_t * major, uint32_t * minor, uint32_t * patch)
- void jsGetError(int32_t return_code, const char ** error_str)
- int32_t jsGetScanHeadCapabilities(jsScanHeadType type, jsScanHeadCapabilities * capabilities)
- jsScanSystem jsScanSystemCreate(void )
- void jsScanSystemFree(jsScanSystem scan_system)
- jsScanHead jsScanSystemCreateScanHead(jsScanSystem scan_system, uint32_t serial, uint32_t id)
- jsScanHead jsScanSystemGetScanHeadById(jsScanSystem scan_system, uint32_t id)
- jsScanHead jsScanSystemGetScanHeadBySerial(jsScanSystem scan_system, uint32_t serial)
- int32_t jsScanSystemGetNumberScanHeads(jsScanSystem scan_system)
- int32_t jsScanSystemConnect(jsScanSystem scan_system, int32_t timeout_s)
- int32_t jsScanSystemDisconnect(jsScanSystem scan_system)
- bool jsScanSystemIsConnected(jsScanSystem scan_system)
- double jsScanSystemGetMaxScanRate(jsScanSystem scan_system)
- int32_t jsScanSystemStartScanning(jsScanSystem scan_system, double rate_hz, jsDataFormat fmt)
- int32_t jsScanSystemStopScanning(jsScanSystem scan_system)
- bool jsScanSystemIsScanning(jsScanSystem scan_system)
- jsScanHeadType jsScanHeadGetType(jsScanHead scan_head)
- uint32_t jsScanHeadGetId(jsScanHead scan_head)
- uint32_t jsScanHeadGetSerial(jsScanHead scan_head)
- bool jsScanHeadIsConnected(jsScanHead scan_head)
- int32_t jsScanHeadConfigure(jsScanHead scan_head, jsScanHeadConfiguration * cfg)
- int32_t jsScanHeadSetConfiguration(jsScanHead scan_head, jsScanHeadConfiguration * cfg)
- int32_t jsScanHeadGetConfiguration(jsScanHead scan_head, jsScanHeadConfiguration * cfg)
- int32_t jsScanHeadSetAlignment(jsScanHead scan_head, double roll_degrees, double shift_x, double shift_y, bool is_cable_downstream)
- int32_t jsScanHeadSetAlignmentCamera(jsScanHead scan_head, jsCamera camera, double roll_degrees, double shift_x, double shift_y, bool is_cable_downstream)
- int32_t jsScanHeadGetAlignmentCamera(jsScanHead scan_head, jsCamera camera, double * roll_degrees, double * shift_x, double * shift_y, bool * is_cable_downstream)
- int32_t jsScanHeadSetWindowRectangular(jsScanHead scan_head, double window_top, double window_bottom, double window_left, double window_right)
- int32_t jsScanHeadGetProfilesAvailable(jsScanHead scan_head)
- int32_t jsScanHeadWaitUntilProfilesAvailable(jsScanHead scan_head, uint32_t count, uint32_t timeout_us)
- int32_t jsScanHeadClearProfiles(jsScanHead scan_head)
- int32_t jsScanHeadGetProfiles(jsScanHead scan_head, jsProfile * profiles, uint32_t max_profiles)
- int32_t jsScanHeadGetRawProfiles(jsScanHead scan_head, jsRawProfile * profiles, uint32_t max_profiles)
- int32_t jsScanHeadGetCameraImage(jsScanHead scan_head, jsCamera camera, bool enable_lasers, jsCameraImage * image)
- int32_t jsScanHeadGetStatus(jsScanHead scan_head, jsScanHeadStatus * status)
Typedefs Documentation
jsScanSystem
Opaque reference to an object in software used to manage a complete system of scan heads.
typedef void* jsScanSystem;
jsScanHead
Opaque reference to an object in software that represents as single physical scan head.
typedef void* jsScanHead;
jsConstants
Constant values used with this API.
Enumerator | Value | Description |
---|---|---|
JS_PROFILE_DATA_LEN | 1456 | Array length of data reserved for a profile. |
JS_RAW_PROFILE_DATA_LEN | 1456 | Array length of data reserved for a raw profile. |
JS_CAMERA_IMAGE_DATA_MAX_WIDTH | 1456 | Maximum number of columns in an image taken from the scan head. |
JS_CAMERA_IMAGE_DATA_MAX_HEIGHT | 1088 | Maximum number of rows in an image taken from the scan head. |
JS_CAMERA_IMAGE_DATA_LEN | JS_CAMERA_IMAGE_DATA_MAX_HEIGHT * JS_CAMERA_IMAGE_DATA_MAX_WIDTH | Array length of data reserved for an image. |
JS_PROFILE_DATA_INVALID_XY | -32768 | Value that x and y will be assigned in jsProfileData if the point is invalid. |
JS_PROFILE_DATA_INVALID_BRIGHTNESS | 0 | Value that brightness will be assigned in jsProfileData if the measurement is invalid. |
JS_SCAN_HEAD_PROFILES_MAX | 1000 | The maximum number of profiles that can be read from a given scan head with one API call. |
jsError
Enumerated value for possible errors returned from API functions.
Note: These values can be converted to a string value by using the jsGetError function.
Enumerator | Value | Description |
---|---|---|
JS_ERROR_INTERNAL | -1 | Error resulted from internal code. |
JS_ERROR_NULL_ARGUMENT | -2 | Error resulted from NULL value passed in as argument. |
JS_ERROR_INVALID_ARGUMENT | -3 | Error resulted from incorrect or out of range argument value. |
JS_ERROR_NOT_CONNECTED | -4 | Error resulted from the system not being in a connected state. |
JS_ERROR_CONNECTED | -5 | Error resulted from the system being in a connected state. |
JS_ERROR_NOT_SCANNING | -6 | Error occurred from the system not being in a scanning state. |
JS_ERROR_SCANNING | -7 | Error occurred from the system being in a scanning state. |
JS_ERROR_VERSION_COMPATIBILITY | -8 | Error occurred from a version compatibility issue between the scan head(s) and the API. |
jsScanHeadType
Enumerated value identifying the scan head type.
Enumerator | Value |
---|---|
JS_SCAN_HEAD_INVALID_TYPE | 0 |
JS_SCAN_HEAD_JS50WX | 1 |
JS_SCAN_HEAD_JS50WSC | 2 |
jsCamera
Data type for identifying a camera on the scan head.
Enumerator | Value |
---|---|
JS_CAMERA_A | 0 |
JS_CAMERA_B | - |
JS_CAMERA_MAX | - |
JS_CAMERA_0 | JS_CAMERA_A |
JS_CAMERA_1 | JS_CAMERA_B |
jsLaser
Data type for identifying a laser on the scan head.
Enumerator | Value |
---|---|
JS_LASER_0 | 0 |
JS_LASER_MAX | - |
jsEncoder
Data type for identifying an encoder on the scan head.
Enumerator | Value |
---|---|
JS_ENCODER_0 | 0 |
JS_ENCODER_1 | - |
JS_ENCODER_2 | - |
JS_ENCODER_MAX | - |
jsDataFormat
Enumerated value representing the types of data and the formats it can take.
For full resolution data formats, every data entry will be filled within the
returned profile's data
array. Selecting half or quarter resolution will
result in every other or every fourth entry in the data
array to be filled
respectively.
Enumerator | Value |
---|---|
JS_DATA_FORMAT_XY_FULL_LM_FULL | - |
JS_DATA_FORMAT_XY_HALF_LM_HALF | - |
JS_DATA_FORMAT_XY_QUARTER_LM_QUARTER | - |
JS_DATA_FORMAT_XY_FULL | - |
JS_DATA_FORMAT_XY_HALF | - |
JS_DATA_FORMAT_XY_QUARTER | - |
JS_DATA_FORMAT_CAMERA_IMAGE_FULL | - |
jsCameraImage
This structure is used to return a greyscale image capture from the scan head.
Name | Description |
---|---|
uint32_t scan_head_id | The Id of the scan head that the image originates from. |
jsCamera camera | The camera used to capture the image. |
uint64_t timestamp_ns | Time of the scan head in nanoseconds when image was taken. |
uint64_t encoder_values | Array holding current encoder values. |
uint32_t num_encoder_values | Number of encoder values in this profile. |
uint32_t camera_exposure_time_us | Time in microseconds for the camera's exposure. |
uint32_t laser_on_time_us | Time in microseconds the laser is emitting. |
jsDataFormat format | The type of image data contained in the data array. |
uint32_t image_height | The overall height of the image in pixels. |
uint32_t image_width | The overall width of the image in pixels. |
uint8_t data | An array of pixel data representing the image. |
jsProfileData
A data point within a returned profile's data.
Name | Description |
---|---|
int32_t x | The X coordinate in 1/1000 inches. |
int32_t y | The Y coordinate in 1/1000 inches. |
int32_t brightness | Measured brightness at given point. |
jsProfile
Scan data is returned from the scan head through profiles; each profile returning a single scan line at a given moment in time.
Name | Description |
---|---|
uint32_t scan_head_id | The Id of the scan head that the profile originates from. |
jsCamera camera | The camera used for the profile. |
jsLaser laser | The laser used for the profile. |
uint64_t timestamp_ns | Time of the scan head in nanoseconds when profile was taken. |
int64_t encoder_values | Array holding current encoder values. |
uint32_t num_encoder_values | Number of encoder values in this profile. |
uint32_t laser_on_time_us | Time in microseconds for the laser emitting. |
jsDataFormat format | The format of the data for the given jsProfile. |
uint32_t udp_packets_received | Number of UDP packets received for the profile. If less than udp_packets_expected , then the profile data is incomplete. Generally, this implies some type of network issue. |
uint32_t udp_packets_expected | Total number of UDP packets expected to comprise the profile. |
uint32_t data_len | The total number of valid scan line measurement points for this profile held in the data array. |
uint64_t reserved_0 | Reserved for future use. |
uint64_t reserved_1 | Reserved for future use. |
uint64_t reserved_2 | Reserved for future use. |
uint64_t reserved_3 | Reserved for future use. |
uint64_t reserved_4 | Reserved for future use. |
uint64_t reserved_5 | Reserved for future use. |
jsProfileData data | An array of scan line data associated with this profile. |
jsRawProfile
A Raw Profile is the most basic type of profile returned back from a scan head. The data is left unprocessed with the contents being dependent on the jsDataFormat that the scan head is configured for.
Name | Description |
---|---|
uint32_t scan_head_id | The Id of the scan head that the profile originates from. |
jsCamera camera | The camera used for the profile. |
jsLaser laser | The laser used for the profile. |
uint64_t timestamp_ns | Time of the scan head in nanoseconds when profile was taken. |
int64_t encoder_values | Array holding current encoder values. |
uint32_t num_encoder_values | Number of encoder values in this profile. |
uint32_t laser_on_time_us | Time in microseconds for the laser emitting. |
jsDataFormat format | The arrangement profile data contained in the data array. For raw profile data, the data will be filled in at most according to the resolution specified in the jsDataFormat type. For full resolution, the entire scan line will be sampled. For half resolution, half of the scan line will be sampled and data array will be populated at every other entry. Similarly for quarter resolution, every fourth entry will be used for scan data. Comparison with JS_PROFILE_DATA_INVALID_XY for X/Y values and JS_PROFILE_DATA_INVALID_BRIGHTNESS can be used to determine if data is set or not. |
uint32_t udp_packets_received | Number of UDP packets received for the profile. If less than udp_packets_expected , then the profile data is incomplete. Generally, this implies some type of network issue. |
uint32_t udp_packets_expected | Total number of UDP packets expected to comprise the profile. |
uint32_t data_len | The total length of profile data held in the data array. This value will be less than or equal to JS_RAW_PROFILE_DATA_LEN and should be used for iterating over the array. |
uint32_t data_valid_brightness | Number of brightness values in the data array that are valid. Invalid brightness will be set to JS_PROFILE_DATA_INVALID_BRIGHTNESS . |
uint32_t data_valid_xy | Number of x and y values in the data array that are valid. Invalid x and y will have both set to JS_PROFILE_DATA_INVALID_XY . |
uint64_t reserved_0 | Reserved for future use. |
uint64_t reserved_1 | Reserved for future use. |
uint64_t reserved_2 | Reserved for future use. |
uint64_t reserved_3 | Reserved for future use. |
uint64_t reserved_4 | Reserved for future use. |
uint64_t reserved_5 | Reserved for future use. |
jsProfileData data | An array of scan line data associated with this profile. |
jsScanHeadCapabilities
Structure used to communicate the various capabilities and limits of a given scan head type.
Name | Description |
---|---|
uint32_t camera_brightness_bit_depth | Number of bits used for a brightness value in jsProfileData. |
uint32_t max_camera_image_height | Maximum image height camera supports. |
uint32_t max_camera_image_width | Maximum image width camera supports. |
double max_scan_rate | The fastest scan rate supported by product. |
uint32_t num_cameras | The number of cameras supported by product. |
uint32_t num_encoders | The number of encoders supported by product. |
uint32_t num_lasers | The number of lasers supported by product. |
jsScanHeadConfiguration
Structure used to configure a scan head's operating parameters.
Name | Description |
---|---|
uint32_t scan_offset_us | Apply a time delay in microseconds to when a scan begins on a given scan head. This can be used to ensure that multiple scan heads are performing scans at distinct points in time rather than at the same time. |
uint32_t camera_exposure_time_min_us | Sets the minimum microseconds time value for the camera autoexposure algorithm used when the scan head is in image mode. This value should be within the range of 15 to 2000000 microseconds. |
uint32_t camera_exposure_time_max_us | Sets the maximum microseconds time value for the camera autoexposure algorithm used when the scan head is in image mode. This value should be within the range of 15 to 2000000 microseconds. |
uint32_t camera_exposure_time_def_us | Sets the default microseconds time value for the camera autoexposure algorithm used when the scan head is in image mode. This value should be within the range of 15 to 2000000 microseconds. |
uint32_t laser_on_time_min_us | Sets the minimum microseconds time value for the laser on algorithm. This value should be within the range of 15 to 650000 microseconds. |
uint32_t laser_on_time_max_us | Sets the maximum microseconds time value for the laser on algorithm. This value should be within the range of 15 to 650000 microseconds. |
uint32_t laser_on_time_def_us | Sets the default microseconds time value for the laser on algorithm. This value should be within the range of 15 to 650000 microseconds. |
uint32_t laser_detection_threshold | The minimum brightness a data point must have to be considered a valid data point. Value must be between 0 and 1023 . |
uint32_t saturation_threshold | Set how bright a data point must be to be considered saturated. Value must be between 0 and 1023 . |
uint32_t saturation_percentage | Set the maximum percentage of the pixels in a scan that are allowed to be brighter than the saturation threshold. Value must be between 0 and 100 . |
jsScanHeadStatus
A scan head will periodically report its status back to the client when not actively scanning; it can be obtained and queried to find information about the scan head.
Name | Description |
---|---|
uint64_t global_time_ns | System global time in nanoseconds. |
int64_t encoder_values | The current encoder positions. |
uint32_t num_encoder_values | The number of encoder values available. |
int32_t camera_pixels_in_window | Total number of pixels seen by the camera's scan window. |
int32_t camera_temp | Current temperature in Celsius reported by the camera. |
int32_t mainboard_temp | Current temperature in Celsius reported by the mainboard. |
uint32_t num_profiles_sent | Total number of profiles sent during the last scan period. |
uint32_t firmware_version_major | Firmware major version number of the scan head. |
uint32_t firmware_version_minor | Firmware minor version number of the scan head. |
uint32_t firmware_version_patch | Firmware patch version number of the scan head. |
Functions Documentation - General
jsGetAPIVersion
Obtains the semantic version of the client API presented in this header. The
version string will be of the form vX.Y.Z
, where X
is the major version
number, Y
is the minor version number, and Z
is the patch number. In some
cases, additional information may be appended to the version string, separated
by hyphens.
void jsGetAPIVersion(
const char ** version_str
)
Parameters:
- version_str Address to be updated wth API version string.
jsGetAPISemanticVersion
Obtains the semantic version of the client API presented as unsigned integer values.
void jsGetAPISemanticVersion(
uint32_t * major,
uint32_t * minor,
uint32_t * patch
)
Parameters:
- major The major version number.
- minor The minor version number.
- patch The patch version number.
jsGetError
Converts a jsError error value returned from an API function call to a string value.
void jsGetError(
int32_t return_code,
const char ** error_str
)
Parameters:
- return_code The jsError value returned from API call.
- error_str Address to be updated with error string.
jsGetScanHeadCapabilities
Obtains the capabilities for a given scan head type.
int32_t jsGetScanHeadCapabilities(
jsScanHeadType type,
jsScanHeadCapabilities * capabilities
)
Parameters:
- type The scan head product type to obtain capabilities for.
- capabilities Pointer to struct to be filled with capabilities.
Return: 0
on success, negative value mapping to jsError on error.
Functions Documentation - Scan System
jsScanSystemCreate
Creates a jsScanSystem used to manage and coordinate jsScanHead objects.
Return: Address to new object on success, NULL
on error.
jsScanSystem jsScanSystemCreate(
void
)
jsScanSystemFree
Frees a jsScanSystem and all resources associated with it. In particular, this will free all jsScanHead objects created by this object.
void jsScanSystemFree(
jsScanSystem scan_system
)
Parameters:
- scan_system Reference to system that will be freed.
jsScanSystemCreateScanHead
Creates a jsScanHead object representing a physical scan head within the system.
Note: This function can only be called when the scan system is disconnected. Once jsScanSystemConnect() is called, jsScanSystemDisconnect() must be called if new scan heads are desired to be created.
jsScanHead jsScanSystemCreateScanHead(
jsScanSystem scan_system,
uint32_t serial,
uint32_t id
)
Parameters:
- scan_system Reference to system that will own the scan head.
- serial The serial number of the physical scan head.
- id A user defined numerically unique id to assign to this scan head.
Return: Address to new object on success, NULL
on error.
jsScanSystemGetScanHeadById
Obtains a reference to an existing jsScanHead object.
jsScanHead jsScanSystemGetScanHeadById(
jsScanSystem scan_system,
uint32_t id
)
Parameters:
- scan_system Reference to system that owns the scan head.
- id The numeric ID of the jsScanHead object.
Return: Address to object on success, NULL
on error.
jsScanSystemGetScanHeadBySerial
Obtains a reference to an existing jsScanHead object.
jsScanHead jsScanSystemGetScanHeadBySerial(
jsScanSystem scan_system,
uint32_t serial
)
Parameters:
- scan_system Reference to system that owns the scan head.
- serial The serial number of the physical scan head.
Return: Address to object on success, NULL
on error.
jsScanSystemGetNumberScanHeads
Returns the total number of scan heads within a given system. This should equal the number of times jsScanSystemCreateScanHead() was successfully called with a new serial number.
int32_t jsScanSystemGetNumberScanHeads(
jsScanSystem scan_system
)
Parameters:
- scan_system Reference to system that owns the scan heads.
Return: The number of scan heads on success, negative value mapping to jsError on error.
jsScanSystemConnect
Attempts to connect to all scan heads within the system.
int32_t jsScanSystemConnect(
jsScanSystem scan_system,
int32_t timeout_s
)
Parameters:
- scan_system Reference to system owning scan heads to connect to.
- timeout_s Connection timeout in seconds.
Return: The total number of connected scan heads on success, negative value mapping to jsError on error.
jsScanSystemDisconnect
Disconnects all scan heads from a given system.
int32_t jsScanSystemDisconnect(
jsScanSystem scan_system
)
Parameters:
- scan_system Reference to system of scan heads.
Return: 0
on success, negative value jsError on error
jsScanSystemIsConnected
Gets connected state for a scan system.
Note: A scan system is said to be connected if all of the scan heads associated with it are connected.
bool jsScanSystemIsConnected(
jsScanSystem scan_system
)
Parameters:
- scan_system Reference to system of scan heads.
Return: Boolean true
if connected, false
if disconnected.
jsScanSystemGetMaxScanRate
Obtains the maximum rate at which a given scan system can begin scanning when jsScanSystemStartScanning is called.
double jsScanSystemGetMaxScanRate(
jsScanSystem scan_system
)
Parameters:
- scan_system Reference to system of scan heads.
Return: Floating point double value corresponding to the max scan rate.
jsScanSystemStartScanning
Commands scan heads in system to begin scanning, returning geometry and/or brightness values to the client.
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.
- The scan rate is the overall rate that each individual scan head will generate profiles. This implies that each camera in a given scan head will be set to an equal fractional amount; for example, a scan rate of 2000hz for a scan head with two cameras will cause each camera to run at 1000hz.
int32_t jsScanSystemStartScanning(
jsScanSystem scan_system,
double rate_hz,
jsDataFormat fmt
)
Parameters:
- scan_system Reference to system of scan heads.
- rate_hz The scan rate at hertz by which profiles are generated.
- fmt The data format of the returned scan profile data.
Return: 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.
Return: 0
on success, negative value jsError on error
jsScanSystemIsScanning
Gets scanning state for a scan system.
bool jsScanSystemIsScanning(
jsScanSystem scan_system
)
Parameters:
- scan_system Reference to system of scan heads.
Return: Boolean true
if scanning, false
if not scanning.
Functions Documentation - Scan Head
jsScanHeadGetType
Obtains the product type of the scan head.
Note: This function can only be called when a scan head is successfully connected after calling jsScanSystemConnect().
uint32_t jsScanHeadGetId(
jsScanHead scan_head
)
Parameters:
- scan_head Reference to scan head.
Return: The enumerated scan head type.
jsScanHeadGetId
Obtains the ID of the scan head.
uint32_t jsScanHeadGetId(
jsScanHead scan_head
)
Parameters:
- scan_head Reference to scan head.
Return: The numeric ID of the scan head.
jsScanHeadGetSerial
Obtains the serial number of the scan head.
uint32_t jsScanHeadGetSerial(
jsScanHead scan_head
)
Parameters:
- scan_head Reference to scan head.
Return: The serial number of the scan head.
jsScanHeadIsConnected
Obtains the connection state of a given scan head.
bool jsScanHeadIsConnected(
jsScanHead scan_head
)
Parameters:
- scan_head Reference to scan head.
Return: Boolean true
on connected, false
otherwise.
jsScanHeadConfigure
Configures the scan head according to the parameters specified.
Deprecated: Use jsScanHeadSetConfiguration
.
Note: The configuration settings are sent to the scan head during the call to jsScanSystemStartScanning().
int32_t jsScanHeadConfigure(
jsScanHead scan_head,
jsScanHeadConfiguration * cfg
)
Parameters:
- scan_head Reference to scan head to be configured.
- cfg The jsScanHeadConfiguration to be applied.
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadSetConfiguration
Configures the scan head according to the parameters specified.
Note: The configuration settings are sent to the scan head during the call to jsScanSystemStartScanning().
int32_t jsScanHeadSetConfiguration(
jsScanHead scan_head,
jsScanHeadConfiguration * cfg
)
Parameters:
- scan_head Reference to scan head to be configured.
- cfg The jsScanHeadConfiguration to be applied.
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadGetConfiguration
Get's the scan head's current configuration settings.
int32_t jsScanHeadGetConfiguration(
jsScanHead scan_head,
jsScanHeadConfiguration * cfg
)
Parameters:
- scan_head Reference to scan head to be configured.
- cfg The jsScanHeadConfiguration to be updated with current settings
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadSetAlignment
Configures spatial parameters of the scan head in order to properly transform the data from a camera based coordinate system to one based on mill placement.
Note: The Alignment settings are sent to the scan head during the call to jsScanSystemConnect().
int32_t jsScanHeadSetAlignment(
jsScanHead scan_head,
double roll_degrees,
double shift_x,
double shift_y,
bool is_cable_downstream
)
Parameters:
- scan_head Reference to scan head.
- roll_degrees The rotation in degrees to be applied to the Z axis.
- shift_x The shift to be applied specified in inches.
- shift_y The shift to be applied specified in inches.
- is_cable_downstream Set to
true
if connection cable is oriented downstream and to rotate about the Y axis 180 degrees, placing positive X orientation at former negative X orientation. This should be set tofalse
if the cable is oriented upstream.
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadSetAlignmentCamera
Configures spatial parameters of the scan head in order to properly transform the data from a camera based coordinate system to one based on mill placement. This function is similar to jsScanHeadSetAlignment except that it only applies to one camera rather than both.
Note:
- Use of this function is discouraged. Users should favor use of jsScanHeadSetAlignment() function instead which will properly configure both cameras with the same alignment settings.
- The Alignment settings are sent to the scan head during the call to jsScanSystemConnect().
int32_t jsScanHeadSetAlignmentCamera(
jsScanHead scan_head,
jsCamera camera,
double roll_degrees,
double shift_x,
double shift_y,
bool is_cable_downstream
)
Parameters:
- scan_head Reference to scan head.
- camera The camera to apply parameters to.
- roll_degrees The rotation in degrees to be applied.
- shift_x The shift to be applied specified in inches.
- shift_y The shift to be applied specified in inches.
- is_cable_downstream Set to
true
if connection cable is oriented downstream and to rotate about the Y axis 180 degrees, placing positive X orientation at former negative X orientation. This should be set tofalse
if the cable is oriented upstream.
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadGetAlignmentCamera
Obtains the currently applied alignment settings.
Note: If configured using jsScanHeadSetAlignment
, each camera will have
the same alignment settings.
int32_t jsScanHeadSetAlignmentCamera(
jsScanHead scan_head,
jsCamera camera,
double roll_degrees,
double shift_x,
double shift_y,
bool is_cable_downstream
)
Parameters:
- scan_head Reference to scan head.
- camera The camera to get settings from.
- roll_degrees Variable to hold roll in degrees.
- shift_x Variable to hold shift in inches.
- shift_y Variable to hold shift in inches.
- is_cable_downstream Variable to hold cable orientation.
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadSetWindowRectangular
Sets a rectangular scan window for a scan head to restrict its field of view when scanning.
Note: The window settings are sent to the scan head during the call to jsScanSystemConnect().
int32_t jsScanHeadSetWindowRectangular(
jsScanHead scan_head,
double window_top,
double window_bottom,
double window_left,
double window_right
)
Parameters:
- scan_head Reference to scan head.
- window_top The top window dimension in inches.
- window_bottom The bottom window dimension in inches.
- window_left The left window dimension in inches.
- window_right The right window dimension in inches.
Return: 0
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.
Return: The total number of profiles able to be read on success, negative value jsError on error
jsScanHeadWaitUntilProfilesAvailable
Blocks until the number of requested profiles are avilable 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.
Return: The total number of profiles able to be read on success, negative value jsError on error
jsScanHeadClearProfiles
Empties the internal client side software buffers used to store profiles received from a given 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.
Return: 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
)
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 leastsizeof(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
.
Return: The number of profiles read on success, negative value mapping to 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 leastsizeof(jsRawProfile) * max
in total number of bytes available. - max_profiles The maximum number of profiles to read. Should not exceed
JS_SCAN_HEAD_PROFILES_MAX
.
Return: The number of profiles read on success, negative value mapping to jsError on error.
jsScanHeadGetCameraImage
Obtains a single camera image from a scan head.
Note: This function should be called after jsScanSystemConnect(), but not while the system is set to scan by calling jsScanSystemStartScanning().
int32_t jsScanHeadGetCameraImage(
jsScanHead scan_head,
jsCamera camera,
bool enable_lasers,
jsCameraImage * image
)
Parameters:
- scan_head Reference to scan head.
- camera Camera to use for image capture.
- enable_lasers Set to
true
to turn on laser for image capture,false
to keep laser off. - image Pointer to memory to store camera image data.
Return: 0
on success, negative value mapping to jsError on error.
jsScanHeadGetStatus
Reads the last reported status update from a scan head.
int32_t jsScanHeadGetStatus(
jsScanHead scan_head,
jsScanHeadStatus * status
)
Parameters:
- scan_head Reference to scan head.
- status Pointer to be updated with status contents.
Return: 0
on success, negative value mapping to jsError on error.