Data Structures

September 10, 2021 · View on GitHub

Typedefs

Context

Type	Name	Description
`FIND_SURFACE_CONTEXT` (`void *`)	N/A	An opaque type represents the context of FindSurface.

Enumerations

`FS_ERROR`

Enum	Value	Description
`FS_NO_ERROR`	0	Found a geometry surface without any error.
`FS_OUT_OF_MEMORY`	-1	Failed to allocate memory blocks in the context due to the out-of-memory issue.
`FS_INVALID_OPERATION`	-2	Failed to operate due to the invalid state of the context.
`FS_INVALID_VALUE`	-3	Failed to operate due to the invalid values of parameters in the context.
`FS_NOT_FOUND`	-100	Not error but found no surfaces.
`FS_UNACCEPTABLE_RESULT`	-101	Reserved for debugging.

`FS_FEATURE_TYPE`

Enum	Value	Description
`FS_TYPE_ANY`	0	Used for input values to search for one of the five types below.
`FS_TYPE_PLANE`	1	Plane
`FS_TYPE_SPHERE`	2	Sphere
`FS_TYPE_CYLINDER`	3	Cylinder
`FS_TYPE_CONE`	4	Cone
`FS_TYPE_TORUS`	5	Torus
`FS_TYPE_NONE`	6	Indicates that no surfaces found. Not used in the C library of FindSurface.

`FS_SEARCH_LEVEL`

Enum	Value	Description
`FS_LEVEL_0` (`FS_LEVEL_OFF`)	0	Search level 0
`FS_LEVEL_1` (`FS_LEVEL_MODERATE`)	1	Search level 1
`FS_LEVEL_2`	2	Search level 2
`FS_LEVEL_3`	3	Search level 3
`FS_LEVEL_4`	4	Search level 4
`FS_LEVEL_5` (`FS_LEVEL_DEFAULT`)	5	Search level 5 (default)
`FS_LEVEL_6`	6	Search level 6
`FS_LEVEL_7`	7	Search level 7
`FS_LEVEL_8`	8	Search level 8
`FS_LEVEL_9`	9	Search level 9
`FS_LEVEL_10` (`FS_LEVEL_RADICAL`)	10	Search level 10

`FS_SMART_CONVERSION_OPTION`

Enum flag	Value	Description
`FS_SCO_NONE`	0	No smart conversion.
`FS_SCO_CONE_TO_CYLINDER`	(1 << 0)	Cones with the vertex angle of zero is converted to cylinders.
`FS_SCO_TORUS_TO_SPHERE`	(1 << 1)	Tori with the mean radius of zero (degenerated), is converted to spheres (double-covered).
`FS_SCO_TORUS_TO_CYLINDER`	(1 << 2)	Tori with the mean radius of infinite is converted to cylinders.

Structures

`FS_FEATURE_RESULT`

Type	Name	Description
`FS_FEATURE_TYPE`	`type`	The feature type of the resulted surface. This value could be one of `FS_TYPE_PLANE`, `FS_TYPE_SPHERE`, `FS_TYPE_CYLINDER`, `FS_TYPE_CONE` and `FS_TYPE_TORUS`.
`float`	`rms`	RMS error of the resulted surface. Refer to here for the meaning of this value.
`union`	N/A	An anonymous union containing various information about the resulted surface.

Anonymous Union

Type	Name	Description
`float[14]`	`reserved`	A placeholder having the maximum size among the structures below.
`struct`	`plane_param`	An anonymous structure containing information about the resulted surface if it is a plane.
`struct`	`sphere_param`	An anonymous structure containing information about the resulted surface if it is a sphere.
`struct`	`cylinder_param`	An anonymous structure containing information about the resulted surface if it is a cylinder.
`struct`	`cone_param`	An anonymous structure containing information about the resulted surface if it is a cone.
`struct`	`torus_param`	An anonymous structure containing information about the resulted surface if it is a torus.

Anonymous Structures

plane_param:

Type	Name	Description
`float[3]`	`ll`	Coordinates of the lower-left bound of the resulted plane.
`float[3]`	`lr`	Coordinates of the lower-right bound of the resulted plane.
`float[3]`	`ur`	Coordinates of the upper-right bound of the resulted plane.
`float[3]`	`ul`	Coordinates of the upper-left bound of the resulted plane.

sphere_param:

Type	Name	Description
`float[3]`	`c`	Coordinates of the center point of the resulted sphere.
`float`	r	The radius of the resulted sphere.

cylinder_param:

Type	Name	Description
`float[3]`	`b`	Coordinates of the bottom-center point of the resulted cylinder.
`float[3]`	`t`	Coordinates of the top-center point of the resulted cylinder.
`float`	`r`	The radius of the resulted cylinder.

cone_param:

Type	Name	Description
`float[3]`	`b`	Coordinates of the bottom-center point of the resulted cone.
`float[3]`	`t`	Coordinates of the top-center point of the resulted cone.
`float`	`br`	The radius of the resulted cone at its bottom.
`float`	`tr`	The radius of the resulted cone at its top.

torus_param:

Type	Name	Description
`float[3]`	`c`	Coordinates of the center point of the resulted torus.
`float[3]`	`n`	Coordinates of the axis vector of the resulted torus.
`float`	`mr`	The mean radius of the resulted torus.
`float`	`tr`	The tube radius of the resulted torus.

API Functions

Context

`createFindSurface`

Signature: FS_ERROR createFindSurface(FIND_SURFACE_CONTEXT *context)
Summary: Creates the FindSurface context object and returns it into the given pointer context.
Return: An error code of FS_ERROR with value of FS_NO_ERROR indicating if succeeded to create the context. Otherwise, error codes corresponding to the reason of the failure is returned.
Possible Errors: FS_OUT_OF_MEMORY in case that the system fails to allocate memory for the context. In this case, context will not be modified.

`cleanUpFindSurface`

Signature: void cleanUpFindSurface(FIND_SURFACE_CONTEXT context)
Summary: Resets the context to the initial state. All parameters will be reset to their default value and the internal buffers allocated by the previous invocations of setPointCloudFloat/Double or getInOutlierFlags will be released.

`releaseFindSurface`

Signature: void releaseFindSurface(FIND_SURFACE_CONTEXT context)
Summary: Release the FindSurface context.

`setPointCloudFloat/Double`

Signature

FS_ERROR setPointCloudFloat(FIND_SURFACE_CONTEXT context, const void *pointer, unsigned int count, unsigned int stride)

FS_ERROR setPointCloudDouble(FIND_SURFACE_CONTEXT context, const void *pointer, unsigned int count, unsigned int stride)

Summary

Sets input pointcloud data through the pointer to the data array, count of the points and stride of the point element in the data array. stride can be zero if the data array contains tightly-packed xyz values. In that case, the value is considered to be 12 for `float` array or 24 for `double` array.

Return

An error code of FS_ERROR with value of FS_NO_ERROR indicating if succeeded to create the context. Otherwise, error codes corresponding to the reason of the failure is returned.

Possible Errors

FS_OUT_OF_MEMORY if the system fails to allocate memory for the input points.

FS_INVALID_VALUE if one of the following cases is true:

pointer is NULL;
count is zero;
stride is a non-zero value that is less than the stride of when the array contains tightly-packed xyz.

Note

The invocation of this function with pointer is set to NULL or count is zero will be ignored silently.

The points data given through pointer is copied to an internal buffer in the context. The buffer will be released and reallocated when new points is given to the context through this function.

`getPointCloudCount`

Signature: unsigned int getPointCloudCount(FIND_SURFACE_CONTEXT context)
Return: The number of points given to the context previously.

Parameters

Refer to here for the meanings of these parameters.

setMeasurementAccuracy

Signature: void setMeasurementAccuracy(FIND_SURFACE_CONTEXT context, float accuracy)
Summary: Sets measurement accuracy to the given accuracy. The value must be non-zero positive. The default value is zero.

Note: this parameter must be set manually before invoking FindSurface's algorithm since the default value will be considered to be invalid when the algorithm begins to operate.

`getMeasurementAccuracy`

Signature: float getMeasurementAccuracy(FIND_SURFACE_CONTEXT context)
Return: The measurement accuracy value that is currently set to the context.

`setMeanDistance`

Signature: void setMeanDistance(FIND_SURFACE_CONTEXT context, float distance)
Summary: Sets mean distance to the given distance. The value must be non-zero positive. The default value is zero.

Note: this parameter must be set manually before invoking FindSurface's algorithm since the default value will be considered to be invalid when the algorithm begins to operate.

`getMeanDistance`

Signature: float getMeanDistance(FIND_SURFACE_CONTEXT context)
Return: The mean distance value that is currently set to the context.

`setRadialExpansion`

Signature: void setRadialExpansion(FIND_SURFACE_CONTEXT context, FS_SEARCH_LEVEL level)
Summary: Sets radial expasion to the given level. The value must be one of enum FS_SEARCH_LEVEL values. The default value is FS_LEVEL_5.

`getRadialExpansion`

Signature: FS_SEARCH_LEVEL getRadialExpansion(FIND_SURFACE_CONTEXT context)
Return: The radial expansion value that is currently set to the context.

`setLateralExtension`

Signature: void setLateralExtension(FIND_SURFACE_CONTEXT context, FS_SEARCH_LEVEL level)
Summary: Sets lateral extension to the given level. The value must be one of enum FS_SEARCH_LEVEL values. The default value is FS_LEVEL_5.

`getLateralExtension`

Signature: FS_SEARCH_LEVEL getLateralExtension(FIND_SURFACE_CONTEXT context)
Return: The lateral extension value that is currently set to the context.

`setSmartConversionOptions`

Signature: void setSmartConversionOptions(FIND_SURFACE_CONTEXT context, int options)
Summary: Sets smart conversion options to the given options, which can be any bit-OR combinations of FS_SMART_CONVERSION_OPTION values. The default value is FS_SCO_NONE.

`getSmartConversionOptions`

Signature: int getSmartConversionOptions(FIND_SURFACE_CONTEXT context)
Return: The smart conversion option value that is currently set to the context.

Algorithm

`findSurface`

Signature

FS_ERROR findSurface(FIND_SURFACE_CONTEXT context, FS_FEATURE_TYPE type, unsigned int start_index, float touchRadius, FS_FEATURE_RESULT *result)

Summary

Run FindSurface algorithm on the point array that have been set to setPointCloudFloat/Double functions. The algorithm searches the points for a specific geometry surface represented by type around the point of which index is start_index (seed index) in the point array. touchRadius (seed radius) defines the initial search space and must be positive a non-zero value. The result will be written in the struct FS_FEATURE_RESULT pointed by result.

Return

An error code of FS_ERROR with value of FS_NO_ERROR indicating if succeeded to create the context. Otherwise, error codes corresponding to the reason of the failure is returned.

Possible errors

FS_OUT_OF_MEMORY if the system fails to allocate memory for intermediate data arrays.

FS_INVALID_OPERATION if one of the following is true:

one of the parameters is in an invalid state;
pointcloud input is in an invalid state;
type is FS_TYPE_NONE;
start_index is greater than or equal to the number of the given points;
touchRadius is zero or a negative number;
result is NULL.

Specializations of `findSurface`

The following variations are specializations of findSurface function, which is designed to search for surfaces of particular feature types. Refer to this document for the usage of these variations.

`findStripPlane`

Signature: FS_ERROR findStripPlane(FIND_SURFACE_CONTEXT context, unsigned int index_1, unsigned int index_2, float touchRadius, FS_FEATURE_RESULT *result)
Summary: A specialization of findSurface function to search for a strip plane (long and narrow) using two seed points (index_1 and index_2) on the plane. touchRadius should be approximately half of the thickness of the target geometry for better results. Refer to the findSurface function reference for the common details.

`findRodCylinder`

Signature: FS_ERROR findRodCylider(FIND_SURFACE_CONTEXT context, unsigned int index_1, unsigned int index_2, float touchRadius, FS_FEATURE_RESULT *result)
Summary: A specialization of findSurface function to search for a rod cylinder (long and narrow) using two seed points (index_1 and index_2) on the lateral surface. touchRadius should be approximately half of the thickness of the target geometry for better results. Refer to the findSurface function reference for the common details.

`findDiskCylinder`

Signature: FS_ERROR findDiskCylinder(FIND_SURFACE_CONTEXT context, unsigned int index_1, unsigned int index_2, unsigned int index_3, float touchRadius, FS_FEATURE_RESULT *result)
Summary: A specialization of findSurface function to search for a disk cylinder (thin and broad) using three seed points (index_1, index_2 and index_3) on the lateral surface. touchRadius should be approximately half of the thickness of the target geometry for better results. Refer to the findSurface function reference for the common details.

`findDiskCone`

Signature: FS_ERROR findDiskCone(FIND_SURFACE_CONTEXT context, unsigned int index_1, unsigned int index_2, unsigned int index_3, float touchRadius, FS_FEATURE_RESULT *result)
Summary: A specialization of findSurface function to search for a disk cone (thin and broad) using three seed points (index_1, index_2 and index_3) on the lateral surface. touchRadius should be approximately half of the thickness of the target geometry for better results. Refer to the findSurface function reference for the common details.

`findThinRingTorus`

Signature: FS_ERROR findThinRingTorus(FIND_SURFACE_CONTEXT context, unsigned int index_1, unsigned int index_2, unsigned int index_3, float touchRadius, FS_FEATURE_RESULT *result)
Summary: A specialization of findSurface function to search for a thin ring torus using three seed points (index_1, index_2 and index_3) on the surface. touchRadius should be approximately half of the thickness of the target geometry for better results. Refer to the findSurface function reference for the common details.

Miscellaneous

`getInOutlierFlags`

Signature: const unsigned char *getInOutlierFlags(FIND_SURFACE_CONTEXT context)
Summary: Provides an array of which elements indicate whether the corresponding points are outliers. A non-zero value means outlier. Otherwise, it means inlier. The length of the array is the same with the input point array.
Note: The returned array must not be modified or deallocated because the returned pointer points to an internal buffer array in the context.