CANDELOR SDK  13.2.131
A computer vision library for 3D scene interpretation.
 All Data Structures Files Functions Typedefs Groups Pages
Automatic Configuration Generation

CANDELOR can load STL models and automatically generate a tuned configuration file to detect the object. The generated configuration. Since the configuration generator's source of information is only the model and not data from the scene, it needs to make a few assumptions about the quality of the scans.

The following example demonstrates generation of a matching configuration from an STL model and using that directly.

Example 1: Loading Model, Scene, and Locating using RANGO.

1 /** \example example_autotune.cpp
2  *
3  * Demonstrates RANGO autotuning capability.
4  * For simplicity, this does not do any error checking.
5  *
6  * Boost is only used to generate examples and is not necessary for working with this SDK.
7  */
8 #include <boost/test/unit_test.hpp>
9 
10 
11 #include <candelor/candelor.h>
12 #include <stdio.h>
13 
14 /* Replace with "int main(int argc, char** argv)" if you don't use BOOST */
15 BOOST_AUTO_TEST_CASE(autotuning)
16 {
17  /* for the test purpose, load a point cloud to perform matching on */
18  float* scene_points;
19  int num_points;
20  ca_points_load(&scene_points, "scan.xyz", &num_points);
21 
22  /* set up RANGO with a configuration file */
23  ca_rango_t* r;
24  ca_rango_create(&r);
25 
26  /* autotune a configuration based on an STL model */
28  "tube.stl", /* the STL model to tune the configuration for. */
29  2.0, /* sensor resolution grid size. */
30  0, 0, 1); /* up vector */
31 
32  /* change number of inliers since only a small percentage of the
33  model is visible in the scan */
34  ca_rango_cfg_set(r, "verification.min_inlier_ratio", "0.1");
35 
36  /* allow a runtime of 0.8 seconds for the main search */
37  ca_rango_cfg_set(r, "stops.min_runtime_seconds", "0.8");
38  ca_rango_cfg_set(r, "stops.max_runtime_seconds", "0.8");
39 
40  /* prepare matching from the model file with the generated configuration settings */
42 
43  /* locate objects on the point cloud */
44  float* transform_results;
45  int num_transforms;
46  ca_rango_locate_in_points(r, scene_points, num_points, &transform_results, &num_transforms);
47 
48  /* show all results */
49  ca_rango_show(r, scene_points, num_points, transform_results, num_transforms, 5.0f);
50  printf("Found %d instances of the model in the scene of %d points.\n", num_transforms, num_points);
51 
52  /* save the configuration for later use */
53  ca_rango_cfg_save(r, "generated_tube_config.cfg");
54 
55  /* clean up */
56  ca_transforms_destroy(&transform_results);
57  ca_points_destroy(&scene_points);
58  ca_rango_destroy(&r);
59 }

Running the Example

When running the example, make sure to move to the data/tube directory that contains all necessary files for the example.

Detailed Description of the Example

Autotuning Process

/* autotune a configuration based on an STL model */
"tube.stl", /* the STL model to tune the configuration for. */
2.0, /* sensor resolution grid size. */
0, 0, 1); /* up vector */

Autotuning tries to estimate configuration parameters for a model file, and some information about the point clouds. The estimations are mostly done based on the visible surface area of the model.

A few parameters are necessary to specify how the sensor data that will later be used for locating looks like. The sensor resolution describes how coarsly the 3D data points are spread over the surface. The given sensor resolution grid size should be at least as big as that resolution, using twice that resolution is a good starting value.

Up vector defines where on the sensor data "up" is. This is the opposite directon from the camera, and used to estimate surface normals for the point cloud (if not available).

Important Changes after Autotuning

Some parameters are highly specific to the use case and will need to be modified to your liking.

Configuring Number of Inliers

This parameter roughly describes the percentage of the model surface area that should be covered by the scan. This value can be between 0 and 1, changing it has a very high influence on the resulting match quality.

Too low, and you will find a lot of instances of the object that are incorrect:

show_005.png
min_inlier_ratio set to 0.05: wrongly detecting objects in the clutter.

Too high, and you will not find many objects:

show_02.png
min_inlier_ratio set to 0.2 - Not detecting any objects.

A good approach is to visually evaluate matching results on representative point clouds.

Configuring Runtime

RANGO is a randomized algorithm wich allows a flexible configuration with regards to a trade off between matching quality and runtime. The default configuration assumes a time-based approach: The locating operation is run for one second. On modern desktop PCs this is usually enough to accurately detect objects.

Depending on your runtime and quality requirements, it might be necessary to change that. RANGO supports several different setups to stop calculation. for a purely time-based approach, change both stops.min_runtime_seconds and stops.max_runtime_seconds of the automatically generated configuration to the amount of time you allow the algorithm to run, e.g. like this:

ca_rango_cfg_set(r, "verification.min_inlier_ratio", "0.1");
ca_rango_cfg_set(r, "stops.min_runtime_seconds", "0.05");
ca_rango_cfg_set(r, "stops.max_runtime_seconds", "0.05");

With min_inlier_ratio back to 0.1 and 0.05 seconds are on an Intel Core 2 Quad Q9550 are enough to accurately detect three objects:

runtime_005.png
Runtime of 0.05 seconds on an Intel Core 2 Quad Q9550.

Keep in mind that the total runtime of the algorithm will be slightly above the specified runtime. The parameter specifies the runtime of the searching procedure, and some preperatory steps need to be performed before that.