Skip to content

Latest commit

 

History

History
529 lines (343 loc) · 22.8 KB

FindSurface-API-reference-C.md

File metadata and controls

529 lines (343 loc) · 22.8 KB

Data Structures

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.

PointCloud

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.