fit_primitives_object_model_3dT_fit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d (Operator)

Name

fit_primitives_object_model_3dT_fit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d — Fit 3D primitives into a set of 3D points.

Signature

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

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

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

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

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

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

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

HObjectModel3D HObjectModel3D.FitPrimitivesObjectModel3d(HTuple genParamName, HTuple genParamValue)

Description

The operator fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d fits a 3D primitive, i.e., a simple 3D shape, into a set of 3D points given by a 3D object model with the handle ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D. The shapes that are available as 3D primitives comprise a cylinder, a sphere, and a plane. As the operator does not perform a segmentation of the set of 3D points that is contained in the input 3D object model, you have to make sure that the contained 3D points already correspond to a 3D primitive. A segmentation can be performed, e.g., with the operator segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d.

fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d returns the handle ObjectModel3DOutObjectModel3DOutObjectModel3DOutObjectModel3DOutobjectModel3DOut for the output 3D object model, which contains information that concern, e.g., the type and parameters of the fitted 3D primitive. This information can be queried from the 3D object model with get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams. Note that the extent of primitives of the type plane and cylinder can be queried with get_object_model_3d_paramsget_object_model_3d_paramsGetObjectModel3dParamsGetObjectModel3dParamsGetObjectModel3dParams, as well.

The parameters of a cylinder are the (x-, y-, z-)coordinates of the center, the normed (x-, y-, z-)directions of the main axis of the cylinder, and the radius of the cylinder. The center does not necessarily lie in the center of gravity of the cylinder (see the explanation of the parameters MinExtent and MaxExtent of the operator gen_cylinder_object_model_3dgen_cylinder_object_model_3dGenCylinderObjectModel3dGenCylinderObjectModel3dGenCylinderObjectModel3d). The sign of the main axis is determined such that the main axis points towards the half space in which the origin is located. For a sphere the parameters are the (x-, y-, z-)coordinates of the center and the radius of the sphere. A plane is given by the 4 parameters of the hessian normal form, i.e., the unit normal (x-, y-, z-) vector and the orthogonal distance of the plane from the origin of the coordinate system. The sign of the hessian normal form is determined such that the normal vector points towards the side of the plane on which the origin is located and the distance is not positive.

If no primitive can be fitted to the set of 3D points, the returned object model will not contain a primitive. However, depending on the parameter values for 'output_point_coord'"output_point_coord""output_point_coord""output_point_coord""output_point_coord" and 'output_xyz_mapping'"output_xyz_mapping""output_xyz_mapping""output_xyz_mapping""output_xyz_mapping" (see below), the returned object model is either empty, or contains the 3D points, or contains the 3D points and the mapping from the 3D points to image coordinates of the input object model ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D.

To control 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:

'primitive_type'"primitive_type""primitive_type""primitive_type""primitive_type":

The parameter specifies which type of 3D primitive should be fitted into the set of 3D points. You can specify a specific primitive type by setting 'primitive_type'"primitive_type""primitive_type""primitive_type""primitive_type" to 'cylinder'"cylinder""cylinder""cylinder""cylinder", 'sphere'"sphere""sphere""sphere""sphere", or 'plane'"plane""plane""plane""plane". Then, only the selected type of 3D primitive is fitted into the set of 3D points. You can also specify a set of specific 3D primitives that should be fitted by setting 'primitive_type'"primitive_type""primitive_type""primitive_type""primitive_type" to a tuple consisting of different primitive types. If all types of 3D primitives should be fitted, you can set 'primitive_type'"primitive_type""primitive_type""primitive_type""primitive_type" to 'all'"all""all""all""all". Note that if more than one primitive type is selected, only the best fitting 3D primitive, i.e., the 3D primitive with the smallest quadratic residual error, is returned.

List of values: 'cylinder'"cylinder""cylinder""cylinder""cylinder", 'sphere'"sphere""sphere""sphere""sphere", 'plane'"plane""plane""plane""plane", 'all'"all""all""all""all"

Default value: 'cylinder'"cylinder""cylinder""cylinder""cylinder"

'fitting_algorithm'"fitting_algorithm""fitting_algorithm""fitting_algorithm""fitting_algorithm":

The parameter specifies the used algorithm for the fitting of the 3D primitive. When fitting a plane, the results are identical for the different algorithms. If 'fitting_algorithm'"fitting_algorithm""fitting_algorithm""fitting_algorithm""fitting_algorithm" is set to 'least_squares'"least_squares""least_squares""least_squares""least_squares", the approach minimizes the quadratic distance between the 3D points and the resulting primitive. If 'fitting_algorithm'"fitting_algorithm""fitting_algorithm""fitting_algorithm""fitting_algorithm" is set to 'least_squares_huber'"least_squares_huber""least_squares_huber""least_squares_huber""least_squares_huber", the approach is similar to 'least_squares'"least_squares""least_squares""least_squares""least_squares", but the points are weighted to decrease the impact of outliers based on the approach of Huber (see below). If 'fitting_algorithm'"fitting_algorithm""fitting_algorithm""fitting_algorithm""fitting_algorithm" is set to 'least_squares_tukey'"least_squares_tukey""least_squares_tukey""least_squares_tukey""least_squares_tukey", the approach is also similar to 'least_squares'"least_squares""least_squares""least_squares""least_squares", but the points are weighted and outliers are ignored based on the approach of Tukey (see below).

For 'least_squares_huber'"least_squares_huber""least_squares_huber""least_squares_huber""least_squares_huber" and 'least_squares_tukey'"least_squares_tukey""least_squares_tukey""least_squares_tukey""least_squares_tukey" a robust error statistics is used to estimate the standard deviation of the distances from the object points without outliers from the fitting primitive. The Tukey algorithm removes outliers, whereas the Huber algorithm only damps them, or more precisely, weights them linearly. In practice, the approach of Tukey is recommended.

List of values: '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"

Default value: 'least_squares'"least_squares""least_squares""least_squares""least_squares"

'min_radius'"min_radius""min_radius""min_radius""min_radius":

The parameter specifies the minimum radius of a cylinder or a sphere. If a cylinder or a sphere with a smaller radius is fitted, the resulting 3D object model is empty. The parameter is ignored when fitting a plane. The unit is meter.

Suggested values: 0.01, 0.02, 0.1

Default value: 0.01

'max_radius'"max_radius""max_radius""max_radius""max_radius":

The parameter specifies the maximum radius of a cylinder or a sphere. If a cylinder or a sphere with a larger radius is fitted, the resulting 3D object model is empty. The parameter is ignored when fitting a plane. The unit is meter.

Suggested values: 0.02, 0.04, 0.2

Default value: 0.2

'output_point_coord'"output_point_coord""output_point_coord""output_point_coord""output_point_coord":

The parameter determines if the 3D points used for the fitting are copied to the output 3D object model. If 'copy_point_coord'"copy_point_coord""copy_point_coord""copy_point_coord""copy_point_coord" is set to 'true'"true""true""true""true", the 3D points are copied. If 'copy_point_coord'"copy_point_coord""copy_point_coord""copy_point_coord""copy_point_coord" is set to 'false'"false""false""false""false", no 3D points are copied.

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

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 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 fitting (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".

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

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

The minimum number of 3D points that are necessary to fit a plane is three. The minimum number of 3D points that is necessary to fit a sphere is four. The minimum number of 3D points that is necessary to fit a cylinder is five.

Execution Information

Parameters

ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D (input_control)  object_model_3d(-array) HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

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_radius'"max_radius""max_radius""max_radius""max_radius", '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: '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", 0.01, 0.05, 0.1, 0.2, 'true'"true""true""true""true", 'false'"false""false""false""false"

ObjectModel3DOutObjectModel3DOutObjectModel3DOutObjectModel3DOutobjectModel3DOut (output_control)  object_model_3d(-array) HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the output 3D object model.

Result

fit_primitives_object_model_3dfit_primitives_object_model_3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3dFitPrimitivesObjectModel3d 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

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

Alternatives

segment_object_model_3dsegment_object_model_3dSegmentObjectModel3dSegmentObjectModel3dSegmentObjectModel3d

Module

3D Metrology