FlexScan3D User Manual - Version 3.3.4.x

You are here: API/SDK and Automation > FlexScan3D DLL Interface

FlexScan3D DLL Interface

The FlexScan3D DLL allows the calling application to start an interactive session via any programming or scripting language that supports the loading up of DLL interfaces. The DLL also supports callbacks that allow users to receive event and mesh data asynchronously.

You can find the include file, library, and example projects under C:\Program Files\LMI Technologies\FlexScan3D 3.3\SDK\ScanInterface after installation.

Callbacks

Callbacks are supported in FlexScan3D version 3.3.2.178 and higher.

Initializing FlexScan3D

For basic applications, FS3D_Init should be called at the beginning to start FlexScan3D and FS3D_Exit at the end to exit FlexScan3D. If the basic command I/O is handled separately through standard input/output, then FlexScan3D should be started separately and the application calls FS3D_Attach and FS3D_Detach to connect to the already running FlexScan3D instance. See below for more information on FS3D_Init and FS3D_Exit.

Either FS3D_Init or FS3D_Attach must be called before FS3D_RegisterCallback.

Registering Callbacks

Call FS3D_RegisterCallback to register callbacks. The callback to be registered is specified by name. The following callbacks are supported:

Callback Name	Description
ScanProcessed	Triggers immediately after a scan has been processed. Allows users to receive vertices or faces.
MotionDetected	Active when live scanning is enabled. Triggers when live scanning is enabled and motion is initially detected.
MotionStopped	Active when live scanning is enabled. Triggers when live scanning is enabled and motion is no longer detected.

Call this function multiple times to register multiple callbacks.

To avoid writing to disk during scanning, the Scanning_WriteToDisk advanced setting must be set to False before scanning.

Processing Callbacks

The callbacks return a FS3D handle, which is container of multiple items. The items contained depend on the callbacks. Users can use the FS3D_Get<Property type> functions to access the contained items.

Callback: ScanProcessed
Item Name	Item Type	Description
gridHeight	int	Height of the scan grid
gridWidth	int	Width of the scan grid
nVertices	int	Number of vertices
nFaces	int	Number of faces
nGrid	int	Number of grid indices (should be the same as nVertices)
vertices	double array	Vertices in X,Y,Z sequence
faces	int array	Triangle faces, with 3 vertex index values per face
grids	int array	Grid indices with a H,W sequence per vertex

Callback: MotionDetected
Item Name	Item Type	Description
scannerName	string	Name of the scanner which detected motion

Callback: MotionStopped
Item Name	Item Type	Description
scannerName	string	Name of the scanner which detected motion
motionDetected	int	Set to 1 if motion was detected, 0 if no motion was detected

Memory returned through various FS3D_Get*() function parameters are accessible throughout the scope of the callback function. There is no need to explicitly allocate or free memory.

Error Handling

Error FS3D_RESULT_WRONGTYPE will be returned if the item names or type do not match.

Callback Functions

See below.

C API command functions

int FS3D_Init(const char* a_PathName)

a_PathName: Full path for the FlexScan3D executable.

Starts FlexScan3D in Interactive mode and connects to the input and output pipes to allow direct control over it. Must be called before any FS3D_Command calls. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_Command(const char* a_Command)

a_Command: Any interactive command for FlexScan3D.

Sends the specified command to FlexScan3D and waits for it to reply that the task is completed. Returns FS3D_RESULT_OK if the command was successful, FS3D_RESULT_ERROR if the command was unsuccessful, and FS3D_RESULT_UNKNOWN if the command was not recognized.

int FS3D_CommandAsync(const char* a_Command)

a_Command: Any interactive command for FlexScan3D.

Sends the specified command to FlexScan3D and returns immediately. Always returns FS3D_RESULT_OK.

int FS3D_AsyncResult()

Used to check the result of an asynchronous command from FS3D_CommandAsync(). While the command is still running, this function will return FS3D_RESULT_EXECUTING. For multi-threaded applications, a "while(FS3D_CommandAsync()==FS3D_RESULT_EXECUTING)" loop can be used to determine when the command has completed.

const char* FS3D_ScriptQuery(const char* a_Query)

a_Query: A script variable name.

Queries FlexScan3D for the current value of a script variable. Returns the value of the variable as a string, or 0 (NULL) if the query failed. String variables are returned as-is, numbers are converted to a string representation before being returned, and nil values are returned as "nil".

Example: For script "a = 4 * 5", FS3D_ScriptQuery("a") returns "20".

int FS3D_Attach()

Opens a direct communication pipe with a running instance of FlexScan3D. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_Detach()

Closes the communication with FlexScan3D. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_RegisterCallback(const char* a_FunctionName, void* userContext, void (a_Callback)(void userContext, FS3D_Handle handle))

a_FunctionName: The internal function name.
userContext: Context pointer which will get passed through to the callback function.
a_Callback: A pointer to a custom function.

Registers a callback with FlexScan3D. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_UnregisterCallback(const char* a_FunctionName)

a_FunctionName: The internal function name.

Unregisters a callback with FlexScan3D. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_GetNumItems(const FS3D_Handle handle, int* numItems)

handle: A handle to FlexScan3D data.
numItems: Returns the number of items.

Gets the number of available named data items. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_GetItem(const FS3D_Handle handle, const int itemIndex, char itemName, char itemType)

handle: A handle to FlexScan3D data.
itemIndex: An index into the entire item list (0-based).
itemName: Returns a text string containing the name of the item.
itemType: Returns a text string containing the internal item type.

Gets information pertaining to the item at a particular index. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure.

int FS3D_GetString(const FS3D_Handle handle, const char* itemName, char** value)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
value: Returns the item text string.

Gets a text string. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not a text string.

int FS3D_GetDouble(const FS3D_Handle handle, const char* itemName, double* value)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
value: Returns the item number value.

Gets a 64-bit floating-point value. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not a 64-bit floating-point value.

int FS3D_GetFloat(const FS3D_Handle handle, const char* itemName, float* value)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
value: Returns the item number value.

Gets a 32-bit floating-point value. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not a 32-bit floating-point value.

int FS3D_GetInt(const FS3D_Handle handle, const char* itemName, int* value)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
value: Returns the item number value.

Gets a 32-bit integer value. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not a 32-bit integer value.

int FS3D_GetDoubleArray(const FS3D_Handle handle, const char* itemName, int* numValues, double** values)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
numValues: Returns the number of values in the array.
values: Returns the item values.

Gets an array of 64-bit floating-point values. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not an array of 64-bit floating-point values.

int FS3D_GetFloatArray(const FS3D_Handle handle, const char* itemName, int* numValues, float** values)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
numValues: Returns the number of values in the array.
values: Returns the item values.

Gets an array of 32-bit floating-point values. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not an array of 32-bit floating-point values.

int FS3D_GetIntArray(const FS3D_Handle handle, const char* itemName, int* numValues, int** values)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
numValues: Returns the number of values in the array.
values: Returns the item values.

Gets an array of 32-bit integer values. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not an array of 32-bit integer values.

int FS3D_GetByteArray(const FS3D_Handle handle, const char* itemName, int* numValues, unsigned char** values)

handle: A handle to FlexScan3D data.
itemName: The name of the desired item.
numValues: Returns the number of values in the array.
values: Returns the item values.

Gets an array of byte values. Returns FS3D_RESULT_OK on success, FS3D_RESULT_ERROR on failure, or FS3D_RESULT_WRONGTYPE if the item defined by itemName is not an array of byte values.

int FS3D_Abort()

Used to abort a command while it is being executed, which can be useful for long operations such as 360-degree rotary scans. This can be used in multi-threaded applications when using FS3D_CommandAsync(). Always returns FS3D_RESULT_OK.

int FS3D_Exit()

Shuts down the communication pipes with FlexScan3D and terminates the application. Failure to call before terminating the calling application may result in data loss and/or error messages from FlexScan3D. Always returns FS3D_RESULT_OK.