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

RANGO Configuration Reference

The RANGO configuration is in a serialized Google Protocol Buffers format. The format supports comments, like in the following excerpt:

performance {
# disable multithreadding and use just one thread
threads: 1
grainsize: 1000
}

The parameters are hierarchically structured and can be accessed with ca_rango_cfg_get() and modifed with ca_rango_cfg_set(). Access is done by a dotted path in the hierarchy, e.g. with

ca_rango_cfg_set(r, "performance.threads", "1");

RANGO Parameters

features

A feature describes the appearance of a local surface area. To find candidate positons of the model in the scene, features are calculated from the model and from the scene. While locating objects, features of the scene and model are correlated with each other. This section configures how the features are calculated and correlated.

grid_size_distance_bucketing

Grid size for surface distance to consider two features as similar. Too small and there will be only few matches between scene features and model features resulting in low detection rates, too large and the performance will suffer because too many equal features are detected.

The appropriate value depends mostly on the size of the object.

grid_size_innerproduct_bucketing

Angular components of the feature are evaluated to consider if two features are similar. Too small and there will be only few matches between scene features and model features resulting in low detection rates, too large and the performance will suffer because too many equal features are detected.

In general, a value between 0.05 and 0.3 should be choosen. 0.1 is generally a good value.

features_filtering_percent

A percentage of features from the model can be discarded to reduce memory requirement and speed up matching by keeping the most descriptive features.

A value between 0 and 1 is possible. Low values will lead to more memory requirements and slower matching, close to 1 will lead to removing most features therefore reducing the chance of finding a feature pair.

Around 0.5 is generally a good value.

min_pointpair_distance_percentile

Feature generation randomly selects two points on the scene and finds corresponding features in the model. If two points are selected that are very close to each other, the feature is not very descriptive because a small error at close distance can lead to a large error on the whole object.

This parameter configures the minimum distance in relation to the model size. It has to be 0 and above, and below max_pointpair_distance_percentile.

A value between 0 to 0.5 is generally a good value.

max_pointpair_distance_percentile

Limits the upper limit of the distance of randomly choosen points of the scene. See min_pointpair_distance_percentile for the lower limit. In general it is impossible that two points on the scene that are further appart than the maximum distance of two points on the model to produce a match.

A value between 0.9 and 1 is generally a good value.

seed_matching

RANGO randomly selects points from the scenes to find matches. This parameter controls the seed for the random number generator.

If set to 0, the seed will be automatically initialized with a timestamp. This is the preferred setting.

When set to any positive value, this given seed is used. Be aware that a call to e.g. ca_rango_locate_in_points() only gets perfectly reproducable results when multithreadding is disabled by setting threads to 1.

seed_model

The order of precalculated features of the model are randomized with this seed. The ordering has some influence on the early_stop_probability and therefore on the runtime performance.

Generally this number does not need to be modified.

grid_size_model_features

In the prepratory step features of the model are calculated with several point pairs of the model. The resolution specified here has a large influence on the number of precalculated features.

For smaller grid_size_model_features more pointpairs and therefore more features will be precalculating, leading to an increase of memory usage and time to precalculate.

For larger grid_size_model_features, memory usage time to prepare goes down.

Generally, this value should be large enough to be able to robustly detect the object. Making it too large will lead to unnecessarily higher runtime and memory requirements. Usually ca_rango_cfg_autotune_from_file() provides good estimates for this parameter.

min_normals_inner_product

When using a single pointcloud from one sensor for matching, it will only show one side of the object. Therefore it is not possible to have two points from completely opposite directions. This property can be used as a filter for the preperatory step.

Use a value between -0.5 and 0 when matching is performed with a pointclouds from a single scanner.

Use -1 to disable the filtering.


verification

When a candidate position and orientation for an object is found, this position is verified if it meets the requirements of being a good match. This verification step is done by calculating how many points of the model have a corresponding close point in the scene. In addition, the orientation of the surface around these point pairs between model and scene have to be similar.

grid_size_model_inliers

The points of the model are filtered with this grid size. Larger grid size means less points, smaller grid size means more points are used.

If you choose a large grid relative to the model, you will get few inlier points to check, which makes the inlier check fast but potentially unrelieable.

A small value will result in a lot of points to check, which take a longer. Additionally, having a low grid size does not necessarily improve matching quality. In fact a larger grid size might give better matching results if the quality of the scene data is not very good.

Generally, it is a good idea to use the autotune functionality to find an appropriate starting value. To improve matching quality, when modifying this parameter you should adapt min_inlier_ratio as well because the appropriate inlier ratio and this grid size depend on each other.

grid_size_scene_inliers

To test if a point from the model has a nearby point in the scene, this grid size is used. If a point pair is further away than the grid size, it is not considered as a valid point pair.

Small values will lead to more precise matches, but if it is too small the number of inliers will can be drastically reduced. If set too large, the algorithm will have difficulties distingusing between a good and a bad match.

Generally the value generated by autotuning is a good starting point. The value should be at least as big as the average scan resolution.

min_inlier_ratio

This is a very important configuration parameter that usually needs to be manually configured for each application. The value should be above 0 and is usually below 0.5. It can be as high as 0.9 or so when practically the whole model should be matched. See Configuring Number of Inliers in the tutorial for the effect on the demo data.

early_stop_probability

RANGO uses a heuristic to stopping the verification process early. This heuristic can lead to an enormous performance boost. The probability has a range between 0 and 1.

Good number are usually between 0.6 and 0.95. In several benchmarks a number around 0.8 had the best performance results. High numbers lead to lots of checks and a slowdown, but fewer discarded solution candidates. Low numbers lead to fast checks but many potential transforms discarded.

min_normal_inner_product

Whenever an point pair between model and scene is found, the orientation of the local surface area should be similar as well. This value controls the level of this similarity.

The value of the inner product corresponds to an angle and should usually be between 0.5 and 1.0. 1.0 means both orientations have to match exactly, 0.5 allows a wide difference. Use -1 to disable this check.

The inner product of an angle can be calculated with inner_product = cos(angle). Here are a few numbers:

inner product angle (deg)
1.0 0.0
0.9 25.8
0.8 36.9
0.7 45.6
0.6 53.1
-1 180.0

remove_scene_inliers_after_match

With this parameter the behavior of the algorithm is modified.

  • true means that immediately after a match was found that meets the min_inlier_ratio requirements, all scene points that contribute to this match will be removed from the scene. This has the effect that as the algorithm continues runnig it will concentrate on the area where no objects have yet been found. The disadvantage is that removing data from the scene can have a severe runtime overhead.

  • false means that no scene data will be removed while performing the matching step, and all results will be collected as candidates. In a post processing step all possible candidates are filtered so that only unique results are returned. This has several advantages: Since it is likely that an object can will be found multiple times, the postprocessing step will keep only the best of these results. This also makes the algorithm more robust against changes in the parameter min_inlier_ratio.

In general, setting the parameter to false provides the best results. Also see the max_objects parameter.


normal_estimation

The orientation of the surface around points on the model and scene are estimated with the neighborhood points.

num_of_neighbours

Number of neighbors to look at for normal vector calculation. This is an integer number and should be above 4. A higher value leads to smoother surface normals, but potentially misses smaller features. This influences min_normals_inner_product. A lower value means faster calculation.

A good value is between around 15. Too low (below 9) could get unstable normals, and bad search results. A reasonable values seems to be above 12 and below 20.

max_distance

Maximum distance to select points for normal calculations. Usually setting the num_of_neighbours is enough, and setting max_distance to a very large number disables this limit.

If the scan has a lot of noise (separated points that are far away from other points), then using a neighborhood of e.g. 15 can be a time consuming overhead, and a lower limit of max_distance can be helpful to speed up normals calculation. Usually autoconfigure chooses a very large value and relies on the num_of_neighbours parameter.

up_vector

This vector is described as a triple of x, y, z values and points towards the camera. It is used as a hint for calculation of normals. E.g. when the pointcloud is a flat surface, without an upvector it is unclear which side of the area is top and which is bottom. The upvector gives a hint where the camera was positioned with regards to the scan.

upvector.png
Up-vector points towards Z axis. The up-vector is x: 0, y: 0, z: 1.

For the Microsoft Kinect, the upvector is usually -Z:

up_vector {
x: 0
y: 0
z: -1
}

For the scans provided in the examples, (scanned with a Sick IVP Ruler) the upvector is in Z:

up_vector {
x: 0
y: 0
z: 1
}

The result of a wrongly configured upvector will be a very low number of inliers.


stops

The stops section controls at what point RANGO should finish working. The basic logic is this:

  1. First, run until all of the min_... requirements are met.
  2. Second, stop working as soon as one of the max_... requirements is met.

This allows for a very flexible configuration. Here are a few example configurations:

Purely Time Based Stop
stops {
min_iterations: 0
max_iterations: 18446744073709551615
min_runtime_seconds: 3.0
max_runtime_seconds: 3.0
max_objects: 1000000
}

Setting min_iterations to 0 and max_iterations to the maximum possible value practically disables the iteration check. Both min_runtime_seconds and max_runtime_seconds are set to the same value of 3 seconds, so RANGO will run exactly 3 secons and stop after that. max_objects is set large enough to not be a stopping issue but only to prevent memory problems.

Purely Iteraton Based Stop
stops {
min_iterations: 2000000
max_iterations: 2000000
min_runtime_seconds: 0
max_runtime_seconds: 3600
max_objects: 100000
}

min_iterations and max_iterations are set to the same value of 2000000, while min_runtime_seconds is set to zero. That means min_runtime_seconds is immediately met, and RANGO only waits for min_iterations to finish. Meanwhile, max_runtime_seconds is set to a very large number (one day) and max_objects is also so large that it does not interfer with calculation but only serve as a stop if all else fails.

Ensure Minimum Iterations

The purely time based approach has a disadvantage if the computer is used for other tasks as well, and not much CPU is available for RANGO. It is possible to ensure a minimum number of iterations in case of high CPU usage, and to make use of as much available time if CPU is available with one configuration.

stops {
min_iterations: 1000000
max_iterations: 18446744073709551615
min_runtime_seconds: 1.0
max_runtime_seconds: 1.0
max_objects: 100000
}

In this example, a minimum of 1,000,000 iterations are required and a minimum of one second. If the computer can do the million iterations in less than a second, it will continue calculating for the rest of the second to provide as accurate a result as possible in the given time frame. If the computer is slower, it is at least guaranteed that it will calculate for 1,000,000 iterations.

min_iterations

Minimum number of iterations. In each iteration RANGO selects random points and evaluates a possible match for the selection. This is a 64 bit unsigned value, ranging from 0 to 2^64 - 1 = 18446744073709551615.

max_iterations

Maximum number of iterations the algorithm should run.

min_runtime_seconds

Minimum runtime in seconds, as a float value.

max_runtime_seconds

Maximum runtime in seconds, as a float value.

max_objects

The maximum number of objects depends on the remove_scene_inliers_after_match parameter. If it is set to false, all objects are collected and the max_object check is met much eariler.

Usually, a large value of 100000 is practical when remove_scene_inliers_after_match is set to false. This relies on filtering with min_inlier_ratio to reduce the number of found objects down to a reasonable number.

When remove_scene_inliers_after_match is set to true, this depends on the number of objects you expect to find in the scene.


performance

Contains performance relevant settings.

threads

Number of threads to use. Use 0 to automatically use every logical processor available. A value of 1 limits can be helpful for debugging purposes.

grainsize

Defines the number of iterations that should be atomically run on one processor. If it is too low, performance will suffer because the CPU is occupied with sheduling tasks. If too large, less parallelism can be used.

A value around 1000 has shown to be a good choice on an Intel Core 2 Q9550.


debug

Settings associated to debugging RANGO.

show_match

Whenever RANGO findes a possible candidate for a match, a 3D window is opened showing the scene with it's normal vectors, and the candidate model match represented as large dots.

Should be set to "false" in normal operation.

statistics

Generates statistics about the algorithm. This is associated with a time overhead, so it is preferred to leave it at false in normal operation.

show_model

When true, opens a window showing calculated model points and normals if a CAD model was used.

log_or_status

Enable/disable some logging output. Set to "false" in normal operation.

show_best_match

Similar to show_model, but only shows just the best match when RANGO has finished.


model

The model describe the object that should be located in a pointcloud.

filename

The filename of the model. Supported extensions are:

.STL

The STereoLitography file format in the binary form is supported. The file is loaded and converted into a format that can be used for matching in the preparatory step.

.csv / .xyz
A collection of points, as described in XYZ Point Clouds. If the filename has the extension .xyz it can be conveniently opened with e.g. Meshlab.

sensor_simulator_resolution

A CAD file will be processed by a simulated scanner. This specifies the resolution of this simulator, e.g. 1mm if approximately 1 point per square mm is expected. Try to use a resolution similar to what is used in the real world, so that the normals estimation on the model is a good approximation to the scene.

This setting has only an effect if a CAD model is loaded.

sensor_simulator_views_from_sphere

When set to true, the sensor simulator performs 18 simulated scans of the model. If set to false, only 6 simulated scans are performed.

Generally, a value of true might take a bit additional time when preparing the model, but will produce better results.

check_correct_triangle_side

When set to true, the back sides of triangles in the model will be ignored when simulating. This should be generally left at true, except when the orientation of the triangles of the source model are faulty.

When set to true, it is also possible to improve recognition rates. When e.g. an object is located where it is known in advance which side is visible, the CAD model can be edited so that the back side of the model is removed. The mesh will be open, and the sensor simulator scanning the back side will not result in any points, keeping only the important front points.