CANDELOR SDK  13.2.131
A computer vision library for 3D scene interpretation.
 All Data Structures Files Functions Typedefs Groups Pages
RANGO - RANdomized Global Object localization

RANGO is a powerful global detection algorithm of CANDELOR. More...

Data Structures

struct  ca_rango_t
 A handle to a RANGO locator. More...
 

Functions

int ca_rango_create (ca_rango_t **r)
 Creates RANGO - RANdomized Global Object localization.
 
int ca_rango_destroy (ca_rango_t **r)
 Destroys the data assciated with the handle, and sets the handle to 0.
 
int ca_rango_cfg_load (ca_rango_t *r, const char *config_file_name)
 Loads the configuration file into an existing RANGO handle.
 
int ca_rango_cfg_save (const ca_rango_t *r, const char *config_file_name)
 Saves the current configuration into the given file name.
 
int ca_rango_cfg_autotune_from_file (ca_rango_t *r, const char *file_name, float resolution, float upvector_x, float upvector_y, float upvector_z)
 Creates a configuration for the specified model.
 
int ca_rango_cfg_autotune_from_points (ca_rango_t *r, const float *points, int num_points, float resolution, float upvector_x, float upvector_y, float upvector_z)
 Creates a configuration for the specified model.
 
int ca_rango_cfg_autotune_from_pointsnormals (ca_rango_t *r, const float *points, const float *normals, int num_points, float upvector_x, float upvector_y, float upvector_z)
 Creates a configuration for the specified model.
 
int ca_rango_cfg_set (ca_rango_t *r, const char *field_name, const char *value)
 Sets a configuration parameters.
 
int ca_rango_cfg_get (const ca_rango_t *r, const char *field_name, char **value, int *num_chars)
 Gets the value behind the field_name as a character array.
 
int ca_rango_prepare_from_model_file (ca_rango_t *r)
 Prepares the RANGO matcher to get ready for locating objects.
 
int ca_rango_prepare_from_points (ca_rango_t *r, const float *points, int num_points)
 Prepares the RANGO matcher with the given 3D points as the model.
 
int ca_rango_prepare_from_pointsnormals (ca_rango_t *r, const float *points, const float *normals, int num_points)
 Prepares the RANGO matcher with the given 3D points as the model.
 
int ca_rango_extract_model_points (const ca_rango_t *r, float **points, int *num_points)
 Extracts the points associated with the model.
 
int ca_rango_extract_model_pointsnormals (const ca_rango_t *r, float **points, float **normals, int *num_points)
 Extracts the points associated with the model.
 
int ca_rango_locate_in_points (const ca_rango_t *r, const float *points, int num_points, float **transform_results, int *num_results)
 Performs RANGO location on the given points.
 
int ca_rango_locate_in_pointsnormals (const ca_rango_t *r, const float *points, const float *normals, int num_points, float **transform_results, int *num_results)
 Performs RANGO location on the given points & normals.
 
int ca_rango_show (const ca_rango_t *r, const float *scene_points, int num_scene_points, const float *transform_results, int num_transform_results, float max_distance)
 Visualizes a scene with the model as points.
 
int ca_rango_log_callback (ca_rango_t *r, ca_log_callback_t lc, void *user_data)
 Sets a callback for log messages.
 

Detailed Description

RANGO is a powerful global detection algorithm of CANDELOR.

RANGO Configuration Reference

Although RANGO can be autotuned with e.g. ca_rango_cfg_autotune_from_file(), all configurations can be configured and tweaked.

Function Documentation

int ca_rango_create ( ca_rango_t **  r)

Creates RANGO - RANdomized Global Object localization.

RANGO is a high performance, robust global registration algorithm. Use ca_rango_destroy(ca_rango_t* r) to free the handle.

Parameters
[out]rThe new RANGO handle.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_rango_destroy ( ca_rango_t **  r)

Destroys the data assciated with the handle, and sets the handle to 0.

Parameters
[in,out]rThe RANGO handle to delete.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_rango_cfg_load ( ca_rango_t r,
const char *  config_file_name 
)

Loads the configuration file into an existing RANGO handle.

After that, a call to ca_rango_prepare() is necessary before calling the locate methods.

Parameters
[in]rThe RANGO handle.
[in]config_file_nameName of the config file, e.g. "rango.cfg".
Returns
Error code, zero on success.
Examples:
example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_rango_cfg_save ( const ca_rango_t r,
const char *  config_file_name 
)

Saves the current configuration into the given file name.

Configurations can be modified with the ca_rango_set() methods, and with the ca_rango_cfg_autotune_from_file()

Parameters
[in]rThe RANGO handle.
[in]config_file_nameFile name where to save the config, e.g. "rango.cfg"
Returns
Error code, zero on success.
Examples:
example_autotune.cpp.
int ca_rango_cfg_autotune_from_file ( ca_rango_t r,
const char *  file_name,
float  resolution,
float  upvector_x,
float  upvector_y,
float  upvector_z 
)

Creates a configuration for the specified model.

This tries to estimate an appropriate matching configuration for the given model, and assumes a runtime of one second. It is usually best to save the generated configuration and tune the relevant parameters by hand to your liking.

Specify a number bigger than the average sensor resolution. E.g. when the minimum distance between two points in the scene is about 1mm, use 1mm or higher here.

Supported file formats are STL and XYZ pointclouds. When loading a pointcloud (and later for locating), the specified x,y,z components are used as the upvector. It should point towards the camera. E.g. for data from the Kinect sensor, x,y,z should be 0,0,-1 - meaning up towards the camera for the perspective of the data points is -z.

Parameters
[in]rThe RANGO handle.
[in]file_nameThe model, e.g. a STL file or a XYZ point cloud.
[in]resolutionExpected resolution of the scans.
[in]upvector_xX component of the upvector for sensor data.
[in]upvector_yY component of the upvector for sensor data.
[in]upvector_zZ component of the upvector for sensor data.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp.
int ca_rango_cfg_autotune_from_points ( ca_rango_t r,
const float *  points,
int  num_points,
float  resolution,
float  upvector_x,
float  upvector_y,
float  upvector_z 
)

Creates a configuration for the specified model.

This tries to estimate an appropriate matching configuration for the given model, and assumes a runtime of one second. It is usually best to save the generated configuration and tune the relevant parameters by hand to your liking.

Specify a number bigger than the average sensor resolution. E.g. when the minimum distance between two points in the scene is about 1mm, use 1mm or higher here.

The specified x,y,z components are used as the upvector for matching. It should point towards the camera. E.g. for data from the Kinect sensor, x,y,z should be 0,0,-1 - meaning up towards the camera for the perspective of the data points is -z.

Here upvector is used to calculate normals of the points to tune for.

Parameters
[in]rThe RANGO handle.
[in]pointsPointer to 3D points data.
[in]num_pointsNumber of points.
[in]resolutionExpected resolution of the scans.
[in]upvector_xX component of the upvector for sensor data.
[in]upvector_yY component of the upvector for sensor data.
[in]upvector_zZ component of the upvector for sensor data.
Returns
Error code, zero on success.
int ca_rango_cfg_autotune_from_pointsnormals ( ca_rango_t r,
const float *  points,
const float *  normals,
int  num_points,
float  upvector_x,
float  upvector_y,
float  upvector_z 
)

Creates a configuration for the specified model.

This tries to estimate an appropriate matching configuration for the given model, and assumes a runtime of one second. It is usually best to save the generated configuration and tune the relevant parameters by hand to your liking.

Specify a number bigger than the average sensor resolution. E.g. when the minimum distance between two points in the scene is about 1mm, use 1mm or higher here.

The specified x,y,z components are used as the upvector for matching. It should point towards the camera. E.g. for data from the Kinect sensor, x,y,z should be 0,0,-1 - meaning up towards the camera for the perspective of the data points is -z.

Here upvector is not used for the specified points, instead the precalculated normals are used.

Parameters
[in]rThe RANGO handle.
[in]pointsPointer to 3D points data.
[in]normalsPointer to 3D normals data.
[in]num_pointsNumber of points.
[in]upvector_xX component of the upvector for sensor data.
[in]upvector_yY component of the upvector for sensor data.
[in]upvector_zZ component of the upvector for sensor data.
Returns
Error code, zero on success.
int ca_rango_cfg_set ( ca_rango_t r,
const char *  field_name,
const char *  value 
)

Sets a configuration parameters.

Hierarchical parameters are separated by a dot, e.g. "debug.show_model".

Parameters
[in]rThe RANGO handle.
[in]field_nameName of the field to set.
[in]valueThe value to set, as null terminated char array.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, and example_configuration_visualization.cpp.
int ca_rango_cfg_get ( const ca_rango_t r,
const char *  field_name,
char **  value,
int *  num_chars 
)

Gets the value behind the field_name as a character array.

Call ca_chars_destroy(char** data) to free the allocated field value.

Parameters
[in]rThe RANGO handle.
[in]field_nameThe field name separated with dot, e.g. "debug.show_model"
[out]valueThe actual value as a character array, allocated by the library.
[out]num_charsNumber of characters value (excluding the zero termination).
Returns
Error code, zero on success.
Examples:
example_configuration_visualization.cpp.
int ca_rango_prepare_from_model_file ( ca_rango_t r)

Prepares the RANGO matcher to get ready for locating objects.

This loades the model file from the configured file name, and performs a preprocessing step to generate data required for the matching procedure.

Parameters
[in]rThe RANGO handle.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_rango_prepare_from_points ( ca_rango_t r,
const float *  points,
int  num_points 
)

Prepares the RANGO matcher with the given 3D points as the model.

Instead of using the file supplied in the configuration, the given points will be used as the model. After this call the points data can be freed because RANGO creates its own data structures required for matching.

Note
The normal_estimation.up_vector defines the view direction of the camera which is used to estimate surface normals of the point cloud. When aligning the model to the scene, the estimated normals of scene and model have to point into the same direction to be able to successfully detect a match.
Parameters
[in]rThe RANGO handle.
[in]pointsThe 3D points that are used for the model.
[in]num_pointsNumber of points.
Returns
Error code, zero on success.
int ca_rango_prepare_from_pointsnormals ( ca_rango_t r,
const float *  points,
const float *  normals,
int  num_points 
)

Prepares the RANGO matcher with the given 3D points as the model.

Instead of using the file supplied in the configuration, the given points and normals will be used as the model. After this call the points data can be freed because RANGO creates its own data structures required for matching.

Parameters
[in]rThe RANGO handle.
[in]pointsThe 3D points that are used for the model.
[in]normalsThe normals for each point of the model.
[in]num_pointsNumber of points / normals.
Returns
Error code, zero on success.
int ca_rango_extract_model_points ( const ca_rango_t r,
float **  points,
int *  num_points 
)

Extracts the points associated with the model.

RANGO converts a loaded model into a 3D pointcloud. This pointcloud can be extracted, e.g. to use in a visualization of the results.

Parameters
[in]rThe RANGO handle.
[out]pointsThe extracted points.
[out]num_pointsNumber of extracted points.
Returns
Error code, zero on success.
int ca_rango_extract_model_pointsnormals ( const ca_rango_t r,
float **  points,
float **  normals,
int *  num_points 
)

Extracts the points associated with the model.

RANGO converts a loaded model into a 3D pointcloud. This pointcloud can be extracted, e.g. to use in a visualization of the results.

Parameters
[in]rThe RANGO handle.
[out]pointsThe extracted points.
[out]normalsThe extracted normals.
[out]num_pointsNumber of extracted points.
Returns
Error code, zero on success.
int ca_rango_locate_in_points ( const ca_rango_t r,
const float *  points,
int  num_points,
float **  transform_results,
int *  num_results 
)

Performs RANGO location on the given points.

Returns the detected objects as transformation matrices, sorted by quality. The first result is the one with the highest overlap. Normals of the input points are estimated with the configured up vector.

Parameters
[in]rThe RANGO handle.
[in]pointsThe pointcloud that should be searched.
[in]num_pointsNumber of points in the pointcloud.
[out]transform_resultsA newly created array of matrices, each consisting of 16 float values.
[out]num_resultsNumber of transforms found.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, example_candelor_one_minute.cpp, and example_configuration_visualization.cpp.
int ca_rango_locate_in_pointsnormals ( const ca_rango_t r,
const float *  points,
const float *  normals,
int  num_points,
float **  transform_results,
int *  num_results 
)

Performs RANGO location on the given points & normals.

Returns the detected objects as transformation matrices, sorted by quality. The first result is the one with the highest overlap. Uses the specified normal vectors for the given points.

Parameters
[in]rThe RANGO handle.
[in]pointsThe pointcloud that should be searched.
[in]normalsThe normals for each of the given points.
[in]num_pointsNumber of points in the pointcloud.
[out]transform_resultsA newly created array of matrices, each consisting of 16 float values.
[out]num_resultsNumber of transforms found.
Returns
Error code, zero on success.
int ca_rango_show ( const ca_rango_t r,
const float *  scene_points,
int  num_scene_points,
const float *  transform_results,
int  num_transform_results,
float  max_distance 
)

Visualizes a scene with the model as points.

Each point of the scene is colorized according to the minimum distance to a point of the model.

Parameters
[in]rThe RANGO handle.
[in]scene_pointsThe points of the scene where the model was located in.
[in]num_scene_pointsNumber of scene points.
[in]transform_resultsThe transformation matrices, e.g. created with ca_rango_locate_in_points().
[in]num_transform_resultsNumber of transform results.
[in]max_distanceMaximum point distance for the visulization. Anything further away will be colored red.
Returns
Error code, zero on success.
Examples:
example_autotune.cpp, and example_configuration_visualization.cpp.
int ca_rango_log_callback ( ca_rango_t r,
ca_log_callback_t  lc,
void *  user_data 
)

Sets a callback for log messages.

To get details about what happens inside RANGO, you can specify a callback method. To clear logging, call ca_rango_log_callback(r, 0, 0).

Parameters
[in,out]rThe RANGO handle where the callback will be registered. Old callbacks are overwritten.
[in]lcThe callback function for all events inside RANGO.
[in]user_dataCustom user data that is passed through to the logging callback.
Returns
Error code, zero on success.