create_deformable_surface_model — Create the data structure needed to perform deformable
create_deformable_surface_model creates a model for
deformable surface-based matching for the 3D object stored in the
3D object model
The 3D object model can, for example, have been read previously from a file
read_object_model_3d or it can have been created by using
The created surface model is returned in
The creation of the deformable surface model requires that the 3D object model contains points and normals. The following combinations are possible:
points and point normals, e.g., from a call to
points and a triangular or polygon mesh, e.g., from a CAD file
points and a 2D-Mapping, e.g., from an XYZ image triple converted with
Note that the direction and orientation (inward or outward) of the normals of the model are important for matching.
The deformable surface model is created by sampling the 3D object model with
a certain distance.
The sampling distance must be specified in the parameter
RelSamplingDistance and is parametrized relative to the diameter
of the axis-parallel bounding box of the 3D object model.
For example, if
RelSamplingDistance is set to 0.05 and
the diameter of
ObjectModel3D is 10 cm, the points
sampled from the object's surface will be approximately 5 mm
The sampled points can be obtained with the operator
get_deformable_surface_model_param using the value
Note that outlier points in the object model should be avoided, as they would
corrupt the diameter.
RelSamplingDistance leads to more points, and in turn
to a more stable but slower matching. Increasing
RelSamplingDistance leads to less points, and in turn to a less
stable but faster matching.
By default, deformable surface models created with
create_deformable_surface_model can handle a moderate amount of
deformation. The operator
can be used to add additional training samples, thus expanding the
range of possible deformations.
The amount of deformation that can be found can also be controlled with the
generic parameters 'scale_min', 'scale_max' and
'bending_max' (see below).
The generic parameter pair
is used to set additional parameters for the model generation.
GenParamName contains the tuple of parameter names that shall be
GenParamValue contains the corresponding values.
The following values are possible for
Invert the orientation of the surface normals of the model. The normal orientation needs to be known for the model generation. If both the model and the scene are acquired with the same setup, the normals will already point in the same direction. If the model was loaded from a CAD file, the normals might point into the opposite direction. If you experience the effect that the model is found on the 'outside' of the scene surface and the model was created from a CAD file, try to set this parameter to 'true'. Also, make sure that the normals in the CAD file all point either outward or inward, i.e., are oriented consistently.
Possible values: 'false', 'true'
Default value: 'false'
The minimum and maximum allowed scaling of the model. Note that if you set one of the two parameters, the other one must be set too.
Suggested values: 0.8, 1, 1.2
Default value: No scaling
Assertion: 0 < 'scale_min' < 'scale_max'
Controls the maximum automatic deformation of the model. The model is deformed automatically by bending it with an angle up to the value of 'bending_max'. This allows for deformations to be found that are within this bending range. The angle is passed in degrees.
Suggested values: 5, 10, 30
Default value: 20
Assertion: 0 <= 'bending_max' < 90
Control the stiffness of the model when performing the refinement. Larger values of this parameter lead to a more stiff model that can be less deformed. Smaller values lead to a less stiff model that allows more deformation.
Suggested values: 0.2, 0.5, 0.8
Default value: 0.5
Assertion: 0 < 'stiffness' <= 1
This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.
This operator supports cancelling timeouts and interrupts.
Handle of the 3D object model.
Sampling distance relative to the object's diameter
Default value: 0.05
Suggested values: 0.1, 0.05, 0.03, 0.02, 0.01
0 < RelSamplingDistance < 1
Names of the generic parameters.
Default value: 
Suggested values: 'model_invert_normals', 'scale_min', 'scale_max', 'bending_max', 'stiffness'
→(string / real / integer)
Values of the generic parameters.
Default value: 
Suggested values: 'true', 'false', 1, 0.9, 1.1, 5, 10, 20, 30, 0.05, 0.1, 0.2
Handle of the deformable surface model.
create_deformable_surface_model returns 2 (H_MSG_TRUE) if all parameters are
correct. If necessary, an exception is raised.
Bertram Drost, Slobodan Ilic: “Graph-Based Deformable 3D Object Matching.” Proceedings of the 37th German Conference on Pattern Recognition, pp. 222-233, 2015.