set_surface_model_param — Set parameters and properties of a surface model.
set_surface_model_param( : : SurfaceModelID, GenParamName, GenParamValue : )
The operator set_surface_model_param sets parameters and
properties of the surface model SurfaceModelID.
The surface model must have been created by create_surface_model
or read_surface_model.
The names of the desired properties are passed in the generic parameter
GenParamName, the corresponding values are passed in
GenParamValue.
The possible values for GenParamName are listed below.
Defining cameras for image-based refinement.
The following parameters allow to set and clear camera parameters and
poses. Those are used by the operators find_surface_model_image
and refine_surface_model_pose_image to project the surface
model into the passed image.
Note that the camera parameters must be set before the camera pose.
Sets the camera parameters for camera number X, where X is a zero-based
index for the cameras. If not given, X defaults zero (first camera).
The camera parameters are used by the operators
find_surface_model_image and
refine_surface_model_pose_image,
which use the images corresponding to the camera for the 3D pose
refinement.
Cameras must be added in increasing order.
Sets the camera pose for camera number X, where X is a zero-based index for the cameras. If not given, X defaults zero (first camera). The pose defaults to the zero-pose [0,0,0,0,0,0,0] when adding a new camera with 'camera_parameter'. This usually means that camera and 3D sensor have the same point of origin.
Removes all previously set cameras from the surface model.
Defining Object Symmetries. The following parameters can be used to define symmetries of the 3D object which was used for the creation of the surface model. If the 3D object is symmetric, that information can be used to speed up the surface-based matching. Note that for surface models created with the 'train_3d_edges' parameter enabled, no symmetries can be set.
By default, no symmetry is active.
Note that for performance reasons, when changing the symmetry with any of the parameters below, certain internal data structures of the surface model are re-created, which can take a few seconds.
Set the direction of the symmetry axis of the model.
GenParamValue must be a tuple with three numbers, containing
the x-, y- and z-value of the axis direction.
The model is modified to use this symmetry information for speeding
up the matching process.
To remove the symmetry information, pass an empty tuple in
GenParamValue.
Note that either a symmetry axis or symmetry poses can be set, but
not both.
Set a point on the symmetry axis of the model.
GenParamValue must be a tuple with three numbers, which
represent a point in model coordinates that lies on the symmetry
axis of the model.
This parameter is optional and defaults to the center of the
model as returned by get_surface_model_param.
Set one or more symmetry poses of the model (see create_pose).
The model must be identical when transformed with any of those
poses.
The model is modified to use this symmetry information for speeding
up the matching process.
When setting one or more symmetry poses, set_surface_model_param
will internally create all poses that can be created by chaining and
inverting the passed poses. To obtain all internally created poses,
use get_surface_model_param with the argument
'symmetry_poses_all'.
If more than 100 poses are created internally, an error is returned,
which indicates that the passed symmetry poses are invalid.
To remove the symmetry poses, pass an empty tuple in
GenParamValue.
Note that either a symmetry axis or symmetry poses can be set, but
not both.
Restrict the pose range.
The following parameters can be used to restrict the range of rotations
in which the surface model is searched for by find_surface_model,
or the allowed range of rotations for the refinement with
refine_surface_model_pose.
By default, no pose range restriction is active.
Note that for performance reasons, when changing the pose range with any of the parameters below, certain internal data structures of the surface model are re-created, which can take a few seconds.
Set a reference pose of the model. The reference pose can be used along with 'pose_restriction_max_angle_diff', to restrict the allowed range of rotations of the model.
If GenParamValue is an empty tuple, any previously set
reference pose is cleared and no pose range restriction will be active
for the model.
Otherwise, GenParamValue must be a pose (see
create_pose).
Note that the translation part of the pose is ignored.
Also note that both 'pose_restriction_reference_pose' and
'pose_restriction_max_angle_diff' must be set in order for
the pose restriction to be active.
Set by how much the rotation of a pose found with
find_surface_model or refined with
refine_surface_model_pose may deviate from the rotation set
with 'pose_restriction_reference_pose', in radians.
If GenParamValue is an empty tuple, any previously set
maximum deviation angle is cleared and no pose range restriction will
be active for the model.
Otherwise, GenParamValue must be an angle, which
indicates by how much the rotations of a detected pose 'P'
and the reference pose 'R' set with
'pose_restriction_reference_pose' may differ.
The comparison is performed using the formula
Angle(R^(-1) * P) <= max_angle_diff
.
Set an axis for which rotations are ignored when evaluating the pose
range (see 'pose_restriction_reference_pose' and
'pose_restriction_max_angle_diff').
If GenParamValue is an empty tuple, any previously set
axis is cleared.
Otherwise, GenParamValue must contain a tuple of three numbers
which are the direction of the axis in model coordinates.
If such an axis is set, then a pose is considered to be within the allowed range if the angle between the axis in the reference pose and the compared pose is smaller than the allowed angle, using Angle(R * axis, P * axis) <= max_angle_diff .
Set a point on the allowed rotation axis of the model.
GenParamValue must be a tuple with three numbers, which
represent a point in model coordinates that lies on the symmetry
axis of the model.
This parameter is optional and defaults to the center of the
model as returned by get_surface_model_param.
This flag allows to switch between two different modi for the pose range restriction.
If GenParamValue is 'false' (default), poses outside the
defined pose range are removed early in the matching process.
Use this setting if the object pose in the scene is always within the
defined rotation range, but the object is sometimes found with incorrect
rotations.
Note that with this setting, find_surface_model might return
poses that the algorithm considers to be locally suboptimal, because the
locally more optimal poses are outside the allowed pose range.
Also note that with this setting, the pose restriction is observed
strictly.
When passing an input pose to refine_surface_model_pose
that is outside the allowed pose range, it will be transformed to be
within the allowed pose range.
If GenParamValue is 'true', only the final poses
are filtered before returning them.
This allows removing poses that are valid object poses, but are not
needed by the application because, for example, the object cannot be
picked up by the robot in a certain orientation.
Note that in this setting, less poses than requested might be returned
by find_surface_model if one or more of the final poses
are outside the allowed pose range.
Modifying self-similarities.
The following parameters can be used to adapt the optimization regarding
self-similar poses, i.e., poses under which the model is almost
symmetric.
The parameters can only be set if the parameter
'train_self_similar_poses' was activated during the call
of create_surface_model.
Note that for performance reasons, when changing the self-similarity search with any of the parameters below, certain internal data structures of the surface model are re-created, which can take a few seconds.
Set the self-similar poses of the model. Those are poses under which the model is very similar to itsself and which can be confused during search.
find_surface_model will find such poses automatically
if the parameter 'use_self_similar_poses' is activated.
The poses can be obtained with get_surface_model_param.
If the automatically determined poses are not sufficient to
resolve self-similarities, the self-similar poses can be adapted
with this parameter.
It is usually not recommended to modify this parameter.
GenParamValue must contain a list of poses.
The identity pose will automatically be added to the list of poses,
if it is not already contained in it.
Note that in some cases, if this operator encounters an error condition while modifying the surface model, such as an out-of-memory error, the model might be left in an inconsistent, partly changed state. In such cases, it is recommended to clear the surface model and to no longer use it.
This does not apply to error codes due to invalid parameters, which are checked before performing any model modification.
Also note that setting some of the options requires re-generation of
internal data structures and can take as long as the original
create_surface_model.
This operator modifies the state of the following input parameter:
During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.
SurfaceModelID (input_control, state is modified) surface_model → (handle)
Handle of the surface model.
GenParamName (input_control) attribute.name → (string)
Name of the parameter.
Default value: 'camera_parameter'
List of values: 'camera_parameter', 'camera_pose', 'clear_cameras', 'pose_restriction_allowed_axis_direction', 'pose_restriction_allowed_axis_origin', 'pose_restriction_filter_final_poses_only', 'pose_restriction_max_angle_diff', 'pose_restriction_reference_pose', 'self_similar_poses', 'symmetry_axis_direction', 'symmetry_axis_origin', 'symmetry_poses'
GenParamValue (input_control) attribute.value(-array) → (real / string / integer)
Value of the parameter.
Suggested values: 'true', 'false', [], [0,0,0,0,0,0,0], [0,0,1]
set_surface_model_param returns 2 (H_MSG_TRUE) if all parameters are
correct. If necessary, an exception is raised.
create_surface_model,
read_surface_model,
get_surface_model_param
find_surface_model,
refine_surface_model_pose,
write_surface_model,
find_surface_model_image,
refine_surface_model_pose_image
create_surface_model,
get_surface_model_param
3D Metrology