set_object_model_3d_attrib — Set attributes of a 3D object model.
set_object_model_3d_attrib( : : ObjectModel3D, AttribName, AttachExtAttribTo, AttribValues : ObjectModel3DOut)
set_object_model_3d_attrib sets the standard attributes or the
extended attributes given in AttribName of a 3D object model
ObjectModel3D to the values in AttribValues and returns
a 3D object model with the new attribute values in ObjectModel3DOut.
set_object_model_3d_attrib is identical to
set_object_model_3d_attrib_mod with the exception that it creates a
new 3D object model and leaves the original 3D object model unchanged.
It is possible to attach the values of extended attributes to
already existing standard attributes of the 3D object model by setting the
parameter AttachExtAttribTo. For standard attributes,
AttachExtAttribTo is ignored.
If the attributes in AttribName do not exist, they are created if
possible.
If already existing attributes are set, the length of AttribValues
must match the existing attribute values. In this case the existing attribute
values are replaced.
If extended attributes are attached to already existing standard
attributes with AttachExtAttribTo, the length of AttribValues
must match the existing attribute values.
The following standard attributes can be set:
The x-coordinates of the 3D points are set with
AttribValues. If the attribute does not exist, the
x-, y- and z-coordinates must be set with 'point_coord_x',
'point_coord_y', and 'point_coord_z' at once. The
number of x-, y-, and z-coordinates must be identical.
The y-coordinates of the 3D points are set with
AttribValues. If the attribute does not exist, the
x-, y- and z-coordinates must be set with 'point_coord_x',
'point_coord_y', and 'point_coord_z' at once. The
number of x-, y-, and z-coordinates must be identical.
The z-coordinates of the 3D points are set with
AttribValues. If the attribute does not exist, the
x-, y- and z-coordinates must be set with 'point_coord_x',
'point_coord_y', and 'point_coord_z' at once. The
number of x-, y-, and z-coordinates must be identical.
The x-components of the 3D point normals of the 3D points are
set with AttribValues. If the attribute does not
exist, the x-, y- and z-components of 3D point normals must be set
with 'point_normal_x', 'point_normal_y', and
'point_normal_z' at once. The number of x-, y-, and
z-components must be identical
to the number of 3D points. Note that the given 3D point normals will
not be normalized to a length of 1.
The y-components of the 3D point normals of the 3D points are
set with AttribValues. If the attribute does not
exist, the x-, y- and z-components of 3D point normals must be set
with 'point_normal_x', 'point_normal_y', and
'point_normal_z' at once. The number of x-, y-, and
z-components must be identical
to the number of 3D points. Note that the given 3D point normals will
not be normalized to a length of 1.
The z-components of the 3D point normals of the 3D points are
set with AttribValues. If the attribute does not
exist, the x-, y- and z-components of 3D point normals must be set
with 'point_normal_x', 'point_normal_y', and
'point_normal_z' at once. The number of x-, y-, and
z-components must be identical
to the number of 3D points. Note that the given 3D point normals will
not be normalized to a length of 1.
The indices of the 3D points that represent triangles are set with
AttribValues in the following order:
The first three values of
AttribValues (input values 0,1,2) represent the first triangle
and contain the indices of the corresponding 3D points
of the triangle corners.
The second three values (input values 3,4,5) represent the
second triangle etc.
The direction of the triangles results from the
order of the point indices.
The indices of the 3D points that represent polygons are set with
AttribValues in the following order:
The first value of AttribValues contains
the number n of points of the first polygon. The following values
(input values 1,2,..,n) contains the
indices of the points of the first polygon. The next value
(input value n+1) contains the number m of the points of the
second polygon.
The following m values (input values n+2,n+3,..,n+1+m)
contain the indices of the points of the second polygon etc.
The indices of the 3D points that represent polylines are set with
AttribValues in the following order:
The first value of AttribValues contains the number n
of points of the first polyline. The following values
(input values 1,2,..,n) represent the indices of the points
of the first polyline.
The next value (input value n+1) contains the number m of
points of the second polyline. The following m values
(input values n+2,n+3,..,n+1+m) represent the indices of the
points of the second polyline etc. All indices correspond to
already existing 3D points.
The mapping of 3D points to image
coordinates is set with AttribValues in the following
order: The first two values of
AttribValues (input value 0 and 1) contain the width
and height of the respective image. The following n
values (input values 2,3,..,n+1, with n being the number
of 3D points) represent the row coordinates of the n points
given in image coordinates. The next n input values (input
values n+2,n+3,..,n*2+1) represent the column coordinates of the
n points in image coordinates. Hence, the total number of input
values is n*2+2.
Extended attributes are attributes, that can be derived from standard
attributes by special operators (e.g., distance_object_model_3d),
or user-defined attributes. Predefined extended attributes can only be
set separately, for these attributes AttachExtAttribTo
will be ignored. The names of user-defined extended attributes are arbitrary,
but must start with the prefix '&', e.g., '&my_attrib'.
Extended attributes can have an arbitrary number of floating point
values.
The following predefined extended attributes can be set:
The original points indices of the 3D points are set with
AttribValues. The number of the original points indices must be
identical to the number of 3D points.
The score of a 3D reconstruction of the 3D points are set with
AttribValues. Since the score is evaluated separately for each
3D point, the number of the score-components must be identical to the
number of 3D points.
The red channel intensities of the 3D points are set with
AttribValues. The number of color values must be identical
to the number of 3D points.
The green channel intensities of the 3D points are set with
AttribValues. The number of color values must be identical
to the number of 3D points.
The blue channel intensities of the 3D points are set with
AttribValues. The number of color values must be identical
to the number of 3D points.
The x-component of a vector that is perpendicular to the edge direction and the viewing direction.
The y-component of a vector that is perpendicular to the edge direction and the viewing direction.
The z-component of a vector that is perpendicular to the edge direction and the viewing direction.
Contains the amplitude of edge points.
Extended attributes can be attached to already existing standard attributes
of the 3D object model by setting the parameter AttachExtAttribTo.
The following values of AttachExtAttribTo are possible:
If this value is set, the extended attribute specified in
AttribName is associated to the 3D object model as a whole.
The number of values specified in AttribValues is not restricted.
If this value is set, the extended attribute specified in
AttribName is associated to the 3D points of the object model.
The number of values specified in AttribValues must be the
same as the number of already existing 3D points.
If this value is set, the extended attribute specified in
AttribName is associated to the triangles of the object model.
The number of values specified in AttribValues must be the
same as the number of already existing triangles.
If this value is set, the extended attribute specified in
AttribName is associated to the polygons of the object model.
The number of values specified in AttribValues must be the
same as the number of already existing polygons.
If this value is set, the extended attribute specified in
AttribName is associated to the lines of the object model.
The number of values specified in AttribValues must be the
same as the number of already existing lines.
If multiple attributes are given in AttribName,
AttribValues is divided into sub-tuples of equal length.
Each sub-tuple is then assigned to one attribute.
E.g., if AttribName and AttribValues are set to
AttribName := ['&attrib1','&attrib2','&attrib3'],
AttribValues := [0.0,1.0,2.0,3.0,4.0,5.0],
the following values are assigned to the individual attributes:
'&attrib1' = [0.0,1.0], '&attrib2' = [2.0,3.0], '&attrib3' = [4.0,5.0].
Consequently, it is not possible to set multiple attributes of different lengths in one call.
set_object_model_3d_attrib stores the input AttribValues
unmodified in the 3D object model. Therefore, special attention must
be paid to the consistency of the input data, as most of the operators
expect consistent 3D object models.
ObjectModel3D (input_control) object_model_3d → (handle)
Handle of the input 3D object model.
AttribName (input_control) string(-array) → (string)
Name of the attributes.
List of values: 'blue', 'green', 'lines', 'original_point_indices', 'point_coord_x', 'point_coord_y', 'point_coord_z', 'point_normal_x', 'point_normal_y', 'point_normal_z', 'polygons', 'red', 'score', 'triangles', 'xyz_mapping'
AttachExtAttribTo (input_control) string → (string)
Defines where extended attributes are attached to.
Default: []
List of values: [], 'lines', 'object', 'points', 'polygons', 'triangles'
AttribValues (input_control) real(-array) → (real / integer)
Attribute values.
ObjectModel3DOut (output_control) object_model_3d → (handle)
Handle of the resulting 3D object model.
If the parameters are valid, the operator
set_object_model_3d_attrib returns the value 2 (
H_MSG_TRUE)
.
If necessary, an exception is raised.
set_object_model_3d_attrib_mod
copy_object_model_3d,
remove_object_model_3d_attrib
3D Metrology