ClassesClasses | | Operators

segment_object_model_3dT_segment_object_model_3dSegmentObjectModel3dSegmentObjectModel3d (Operator)

Name

segment_object_model_3dT_segment_object_model_3dSegmentObjectModel3dSegmentObjectModel3d — Segment a set of 3D points into sub-sets with similar characteristics.

Signature

segment_object_model_3d( : : ObjectModel3D, GenParamName, GenParamValue : ObjectModel3DOut)

Herror T_segment_object_model_3d(const Htuple ObjectModel3D, const Htuple GenParamName, const Htuple GenParamValue, Htuple* ObjectModel3DOut)

void SegmentObjectModel3d(const HTuple& ObjectModel3D, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* ObjectModel3DOut)

static HObjectModel3DArray HObjectModel3D::SegmentObjectModel3d(const HObjectModel3DArray& ObjectModel3D, const HTuple& GenParamName, const HTuple& GenParamValue)

HObjectModel3D HObjectModel3D::SegmentObjectModel3d(const HTuple& GenParamName, const HTuple& GenParamValue) const

static void HOperatorSet.SegmentObjectModel3d(HTuple objectModel3D, HTuple genParamName, HTuple genParamValue, out HTuple objectModel3DOut)

static HObjectModel3D[] HObjectModel3D.SegmentObjectModel3d(HObjectModel3D[] objectModel3D, HTuple genParamName, HTuple genParamValue)

HObjectModel3D HObjectModel3D.SegmentObjectModel3d(HTuple genParamName, HTuple genParamValue)

Description

The operator segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d segments a set of 3D points given by a 3D object model with the handle ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D into several sub-sets of neighbored 3D points with similar characteristics like the same normal orientation or curvature. By default, the operator then tries to fit a 3D primitive, i.e., a simple 3D shape like a plane, a sphere, or a cylinder, into each of these sub-sets. As result, the operator returns a tuple of handles for the 3D object models that represent the individual sub-sets of 3D points (ObjectModel3DOutObjectModel3DOutObjectModel3DOutObjectModel3DOutobjectModel3DOut). Within these 3D object models information is stored that concern, e.g., the success of the fitting and the type and parameters of the fitted 3D primitive. This information can be queried from the individual 3D object model with get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams.

Before calling segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d, the input 3D object model should be prepared for the segmentation using the operator prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d with the parameter PurposePurposePurposePurposepurpose set to 'segmentation'"segmentation""segmentation""segmentation""segmentation". If the input 3D object model is not prepared this way, the operator prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d is called internally within segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d to extend the 3D object model with attributes that were not explicitly but only implicitly contained in the 3D object model.

To control the segmentation and the fitting, you can adjust some generic parameters within GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue. But note that for a lot of applications the default values are sufficient and no adjustment is necessary. The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue are possible:

'max_orientation_diff'"max_orientation_diff""max_orientation_diff""max_orientation_diff""max_orientation_diff":

The parameter specifies the maximum angle between the point normals of two neighbored 3D points (in radians) that is allowed so that the two points belong to the same sub-set of 3D points. For a cylinder or sphere, the parameter value depends on the dimension of the object and on the distance of the neighbored 3D points. I.e., if the cylinder or sphere has a very small radius or if the 3D points are not very dense, the value must be chosen higher. For a plane the value is independent from the dimension of the object and can be set to a small value.

Suggested values: 0.10, 0.15, 0.20

Default value: 0.15

'max_curvature_diff'"max_curvature_diff""max_curvature_diff""max_curvature_diff""max_curvature_diff":

The parameter specifies the maximum difference between the curvatures of the surface at the positions of two neighbored 3D points that is allowed so that the two points belong to the same sub-set of 3D points. The value depends on the noise of the 3D points. I.e., if the noise level of the 3D points is very high, the value must be set to a higher value. Generally, the number of resulting 3D object models decreases for a higher value, because more 3D points are merged to a sub-set of 3D points.

Suggested values: 0.03, 0.04, 0.05

Default value: 0.05

'min_area'"min_area""min_area""min_area""min_area":

The parameter specifies the minimum number of 3D points needed for a sub-set of connected 3D points to be returned by the segmentation. Thus, for a sub-set with fewer points the points are deleted and no output handle is created.

Suggested values: 1, 10, 100

Default value: 100

'fitting'"fitting""fitting""fitting""fitting":

The parameter specifies whether after the segmentation 3D primitives are fitted into the sub-sets of 3D points. If 'fitting'"fitting""fitting""fitting""fitting" is set to 'true'"true""true""true""true", which is the default, the fitting is calculated and the 3D object models with the resulting handles contain the parameters of the corresponding 3D primitives. The output parameters of a cylinder, a sphere, or a plane are described with the operator fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d. If 'fitting'"fitting""fitting""fitting""fitting" is set to 'false'"false""false""false""false", only a segmentation is performed and the output 3D object models contain the segmented sub-sets of 3D points. A later fitting can be performed with the operator fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d.

List of values: 'false'"false""false""false""false", 'true'"true""true""true""true"

Default value: 'true'"true""true""true""true"

'output_xyz_mapping'"output_xyz_mapping""output_xyz_mapping""output_xyz_mapping""output_xyz_mapping":

The parameter determines if a mapping from the segmented 3D points to image coordinates is copied to the output 3D object model. This information is needed, e.g., when using the operator object_model_3d_to_xyzobject_model_3d_to_xyzObjectModel3dToXyzObjectModel3dToXyzObjectModel3dToXyz after the segmentation (e.g., for a visualization). If 'output_xyz_mapping'"output_xyz_mapping""output_xyz_mapping""output_xyz_mapping""output_xyz_mapping" is set to 'true'"true""true""true""true", the image coordinate mapping is copied. Note that the parameter is only valid, if the image coordinate mapping is available in the input 3D object model. Make sure that, if you derive the input 3D object model by copying it with the operator copy_object_model_3dcopy_object_model_3dCopyObjectModel3dCopyObjectModel3dCopyObjectModel3d from a 3D object model that contains such a mapping, the mapping is copied, too. Furthermore, the parameter is only valid, if the 3D points are copied to the output 3D object model, which is set with the parameter 'output_point_coord'"output_point_coord""output_point_coord""output_point_coord""output_point_coord". If 'output_xyz_mapping'"output_xyz_mapping""output_xyz_mapping""output_xyz_mapping""output_xyz_mapping" is set to 'false'"false""false""false""false", the image coordinate mapping is not copied.

List of values: 'true'"true""true""true""true",'false'"false""false""false""false"

Default value: 'false'"false""false""false""false"

'primitive_type'"primitive_type""primitive_type""primitive_type""primitive_type",'fitting_algorithm'"fitting_algorithm""fitting_algorithm""fitting_algorithm""fitting_algorithm", 'min_radius'"min_radius""min_radius""min_radius""min_radius",'max_radius'"max_radius""max_radius""max_radius""max_radius", 'output_point_coord'"output_point_coord""output_point_coord""output_point_coord""output_point_coord":

These parameters are used, if 'fitting'"fitting""fitting""fitting""fitting" is set to 'true'"true""true""true""true", which is the default. The meaning and the use of these parameters is described with the operator fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d.

Note that if a 3D object model is no longer needed or should be overwritten, the memory has to be freed first by calling the operator clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3d.

Execution Information

Parameters

ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D (input_control)  object_model_3d(-array) HObjectModel3D, HTupleHTupleHtuple (integer) (IntPtr) (Hlong) (Hlong)

Handle of the input 3D object model.

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  attribute.name-array HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters.

Number of elements: GenParamName == GenParamValue

List of values: 'fitting_algorithm'"fitting_algorithm""fitting_algorithm""fitting_algorithm""fitting_algorithm", 'max_curvature_diff'"max_curvature_diff""max_curvature_diff""max_curvature_diff""max_curvature_diff", 'max_orientation_diff'"max_orientation_diff""max_orientation_diff""max_orientation_diff""max_orientation_diff", 'max_radius'"max_radius""max_radius""max_radius""max_radius", 'min_area'"min_area""min_area""min_area""min_area", 'min_radius'"min_radius""min_radius""min_radius""min_radius", 'output_point_coord'"output_point_coord""output_point_coord""output_point_coord""output_point_coord", 'output_xyz_mapping'"output_xyz_mapping""output_xyz_mapping""output_xyz_mapping""output_xyz_mapping", 'primitive_type'"primitive_type""primitive_type""primitive_type""primitive_type"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  attribute.name-array HTupleHTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

Values of the generic parameters.

Number of elements: GenParamValue == GenParamName

Suggested values: 0.15, 0.05, 100, 'true'"true""true""true""true", 'false'"false""false""false""false", 'cylinder'"cylinder""cylinder""cylinder""cylinder", 'sphere'"sphere""sphere""sphere""sphere", 'plane'"plane""plane""plane""plane", 'all'"all""all""all""all", 'least_squares'"least_squares""least_squares""least_squares""least_squares", 'least_squares_huber'"least_squares_huber""least_squares_huber""least_squares_huber""least_squares_huber", 'least_squares_tukey'"least_squares_tukey""least_squares_tukey""least_squares_tukey""least_squares_tukey"

ObjectModel3DOutObjectModel3DOutObjectModel3DOutObjectModel3DOutobjectModel3DOut (output_control)  object_model_3d(-array) HObjectModel3D, HTupleHTupleHtuple (integer) (IntPtr) (Hlong) (Hlong)

Handle of the output 3D object model.

Result

segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d returns 2 (H_MSG_TRUE) if all parameter values are correct. If necessary, an exception is raised.

Possible Predecessors

xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d, read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d, prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d

Possible Successors

get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams, object_model_3d_to_xyzobject_model_3d_to_xyzObjectModel3dToXyzObjectModel3dToXyzObjectModel3dToXyz, write_object_model_3dwrite_object_model_3dWriteObjectModel3dWriteObjectModel3dWriteObjectModel3d, clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3d

See also

fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d

Module

3D Metrology


ClassesClasses | | Operators